DesiredPacketDescription Property

  • Article

DesiredPacketDescription Property

Returns or sets the desired packet description of the InkCollector.

Declaration

[C++]

[propput] HRESULT put_DesiredPacketDescription ([in] BSTR*
    DesiredPacketDescription);
[propget] HRESULT get_DesiredPacketDescription ([out, retval]
    BSTR** DesiredPacketDescription);

[Microsoft® Visual Basic® 6.0]

Public Property Get DesiredPacketDescription As Variant
Public Property Let DesiredPacketDescription( _
    ByVal theDescription As Variant)

Property Value

BSTR Returns or sets an array of PacketProperty objects that specify the properties of the packets that the InkCollector collects. The default value is {X, Y, NormalPressure}

This property is read/write.

For more information about the BSTR data type, see Using the Automation Library.

Return Value

HRESULT value Description
S_OK Success.
E_FAIL An unspecified error occurred.
E_OUTOFMEMORY Cannot allocate the memory necessary to complete this operation.
E_INK_EXCEPTION An exception occurred inside the method.
E_INVALIDARG The parameter must be an array of BSTRs.

Remarks

The description is an array of globally unique identifiers (GUIDs) from the PacketProperty object.

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

By default, DesiredPacketDescription contains STR_GUID_X, STR_GUID_Y, and STR_GUID_NORMALPRESSURE from the PacketProperty object. If you set DesiredPacketDescription to anything else, STR_GUID_BUTTONPRESSURE only for example, STR_GUID_X and STR_GUID_Y is also added—a get of DesiredPacketDescription returns {X,Y,ButtonPressure} and not {ButtonPressure}.

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

In Visual Basic 6.0, if you try to access the DesiredPacketDescriptionGUID array data using the IDispatch interface, run-time error 451 occurs. This error occurs because Visual Basic 6.0 treats the "(0)" in "theInkCollector.DesiredPacketDescription(0)" as a parameter being passed to DesiredPacketDescription rather than as an index into the DesiredPacketDescription array. To avoid this error, assign the array to a temporary variable that is dimensioned as an array of GUIDs and then index the variable, or declare the InkCollector object directly with a Dim x As InkCollector statement instead of through the IDispatch interface using a call to CreateObject.

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

Example

[Visual Basic 6.0]

This Visual Basic 6.0 example function finds the offset of a particular packet description item within the data array.

'Return the index of the description represented
'by theGuid in the packet data array, or -1 if it is
'not present.
Private Function GetDescriptionIndex( _
ByVal theInkCollector As InkCollector, _
ByVal theGuid As String) As Long
    Dim theGuids() As String
    theGuids = theInkCollector.DesiredPacketDescription
    Dim i As Integer
    GetDescriptionIndex = -1
    For i = 0 To UBound(theGuids)
        If theGuids(i) = theGuid Then
            GetDescriptionIndex = i
        End If
    Next
End Function

Applies To