InkCollector.DesiredPacketDescription Property

Gets or sets interest in aspects of the packets associated with ink drawn on the InkCollector object.

Definition

Visual Basic .NET	Public Property DesiredPacketDescription As Guid()
C#	public Guid[] DesiredPacketDescription { get; set; }
Managed C++	public: __property Guid* get_DesiredPacketDescription(); public: __property void set_DesiredPacketDescription(Guid*);

Property Value

System.Guid[]. The array of Guid objects, each of which represents an aspect of the packets associated with ink drawn on the InkCollector object.

This property is read/write. This property has no default value.

Exceptions

ArgumentNullException :
ObjectDisposedException :

Remarks

The packet description is an array of Guid objects from the PacketProperty object.

By default, DesiredPacketDescription contains X, Y, and NormalPressure from the PacketProperty object. If you set DesiredPacketDescription to anything else, X and Y are also added. For example, if you set DesiredPacketDescription to ButtonPressure only, a get returns {X, Y, ButtonPressure}, not just {ButtonPressure}.

When DesiredPacketDescription is set to something that includes PacketStatus, PacketStatus is added in the third position. For example, if you set DesiredPacketDescription to (a, b, c, d, PacketStatus, e, f), a get returns (X, Y, PacketStatus, a, b, c, d, e, f).

In multitablet mode, this is the packet description for all of the tablet devices. If any of the devices do not support a known packet description property, the property data is not returned.

Changes to this property do not affect incoming packet data until the Enabled property changes from false to true.

Examples

[C#]

This C# example draws a rectangle on the form with a bold outline when the in-air packets are within the rectangle and with a narrow outline when the packets are outside the rectangle. This demonstrates how to use the packet events to control application behaviors.

using System;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using Microsoft.Ink;

namespace CSInAirPacketEvents
{
    public class Form1 : System.Windows.Forms.Form
    {
    //...

        InkCollector theInkCollector;
        int indexX, indexY;
        Rectangle rectInterest;
        bool thickBorder;

        public Form1()
        {
            //...

            //Initialize our InkCollector object.
            theInkCollector = new InkCollector(Handle);
            theInkCollector.Enabled = true;

            //Initialize our target rectangle
            rectInterest = new Rectangle(40, 40, 200, 80);
            thickBorder = false;

            //Save the X and Y data locations within the packet data.
            GetXYIndexes(ref indexX, ref indexY);

            //Add the event handler for in air packets
            theInkCollector.NewInAirPackets += new InkCollectorNewInAirPacketsEventHandler(NewInAirPackets_Event);
        }

//...

        private void GetXYIndexes(ref int theXIndex, ref int theYIndex)
        {
            // Get the indexes of the X and Y data within the raw
            // packet data array.
            Guid [] theGuids = theInkCollector.DesiredPacketDescription;
            for (int i = 0; i < theGuids.Length; i++)
            {
                if (theGuids[i].Equals(PacketProperty.X))
                    theXIndex = i;
                if (theGuids[i].Equals(PacketProperty.Y))
                    theYIndex = i;
            }
        }

        private void NewInAirPackets_Event(object sender, InkCollectorNewInAirPacketsEventArgs e)
        {
            Graphics g = this.CreateGraphics();
            Point [] pt = new Point [1];
            pt[0].X = e.PacketData[indexX];
            pt[0].Y = e.PacketData[indexY];
            theInkCollector.Renderer.InkSpaceToPixel(g, ref pt);

            // The event may return with data for multiple packets.
            // To simplify things, we'll only look at the first.
            if (rectInterest.Contains(pt[0].X, pt[0].Y))
            {
                if (!thickBorder)
                {
                    thickBorder = true;
                    Refresh();
                }
            }
            else
            {
                if (thickBorder)
                {
                    thickBorder = false;
                    Refresh();
                }
            }
        }

        private void Form1_Paint(object sender, System.Windows.Forms.PaintEventArgs e)
        {
            Graphics g = e.Graphics;
            Pen thePen = new Pen(Color.Black, 2);
            if (thickBorder)
                thePen.Width = 5;
            g.DrawRectangle(thePen, rectInterest);
        }

        // Event handler for the form's closed event
        private void Form1_Closed(object sender, System.EventArgs e)
        {
            theInkCollector.Dispose();
            theInkCollector = null;
        }
    }
}
            

[VB.NET]

This Microsoft® Visual Basic® .NET example draws a rectangle on the form with a bold outline when the in-air packets are within the rectangle and with a narrow outline when the packets are outside the rectangle. This demonstrates how to use the packet events to control application behaviors.

Imports Microsoft.Ink
Public Class Form1
    Inherits System.Windows.Forms.Form

    Dim theInkCollector As InkCollector
    Dim indexX, indexY As Integer
    Dim rectInterest As Rectangle
    Dim thickBorder As Boolean

'...

    Public Sub New()
        MyBase.New()

        'This call is required by the Windows Form Designer.
        InitializeComponent()

        'Initialize our InkCollector object.
        theInkCollector = New InkCollector(Handle)
        theInkCollector.Enabled = True

        'Initialize our target rectangle
        rectInterest = New Rectangle(40, 40, 200, 80)
        thickBorder = False

        'Save the X and Y data locations within the packet data.
        GetXYIndexes(indexX, indexY)

        'Add the event handler for in air packets
        AddHandler theInkCollector.NewInAirPackets, AddressOf NewInAirPackets_Event

    End Sub

'...

    Private Sub GetXYIndexes(ByRef theXIndex As Integer, _
        ByRef theYIndex As Integer)
        ' Get the indexes of the X and Y data within the raw
        ' packet data array.
        Dim theGuids() As Guid = theInkCollector.DesiredPacketDescription
        Dim i As Integer
        For i = 0 To theGuids.Length - 1
            If theGuids(i).Equals(PacketProperty.X) Then
                theXIndex = i
            End If
            If theGuids(i).Equals(PacketProperty.Y) Then
                theYIndex = i
            End If
        Next
    End Sub

    Private Sub NewInAirPackets_Event(ByVal sender As Object, _
        ByVal e As InkCollectorNewInAirPacketsEventArgs)
        'The event may return with data for multiple packets.
        'To simplify things, we'll only look at the first.
        Dim g As Graphics
        Dim pt() As Point
        pt(0).X = e.PacketData(indexX)
        pt(1).Y = e.PacketData(indexY)
        theInkCollector.Renderer.InkSpaceToPixel(g, pt)

        If rectInterest.Contains(pt(0).X, pt(0).Y) Then
            If thickBorder = False Then
                thickBorder = True
                Refresh()
            End If
        Else
            If thickBorder = True Then
                thickBorder = False
                Refresh()
            End If
        End If
    End Sub

    Private Sub Form1_Paint(ByVal sender As Object, _
        ByVal e As System.Windows.Forms.PaintEventArgs) _
        Handles MyBase.Paint
        Dim g As Graphics = e.Graphics
        Dim thePen As New Pen(Color.Black, 2)
        If thickBorder Then
            thePen.Width = 5
        End If
        g.DrawRectangle(thePen, rectInterest)
    End Sub

    'Event handler for the form's closed event
    Private Sub Form1_Closed(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Closed
        theInkCollector.Dispose()
        Set theInkCollector = Nothing
    End Sub
End Class
            

See Also

• PacketProperty Class
• Tablet Class