Ink​Toolbar Ink​Toolbar Ink​Toolbar 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.

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

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>

Remarks

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

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:

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

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.

Constructors

InkToolbar() InkToolbar() InkToolbar()

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.

See Also

ActiveToolProperty ActiveToolProperty ActiveToolProperty

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
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

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
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

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.

See Also

ChildrenProperty ChildrenProperty ChildrenProperty

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

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;
}

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.

See Also

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
See Also

InkDrawingAttributes InkDrawingAttributes InkDrawingAttributes

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
See Also

IsRulerButtonChecked IsRulerButtonChecked IsRulerButtonChecked

IsRulerButtonCheckedProperty IsRulerButtonCheckedProperty IsRulerButtonCheckedProperty

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 : PlatForm::Boolean IsStencilButtonChecked { get; set; }public bool IsStencilButtonChecked { get; set; }Public ReadWrite Property IsStencilButtonChecked As bool
Value
PlatForm::Boolean bool bool

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

Attributes
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

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
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

Orientation Orientation Orientation

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
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

TargetInkCanvas TargetInkCanvas TargetInkCanvas

TargetInkCanvasProperty TargetInkCanvasProperty TargetInkCanvasProperty

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
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

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
See Also

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
See Also

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
See Also

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.

See Also

InkDrawingAttributesChanged InkDrawingAttributesChanged InkDrawingAttributesChanged

IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged

IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged

See Also