DynamicRenderer.ReleaseCachedData Method
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
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
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
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