| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.InkToolbarCustomToolButton |
winrt class |
Represents an InkToolbar button that invokes a non-pen tool, defined by the host app.
The InkToolbar consists of two distinct groups of button types:
-
One group of "tool" buttons containing the built-in drawing (InkToolbarBallpointPenButton, InkToolbarPencilButton), erasing (InkToolbarEraserButton), and highlighting (InkToolbarHighlighterButton) buttons. Custom tools (InkToolbarCustomPenButton and InkToolbarCustomToolButton) are added here.
Feature selection is mutually exclusive.
-
A second group of "toggle" buttons containing the built-in stencil (InkToolbarStencilButton) button (or the InkToolbarRulerButton button). Custom toggles (InkToolbarCustomToggleButton) are added here.
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.
You cannot change the display order of the built-in buttons. The default display order is: InkToolbarBallpointPenButton, InkToolbarPencilButton, InkToolbarHighlighterButton, InkToolbarEraserButton, and InkToolbarRulerButton, with custom tool buttons appended to the radio button group and custom toggle buttons appended to the toggle button group.
By default, InkPresenter processes all input as either an ink stroke or an erase stroke. This includes input modified by a secondary hardware affordance such as a pen barrel button, a right mouse button, or similar. However, InkPresenter can be configured to leave specific input unprocessed, which can then be passed through to your app for custom processing.
In this example, we define a custom tool button that, when selected, causes subsequent strokes to be processed and rendered as a selection lasso (dashed line) instead of ink. All ink strokes within the bounds of the selection area are set to Selected.
The following example steps through how to enable stroke selection through a custom tool button.
Note
See Inking controls for both InkCanvas and InkToolbar UX guidelines. The following recommendation is relevant to this example:
- If providing stroke selection, we recommend using the "EF20" icon from the "Segoe MLD2 Assets" font for the tool button, with a "Selection tool" tooltip.
First, we set up the UI in MainPage.xaml.
- We declare an InkToolbarCustomToolButton element (
customToolButton) with a Click event listener that specifies the event handler (customToolButton_Click) where stroke selection is configured. (We've also added a set of buttons for copying, cutting, and pasting the stroke selection.) - We also add a Canvas element for drawing our selection stroke. Using a separate layer to draw the selection stroke leaves the InkCanvas and its content untouched.
[!code-xamlSnippetUI_AddCustomTool]
We then handle the Click event for the InkToolbarCustomToolButton in the MainPage.xaml.cs code-behind file.
This handler configures the InkPresenter to pass unprocessed input through to the app.
For a more detailed step through of this code See the Pass-through input for advanced processing section of Pen interactions and Windows Ink in UWP apps.
We also specified an icon for the button using the SymbolIcon element and the {x:Bind} markup extension that binds it to a field defined in the code-behind file (SelectIcon).
The following snippet includes both the Click event handler and the definition of SelectIcon for this example.
[!code-csharpSnippetCustomToolMain]
Pen and stylus interactions, Add an InkToolbar to a Universal Windows Platform (UWP) app, Get Started Tutorial: Support ink in your UWP app, Ink sample (JavaScript), Get Started Tutorial: Support ink in your UWP app, Coloring book sample, Family notes sample