DynamicRenderer.EnableDataCache Property
Gets or sets a value that indicates whether data caching is enabled for the DynamicRenderer object.
Namespace: Microsoft.StylusInput
Assembly: Microsoft.Ink (in Microsoft.Ink.dll)
Syntax
'Declaration
Public Property EnableDataCache As Boolean
'Usage
Dim instance As DynamicRenderer
Dim value As Boolean
value = instance.EnableDataCache
instance.EnableDataCache = value
public bool EnableDataCache { get; set; }
public:
property bool EnableDataCache {
bool get ();
void set (bool value);
}
public function get EnableDataCache () : boolean
public function set EnableDataCache (value : boolean)
Property Value
Type: System.Boolean
true if data caching is enabled; otherwise, false.
Remarks
Setting the EnableDataCache property to true enables you to 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 the DynamicRenderer object, there may be a delay before the collected strokes can be drawn again. By placing the strokes of the DynamicRenderer in a cache, the strokes can be redrawn by calling the Refresh method. Once the strokes are collected, however, release them from the cache by calling the ReleaseCachedData method. Generally, the release occurs in the CustomStylusDataAdded method.
Another situation in which it is useful to set the EnableDataCache property to true is when 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, store the data identifiers in the data parameter of the CustomStylusDataAdded method, and then release the data when you no longer need the cached strokes.
If this property is true, you must call the ReleaseCachedData method for strokes which have been stored in the ink collecting object. If false, you need not call the ReleaseCachedData method. The disadvantage to setting this to false is that any stroke data that was initially dynamically rendered but invalidated by other miscellaneous operations does not render until the stroke data reaches the ink collection object and is rendered there.
Setting this property to false clears the cached data. Thus, an argument exception is raised when code calls the ReleaseCachedData method for any pending DynamicRendererCachedData object in the queue after setting the EnableDataCache property to false.
For more details about this property, see Dynamic-Renderer Plug-ins.
Examples
This C# example expands on the RealTimeStylus Ink Collection Sample provided in the Tablet and Touch Technology section of the Windows SDK. After enabling the DynamicRenderer, theDynamicRenderer, the EnableDataCache property is set to true. The DataInterest property is modified so that DataInterestMask is added. The CustomStylusDataAdded method looks for data with the DynamicRendererCachedDataGuid field's identifier, and then releases the data by 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);
}
}
// ...
This C# example places the data from a DynamicRenderer object in a cache. Doing so ensures that a window invalidation doe not erase the strokes. The example then clears the strokes programmatically. After enabling the DynamicRenderer object, theDynamicRenderer, the EnableDataCache property is set to true. In the Paint event handler, the example calls DynamicRenderer.Refresh to redraw the tablet pen data in the cache. The DataInterest property is modified so that DataInterestMask is added. The CustomStylusDataAdded method looks for data with the DynamicRendererCachedDataGuid field's identifier, and stores the data identifier into an ArrayList, cachedIds. The ClearStrokes method calls ReleaseCachedData on all the identifiers 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.ClipRectangle = e.ClipRectangle;
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()
}
}
This Microsoft Visual Basic .NET example places the data from a DynamicRenderer object in a cache. Doing so ensures that a window invalidation doe not erase the strokes. The example then clears the strokes programmatically. After enabling the DynamicRenderer object, theDynamicRenderer, the EnableDataCache property is set to true. In the Paint event handler, the example calls DynamicRenderer.Refresh to redraw the tablet pen data in the cache. The DataInterest property is modified so that DataInterestMask is added. The CustomStylusDataAdded method looks for data with the DynamicRendererCachedDataGuid field's identifier, and stores the data identifier into an ArrayList, cachedIds. The ClearStrokes method calls ReleaseCachedData on all the identifiers 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.ClipRectangle = e.ClipRectangle
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
Platforms
Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Version Information
.NET Framework
Supported in: 3.0
See Also
Reference
Microsoft.StylusInput Namespace
DynamicRenderer.ReleaseCachedData