RealTimeStylus.SetDesiredPacketDescription Method
Sets the RealTimeStylus object's interest in aspects of the packet collected on a tablet context.
Namespace: Microsoft.StylusInput
Assembly: Microsoft.Ink (in Microsoft.Ink.dll)
Syntax
'Declaration
Public Sub SetDesiredPacketDescription ( _
value As Guid() _
)
'Usage
Dim instance As RealTimeStylus
Dim value As Guid()
instance.SetDesiredPacketDescription(value)
public void SetDesiredPacketDescription(
Guid[] value
)
public:
void SetDesiredPacketDescription(
array<Guid>^ value
)
public function SetDesiredPacketDescription(
value : Guid[]
)
Parameters
value
Type: array<System.Guid[]The globally unique identifiers (GUIDs) for the packet properties in which the RealTimeStylus object has interest.
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 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 object, 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. For more information about how to collect ink by using the RealTimeStylus object, see Accessing and Manipulating Stylus Input.
The SetDesiredPacketDescription method can only be called while the RealTimeStylus object is disabled. However, calls to the SetDesiredPacketDescription method are immediately reflected in the return value of the GetDesiredPacketDescription method.
The following list describes how the RealTimeStylus object orders the packet property GUIDs.
The PacketProperty.X and PacketProperty.Y GUIDs are always returned in the first two positions in the array by the GetDesiredPacketDescription method, whether or not they were specified in a previous call to the SetDesiredPacketDescription method.
If the PacketProperty.PacketStatus GUID is specified in the call to the SetDesiredPacketDescription method, the PacketProperty.PacketStatus GUID is always returned in the last position in the array by the GetDesiredPacketDescription method.
If any GUIDs are specified more than once in the call to the SetDesiredPacketDescription method, each GUID occurs only once in the array returned by the GetDesiredPacketDescription method.
By default, the GetDesiredPacketDescription method returns the PacketProperty.X, PacketProperty.Y, and PacketProperty.NormalPressure 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).
This method throws an exception under the following conditions.
The RealTimeStylus object is disposed.
The RealTimeStylus object was created with the RealTimeStylus() constructor.
The RealTimeStylus object is enabled.
The value parameter is nulla null reference (Nothing in Visual Basic) (Nothing in Visual Basic .NET) or contains an empty array.
Examples
This Microsoft Visual C# .NET example is a snippet from a menu item's Click event handler. The menu is part of a form on which a TextBox 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.
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.";
}
Platforms
Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003
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