InkToolbar InkToolbar InkToolbar Class

Definition

Represents a Universal Windows app control containing a customizable and extensible collection of buttons that activate ink-related features in an associated InkCanvas.

By default, the toolbar includes buttons for drawing, erasing, highlighting, and displaying a ruler. Depending on the feature, other settings and commands, such as ink color, stroke thickness, erase all, are provided in a flyout. An "extension glyph" is displayed on the button to indicate the existence of the flyout.

The InkToolbar consists of two distinct groups of button types:

Feature selection is mutually exclusive.

Features are not mutually exclusive and can be used concurrently with other active tools. Built-in buttons can be displayed by default, or you can specify which should be displayed by your app. See InitialControls.

You cannot change the display order of the built-in buttons. The default display order is: InkToolbarBallpointPenButton, InkToolbarPencilButton, InkToolbarHighlighterButton, InkToolbarEraserButton, and InkToolbarRulerButton. Custom tool buttons are added between the highlighter button and the eraser button and custom toggle buttons are added after the ruler button. (Custom buttons are added in the order they are specified.)

public class InkToolbar : Control, IInkToolbar, IInkToolbar2public class InkToolbar : Control, IInkToolbar, IInkToolbar2Public Class InkToolbar Inherits Control Implements IInkToolbar, IInkToolbar2
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Inherited Members

Inherited properties

Inherited events

Inherited methods

Remarks

Associate an InkToolbar with an InkCanvas control through the TargetInkCanvas property.

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.

Examples

Here, we show a typical InkToolbar declaration and binding to an InkCanvas.

<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 sample" 
                   Style="{ThemeResource HeaderTextBlockStyle}" 
                   Margin="10,0,0,0" />
    </StackPanel>
    <Grid Grid.Row="1">
        <Image Source="Assets\StoreLogo.png" />
        <InkCanvas x:Name="inkCanvas" />
        <InkToolbar x:Name="inkToolbar" VerticalAlignment="Top" TargetInkCanvas="{x:Bind inkCanvas}" />
    </Grid>
</Grid>

Constructors

InkToolbar() InkToolbar() InkToolbar()

Initializes a new instance of the InkToolbar class.

public InkToolbar()public InkToolbar()Public Sub New()
Attributes

Properties

ActiveTool ActiveTool ActiveTool

Gets or sets the currently selected feature in the "tools" group of the InkToolbar (see remarks). This property provides access to the following objects:

Features in this group are mutually exclusive: selecting a feature deselects the currently active feature.

Note

InkToolbarRulerButton and InkToolbarCustomToggleButton objects work in conjunction with the active feature and are not exposed to the ActiveTool property.

public InkToolbarToolButton ActiveTool { get; set; }public InkToolbarToolButton ActiveTool { get; set; }Public ReadWrite Property ActiveTool As InkToolbarToolButton
Value
InkToolbarToolButton InkToolbarToolButton InkToolbarToolButton

The currently selected feature. By default, this is the first button on the InkToolbar.

Attributes

Remarks

The InkToolbar consists of two distinct groups of button types:

Feature selection is mutually exclusive.

Features are not mutually exclusive and can be used concurrently with other active tools.

ActiveToolProperty ActiveToolProperty ActiveToolProperty

Identifies the ActiveTool dependency property.

public static DependencyProperty ActiveToolProperty { get; }public static DependencyProperty ActiveToolProperty { get; }Public Static ReadOnly Property ActiveToolProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the ActiveTool dependency property.

Attributes

ButtonFlyoutPlacement ButtonFlyoutPlacement ButtonFlyoutPlacement

Gets or sets the location of ink stroke configuration flyout relative to the InkToolbar.

public InkToolbarButtonFlyoutPlacement ButtonFlyoutPlacement { get; set; }public InkToolbarButtonFlyoutPlacement ButtonFlyoutPlacement { get; set; }Public ReadWrite Property ButtonFlyoutPlacement As InkToolbarButtonFlyoutPlacement
Value
InkToolbarButtonFlyoutPlacement InkToolbarButtonFlyoutPlacement InkToolbarButtonFlyoutPlacement

The location of the flyout relative to the ink toolbar.

Attributes

ButtonFlyoutPlacementProperty ButtonFlyoutPlacementProperty ButtonFlyoutPlacementProperty

Identifies the ButtonFlyoutPlacement dependency property.

public static DependencyProperty ButtonFlyoutPlacementProperty { get; }public static DependencyProperty ButtonFlyoutPlacementProperty { get; }Public Static ReadOnly Property ButtonFlyoutPlacementProperty As DependencyProperty
Attributes

Children Children Children

Gets the collection of custom buttons displayed on the InkToolbar.

public DependencyObjectCollection Children { get; }public DependencyObjectCollection Children { get; }Public ReadOnly Property Children As DependencyObjectCollection
Attributes

Remarks

Children returns only the number of buttons on the InkToolbar that have been added manually (see ActiveTool and InitialControls ). The default InkToolbar does not add any buttons to the value of this property.

Children does not include buttons declared in markup.

The InkToolbar consists of two distinct groups of button types:

Feature selection is mutually exclusive.

Features are not mutually exclusive and can be used concurrently with other active tools.

ChildrenProperty ChildrenProperty ChildrenProperty

Identifies the Children dependency property.

public static DependencyProperty ChildrenProperty { get; }public static DependencyProperty ChildrenProperty { get; }Public Static ReadOnly Property ChildrenProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Children dependency property.

Attributes

InitialControls InitialControls InitialControls

Gets or sets the collection of built-in buttons added to the InkToolbar at initialization.

This property overrides the default collection of built-in buttons.

By default, the InkToolbar consists of two distinct groups of button types:

Feature selection is mutually exclusive.

Features are not mutually exclusive and can be used concurrently with other active tools.

public InkToolbarInitialControls InitialControls { get; set; }public InkToolbarInitialControls InitialControls { get; set; }Public ReadWrite Property InitialControls As InkToolbarInitialControls
Value
InkToolbarInitialControls InkToolbarInitialControls InkToolbarInitialControls

The collection of built-in buttons to add to the InkToolbar.

Attributes

Remarks

Default built-in buttons, or those specified through InitialControls, are not added to the Children property.

Built-in or custom buttons added programmatically or declared in XAML, are added to the Children property.

Built-in buttons are displayed in a pre-determined order within their respective control groups. Custom buttons are added to the appropriate control group in the order specified, after all built-in buttons.

Examples

To specify which built-in buttons are displayed at initialization:

  1. Set InitialControls to None.
  2. Add the individual buttons.
  3. Specify the InkToolbar UI experience, such as the default button. The following examples (both XAML and code-behind) show how to clear the default buttons from the InkToolber, add ballpoint pen, pencil, and eraser buttons, and set the default button to pencil.

XAML

<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 sample" 
                   Style="{ThemeResource HeaderTextBlockStyle}" 
                   Margin="10,0,0,0" />
    </StackPanel>
    <Grid Grid.Row="1">
        <Image Source="Assets\StoreLogo.png" />
        <!-- Clear the default InkToolbar buttons by setting InitialControls to None. -->
        <!-- Set the active tool to the pencil button. -->
        <InkCanvas x:Name="inkCanvas" />
        <InkToolbar x:Name="inkToolbar" 
                    VerticalAlignment="Top" 
                    TargetInkCanvas="{x:Bind inkCanvas}" 
                    InitialControls="None"
                    ActiveTool="{x:Bind pencilButton}">
            <!-- 
             Add only the ballpoint pen, pencil, and eraser. 
             Note that the buttons are added to the toolbar in the order 
             defined by the framework, not the order we specify here.
            -->
            <InkToolbarEraserButton />
            <InkToolbarBallpointPenButton />
            <InkToolbarPencilButton x:Name="pencilButton"/>
        </InkToolbar>
    </Grid>
</Grid>
<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 sample" 
                   Style="{ThemeResource HeaderTextBlockStyle}" 
                   Margin="10,0,0,0" />
    </StackPanel>
    <Grid Grid.Row="1">
        <Image Source="Assets\StoreLogo.png" />
        <InkCanvas x:Name="inkCanvas" />
        <InkToolbar x:Name="inkToolbar" VerticalAlignment="Top" TargetInkCanvas="{x:Bind inkCanvas}" />
    </Grid>
</Grid>
/// <summary>
/// An empty page that can be used on its own or navigated to within a Frame.
/// Here, we set up InkToolbar event listeners.
/// </summary>
public MainPage_CodeBehind()
{
    this.InitializeComponent();
    // Add handlers for InkToolbar events.
    inkToolbar.Loading += inkToolbar_Loading;
    //inkToolbar.Loaded += inkToolbar_Loaded;
}
/// <summary>
/// Handles the Loading event of the InkToolbar. 
/// Here, we identify the buttons to include on the InkToolbar.
/// </summary>
/// <param name="sender">The InkToolbar</param>
/// <param name="args">The InkToolbar event data. 
/// If there is no event data, this parameter is null</param>
private void inkToolbar_Loading(FrameworkElement sender, object args)
{
    // Clear all built-in buttons from the InkToolbar.
    inkToolbar.InitialControls = InkToolbarInitialControls.None;

    // Add only the ballpoint pen, pencil, and eraser.
    // Note that the buttons are added to the toolbar in the order
    // defined by the framework, not the order we specify here.
    InkToolbarBallpointPenButton ballpoint = new InkToolbarBallpointPenButton();
    InkToolbarPencilButton pencil = new InkToolbarPencilButton();
    InkToolbarEraserButton eraser = new InkToolbarEraserButton();
    inkToolbar.Children.Add(eraser);
    inkToolbar.Children.Add(ballpoint);
    inkToolbar.Children.Add(pencil);
}
/// <summary>
/// Handle the Loaded event of the InkToolbar.
/// By default, the active tool is set to the first tool on the toolbar.
/// Here, we set the active tool to the pencil button. 
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void inkToolbar_Loaded(object sender, RoutedEventArgs e)
{
    InkToolbarToolButton pencilButton = inkToolbar.GetToolButton(InkToolbarTool.Pencil);
    inkToolbar.ActiveTool = pencilButton;
}

InitialControlsProperty InitialControlsProperty InitialControlsProperty

Identifies the InitialControls dependency property.

public static DependencyProperty InitialControlsProperty { get; }public static DependencyProperty InitialControlsProperty { get; }Public Static ReadOnly Property InitialControlsProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the InitialControls dependency property.

Attributes

InkDrawingAttributes InkDrawingAttributes InkDrawingAttributes

Gets the InkStroke properties specified through the InkToolbar.

public InkDrawingAttributes InkDrawingAttributes { get; }public InkDrawingAttributes InkDrawingAttributes { get; }Public ReadOnly Property InkDrawingAttributes As InkDrawingAttributes
Attributes

InkDrawingAttributesProperty InkDrawingAttributesProperty InkDrawingAttributesProperty

Identifies the InkDrawingAttributes dependency property.

public static DependencyProperty InkDrawingAttributesProperty { get; }public static DependencyProperty InkDrawingAttributesProperty { get; }Public Static ReadOnly Property InkDrawingAttributesProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the InkDrawingAttributes dependency property.

Attributes

IsRulerButtonChecked IsRulerButtonChecked IsRulerButtonChecked

Gets or sets the state of the InkToolbarRulerButton (and associated tool) to on or off.

When turned on, the ruler works in conjunction with the active tool.

public bool IsRulerButtonChecked { get; set; }public bool IsRulerButtonChecked { get; set; }Public ReadWrite Property IsRulerButtonChecked As bool
Value
bool bool bool

true if the ruler button is selected and the ruler is active; otherwise, false.

Attributes

IsRulerButtonCheckedProperty IsRulerButtonCheckedProperty IsRulerButtonCheckedProperty

Identifies the IsRulerButtonChecked dependency property.

public static DependencyProperty IsRulerButtonCheckedProperty { get; }public static DependencyProperty IsRulerButtonCheckedProperty { get; }Public Static ReadOnly Property IsRulerButtonCheckedProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsRulerButtonChecked dependency property.

Attributes

IsStencilButtonChecked IsStencilButtonChecked IsStencilButtonChecked

Gets or sets the state of the InkToolbarStencilButton (and associated tool) to on or off.

When turned on, the stencil works in conjunction with the active tool.

public bool IsStencilButtonChecked { get; set; }public bool IsStencilButtonChecked { get; set; }Public ReadWrite Property IsStencilButtonChecked As bool
Value
bool bool bool

true if the stencil button is selected and the stencil is active; otherwise, false.

Attributes

IsStencilButtonCheckedProperty IsStencilButtonCheckedProperty IsStencilButtonCheckedProperty

Identifies the IsStencilButtonChecked dependency property.

public static DependencyProperty IsStencilButtonCheckedProperty { get; }public static DependencyProperty IsStencilButtonCheckedProperty { get; }Public Static ReadOnly Property IsStencilButtonCheckedProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsStencilButtonChecked dependency property.

Attributes

Orientation Orientation Orientation

Gets or sets the orientation of the InkToolbar.

public Orientation Orientation { get; set; }public Orientation Orientation { get; set; }Public ReadWrite Property Orientation As Orientation
Value
Orientation Orientation Orientation

The different orientations that ink toolbar can have.

Attributes

OrientationProperty OrientationProperty OrientationProperty

Identifies the InkToolbar.Orientation dependency property.

public static DependencyProperty OrientationProperty { get; }public static DependencyProperty OrientationProperty { get; }Public Static ReadOnly Property OrientationProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the InkToolbar.Orientation dependency property.

Attributes

TargetInkCanvas TargetInkCanvas TargetInkCanvas

Gets or sets the InkCanvas control associated with the InkToolbar.

All InkToolbar settings are propagated to the associated InkCanvas.

public InkCanvas TargetInkCanvas { get; set; }public InkCanvas TargetInkCanvas { get; set; }Public ReadWrite Property TargetInkCanvas As InkCanvas
Value
InkCanvas InkCanvas InkCanvas

The InkCanvas control to associate with the InkToolbar.

Attributes

TargetInkCanvasProperty TargetInkCanvasProperty TargetInkCanvasProperty

Identifies the TargetInkCanvas dependency property.

public static DependencyProperty TargetInkCanvasProperty { get; }public static DependencyProperty TargetInkCanvasProperty { get; }Public Static ReadOnly Property TargetInkCanvasProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the TargetInkCanvas dependency property.

Attributes

Methods

GetMenuButton(InkToolbarMenuKind) GetMenuButton(InkToolbarMenuKind) GetMenuButton(InkToolbarMenuKind)

Retrieves a reference to an InkToolbarMenuButton object from the menu button group of the InkToolbar.

public InkToolbarMenuButton GetMenuButton(InkToolbarMenuKind menu)public InkToolbarMenuButton GetMenuButton(InkToolbarMenuKind menu)Public Function GetMenuButton(menu As InkToolbarMenuKind) As InkToolbarMenuButton
Parameters
Returns
Attributes

GetToggleButton(InkToolbarToggle) GetToggleButton(InkToolbarToggle) GetToggleButton(InkToolbarToggle)

Retrieves a reference to an InkToolbarToggleButton object from the toggle button group of the InkToolbar.

public InkToolbarToggleButton GetToggleButton(InkToolbarToggle tool)public InkToolbarToggleButton GetToggleButton(InkToolbarToggle tool)Public Function GetToggleButton(tool As InkToolbarToggle) As InkToolbarToggleButton
Parameters
Returns
Attributes

GetToolButton(InkToolbarTool) GetToolButton(InkToolbarTool) GetToolButton(InkToolbarTool)

Retrieves a reference to one of the following objects from the radio button group of the InkToolbar.

public InkToolbarToolButton GetToolButton(InkToolbarTool tool)public InkToolbarToolButton GetToolButton(InkToolbarTool tool)Public Function GetToolButton(tool As InkToolbarTool) As InkToolbarToolButton
Parameters
tool
InkToolbarTool InkToolbarTool InkToolbarTool

Indicates the type of InkToolbarToolButton to retrieve.

Returns

The InkToolbarToolButton specified, or null if the button has not been added to the InkToolbar.

Attributes

Events

ActiveToolChanged ActiveToolChanged ActiveToolChanged

Occurs when the currently selected feature in the RadioButton group of the InkToolbar is changed. This event provides access to the following objects:

Features in this group are mutually exclusive: selecting a feature deselects the currently active feature.

Note

InkToolbarRulerButton and InkToolbarCustomToggleButton objects work in conjunction with the active feature and are not exposed to the ActiveToolChanged event.

public event TypedEventHandler ActiveToolChangedpublic event TypedEventHandler ActiveToolChangedPublic Event ActiveToolChanged
Attributes

EraseAllClicked EraseAllClicked EraseAllClicked

Occurs when "Erase All Ink" is selected from the flyout for the InkToolbarEraserButton on the InkToolbar.

public event TypedEventHandler EraseAllClickedpublic event TypedEventHandler EraseAllClickedPublic Event EraseAllClicked
Attributes

Remarks

Each feature on the InkToolbar can support supplementary functionality in a flyout (an "extension glyph" on the feature button indicates to the user that the functionality is available). "Erase All Ink" is the built-in flyout for the Eraser button.

To access the functionality, the feature button must be selected already, and the user must select the button again.

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.

InkDrawingAttributesChanged InkDrawingAttributesChanged InkDrawingAttributesChanged

Occurs when any InkDrawingAttributes are changed.

public event TypedEventHandler InkDrawingAttributesChangedpublic event TypedEventHandler InkDrawingAttributesChangedPublic Event InkDrawingAttributesChanged
Attributes

IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged

Occurs when the toggled state of the InkToolbarRulerButton changes.

public event TypedEventHandler IsRulerButtonCheckedChangedpublic event TypedEventHandler IsRulerButtonCheckedChangedPublic Event IsRulerButtonCheckedChanged
Attributes

IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged

Occurs when the toggled state of the InkToolbaStencilButton changes.

public event TypedEventHandler IsStencilButtonCheckedChangedpublic event TypedEventHandler IsStencilButtonCheckedChangedPublic Event IsStencilButtonCheckedChanged
Attributes