InkPresenter 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, IInkPresenter2, IInkPresenter3
struct winrt::Windows::UI::Input::Inking::InkPresenter : IInkPresenter, IInkPresenter2, IInkPresenter3
public sealed class InkPresenter : IInkPresenter, IInkPresenter2, IInkPresenter3
Public NotInheritable Class InkPresenter Implements IInkPresenter, IInkPresenter2, IInkPresenter3
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
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 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.

InputConfiguration InputConfiguration InputConfiguration InputConfiguration InputConfiguration

Gets which types of secondary input can be processed by the the InkPresenter object.

InputDeviceTypes 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.

InputProcessingConfiguration InputProcessingConfiguration InputProcessingConfiguration InputProcessingConfiguration InputProcessingConfiguration

Gets how input is processed by the InkPresenter object.

IsInputEnabled IsInputEnabled IsInputEnabled IsInputEnabled IsInputEnabled

Gets or sets whether input is enabled for inking.

StrokeContainer 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.

StrokeInput StrokeInput StrokeInput StrokeInput StrokeInput

Gets an InkStrokeInput object for managing ink input events.

UnprocessedInput 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.

Methods

ActivateCustomDrying() 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

InkCanvas

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.

CopyDefaultDrawingAttributes() 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.

SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration) SetPredefinedConfiguration(InkPresenterPredefinedConfiguration)

Sets the inking behavior of one or more contact points on the associated InkCanvas control.

UpdateDefaultDrawingAttributes(InkDrawingAttributes) 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.

Events

StrokesCollected 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.

StrokesErased 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.

See Also