InkPresenter
InkPresenter
InkPresenter
InkPresenter
Class
Definition
Note
For Universal Windows app using Extensible Application Markup Language (XAML), we recommend using InkPresenter and the InkCanvas control instead of InkManager.
Provides properties, methods, and events for managing the input, processing, and rendering of ink input (standard and modified) for an InkCanvas control.
Note
Standard ink input (pen tip or eraser tip/button) is not modified with a secondary affordance, such as a pen barrel button, right mouse button, or similar (see RightDragAction ).
By default, both standard and modified ink input is managed entirely by the InkPresenter and rendered to the InkCanvas as either an ink stroke or an erase stroke, based on InkInputProcessingConfiguration.Mode.
Modified input can be passed through to your app for processing by setting InkInputProcessingConfiguration.RightDragAction to InkInputRightDragAction.LeaveUnprocessed.
All input can be passed through to your app for processing by setting InkInputProcessingConfiguration.Mode to None.
Leaving input unprocessed by the InkPresenter lets you support a customized ink experience and extended functionality such as selection.
For complete control of ink input and to render it to the Direct2D device context of your Universal Windows app, instead of the default InkCanvas control, call ActivateCustomDrying prior to loading the InkCanvas. This requires an IInkD2DRenderer object to manage the ink input (see the Complex ink sample).
public : sealed class InkPresenter : IInkPresenter, IInkPresenter2public sealed class InkPresenter : IInkPresenter, IInkPresenter2Public NotInheritable Class InkPresenter Implements IInkPresenter, IInkPresenter2// This API is not available in Javascript.
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Examples
Here, we show how to overlay ink annotations on an image. For this example, ink data is not captured or saved by a corresponding InkPresenter.
<ScrollViewer>
<Grid>
<Image Source="<path>"></Image>
<InkCanvas x:Name="MyInkCanvas"></InkCanvas>
</Grid>
</ScrollView
Here, we configure the InkPresenter to interpret input data from both pen and mouse as ink strokes. We also set some initial ink stroke attributes used for rendering strokes to the InkCanvas.
public MainPage()
{
this.InitializeComponent();
// Set supported inking device types.
inkCanvas.InkPresenter.InputDeviceTypes =
Windows.UI.Core.CoreInputDeviceTypes.Mouse |
Windows.UI.Core.CoreInputDeviceTypes.Pen;
// Set initial ink stroke attributes.
InkDrawingAttributes drawingAttributes = new InkDrawingAttributes();
drawingAttributes.Color = Windows.UI.Colors.Black;
drawingAttributes.IgnorePressure = false;
drawingAttributes.FitToCurve = true;
inkCanvas.InkPresenter.UpdateDefaultDrawingAttributes(drawingAttributes);
}
Ink stroke attributes can be set dynamically to accommodate user preferences or app requirements.
Here, we let a user choose from a list of ink colors.
<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
<Grid.RowDefinitions>
<RowDefinition Height="Auto"/>
<RowDefinition Height="*"/>
</Grid.RowDefinitions>
<StackPanel x:Name="HeaderPanel" Orientation="Horizontal" Grid.Row="0">
<TextBlock x:Name="Header"
Text="Basic ink customization sample"
VerticalAlignment="Center"
Style="{ThemeResource HeaderTextBlockStyle}"
Margin="10,0,0,0" />
<TextBlock Text="Color:"
Style="{StaticResource SubheaderTextBlockStyle}"
VerticalAlignment="Center"
Margin="50,0,10,0"/>
<ComboBox x:Name="PenColor"
VerticalAlignment="Center"
SelectedIndex="0"
SelectionChanged="OnPenColorChanged">
<ComboBoxItem Content="Black"/>
<ComboBoxItem Content="Red"/>
</ComboBox>
</StackPanel>
<Grid Grid.Row="1">
<Image Source="Assets\StoreLogo.png" />
<InkCanvas x:Name="inkCanvas" />
</Grid>
</Grid>
We then handle changes to the selected color and update the ink stroke attributes accordingly.
// Update ink stroke color for new strokes.
private void OnPenColorChanged(object sender, SelectionChangedEventArgs e)
{
if (inkCanvas != null)
{
InkDrawingAttributes drawingAttributes =
inkCanvas.InkPresenter.CopyDefaultDrawingAttributes();
string value = ((ComboBoxItem)PenColor.SelectedItem).Content.ToString();
switch (value)
{
case "Black":
drawingAttributes.Color = Windows.UI.Colors.Black;
break;
case "Red":
drawingAttributes.Color = Windows.UI.Colors.Red;
break;
default:
drawingAttributes.Color = Windows.UI.Colors.Black;
break;
};
inkCanvas.InkPresenter.UpdateDefaultDrawingAttributes(drawingAttributes);
}
}
Remarks
The InkPresenter class cannot be instantiated directly. It is returned as a property of an InkCanvas object.
Properties
HighContrastAdjustment HighContrastAdjustment HighContrastAdjustment HighContrastAdjustment
Gets or sets how the InkPresenter object handles input (standard and modified) from the associated InkCanvas control when system is in high contrast mode.
public : InkHighContrastAdjustment HighContrastAdjustment { get; set; }public InkHighContrastAdjustment HighContrastAdjustment { get; set; }Public ReadWrite Property HighContrastAdjustment As InkHighContrastAdjustment// This API is not available in Javascript.
- Value
- InkHighContrastAdjustment InkHighContrastAdjustment InkHighContrastAdjustment InkHighContrastAdjustment
The ink color (selected or system) that works best against the background color.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
InputDeviceTypes InputDeviceTypes InputDeviceTypes InputDeviceTypes
Gets or sets the input device type from which input data is collected by the InkPresenter to construct and render an InkStroke. The default is Pen.
public : CoreInputDeviceTypes InputDeviceTypes { get; set; }public CoreInputDeviceTypes InputDeviceTypes { get; set; }Public ReadWrite Property InputDeviceTypes As CoreInputDeviceTypes// This API is not available in Javascript.
The input device types.
Examples
Here we specify that data from all supported input devices (CoreInputDeviceTypes ) be collected by the InkPresenter and processed as ink input.
inkCanvas.InkPresenter.InputDeviceTypes =
Windows.UI.Core.CoreInputDeviceTypes.Mouse |
Windows.UI.Core.CoreInputDeviceTypes.Pen |
Windows.UI.Core.CoreInputDeviceTypes.Touch;
Remarks
If you set this property to None, you should remove listeners for all pointer events, including PointerEntered, PointerHovered, and PointerExited. In this case, pointer events are passed to the InkCanvas object and not to the InkPresenter object through InkPresenter.UnprocessedInput.
- See Also
InputProcessingConfiguration InputProcessingConfiguration InputProcessingConfiguration InputProcessingConfiguration
Gets the input behavior (standard or modified) of the InkPresenter object.
Standard ink input is not modified with a secondary affordance, such as a pen barrel button, right mouse button, or similar.
public : InkInputProcessingConfiguration InputProcessingConfiguration { get; }public InkInputProcessingConfiguration InputProcessingConfiguration { get; }Public ReadOnly Property InputProcessingConfiguration As InkInputProcessingConfiguration// This API is not available in Javascript.
- Value
- InkInputProcessingConfiguration InkInputProcessingConfiguration InkInputProcessingConfiguration InkInputProcessingConfiguration
The input behavior.
- See Also
IsInputEnabled IsInputEnabled IsInputEnabled IsInputEnabled
Gets or sets whether input is enabled for inking.
public : PlatForm::Boolean IsInputEnabled { get; set; }public bool IsInputEnabled { get; set; }Public ReadWrite Property IsInputEnabled As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean bool bool bool
true if input is enabled for inking. Otherwise, false.
- See Also
StrokeContainer StrokeContainer StrokeContainer StrokeContainer
Gets or sets an InkStrokeContainer object to store and manage the collection of InkStroke objects rendered by the InkPresenter.
Modifications made to any of the ink strokes in the stroke container are immediately rendered to the drawing surface associated with the InkPresenter.
public : InkStrokeContainer StrokeContainer { get; set; }public InkStrokeContainer StrokeContainer { get; set; }Public ReadWrite Property StrokeContainer As InkStrokeContainer// This API is not available in Javascript.
Stores and manages one or more InkStroke objects.
If custom dry mode is enabled (ActivateCustomDrying ), StrokeContainer is null.
Remarks
The StrokesCollected event is fired when ink strokes are processed ("wet" to "dry") on the UI thread.
For ink recognition, use an InkRecognizerContainer object.
- See Also
StrokeInput StrokeInput StrokeInput StrokeInput
Gets an InkStrokeInput object for managing ink input events.
public : InkStrokeInput StrokeInput { get; }public InkStrokeInput StrokeInput { get; }Public ReadOnly Property StrokeInput As InkStrokeInput// This API is not available in Javascript.
The ink input.
Examples
Here, we declare a StrokeStarted listener.
inkCanvas.InkPresenter.StrokeInput.StrokeStarted += StrokeInput_StrokeStarted;
We then define the corresponding handler, which clears any selected strokes when a new ink stroke is started.
private void StrokeInput_StrokeStarted(InkStrokeInput sender, Windows.UI.Core.PointerEventArgs args)
{
var strokes = inkCanvas.InkPresenter.StrokeContainer.GetStrokes();
foreach (var stroke in strokes)
{
stroke.Selected = false;
}
ClearDrawnBoundingRect();
}
- See Also
UnprocessedInput UnprocessedInput UnprocessedInput UnprocessedInput
Gets input (standard or modified) from the associated InkCanvas control and passes the data through for custom processing by the app. The data is not processed by the InkPresenter.
Note
Standard input is not modified with a secondary affordance, such as a pen barrel button, right mouse button, or similar.
Use InkInputProcessingConfiguration to indicate the input to be passed as InkUnprocessedInput through to your app for custom processing.
public : InkUnprocessedInput UnprocessedInput { get; }public InkUnprocessedInput UnprocessedInput { get; }Public ReadOnly Property UnprocessedInput As InkUnprocessedInput// This API is not available in Javascript.
The input from the InkCanvas control.
- See Also
Methods
ActivateCustomDrying() ActivateCustomDrying() ActivateCustomDrying() ActivateCustomDrying()
Indicates that your app requires complete control of ink input rendering.
By default, ink input is processed on a low-latency background thread and rendered "wet" as it is drawn. When the stroke is completed (pen or finger lifted, or mouse button released), the stroke is processed on the UI thread and rendered "dry" to the rendering layer (above the application content and replacing the wet ink).
InkPresenter hosting models
By calling ActivateCustomDrying (before the InkCanvas is loaded), an app creates an InkSynchronizer object to customize how an ink stroke is rendered dry to a SurfaceImageSource or VirtualSurfaceImageSource. For example, an ink stroke could be rasterized and integrated into application content instead of as a separate InkCanvas layer.
InkDesktopHost (Windows 10 version 1511 and newer)
Win32 apps can host an InkPresenter in an InkDesktopHost using the DirectComposition visual tree.
This requires an IInkD2DRenderer object to manage the ink input (see the Complex ink sample).
CoreInkPresenterHost (Windows 10 Fall Creators Update and newer)
Host an InkPresenter in your own Windows.UI.Composition tree without an associated InkCanvas control.
public : InkSynchronizer ActivateCustomDrying()public InkSynchronizer ActivateCustomDrying()Public Function ActivateCustomDrying() As InkSynchronizer// This API is not available in Javascript.
The object used for custom ink stroke rendering.
Remarks
Error codes
E_ILLEGAL_METHOD_CALL (0x8000000E)
Thrown if ActivateCustomDrying is called after InkCanvas is loaded.
This method must be called prior to loading the InkCanvas.
Custom drying and the InkToolbar
By default, ink input is processed on a low-latency background thread and rendered "wet" as it is drawn. When the stroke is completed (pen or finger lifted, or mouse button released), the stroke is processed on the UI thread and rendered "dry" to the InkCanvas layer (above the application content and replacing the wet ink). The ink platform enables you to override this behavior and completely customize the inking experience by custom drying the ink input.
If your app overrides the default ink rendering behavior of the InkPresenter with a custom drying implementation, the rendered ink strokes are no longer available to the InkToolbar and the built-in erase commands of the InkToolbar do not work as expected. To provide erase functionality, you must handle all pointer events, perform hit-testing on each stroke, and override the built-in "Erase all ink" command.
For more info on custom drying, see Pen interactions and Windows Ink in UWP apps.
- See Also
CopyDefaultDrawingAttributes() CopyDefaultDrawingAttributes() CopyDefaultDrawingAttributes() CopyDefaultDrawingAttributes()
Retrieves the InkDrawingAttributes used by the InkPresenter when rendering a new InkStroke on an InkCanvas control.
This method is used in conjunction with UpdateDefaultDrawingAttributes to set drawing attributes at run time.
public : InkDrawingAttributes CopyDefaultDrawingAttributes()public InkDrawingAttributes CopyDefaultDrawingAttributes()Public Function CopyDefaultDrawingAttributes() As InkDrawingAttributes// This API is not available in Javascript.
The drawing attributes applied to a new ink stroke.
Remarks
This method does not return the attributes of existing, or currently drawing, ink strokes.
- See Also
SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration)
Sets the inking behavior of one or more contact points on the associated InkCanvas control.
public : void SetPredefinedConfiguration(InkPresenterPredefinedConfiguration value)public void SetPredefinedConfiguration(InkPresenterPredefinedConfiguration value)Public Function SetPredefinedConfiguration(value As InkPresenterPredefinedConfiguration) As void// This API is not available in Javascript.
- value
- InkPresenterPredefinedConfiguration InkPresenterPredefinedConfiguration InkPresenterPredefinedConfiguration InkPresenterPredefinedConfiguration
The inking behavior of one or more contact points. The default is SimpleSinglePointer.
SimpleSinglePointer specifies that single pointer inking is supported.
SimpleMultiplePointer specifies that multi-pointer inking is supported.
Note
Multi-pointer inking requires ink input to be processed in custom drying mode. ActivateCustomDrying must be called before setting SetPredefinedConfiguration to SimpleMultiplePointer.
Remarks
Error codes
E_ILLEGAL_METHOD_CALL (0x8000000E)
Thrown if multi-pointer inking is enabled through SetPredefinedConfiguration before ActivateCustomDrying is called.
E_INVALIDARG (0x80070057)
An invalid parameter was specified.
- See Also
UpdateDefaultDrawingAttributes(InkDrawingAttributes) UpdateDefaultDrawingAttributes(InkDrawingAttributes) UpdateDefaultDrawingAttributes(InkDrawingAttributes) UpdateDefaultDrawingAttributes(InkDrawingAttributes)
Sets the InkDrawingAttributes used by the InkPresenter when rendering a new InkStroke on an InkCanvas control.
This method is used in conjunction with CopyDefaultDrawingAttributes to set drawing attributes at run time.
public : void UpdateDefaultDrawingAttributes(InkDrawingAttributes value)public void UpdateDefaultDrawingAttributes(InkDrawingAttributes value)Public Function UpdateDefaultDrawingAttributes(value As InkDrawingAttributes) As void// This API is not available in Javascript.
The drawing attributes for new ink strokes.
Remarks
This method does not return the attributes of existing, or currently drawing, ink strokes.
- See Also
Events
StrokesCollected StrokesCollected StrokesCollected StrokesCollected
Occurs when one or more ink strokes are processed ("wet" to "dry") by the application thread.
By default, an ink stroke is processed on a low-latency background thread and rendered wet as it is drawn. When the stroke is completed (pen or finger lifted, or mouse button released), the stroke is processed on the UI thread and rendered dry to the InkCanvas layer (above the application content). If the UI thread is busy, more than one ink stroke might be processed (collected) when the thread becomes available.
public : event TypedEventHandler StrokesCollected<InkPresenter, InkStrokesCollectedEventArgs>public event TypedEventHandler StrokesCollected<InkPresenter, InkStrokesCollectedEventArgs>Public Event StrokesCollected<InkPresenter, InkStrokesCollectedEventArgs>// This API is not available in Javascript.
- See Also
StrokesErased StrokesErased StrokesErased StrokesErased
Occurs when an InkStroke object is removed from an InkCanvas control using the pen eraser or the pen tip when Mode is set to Erasing.
public : event TypedEventHandler StrokesErased<InkPresenter, InkStrokesErasedEventArgs>public event TypedEventHandler StrokesErased<InkPresenter, InkStrokesErasedEventArgs>Public Event StrokesErased<InkPresenter, InkStrokesErasedEventArgs>// This API is not available in Javascript.
Remarks
InkStrokeContainer.DeleteSelected does not cause this event to fire.
This event is not raised in custom dry mode (ActivateCustomDrying ).
Custom drying and the InkToolbar By default, ink input is processed on a low-latency background thread and rendered "wet" as it is drawn. When the stroke is completed (pen or finger lifted, or mouse button released), the stroke is processed on the UI thread and rendered "dry" to the InkCanvas layer (above the application content and replacing the wet ink). The ink platform enables you to override this behavior and completely customize the inking experience by custom drying the ink input.
If your app overrides the default ink rendering behavior of the InkPresenter with a custom drying implementation, the rendered ink strokes are no longer available to the InkToolbar and the built-in erase commands of the InkToolbar do not work as expected. To provide erase functionality, you must handle all pointer events, perform hit-testing on each stroke, and override the built-in "Erase all ink" command.
For more info on custom drying, see Pen interactions and Windows Ink in UWP apps.
- See Also