Share via


InkPicture.DesiredPacketDescription Property

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

Namespace:  Microsoft.Ink
Assembly:  Microsoft.Ink (in Microsoft.Ink.dll)

Syntax

'Declaration
<BrowsableAttribute(False)> _
Public Property DesiredPacketDescription As Guid()
'Usage
Dim instance As InkPicture 
Dim value As Guid()

value = instance.DesiredPacketDescription

instance.DesiredPacketDescription = value
[BrowsableAttribute(false)]
public Guid[] DesiredPacketDescription { get; set; }
[BrowsableAttribute(false)]
public:
property array<Guid>^ DesiredPacketDescription {
    array<Guid>^ get ();
    void set (array<Guid>^ value);
}
public function get DesiredPacketDescription () : Guid[]
public function set DesiredPacketDescription (value : Guid[])

Property Value

Type: array<System.Guid[]
The array of Guidobjects, each of which represents an aspect of the packets associated with ink drawn on the InkPicture object.

Remarks

The packet description is an array of Guidobjects 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 InkEnabled property changes from false to true.

Examples

The following example shows how you can use the DesiredPacketDescription property to express interest in specific Guid objects from the PacketProperty object, and then use the exposed packet properties during the NewPackets event.

First, the DesiredPacketDescription property is initialized, and the event handlers are assigned.

' Express interest in PacketStatus, TimerTick, and NormalPressure 
' X and Y will be added automatically 
Dim PacketDesc As Guid() = New Guid() _
    { _
        PacketProperty.PacketStatus, _
        PacketProperty.TimerTick, _
        PacketProperty.NormalPressure _
    }

' mInkObject can be InkCollector, InkOverlay, or InkPicture
mInkObject.DesiredPacketDescription = PacketDesc
' assign event handlers 
AddHandler mInkObject.CursorInRange, New InkCollectorCursorInRangeEventHandler(AddressOf mInkObject_CursorInRange)
AddHandler mInkObject.NewPackets, New InkCollectorNewPacketsEventHandler(AddressOf mInkObject_NewPackets)
// Express interest in PacketStatus, TimerTick, and NormalPressure 
// X and Y will be added automatically
Guid[] PacketDesc = new Guid[] 
{
    PacketProperty.PacketStatus,
    PacketProperty.TimerTick,
    PacketProperty.NormalPressure
};
// mInkObject can be InkCollector, InkOverlay, or InkPicture
mInkObject.DesiredPacketDescription = PacketDesc;
// assign event handlers
mInkObject.CursorInRange += new InkCollectorCursorInRangeEventHandler(mInkObject_CursorInRange);
mInkObject.NewPackets += new InkCollectorNewPacketsEventHandler(mInkObject_NewPackets);

When the CursorInRange event fires, a check is made to see if this is the first time that the InkPicture object has come in contact with this particular Cursor object. If so, the DrawingAttributes property is assigned with a clone of the DefaultDrawingAttributes property. This ensures that subsequent access to the DrawingAttributes property does not throw a null reference exception.

Private Sub mInkObject_CursorInRange(ByVal sender As Object, ByVal e As InkCollectorCursorInRangeEventArgs)
    Const MOUSE_CURSOR_ID As Integer = 1
    If e.NewCursor Then 
        ' mInkObject can be InkCollector, InkOverlay, or InkPicture
        e.Cursor.DrawingAttributes = mInkObject.DefaultDrawingAttributes.Clone()
        ' if this cursor is the mouse, we'll set color to red 
        If (MOUSE_CURSOR_ID = e.Cursor.Id) Then
            e.Cursor.DrawingAttributes.Color = Color.Red
        End If 

    End If 
End Sub
private void mInkObject_CursorInRange(object sender, InkCollectorCursorInRangeEventArgs e)
{
    const int MOUSE_CURSOR_ID = 1;

    if (e.NewCursor)
    {
        // mInkObject can be InkCollector, InkOverlay, or InkPicture
        e.Cursor.DrawingAttributes = mInkObject.DefaultDrawingAttributes.Clone();
        // if this cursor is the mouse, we'll set color to red 
        if (MOUSE_CURSOR_ID == e.Cursor.Id)
        {
            e.Cursor.DrawingAttributes.Color = Color.Red;
        }
    }
}

When the NewPackets event fires, a check is made to see if NormalPressure is included in the packet data. If so, pressure information is displayed on a status label, and the DrawingAttributes property is modified.

Private Sub mInkObject_NewPackets(ByVal sender As Object, ByVal e As InkCollectorNewPacketsEventArgs)

    ' find the NormalPressure PacketProperty 
    ' Set NormalPressure to -1 if not there, as some digitizers won't support it 
    Dim PacketDesc As Guid() = e.Stroke.PacketDescription
    Dim NormalPressure As Integer = -1

    For k As Integer = 0 To PacketDesc.Length - 1
        If PacketDesc(k) = PacketProperty.NormalPressure Then 
            ' for simplicity, in case of multiple packets, use the first packet only
            NormalPressure = e.PacketData(k)
        End If 
    Next k

    ' If we have the NormalPressure information 
    ' change DrawingAttributes according to the NormalPressure 
    ' Note that the change does not take effect until the next stroke 
    If NormalPressure <> -1 Then 
        ' display the pressure on a status label 
        Me.statusLabelPressure.Text = NormalPressure.ToString()
        e.Cursor.DrawingAttributes.Width = NormalPressure * 4
        ' if pressure is above 127, change color to Red 
        If NormalPressure > 127 Then
            e.Cursor.DrawingAttributes.Color = Color.Red
        Else
            e.Cursor.DrawingAttributes.Color = mInkObject.DefaultDrawingAttributes.Color
        End If 
    End If 

End Sub
private void mInkObject_NewPackets(object sender, InkCollectorNewPacketsEventArgs e)
{
    // find the NormalPressure PacketProperty 
    // Set NormalPressure to -1 if not there, as some digitizers won't support it
    Guid[] PacketDesc = e.Stroke.PacketDescription;
    int NormalPressure = -1;
    for (int k = 0; k < PacketDesc.Length; k++)
    {
        if (PacketDesc[k] == PacketProperty.NormalPressure)
        {
            // for simplicity, in case of multiple packets, use the first packet only
            NormalPressure = e.PacketData[k];
        }
    }

    // If we have the NormalPressure information 
    // change DrawingAttributes according to the NormalPressure 
    // Note that the change does not take effect until the next stroke 
    if (NormalPressure != -1)
    {
        // display the pressure on a status label 
        this.statusLabelPressure.Text = NormalPressure.ToString();
        e.Cursor.DrawingAttributes.Width = NormalPressure * 4;
        // if pressure is above 127, change color to Red 
        if (NormalPressure > 127)
        {
            e.Cursor.DrawingAttributes.Color = Color.Red;
        }
        else
        {
            e.Cursor.DrawingAttributes.Color = mInkObject.DefaultDrawingAttributes.Color;
        }
    }
}

Platforms

Windows 7, Windows Vista, Windows Server 2008 R2, Windows Server 2008

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.0

See Also

Reference

InkPicture Class

InkPicture Members

Microsoft.Ink Namespace

PacketProperty

Tablet