Share via

Add Method [IInkExtendedProperties Interface]

  • Article

Add Method [IInkExtendedProperties Interface]

Creates and adds an IInkExtendedProperty object to the IInkExtendedProperties collection.

Declaration

[C++]

HRESULT Add (
    [in] BSTR Guid,
    [in] VARIANT data,
    [out, retval] IInkExtendedProperty** InkExtendedProperty
);

[Microsoft® Visual Basic® 6.0]

Public Function Add( _
    Guid As String, _
    data _
) As IInkExtendedProperty

Parameters

Guid

[in] Specifies the name of the new IInkExtendedProperty object. The name is expressed as a BSTR that represents the globally unique identifier (GUID) in the following format:

{dfc71f44-354b-4ca1-93d7-7459410b6343} (including curly braces)

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

data

[in] Specifies the data for the new IInkExtendedProperty object.

For more information about the VARIANT structure, see Using the Automation Library.

InkExtendedProperty

[out, retval] Returns the new extended property.

Return Value

HRESULT value Description
S_OK Success.
E_POINTER A parameter contained an invalid pointer.
E_INVALIDARG The user did not specify data.
CO_E_CLASSSTRING Invalid GUID format.
E_INK_EXCEPTION An exception occurred inside the method.
TPC_E_INVALID_STROKE The stroke is invalid.

Remarks

Note: You cannot store an empty IInkExtendedProperty object. The object must contain data before it can be stored. For example, if you try to add extended properties to a stroke for later use, an exception is thrown if the extended property contains no data.

The following types are acceptable:

  • Byte or CHAR array
  • Arrays of integers, floats, large integers, doubles, dates, or decimals
  • Booleans (but not arrays of Booleans)
  • BSTRs (but not arrays of BSTRs)
  • Arrays of Variants. All arrays of variants passed as an IInkExtendedProperty must be of the same type and be all numeric. For example, variant arrays of BSTRS, arrays of arrays, VT_NULL and VT_EMPTY are not supported.

Note: If you call this method with the Guid parameter set to a GUID that already exists in the IInkExtendedProperties collection, the new data will replace the existing extended property for that GUID instead of adding a second element.

Examples

[Visual Basic 6.0]

This Visual Basic 6.0 example demonstrates using the Stroke event handler of an InkCollector to store a custom property in each stroke that contains a timestamp, using the ExtendedProperties member. This sample application began with a simple form and added a command button and a list box, as well as a reference to the Tablet PC Type Library. Each stroke drawn on the form stores a timestamp in its extended properties and, when the button is pressed, the list box is filled with a list of the timestamps of the strokes.

Option Explicit
Dim WithEvents theInkCollector As InkCollector
Dim theTimeGuid

Private Sub Command1_Click()
    Call PopulateList
End Sub

Private Sub Form_Load()
'Add the InkCollector initialization.
    Set theInkCollector = New InkCollector
    theInkCollector.hWnd = Me.hWnd
    theInkCollector.Enabled = True
    ' This GUID constant will be used for the strokes'
    ' timestamp extended property.
    theTimeGuid = "{00000010-0011-0012-0010-000000000000}"
End Sub

Public Sub PopulateList()
    ' Clear the list before repopulating it.
    List1.Clear
    ' Query the InkCollector's Ink for its strokes collection.
    Dim theStrokes As InkStrokes
    Set theStrokes = theInkCollector.Ink.Strokes
    Dim theStroke As IInkStrokeDisp
    For Each theStroke In theStrokes
        ' If the timestamp property exists in this stroke:
        If _
        theStroke.ExtendedProperties.DoesPropertyExist(theTimeGuid) _
        Then
            Dim theTime As String
            ' Get the time data out of this stroke's extended
            ' properties list, using the previously defined
            ' Guid as a key to the required extended property.
            theTime = theStroke.ExtendedProperties(theTimeGuid).Data
            List1.AddItem (theTime)
        End If
    Next
End Sub

Private Sub theInkCollector_Stroke( _
ByVal Cursor As MSINKAUTLib.IInkCursor, _
ByVal Stroke As MSINKAUTLib.IInkStrokeDisp, _
Cancel As Boolean)
    Dim theExtendedProperty As IInkExtendedProperty
    ' Write the current time into each stroke when it is created
    ' using the Guid as a unique retrieval key.
    Set theExtendedProperty = Stroke.ExtendedProperties.Add(theTimeGuid, Now)
End Sub

Applies To