Compartilhar via


RealTimeStylus.SetDesiredPacketDescription Method

RealTimeStylus.SetDesiredPacketDescription Method

Sets the RealTimeStylus object's interest in aspects of the packets collected on a tablet context.

Definition

Visual Basic .NET Public Sub SetDesiredPacketDescription( _
ByVal value() As Guid _
)
C# public void SetDesiredPacketDescription(
Guid[] value
);
Managed C++ public: void SetDesiredPacketDescription(
Guid *value __gc[]
);

Parameters

value System.Guid[]. The globally unique identifiers (GUIDs) for the packet properties in which the RealTimeStylus object is interested.

Exceptions

ArgumentNullException Leave Site: The value parameter is null.
ArgumentOutOfRangeException Leave Site: The value parameter is an empty array.
COMException Leave Site:
Exception Leave Site: Raises exception when the property is changed while the pen is down and collecting ink.
ObjectDisposedException Leave Site: The RealTimeStylus object is disposed.

Remarks

Use this method to set the RealTimeStylus object's interest in a set of packet properties. The packet properties are represented by an array of globally unique identifiers (GUIDs). The PacketProperty object defines standard packet property GUIDs; however, other GUIDs may also be used.

When the RealTimeStylus object is collecting ink from a tablet, the RealTimeStylus object only returns packet data for the packet properties that you have set interest in, as represented by the return value of the GetDesiredPacketDescription method, and that are supported by the tablet on which the ink is being collected.

Calls to the SetDesiredPacketDescription method do not affect incoming packet data until the Enabled property changes from false to true. However, calls to the SetDesiredPacketDescription method immediately affect what is returned by calls to the GetDesiredPacketDescription method.

The following list describes how the RealTimeStylus object orders the packet property GUIDs.

For example, if you call the SetDesiredPacketDescription method with (a, b, a, PacketStatus, b, c, d), a call to the GetDesiredPacketDescription method returns (X, Y, a, b, c, d, PacketStatus).

Examples

This Microsoft® Visual C#® .NET example is a snippet from a menu item's Click Leave Site event handler. The menu is part of a form on which a TextBox Leave Site object, theTextBox, is defined. If the RealTimeStylus object is enabled or if none of the packet property GUIDs are checked on the form, the event handler exits. Otherwise, the event handler calls the RealTimeStylus object's SetDesiredPacketDescription method.

[C#]using Microsoft.Ink;
using Microsoft.StylusInput;
using Microsoft.StylusInput.PluginData;

// ...

// Declare the RealTimeStylus objects, the GestureRecognizer plugin,
// and the DynamicRenderer plug-in.
private Microsoft.StylusInput.RealTimeStylus thePrimaryRealTimeStylus = null;
private Microsoft.StylusInput.RealTimeStylus theSecondaryRealTimeStylus = null;
private Microsoft.StylusInput.GestureRecognizer theGestureRecognizer = null;
private Microsoft.StylusInput.DynamicRenderer theDynamicRenderer = null;

// ...

// The SetDesiredPacketDescription menu item's Click event handler
private void theMenuItemSetDesiredPacketDescription_Click(object sender,
    System.EventArgs e)
{
    // Can not call this method while the RealTimeStylus is enabled.
    if (this.thePrimaryRealTimeStylus.Enabled)
    {
        MessageBox.Show("The SetDesiredPacketDescription method of the RealTimeStylus can only be called while the RealTimeStylus is disabled.");
        return;
    }

    // Create an array of GUIDs from the checked packet properties.
    ArrayList result = new ArrayList();

    // ...

    // Can not pass an empty array to the SetDesiredPacketDescription method.
    if (0 == result.Count)
    {
        this.theTextBox.Text = "No PacketProperty GUID's checked. The desired packet property's of the RealTimeStylus have not been changed.";
        return;
    }

    // Set the desired packet properties.
    Guid[] theGuids = (Guid[])result.ToArray(typeof(Guid));
    this.thePrimaryRealTimeStylus.SetDesiredPacketDescription(theGuids);
    this.theTextBox.Text = "The desired packet property's of the RealTimeStylus have been changed.";
}

See Also