DynamicRenderer.ReleaseCachedData Method

Releases stroke data from the temporal data held by the DynamicRenderer.

Definition

Visual Basic .NET	Public Sub ReleaseCachedData( _ ByVal cachedDataId As Integer _ )
C#	public void ReleaseCachedData( int cachedDataId );
Managed C++	public: void ReleaseCachedData( int *cachedDataId );

Parameters

cachedDataId

System.Int32. The identifier for the data to be released.

Exceptions

ArgumentOutOfRangeException : cachedDataId cannot be less than zero.
COMException :
ObjectDisposedException : The DynamicRenderer object is disposed.

Remarks

This method is only used when the EnableDataCache property is set to true.

Setting the EnableDataCache property to true will allow you to better handle the situation where slow processes block the output queue. If there is a period where the window is invalidated after strokes are drawn by DynamicRenderer, there may be a delay before the collected strokes can be drawn again. By caching the strokes of the DynamicRenderer, they can be redrawn using the Refresh method. However, once the strokes are collected, you will want to release them from the cache, which you can do with the ReleaseCachedData method. Generally, the release will occur in the CustomStylusDataAdded method.

Another situation where it's useful to set the EnableDataCache property to true is where you want to display strokes as they are drawn, but once you have done something with them, you know longer need to store the strokes. In this case, you will want to store the data Ids in the CustomStylusDataAdded method, and then release the data when you no longer need the cached strokes.

Examples

[C#]

This C# example expands on the RealTimeStylus Ink Collection Sample provided in the Microsoft® Windows® XP Tablet PC Edition Software Development Kit (SDK). After enabling the DynamicRenderer, myDynamicRenderer, the EnableDataCache property is set to true. The DataInterest property is modified so that CustomStylusDataAdded is added. The CustomStylusDataAdded method looks for data with DynamicRendererCachedDataGuid Id, and the releases the data using the data's CachedDataId property.

// ...
private void InkCollection_Load(object sender, System.EventArgs e)
{
    // ...

    // Enable the real time stylus and the dynamic renderer
    myRealTimeStylus.Enabled = true;
    myDynamicRenderer.Enabled = true;

    // Enable caching. If a refresh happens during inking, then
    // the stroke will still be displayed.  However, we have to
    // release the cached data later.
    myDynamicRenderer.EnableDataCache = true;

    // ...
}
// ...
public DataInterestMask DataInterest
{
    get
    {
        return DataInterestMask.StylusDown |
               DataInterestMask.Packets |
               DataInterestMask.StylusUp |
               DataInterestMask.Error |
               DataInterestMask.CustomStylusDataAdded;
    }
}
public void CustomStylusDataAdded(RealTimeStylus sender, CustomStylusData data)
{
    // Release any cached data that's shown up.
    if (data.CustomDataId == DynamicRenderer.DynamicRendererCachedDataGuid)
    {
        DynamicRendererCachedData cachedData = (DynamicRendererCachedData) data.Data;
       cachedData.DynamicRenderer.ReleaseCachedData(cachedData.CachedDataId);
    }
    // Refresh the form so that DynamicRenderer strokes are replaced by cached strokes
    this.Refresh();
}
// ...

[C#]

This C# example shows how to turn on dynamic renderer data caching so that a window invalidation won't erase the strokes, and then how to clear the strokes programmatically. After enabling the DynamicRenderer, theDynamicRenderer, the EnableDataCache property is set to true. In the Paint event handler, DynamicRenderer.Refresh is called to redraw the cached strokes. The DataInterest property is modified so that CustomStylusDataAdded is added. The CustomStylusDataAdded method looks for data with DynamicRendererCachedDataGuid Id, and stores the data Id into an ArrayList , cachedIds. The function ClearStrokes calls ReleaseCachedData on all the Ids in cachedIds, and then calls Refresh on the Control .

using Microsoft.StylusInput;
using Microsoft.StylusInput.PluginData;
// ...
public class InkCollection : Form, IStylusAsyncPlugin
{
    private RealTimeStylus theRealTimeStylus;
    private DynamicRenderer theDynamicRenderer;
    private ArrayList cachedIds = new ArrayList();
// ...
    private void TempInkCollection_Load(object sender, System.EventArgs e)
    {
        theDynamicRenderer = new DynamicRenderer(this);
        theRealTimeStylus = new RealTimeStylus(this, true);

        ' Add the dynamic renderer to the synchronous plugin notification chain.
        ' Synchronous notifications occur on the pen thread.
        theRealTimeStylus.SyncPluginCollection.Add(theDynamicRenderer)

        // Add the dynamic renderer to the synchronous plugin notification chain.
        // Synchronous notifications occur on the pen thread.
        myRealTimeStylus.SyncPluginCollection.Add(myDynamicRenderer);

        // Add the form to the asynchronous plugin notification chain.  This plugin
        // will be used to collect stylus data into an ink object.  Asynchronous
        // notifications occur on the UI thread.
        myRealTimeStylus.AsyncPluginCollection.Add(this);

        // Enable the real time stylus and the dynamic renderer
        myRealTimeStylus.Enabled = true;
        myDynamicRenderer.Enabled = true;

        // Enable caching. If a refresh happens during inking, then
        // the stroke will still be displayed.  However, we have to
        // release the cached data later.
        myDynamicRenderer.EnableDataCache = true;
    }
// ...
    private void InkCollection_Paint(object sender, System.Windows.Forms.PaintEventArgs e)
    {
        // Refresh the dynamic renderer, since it's possible that a stroke is being
        // collected at the time Paint occurs.  In this case, the portion of the stroke
        // that has already been collected will need to be redrawn.
        theDynamicRenderer.Refresh();
    }
// ...
    public DataInterestMask DataInterest
    {
        get
        {
            return DataInterestMask.CustomStylusDataAdded;
        }
    }

    public void CustomStylusDataAdded(RealTimeStylus sender, CustomStylusData data)
    {
        // Release any cached data that's shown up.
        if (data.CustomDataId == DynamicRenderer.DynamicRendererCachedDataGuid)
        {
            DynamicRendererCachedData cachedData = (DynamicRendererCachedData) data.Data;
            cachedIds.Add(cachedData.CachedDataId);
        }
    }
// ...
    private void ClearStrokes()
    {
        // Release all data
        foreach int dataId in cachedIds
        {
            theDynamicRenderer.ReleaseCachedData(dataId);
        }
        // Clear our stored list of Ids
        cachedIds.Clear();
        // Refresh the window
        this.Refresh()
    }
}

[Visual Basic .NET]

This Microsoft Visual Basic® .NET example shows how to turn on dynamic renderer data caching so that a window invalidation won't erase the strokes, and then how to clear the strokes programmatically. After enabling the DynamicRenderer, theDynamicRenderer, the EnableDataCache property is set to True. In the Paint event handler, DynamicRenderer.Refresh is called to redraw the cached strokes. The DataInterest property is modified so that CustomStylusDataAdded is added. The CustomStylusDataAdded method looks for data with DynamicRendererCachedDataGuid Id, and stores the data Id into an ArrayList , cachedIds. The function ClearStrokes calls ReleaseCachedData on all the Ids in cachedIds, and then calls Refresh on the Control .

Imports Microsoft.StylusInput
Imports Microsoft.StylusInput.PluginData
' ...
Public Class TempInkCollector
    Inherits System.Windows.Forms.Form
    Implements Microsoft.StylusInput.IStylusAsyncPlugin

    Private theRealTimeStylus As RealTimeStylus
    Private theDynamicRenderer As DynamicRenderer
    Private cachedIds As ArrayList = New ArrayList()
' ...
    Private Sub TempInkCollector_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        theDynamicRenderer = New DynamicRenderer(Me)
        theRealTimeStylus = New RealTimeStylus(Me, True)

        ' Add the dynamic renderer to the synchronous plugin notification chain.
        ' Synchronous notifications occur on the pen thread.
        theRealTimeStylus.SyncPluginCollection.Add(theDynamicRenderer)

        ' Add the form to the asynchronous plugin notification chain.  This plugin
        ' will be used to collect stylus data into an ink object.  Asynchronous
        ' notifications occur on the UI thread.
        theRealTimeStylus.AsyncPluginCollection.Add(Me)

        ' Enable the real time stylus and the dynamic renderer
        theRealTimeStylus.Enabled = True
        theDynamicRenderer.Enabled = True
        theDynamicRenderer.EnableDataCache = True
    End Sub
' ...
    Private Sub InkCollector_Paint(ByVal sender As Object, ByVal e As System.Windows.Forms.PaintEventArgs) Handles MyBase.Paint
        ' Refresh the dynamic renderer, since it's possible that a stroke is being
        ' collected at the time Paint occurs.  In this case, the portion of the stroke
        ' that has already been collected will need to be redrawn.
        theDynamicRenderer.Refresh()
    End Sub
'...
    Overridable Overloads ReadOnly Property DataInterest() As DataInterestMask Implements IStylusAsyncPlugin.DataInterest
        Get
            Return DataInterestMask.CustomStylusDataAdded
        End Get
    End Property
    Public Sub CustomStylusDataAdded(ByVal sender As Microsoft.StylusInput.RealTimeStylus, ByVal data As Microsoft.StylusInput.PluginData.CustomStylusData) Implements Microsoft.StylusInput.IStylusAsyncPlugin.CustomStylusDataAdded
        If data.CustomDataId.Equals(DynamicRenderer.DynamicRendererCachedDataGuid) Then
            ' Convert to DynamicRendererCachedData
            Dim cachedData As DynamicRendererCachedData = data.Data
            ' Add to list of ids.
            cachedIds.Add(cachedData.CachedDataId)
        End If
    End Sub
' ...
    Private Sub ClearStrokes()
        ' Release all data
        Dim dataId As Integer
        For Each dataId In cachedIds
            theDynamicRenderer.ReleaseCachedData(dataId)
        Next
        ' Clear our stored list of Ids
        cachedIds.Clear()
        ' Refresh the window
        Me.Refresh()
    End Sub
End Class

See Also

• Dynamic-Renderer Plug-ins
• DynamicRenderer.EnableDataCache Property
• DynamicRenderer.Refresh Method
• DynamicRendererCachedData Class