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

public : class InkToolbar : Control, IInkToolbar, IInkToolbar2public class InkToolbar : Control, IInkToolbar, IInkToolbar2Public Class InkToolbar Inherits Control Implements IInkToolbar, IInkToolbar2// This API is not available in Javascript.
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() InkToolbar()

Properties

ActiveTool 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// This API is not available in Javascript.
Value
InkToolbarToolButton InkToolbarToolButton InkToolbarToolButton InkToolbarToolButton

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

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 ActiveToolProperty

Identifies the ActiveTool dependency property.

public : static DependencyProperty ActiveToolProperty { get; }public static DependencyProperty ActiveToolProperty { get; }Public Static ReadOnly Property ActiveToolProperty As DependencyProperty// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the ActiveTool dependency property.

See Also

ButtonFlyoutPlacement 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// This API is not available in Javascript.
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 ButtonFlyoutPlacementProperty

Identifies the ButtonFlyoutPlacement dependency property.

public : static DependencyProperty ButtonFlyoutPlacementProperty { get; }public static DependencyProperty ButtonFlyoutPlacementProperty { get; }Public Static ReadOnly Property ButtonFlyoutPlacementProperty As DependencyProperty// This API is not available in Javascript.
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 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// This API is not available in Javascript.

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 ChildrenProperty

Identifies the Children dependency property.

public : static DependencyProperty ChildrenProperty { get; }public static DependencyProperty ChildrenProperty { get; }Public Static ReadOnly Property ChildrenProperty As DependencyProperty// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the Children dependency property.

See Also

InitialControls 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// This API is not available in Javascript.

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 InitialControlsProperty

Identifies the InitialControls dependency property.

public : static DependencyProperty InitialControlsProperty { get; }public static DependencyProperty InitialControlsProperty { get; }Public Static ReadOnly Property InitialControlsProperty As DependencyProperty// This API is not available in Javascript.
See Also

InkDrawingAttributes 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// This API is not available in Javascript.
See Also

InkDrawingAttributesProperty 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// This API is not available in Javascript.
See Also

IsRulerButtonChecked 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 : PlatForm::Boolean IsRulerButtonChecked { get; set; }public bool IsRulerButtonChecked { get; set; }Public ReadWrite Property IsRulerButtonChecked As bool// This API is not available in Javascript.
Value
PlatForm::Boolean bool bool bool

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

See Also

IsRulerButtonCheckedProperty 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// This API is not available in Javascript.
See Also

IsStencilButtonChecked 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// This API is not available in Javascript.
Value
PlatForm::Boolean bool bool bool

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

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 IsStencilButtonCheckedProperty

Identifies the IsStencilButtonChecked dependency property.

public : static DependencyProperty IsStencilButtonCheckedProperty { get; }public static DependencyProperty IsStencilButtonCheckedProperty { get; }Public Static ReadOnly Property IsStencilButtonCheckedProperty As DependencyProperty// This API is not available in Javascript.
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 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// This API is not available in Javascript.
Value
Orientation Orientation Orientation Orientation

The different orientations that ink toolbar can have.

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

OrientationProperty 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// This API is not available in Javascript.
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 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// This API is not available in Javascript.
Value
InkCanvas InkCanvas InkCanvas InkCanvas

The InkCanvas control to associate with the InkToolbar.

See Also

TargetInkCanvasProperty 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// This API is not available in Javascript.
See Also

Methods

GetMenuButton(InkToolbarMenuKind) 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// This API is not available in Javascript.
Parameters
Returns
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) GetToggleButton(InkToolbarToggle)

GetToolButton(InkToolbarTool) 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// This API is not available in Javascript.
Parameters
Returns
See Also

Events

ActiveToolChanged 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 ActiveToolChanged<InkToolbar,  object>public event TypedEventHandler ActiveToolChanged<InkToolbar,  object>Public Event ActiveToolChanged<InkToolbar,  object>// This API is not available in Javascript.
See Also

EraseAllClicked EraseAllClicked EraseAllClicked EraseAllClicked

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

public : event TypedEventHandler EraseAllClicked<InkToolbar,  object>public event TypedEventHandler EraseAllClicked<InkToolbar,  object>Public Event EraseAllClicked<InkToolbar,  object>// This API is not available in Javascript.

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 InkDrawingAttributesChanged

Occurs when any InkDrawingAttributes are changed.

public : event TypedEventHandler InkDrawingAttributesChanged<InkToolbar,  object>public event TypedEventHandler InkDrawingAttributesChanged<InkToolbar,  object>Public Event InkDrawingAttributesChanged<InkToolbar,  object>// This API is not available in Javascript.
See Also

IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged IsRulerButtonCheckedChanged

Occurs when the toggled state of the InkToolbarRulerButton changes.

public : event TypedEventHandler IsRulerButtonCheckedChanged<InkToolbar,  object>public event TypedEventHandler IsRulerButtonCheckedChanged<InkToolbar,  object>Public Event IsRulerButtonCheckedChanged<InkToolbar,  object>// This API is not available in Javascript.
See Also

IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged IsStencilButtonCheckedChanged

Occurs when the toggled state of the InkToolbaStencilButton changes.

public : event TypedEventHandler IsStencilButtonCheckedChanged<InkToolbar,  InkToolbarIsStencilButtonCheckedChangedEventArgs>public event TypedEventHandler IsStencilButtonCheckedChanged<InkToolbar,  InkToolbarIsStencilButtonCheckedChangedEventArgs>Public Event IsStencilButtonCheckedChanged<InkToolbar,  InkToolbarIsStencilButtonCheckedChangedEventArgs>// This API is not available in Javascript.
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)
See Also

See Also