Table of Contents

Toolbar Items

Toolbar items are used to display buttons, check buttons, text labels, sub-menus, and in-place editors in toolbars and menus. You can add any number of items to each bar/menu, and create multiple hierarchy levels using sub-menus.

toolbar-items

Add Toolbar Items to a Bar and Context Menu

Use the Toolbar.Items and PopupMenu.Items collections to populate bars and menus with items. In XAML, you can define items directly between the start and end <Toolbar>/<PopupMenu> tags.

The following example displays three items in a toolbar.

xmlns:mxb="https://schemas.eremexcontrols.net/avalonia/bars"

<mxb:Toolbar x:Name="EditToolbar" ToolbarName="Edit" ShowCustomizationButton="False">
    <mxb:ToolbarButtonItem Header="Cut" Command="{Binding #textBox.Cut}" 
     IsEnabled="{Binding #textBox.CanCut}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Cut.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Copy" Command="{Binding #textBox.Copy}" 
     IsEnabled="{Binding #textBox.CanCopy}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Copy.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Paste" Command="{Binding #textBox.Paste}" 
     IsEnabled="{Binding #textBox.CanPaste}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Paste.svg'}" 
     Category="Edit"/>
</mxb:Toolbar>

Toolbar Item Types

The toolbar library supports multiple toolbar item types. All of them are descendants of the ToolbarItem class, which contains settings common to all toolbar items.

Common Toolbar Item Settings

  • Alignment — The item's alignment within the toolbar.
  • Category — The category to which the item belongs. Categories are used to organize items into logical groups within the Customization window. See the following section for more information: Toolbar Item Categories.
  • Command — A command executed when the button is clicked.
  • CommandParameter — A command parameter passed to the specified command.
  • DisplayMode — Gets or sets whether to display only the glyph, the header, or both.
  • Glyph — The item's image.
  • GlyphAlignment — The glyph alignment relative to the item's header.
  • GlyphSize — The glyph display size.
  • Header — The item's display text.
  • ShowSeparator — Gets or sets whether to display a separator before the item. You can also use the ToolbarSeparatorItem bar item to insert a separator.

ToolbarButtonItem

ToolbarButtonItem is the most common item that encapsulates a regular button. A user can click the button to invoke a linked command.

toolbarbuttonitem

xmlns:mxb="https://schemas.eremexcontrols.net/avalonia/bars"

<mxb:ToolbarButtonItem Header="Open" 
 Glyph="{SvgImage 'avares://bars_sample/Images/Toolbars/FileOpen.svg'}" 
 Category="File" Command="{Binding OpenFileCommand}"/>

You can associate a dropdown control with a ToolbarButtonItem object. This control will be displayed when a user clicks the item or the built-in down arrow.

toolbarbuttonitem-dropdowncontrol

xmlns:mxb="https://schemas.eremexcontrols.net/avalonia/bars"

<mxb:ToolbarButtonItem Header="Paste"
                       Command="{Binding #textBox.Paste}"
                       IsEnabled="{Binding #textBox.CanPaste}"
                       Glyph="{SvgImage 'avares://bars_sample/Images/Toolbars/EditPaste.svg'}"
                       Category="Edit"
                       DropDownArrowVisibility="ShowArrow" DropDownArrowAlignment="Default"
                       >
    <mxb:ToolbarButtonItem.DropDownControl>
        <mxb:PopupMenu>
            <mxb:ToolbarButtonItem Header="Paste" Command="{Binding #textBox.Paste}" 
             IsEnabled="{Binding #textBox.CanPaste}"/>
            <mxb:ToolbarButtonItem Header="Paste As" Command="{Binding PasteAsCommand}" 
             IsEnabled="{Binding #textBox.CanPaste}"/>
        </mxb:PopupMenu>
    </mxb:ToolbarButtonItem.DropDownControl>
</mxb:ToolbarButtonItem>

ToolbarButtonItem's Main Settings

  • DropDownControl — Gets or sets a dropdown control (an Eremex.AvaloniaUI.Controls.Bars.IPopup object) associated with the item. The control pops up when a user clicks the item or the built-in dropdown arrow (see DropDownArrowVisibility). The following objects implement the Eremex.AvaloniaUI.Controls.Bars.IPopup interface, and so they can be displayed as dropdown controls:

    • Eremex.AvaloniaUI.Controls.Bars.PopupMenu — A popup menu. You can add all types of toolbar items to the menu to populate it with content.
    • Eremex.AvaloniaUI.Controls.Bars.PopupContainer — A container of controls. Use PopupContainer to display custom controls in a dropdown.

  • DropDownArrowVisibility — Gets or sets whether the item displays a dropdown arrow used to invoke the associated dropdown control. Supported options include:

    • ShowArrow — The dropdown arrow is visible. The item and arrow act as a single button. A click on them displays an associated dropdown control.

    • ShowSplitArrow or Default — The dropdown arrow is visible. It acts as a separate button embedded in the item. A click on the dropdown arrow invokes the associated dropdown control. A click on the item invokes its command.

    • Hide — The dropdown arrow is hidden. A click on the item invokes the dropdown control.

  • DropDownArrowAlignment — Gets or sets the position of the dropdown arrow.

  • DropDownOpenMode — Gets or sets whether and when the dropdown control is invoked when a user touches the item/dropdown arrow. Supported options include:

    • Press or Default — The dropdown is displayed on a mouse press event.
    • Click — The dropdown is displayed after the mouse is pressed and then released over the item.
    • Never — The dropdown is not displayed.

  • DropDownPress — The event that fires when the dropdown arrow is pressed.

See also: Common Toolbar Item Settings.

ToolbarCheckItem

ToolbarCheckItem encapsulates a check button, which supports two states - normal and pressed.

toolbarcheckitem

xmlns:mxb="https://schemas.eremexcontrols.net/avalonia/bars"

<mxb:ToolbarCheckItem Header="Bold" 
 IsChecked="{Binding #textBox.FontWeight, 
  Converter={helpers:BoolToFontWeightConverter}, Mode=TwoWay}" 
 Glyph="{SvgImage 'avares://DemoCenter/Images/FontBold.svg'}" Category="Font"/>

ToolbarCheckItem's Main Settings and Events

  • IsChecked — Gets or sets the button's check state.
  • CheckedChanged — The event that fires when the check state changes.

See also: Common Toolbar Item Settings.

ToolbarMenuItem

ToolbarMenuItem is an item that displays a sub-menu on a click.

toolbarMenuItem

To specify a sub-menu's content, define items between the start and end <ToolbarMenuItem> tags in XAML, or add items to the ToolbarMenuItem.Items collection in code-behind.

xmlns:mxb="https://schemas.eremexcontrols.net/avalonia/bars"

<mxb:ToolbarMenuItem Header="File" Category="File">
    <mxb:ToolbarButtonItem Header="New" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=NewDraftAction.svg'}" 
     Category="File" Command="{Binding NewFileCommand}"/>
    <mxb:ToolbarButtonItem Header="Open" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Folder Open.svg'}" 
     Category="File" Command="{Binding OpenFileCommand}"/>
    <mxb:ToolbarButtonItem Header="Save" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Save.svg'}" 
     Category="File" Command="{Binding SaveFileCommand}"/>
    <mxb:ToolbarButtonItem Header="Print" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Print.svg'}" 
     ShowSeparator="True"  Category="File" Command="{Binding PrintFileCommand}"/>
</mxb:ToolbarMenuItem>

ToolbarMenuItem's Main Settings and Events

  • DropDownOpenMode — Gets or sets whether and how the sub-menu is invoked when a user touches the item. Supported options include:
    • Press or Default — The menu is displayed on a mouse press event.
    • Click — The menu is displayed after the mouse is pressed and then released over the item.
    • Never — The menu is not displayed.
  • Items — A collection of items displayed in the sub-menu.

Events

  • Opening — Fires when the menu is about to be displayed. This event allows you to cancel the display of the menu.
  • Opened — Fires after the menu is displayed.
  • Closing — Fires when the menu is about to be closed. This event allows you to cancel closing the menu.
  • Closed — Fires after the menu is closed.

See also: Common Toolbar Item Settings.

ToolbarEditorItem

ToolbarEditorItem allows you to display an in-place editor.

ToolbarEditorItem

To specify the in-place editor's type and settings, use the ToolbarEditorItem.EditorProperties property. This member can be set to the following editor types:

  • ButtonEditorProperties — Contains settings specific to the ButtonEditor control.
  • CheckEditorProperties — Contains settings specific to the CheckEditor control.
  • ColorEditorProperties — Contains settings specific to the ColorEditor control.
  • ComboBoxEditorProperties — Contains settings specific to the ComboBoxEditor control.
  • HyperlinkEditorProperties — Contains settings specific to the HyperlinkEditor control.
  • PopupColorEditorProperties — Contains settings specific to the PopupColorEditor control.
  • PopupEditorProperties — Contains settings specific to the PopupEditor control.
  • SegmentedEditorProperties — Contains settings specific to the SegmentedEditor control.
  • SpinEditorProperties — Contains settings specific to the SpinEditor control.
  • TextEditorProperties — Contains settings specific to the TextEditor control.

In the following example, the Font ToolbarEditorItem object displays a list of fonts using a combobox in-place editor. The ToolbarEditorItem.EditorProperties property is set to a ComboBoxEditorProperties, which corresponds to a ComboBoxEditor control.

<mxb:ToolbarEditorItem Header="Font:" EditorWidth="150" Category="Font" 
 EditorValue="{Binding #textBox.FontFamily, Converter={helpers:FontNameToFontFamilyConverter}}">
    <mxb:ToolbarEditorItem.EditorProperties>
        <mxe:ComboBoxEditorProperties 
         ItemsSource="{Binding $parent[view:ToolbarAndMenuPageView].Fonts}"
         IsTextEditable="False"/>
    </mxb:ToolbarEditorItem.EditorProperties>
</mxb:ToolbarEditorItem>

ToolbarEditorItem's Main Settings and Events

  • ToolbarEditorItem.EditorProperties — Gets or sets the object that specifies the type and settings of the in-place editor.
  • ToolbarEditorItem.EditorValue — Gets or sets the in-place editor's value. Use this property for data binding.
  • ToolbarEditorItem.SizeMode — Gets or sets the item's size mode. This property allows you to stretch the bar item, so it occupues all the available empty space within the bar.
  • ToolbarEditorItem.EditorWidth — Gets or sets the in-place editor's width.
  • ToolbarEditorItem.EditorHeight — Gets or sets the in-place editor's height.
  • ToolbarEditorItem.EditorAlignment — Gets or sets the editor's alignment relative to the item's header.

See also: Common Toolbar Item Settings.

ToolbarTextItem

ToolbarTextItem creates a text label. Use this item to render text that is not editable by users.

ToolbarTextItem

<mxb:ToolbarTextItem 
 Header="{Binding #scaleDecorator.Scale, StringFormat={}Zoom: {0:P0}}" 
 ShowBorder="True" Alignment="Far" ShowSeparator="True" Category="Info" 
 CustomizationName="Zoom Info"/>

ToolbarTextItem's Main Settings and Events

  • ToolbarTextItem.SizeMode — Gets or sets the item's size mode. This property allows you to stretch the item, so it occupues all the available empty space within the bar.
  • ToolbarTextItem.ShowBorder — Gets or sets whether the item's border is visible. You can use the ToolbarTextItem.BorderTemplate property to specify a custom template to paint the border.
  • ToolbarTextItem.BorderTemplate — Gets or sets a custom template to paint the item's border. This template is in effect if the ToolbarTextItem.ShowBorder option is enabled.

See also: Common Toolbar Item Settings.

ToolbarItemGroup

ToolbarItemGroup represents a group (container) of toolbar items.

When you combine items into a group they function as a whole. To specify the group's contents, define items between the start and end <ToolbarItemGroup> tags, or add items to the ToolbarItemGroup.Items collection in code-behind.

<mxb:ToolbarItemGroup CustomizationName="Clipboard" >
    <mxb:ToolbarButtonItem Header="Cut" Command="{Binding #textBox.Cut}" 
     IsEnabled="{Binding #textBox.CanCut}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Cut.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Copy" Command="{Binding #textBox.Copy}" 
     IsEnabled="{Binding #textBox.CanCopy}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Copy.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Paste" Command="{Binding #textBox.Paste}" 
     IsEnabled="{Binding #textBox.CanPaste}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Paste.svg'}" 
     Category="Edit"/>
</mxb:ToolbarItemGroup>

ToolbarItemGroup's Main Settings and Events

  • ToolbarItemGroup.Items — Allows you to access the group's children.

ToolbarCheckItemGroup

ToolbarCheckItemGroup represents a check item group (container) that controls the check state of its child items (ToolbarCheckItem objects). The ToolbarCheckItemGroup class allows you to create a group of mutually exclusive items (radio group), and a group that allows multiple items to be checked at the same time.

To specify the group's content, add ToolbarCheckItem items between the start and end <ToolbarCheckItemGroup> tags in XAML, or add items to the ToolbarCheckItemGroup.Items collection in code-behind.

<mxb:ToolbarCheckItemGroup CustomizationName="Check group" CheckType="Radio" >
    <mxb:ToolbarCheckItem Header="1" IsChecked="{Binding Option1}"  
     Category="Settings"/>
    <mxb:ToolbarCheckItem Header="2" IsChecked="{Binding Option2}" 
     Category="Settings"/>
    <mxb:ToolbarCheckItem Header="3" IsChecked="{Binding Option3}" 
     Category="Settings"/>
</mxb:ToolbarCheckItemGroup>

A ToolbarCheckItemGroup object accepts child items of all supported bar item types. The group, however, only manipilates the check states of nested ToolbarCheckItem objects.

ToolbarCheckItemGroup's Main Settings and Events

  • ToolbarCheckItemGroup.CheckType — Gets or sets whether a single or multiple items can be checked in the group at a time. The following options are supported:

    • Default or Multiple — Multiple items can be checked at a time.
    • Radio — A group of mutually exclusive items. A user cannot uncheck an item other than by checking another one.
    • Single — A group of mutually exclusive items. A user can uncheck all items within the group.

  • ToolbarCheckItemGroup.Items — Allows you to access the group's children.

See also: Common Toolbar Item Settings.

ToolbarSeparatorItem

  • ToolbarSeparatorItem — Draws a separator.
<mxb:ToolbarMenuItem Header="File" Category="File">
    <mxb:ToolbarButtonItem Header="New" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=NewDraftAction.svg'}" 
     Category="File"/>
    <mxb:ToolbarButtonItem Header="Open" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Folder Open.svg'}" 
     Category="File"/>
    <mxb:ToolbarButtonItem Header="Save" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Save.svg'}" 
     Category="File"/>
    <mxb:ToolbarSeparatorItem/>
    <mxb:ToolbarButtonItem Header="Print" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Print.svg'}" 
     Category="File"/>
</mxb:ToolbarMenuItem>

Toolbar Item Categories

You can classify toolbar items into categories to enable item grouping in the Customization Window. A user can select a category in the Customization Window to access related items.

toolbars-customizationwindow-categories

Use the ToolbarItem.Category property to assign an item to a category. This property specifies the category name. To assign a group of items to the same category, set their ToolbarItem.Category property to the same category name.

<mxb:ToolbarMenuItem Header="Edit" Category="Edit">
    <mxb:ToolbarButtonItem Header="Cut" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Cut.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Copy" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Copy.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Paste" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Context Menu, Icon=Paste.svg'}" 
     Category="Edit"/>
    <mxb:ToolbarButtonItem Header="Select All" 
     Command="{Binding #textBox.SelectAll}" Category="Edit" ShowSeparator="True"/>
    <mxb:ToolbarButtonItem Header="Clear all" 
     Command="{Binding #textBox.Clear}" 
     Glyph="{SvgImage 'avares://DemoCenter/Images/Group=Basic, Icon=Clear.svg'}" 
     Category="Edit"/>
</mxb:ToolbarMenuItem>

Hotkeys

You can use the ToolbarItem.HotKey property to assign hotkeys to items.

<mxb:ToolbarButtonItem 
    Header="Clear" Command="{Binding #textBox.Clear}" HotKey="Ctrl+Q"
    Glyph="{SvgImage 'avares://bars_sample/Images/Toolbars/EditDelete.svg'}"/>

A hotkey press activates an item's command provided that focus is within the hotkey scope. The default hotkey scope is the UI region within the ToolbarManager component's bounds. When the input focus is beyond the hotkey scope, ToolbarManager is not able to intercept hotkeys.

The ToolbarManager.IsWindowManager property allows you to extend the hotkey scope to the entire window. When you set this property to true, the ToolbarManager component registers item hotkeys in the window. It will be able to intercept and process hotkeys even if focus is outside its client area.

Displaying Hotkeys

Hotkeys assigned to toolbar items are displayed in the following cases:

  • In items when they reside within sub-menus or popup menus.
  • In items' tooltips.

toolbaritem-hotkey-display-in-tooltip

You can use the ToolbarItem.HotKeyDisplayString property to specify a hotkey display text. This text is displayed even if no hotkey is assigned to the item. This is helpful if a target hotkey is already registered by another object to perform a specific operation, and you want to indicate that the same hotkey is linked to a toolbar item.

For instance, a TextBox registers the Ctrl+Z shortcut to perform an Undo opearation. If a toolbar item performs the same Undo operation on the TextBox, do not assign the Ctrl+Z hotkey to the item. Instead, set the item's ToolbarItem.HotKeyDisplayString to "Ctrl+Z" to display this shortcut to users in tooltips and sub-menus/popup menus.

<mxb:ToolbarButtonItem Header="Undo" HotKeyDisplayString="Ctrl+Z" 
    Command="{Binding $parent[TextBox].Undo}" 
    IsEnabled="{Binding $parent[TextBox].CanUndo}" 
    Glyph="{SvgImage 'avares://bars_sample/Images/Toolbars/EditUndo.svg'}"/>

toolbaritem-hotkeydisplaystring