DesiredPacketDescription Property
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