InkToolbar¶

Header: winui/ui/media/InkToolbar.hpp. Spec: winui/ui/media/InkToolbar.hpp.

A row of ink tools bound to a ui::InkCanvasControl. By default it holds a ballpoint pen, a pencil, a highlighter and an eraser, in that order.

Clicking a tool makes it the active tool and sets the target canvas up for it. A pen sets its drawing attributes and Inking mode, and the eraser sets Erasing mode. Clicking the active tool again opens its flyout. A pen's flyout picks a color from the pen's palette and a stroke width with a slider, over a sample stroke. The palette has 30 colors, six for the highlighter, and the width goes from 1 to 24 DIPs, 12 to 64 for the highlighter. The eraser's flyout switches the target canvas between its stroke and point erasers (InkCanvasControl::set_erase_mode()) and offers "Erase all ink", which clears the canvas. The toolbar is one tab stop. The arrow keys move between the tools, and Space or Enter does what a click does.

The app can add tools of its own after the built-in ones. A custom pen draws with attributes it makes from the picked color and width. A custom tool turns the canvas's inking off, so the app handles its input through on_unprocessed_input(), for example for a lasso. A custom toggle sits after the tools. add_stencil_button() adds the button that shows a ruler or a protractor on the canvas. ui::InkToolbar is the declarative form.

Example:

auto  canvas  = std::make_unique<ui::InkCanvasControl>();
auto  toolbar = std::make_unique<ui::InkToolbarControl>();
toolbar->set_target_ink_canvas(canvas.get());
toolbar->on_active_tool_changed([](ui::InkToolbarTool tool)
                                { std::println("tool {}", static_cast<int>(tool)); });
toolbar->set_active_tool(ui::InkToolbarTool::Highlighter); // the canvas now highlights

auto stack = std::make_unique<ui::StackControl>(ui::Orientation::Vertical);
stack->add(std::move(toolbar));
canvas->set_height(300.0f);
stack->add(std::move(canvas));
window.set_content(std::move(stack));

ui::InkToolbar¶

A row of ink tools for an InkCanvas. Builds a ui::InkToolbarControl, whose description lists the tools and their flyouts.

.target names the canvas by its handle, and the canvas can be built before or after the toolbar. Until the canvas exists, the tools only change the toolbar's own state. The active tool's attributes reach the canvas once it is linked. .active_tool = tool is two-way.

Example:

ui::Control<ui::InkCanvas>       canvas;
ui::Property<ui::InkToolbarTool> tool{ui::InkToolbarTool::BallpointPen};

window.set_content(ui::VerticalStack{.spacing = 8, .content = {
    ui::InkToolbar{
        .tools                = {ui::InkToolbarTool::BallpointPen, ui::InkToolbarTool::Highlighter,
                                 ui::InkToolbarTool::Eraser},
        .active_tool          = tool,
        .target               = canvas, // the canvas draws with the active tool
        .horizontal_alignment = ui::Alignment::Leading,
        .accessibility        = {.name = "Drawing tools"},
    },
    ui::Border{.background = ui::colors::White,
               .height     = 280.0f,
               .content    = ui::InkCanvas{.control = canvas}},
}});

Every field, in the order a designated initializer names them:

ui::InkToolbar{
    .tools, .custom_pens, .custom_tools, .custom_toggles, .stencil_button, .active_tool,
    .orientation, .button_flyout_placement, .target, .style, .margin, .width, .height,
    .min_width, .min_height, .max_width, .max_height, .horizontal_alignment,
    .vertical_alignment, .visible, .tool_tip, .enabled, .accessibility,
    .on_active_tool_changed, .on_ink_drawing_attributes_changed, .on_erase_all_clicked,
    .on_stencil_button_checked_changed, .on_pointer_entered, .on_pointer_exited, .on_got_focus,
    .on_lost_focus, .on_key_down, .on_wheel, .control
}

Fields, in declaration order (designators must follow it):

Plus the common fields style, margin, width, height, min_width, min_height, max_width, max_height, horizontal_alignment, vertical_alignment, visible, tool_tip, enabled, accessibility every spec carries (conventions).

build¶

std::unique_ptr<Element> build()&&

Consumes the spec and returns the built ui::InkToolbarControl; the caller owns it.

ui::InkToolbarControl¶

Derives from ui::Element.

A row of ink tools bound to a ui::InkCanvasControl. By default it holds a ballpoint pen, a pencil, a highlighter and an eraser, in that order.

Clicking a tool makes it the active tool and sets the target canvas up for it. A pen sets its drawing attributes and Inking mode, and the eraser sets Erasing mode. Clicking the active tool again opens its flyout. A pen's flyout picks a color from the pen's palette and a stroke width with a slider, over a sample stroke. The palette has 30 colors, six for the highlighter, and the width goes from 1 to 24 DIPs, 12 to 64 for the highlighter. The eraser's flyout switches the target canvas between its stroke and point erasers (InkCanvasControl::set_erase_mode()) and offers "Erase all ink", which clears the canvas. The toolbar is one tab stop. The arrow keys move between the tools, and Space or Enter does what a click does.

The app can add tools of its own after the built-in ones. A custom pen draws with attributes it makes from the picked color and width. A custom tool turns the canvas's inking off, so the app handles its input through on_unprocessed_input(), for example for a lasso. A custom toggle sits after the tools. add_stencil_button() adds the button that shows a ruler or a protractor on the canvas. ui::InkToolbar is the declarative form.

Example:

auto  canvas  = std::make_unique<ui::InkCanvasControl>();
auto  toolbar = std::make_unique<ui::InkToolbarControl>();
toolbar->set_target_ink_canvas(canvas.get());
toolbar->on_active_tool_changed([](ui::InkToolbarTool tool)
                                { std::println("tool {}", static_cast<int>(tool)); });
toolbar->set_active_tool(ui::InkToolbarTool::Highlighter); // the canvas now highlights

auto stack = std::make_unique<ui::StackControl>(ui::Orientation::Vertical);
stack->add(std::move(toolbar));
canvas->set_height(300.0f);
stack->add(std::move(canvas));
window.set_content(std::move(stack));

AllTools¶

static std::array<InkToolbarTool, 4> AllTools {InkToolbarTool::BallpointPen, InkToolbarTool::Pencil, InkToolbarTool::Highlighter, InkToolbarTool::Eraser}

Every built-in tool, in the default order.

InkToolbarControl¶

InkToolbarControl(std::span<const InkToolbarTool> tools = AllTools)

A toolbar with a button for each of tools, in that order. A repeated tool appears once. The first is the active tool.

~InkToolbarControl¶

~InkToolbarControl() override

tool_button¶

InkToolbarToolButtonControl* tool_button(InkToolbarTool tool) const

The button for tool, or nullptr when this toolbar has none.

active_tool¶

InkToolbarTool active_tool() const

The selected tool. CustomPen or CustomTool for a custom button. active_tool_button() tells custom buttons apart.

set_active_tool¶

void set_active_tool(InkToolbarTool tool)

Selects tool and sets the target canvas up for it, raising on_active_tool_changed(). For a pen whose attributes differ, it also raises on_ink_drawing_attributes_changed(). Does nothing when the toolbar has no button for tool. CustomPen and CustomTool select the first button of their kind.

active_tool_button¶

InkToolbarToolButtonControl* active_tool_button() const

The active tool's button.

set_active_tool_button¶

void set_active_tool_button(InkToolbarToolButtonControl* button)

Selects button, one of this toolbar's, as set_active_tool() does. Does nothing for a button of another toolbar.

add_custom_pen¶

InkToolbarToolButtonControl* add_custom_pen(InkToolbarCustomButton button)

Adds a pen after the tools. It draws with what button.pen makes of the color and width picked in its flyout. Returns the new button.

add_custom_tool¶

InkToolbarToolButtonControl* add_custom_tool(InkToolbarCustomButton button)

Adds a tool after the tools. While it is active, the target canvas inks nothing (InkCanvasInputMode::None) and reports its input through InkCanvasControl::on_unprocessed_input() for the app to act on. Returns the new button.

add_custom_toggle¶

InkToolbarToggleButtonControl* add_custom_toggle(InkToolbarCustomButton button)

Adds a toggle after the tools and the toggles before it. Returns the new toggle.

toggle_buttons¶

std::vector<InkToolbarToggleButtonControl*> toggle_buttons() const

The toggles, in order.

add_stencil_button¶

InkToolbarStencilButtonControl* add_stencil_button()

Adds the stencil button after the tools, before the toggles, and returns it. A second call returns the one already there.

stencil_button¶

InkToolbarStencilButtonControl* stencil_button() const

The stencil button, or nullptr when there is none.

stencil_button_checked¶

bool stencil_button_checked() const

Whether a stencil shows on the target canvas.

set_stencil_button_checked¶

void set_stencil_button_checked(bool checked)

Shows the selected stencil on the target canvas, or hides both. Raises on_stencil_button_checked_changed() on a change. Does nothing without a stencil button.

on_stencil_button_checked_changed¶

void on_stencil_button_checked_changed(Callback<void(const InkToolbarStencilChangedArgs&)> handler)

Raised when the stencil button turns on or off, with the stencil it shows.

tool_visible¶

bool tool_visible(InkToolbarTool tool) const

Whether the button for tool is shown. False when the toolbar has none.

set_tool_visible¶

void set_tool_visible(InkToolbarTool tool, bool visible)

Shows or collapses the button for tool. Hiding the active tool leaves it active, so select another tool first.

ink_drawing_attributes¶

const InkDrawingAttributes& ink_drawing_attributes() const

What the last active pen draws with. Until a pen has been active, the ballpoint pen's attributes.

orientation¶

Orientation orientation() const

Whether the tools form a row or a column. Horizontal by default.

set_orientation¶

void set_orientation(Orientation orientation)

Lays the tools out in a row or a column.

button_flyout_placement¶

InkToolbarButtonFlyoutPlacement button_flyout_placement() const

Where the tool flyouts open. Auto, which is below, by default.

set_button_flyout_placement¶

void set_button_flyout_placement(InkToolbarButtonFlyoutPlacement placement)

Sets where the tool flyouts open. Applies to the next flyout opened, and moves the chevron to that side.

target_ink_canvas¶

InkCanvasControl* target_ink_canvas() const

The canvas the tools drive, or nullptr when none is set or it was destroyed.

set_target_ink_canvas¶

void set_target_ink_canvas(InkCanvasControl* canvas)

Attaches to canvas and sets it up for the active tool at once. nullptr detaches. The toolbar doesn't own the canvas and lets go of it when the canvas is destroyed, so the canvas may go first. Until a canvas is set, the tools only change the toolbar's own state.

erase_all¶

void erase_all()

Clears the target canvas and raises on_erase_all_clicked(), like the eraser flyout's "Erase all ink" item.

open_flyout¶

bool open_flyout(InkToolbarTool tool)

Opens the flyout of tool's button. Returns false when it has none, as for a hidden or missing tool or an eraser without "Erase all ink".

close_flyout¶

void close_flyout()

Closes whichever tool flyout is open.

open_flyout_tool¶

std::optional<InkToolbarTool> open_flyout_tool() const

The tool whose flyout is open, or nullopt when none is.

on_active_tool_changed¶

void on_active_tool_changed(Callback<void(InkToolbarTool)> handler)

Raised with the new tool.

on_ink_drawing_attributes_changed¶

void on_ink_drawing_attributes_changed(Callback<void(const InkDrawingAttributes&)> handler)

Raised when the active pen's color, width or kind changes.

on_erase_all_clicked¶

void on_erase_all_clicked(Callback<void()> handler)

Raised after "Erase all ink" has cleared the canvas.

focused¶

bool focused() const

Whether the toolbar has keyboard focus.

focusable¶

bool focusable() const override

A tab stop while enabled.

collect_focusables¶

void collect_focusables(std::vector<Element*>& out) override

The toolbar is one tab stop. Its buttons aren't.

focused_button¶

const InkToolbarToolButtonControl* focused_button() const

The tool under the keyboard cursor while the toolbar is focused. nullptr while the cursor is on a toggle.

for_each_child¶

void for_each_child(ChildVisitor visit) const override

The internal panel.

automation_children¶

void automation_children(std::vector<Element*>& out) const override

The visible tool buttons (through their flyouts) and the toggles, not the internal panel.

automation_role¶

AutomationRole automation_role() const override

Exposed to UI Automation as a toolbar, like ui::ToolbarControl.

measure_override¶

Size measure_override(Size available, const MeasureContext& context) const override

The tools in a row or column, 40 DIPs a tool, inside a 2 DIP margin.

arrange_override¶

void arrange_override(const Rect& final_rect, const ArrangeContext& context) override

Places the tools.

render_override¶

void render_override(Renderer& renderer, const RenderContext& context) const override

The tools, and the focus ring around the tool under the keyboard cursor.

enabled_changed¶

void enabled_changed() override

is_enabled() flipped, through set_enabled() here or on an ancestor, or a move to another parent. Drop any press or hover state. The element is redrawn either way. No-op by default.

focus_changed¶

void focus_changed(bool focused) override

Puts the keyboard cursor on the active tool when focus arrives.

key_override¶

bool key_override(const KeyEvent& e) override

Left and Right, or Up and Down in a vertical toolbar, move between the visible tools and toggles. Home and End move to the ends. Space and Enter act on the one under the cursor as a click does.

focus_ring_rect¶

Rect focus_ring_rect(const Theme& theme) const override

Around the tool or toggle under the keyboard cursor.

class InkToolbarToolButtonControl¶

Derives from ui::Element, ui::SelectionItemProvider, ui::ExpandCollapseProvider.

One tool button of a ui::InkToolbarControl: a pen, the eraser or another tool. The toolbar makes these. Reach one through InkToolbarControl::tool_button().

The button is a 36 DIP square with the tool's glyph. A pen button also shows its selected color in the glyph, and holds the palette and the stroke width its flyout edits. The eraser button holds whether its flyout offers "Erase all ink". The active tool's button is drawn selected, with a small chevron toward the flyout it opens on a second click.

Example:

auto                             toolbar = std::make_unique<ui::InkToolbarControl>();
ui::InkToolbarToolButtonControl* pen     = toolbar->tool_button(ui::InkToolbarTool::BallpointPen);
pen->set_selected_brush_index(7);       // red, in the default palette
pen->set_selected_stroke_width(6.0f);   // within min_stroke_width()..max_stroke_width()

InkToolbarToolButtonControl¶

InkToolbarToolButtonControl(InkToolbarTool tool)

The button for tool, with that tool's palette, width range and defaults.

InkToolbarToolButtonControl¶

InkToolbarToolButtonControl(InkToolbarTool tool, InkToolbarCustomButton custom)

A custom pen or tool button, looking as custom says. tool is CustomPen or CustomTool. A custom pen starts with the ballpoint pen's palette and widths.

~InkToolbarToolButtonControl¶

~InkToolbarToolButtonControl() override

tool¶

InkToolbarTool tool() const

Which tool the button is.

is_pen¶

bool is_pen() const

True for the ballpoint pen, the pencil, the highlighter and a custom pen.

custom¶

const InkToolbarCustomButton* custom() const

What a custom button was made with, or nullptr for a built-in tool.

checked¶

bool checked() const

Whether this is the toolbar's active tool.

palette¶

const std::vector<Color>& palette() const

The colors the flyout offers. The ballpoint pen and the pencil share a 30-color palette, and the highlighter has six colors.

set_palette¶

void set_palette(std::vector<Color> palette)

Replaces the palette. The selected index is clamped into it.

selected_brush_index¶

std::size_t selected_brush_index() const

The selected palette index. 0 by default, which is black for the pens and yellow for the highlighter.

set_selected_brush_index¶

void set_selected_brush_index(std::size_t index)

Selects a palette color, clamping index into the palette. Updates the drawing attributes when this is the active pen.

selected_color¶

Color selected_color() const

The palette color at the selected index, or black for an empty palette.

min_stroke_width¶

float min_stroke_width() const

The thinnest stroke width: 1 for the pens, 12 for the highlighter.

max_stroke_width¶

float max_stroke_width() const

The thickest stroke width: 24 for the pens, 64 for the highlighter.

set_stroke_width_range¶

void set_stroke_width_range(float min, float max)

Sets both ends of the range, swapping them when given backwards, and clamps the selected width into it.

selected_stroke_width¶

float selected_stroke_width() const

The selected stroke width: 2 for the ballpoint pen, 4 for the pencil, 16 for the highlighter.

set_selected_stroke_width¶

void set_selected_stroke_width(float width)

Sets the stroke width, clamped into the range. Updates the drawing attributes when this is the active pen.

drawing_attributes¶

InkDrawingAttributes drawing_attributes() const

What this pen draws with. The ballpoint pen draws with a round nib of the selected width, and the pencil with pencil ink of that width. The highlighter draws as a highlighter, with a chisel a third of the width wide and the width tall. A custom pen draws with what its InkToolbarCustomButton::pen makes of the color and width.

clear_all_visible¶

bool clear_all_visible() const

Whether the eraser's flyout offers "Erase all ink" under its stroke and point erasers. True by default.

set_clear_all_visible¶

void set_clear_all_visible(bool visible)

Shows or hides the "Erase all ink" item.

extension_glyph_shown¶

bool extension_glyph_shown() const

Whether the chevron that says a second click opens a flyout shows. It shows on the active tool while it has a flyout and that flyout is closed.

hovered¶

bool hovered() const

Whether the pointer is over the button.

tool_tip¶

std::string tool_tip() const override

Shows the tool's name.

automation_role¶

AutomationRole automation_role() const override

Button for the pens, Custom for the eraser and a custom tool.

automation_name_fallback¶

std::string automation_name_fallback() const override

The tool's name, such as "Ballpoint pen", with ", selected" while it is the active tool.

measure_override¶

Size measure_override(Size available, const MeasureContext& context) const override

36 by 36 DIPs. The toolbar adds the 2 DIP margin around it.

render_override¶

void render_override(Renderer& renderer, const RenderContext& context) const override

The background for the state, the color glyph of a pen, the tool's glyph and the chevron.

pointer_override¶

bool pointer_override(const PointerEvent& e) override

A left click selects the tool. On the active tool, it opens the tool's flyout.

struct InkToolbarCustomButton¶

How a custom button of a ui::InkToolbarControl looks and what it does. The button is a custom pen, a custom tool or a custom toggle. Each field applies to the kinds its comment names.

The callables are std::function, so they can be copied. The spec lists custom buttons in a braced list, which copies its entries.

Example:

// A calligraphy pen: a flat nib a third as wide as it is tall.
auto toolbar = std::make_unique<ui::InkToolbarControl>();
toolbar->add_custom_pen({.name  = "Calligraphy pen",
                         .icon  = ui::IconGlyph{0xEDFB},
                         .pen   = [](ui::Color color, float width)
                         {
                             return ui::InkDrawingAttributes{.color   = color,
                                                             .size    = {width / 3.0f, width},
                                                             .pen_tip = ui::InkPenTip::Rectangle};
                         }});

struct InkToolbarStencilChangedArgs¶

What an InkToolbar's on_stencil_button_checked_changed gets: whether the stencil button is on, and the stencil it shows.

class InkToolbarToggleButtonControl¶

Derives from ui::Element, ui::ToggleProvider.

A toggle button on a ui::InkToolbarControl. It turns on or off and sits after the tools. Add one with InkToolbarControl::add_custom_toggle().

Example:

// A toggle that lets touch draw as well as the pen and the mouse.
auto canvas  = std::make_unique<ui::InkCanvasControl>();
auto toolbar = std::make_unique<ui::InkToolbarControl>();
ui::InkToolbarToggleButtonControl* touch =
    toolbar->add_custom_toggle({.name = "Touch writing", .icon = ui::IconGlyph{0xED5F}});
touch->on_checked_changed([ink = canvas.get()](bool on) {
    ink->set_input_device_types(on ? ui::PointerDeviceTypes::All
                                   : ui::PointerDeviceTypes::Pen | ui::PointerDeviceTypes::Mouse);
});

InkToolbarToggleButtonControl¶

InkToolbarToggleButtonControl(InkToolbarCustomButton look)

A toggle looking as look says, off.

~InkToolbarToggleButtonControl¶

~InkToolbarToggleButtonControl() override

look¶

const InkToolbarCustomButton& look() const

What the toggle was made with.

checked¶

bool checked() const

Whether the toggle is on.

set_checked¶

void set_checked(bool checked)

Turns the toggle on or off, raising on_checked_changed() when the state changes.

on_checked_changed¶

void on_checked_changed(Callback<void(bool)> handler)

Raised with the new state when the toggle turns on or off, after the look's own handler.

hovered¶

bool hovered() const

Whether the pointer is over the button.

tool_tip¶

std::string tool_tip() const override

The look's name.

automation_role¶

AutomationRole automation_role() const override

A button that toggles.

automation_name_fallback¶

std::string automation_name_fallback() const override

automation_name()'s fallback when accessibility().name is empty. Default: no inherent name, correct for controls with no visible text of their own (Slider, ProgressBar), which need an explicit accessibility().name from the caller. A control with its own visible text (Button, CheckBox, TextControl, ...) overrides this to return it.

measure_override¶

Size measure_override(Size available, const MeasureContext& context) const override

36 by 36 DIPs, like a tool button.

render_override¶

void render_override(Renderer& renderer, const RenderContext& context) const override

The background for the state, with the selected color while on, and the glyph.

pointer_override¶

bool pointer_override(const PointerEvent& e) override

A left click flips it.

class InkToolbarStencilButtonControl¶

Derives from ui::Element, ui::ToggleProvider, ui::ExpandCollapseProvider.

The stencil button of a ui::InkToolbarControl, which shows the ruler or the protractor on the target canvas. Add it with InkToolbarControl::add_stencil_button().

A click while it is off turns it on and shows the stencil picked last, the ruler at first. A click while it is on opens its flyout, which picks the ruler or the protractor. Picking the one showing hides it and turns the button off. With only one of the two offered, it is a plain toggle with no flyout.

Example:

auto                                toolbar  = std::make_unique<ui::InkToolbarControl>();
ui::InkToolbarStencilButtonControl* stencils = toolbar->add_stencil_button();
stencils->set_selected_stencil(ui::InkToolbarStencilKind::Protractor);
toolbar->set_stencil_button_checked(true); // the protractor shows on the canvas

InkToolbarStencilButtonControl¶

InkToolbarStencilButtonControl()

~InkToolbarStencilButtonControl¶

~InkToolbarStencilButtonControl() override

selected_stencil¶

InkToolbarStencilKind selected_stencil() const

The stencil the button shows while it is on. The ruler by default.

set_selected_stencil¶

void set_selected_stencil(InkToolbarStencilKind kind)

Picks the stencil, and shows it at once while the button is on.

ruler_item_visible¶

bool ruler_item_visible() const

Whether the flyout offers the ruler. True by default.

set_ruler_item_visible¶

void set_ruler_item_visible(bool visible)

See ruler_item_visible().

protractor_item_visible¶

bool protractor_item_visible() const

Whether the flyout offers the protractor. True by default.

set_protractor_item_visible¶

void set_protractor_item_visible(bool visible)

See protractor_item_visible().

checked¶

bool checked() const

Whether the button is on, with a stencil showing.

extension_glyph_shown¶

bool extension_glyph_shown() const

Whether the chevron that says a click opens the flyout shows. It shows while the button is on, offers both stencils and its flyout is closed.

hovered¶

bool hovered() const

Whether the pointer is over the button.

tool_tip¶

std::string tool_tip() const override

The selected stencil's name.

automation_role¶

AutomationRole automation_role() const override

A button that toggles, and expands and collapses its flyout.

automation_name_fallback¶

std::string automation_name_fallback() const override

automation_name()'s fallback when accessibility().name is empty. Default: no inherent name, correct for controls with no visible text of their own (Slider, ProgressBar), which need an explicit accessibility().name from the caller. A control with its own visible text (Button, CheckBox, TextControl, ...) overrides this to return it.

measure_override¶

Size measure_override(Size available, const MeasureContext& context) const override

36 by 36 DIPs, like a tool button.

render_override¶

void render_override(Renderer& renderer, const RenderContext& context) const override

The background for the state, the selected stencil's glyph and the chevron.

pointer_override¶

bool pointer_override(const PointerEvent& e) override

A left click turns it on or opens its flyout.

Enumerations¶

InkToolbarTool¶

enum class InkToolbarTool

A tool on a ui::InkToolbarControl.

InkToolbarStencilKind¶

enum class InkToolbarStencilKind

Which stencil the stencil button shows on the canvas.

InkToolbarButtonFlyoutPlacement¶

enum class InkToolbarButtonFlyoutPlacement

Which side of its button a tool's flyout opens on.

Tests¶

• tests/test_ink_toolbar.cpp