Class

# DesktopToolbarButton

<div class="rst-class">

forsearch

</div>

Toolbar

<div class="rst-class">

forsearch

</div>

ToolbarButton

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

A button for a `DesktopToolbar</api/user_interface/desktop/desktoptoolbar>`. Use the <span class="title-ref">DesktopToolbarButton</span> class to create the items in cross-platform toolbars.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                                | Type                                                           | Read-Only | Shared |
|---------------------------------------------------------------------|----------------------------------------------------------------|-----------|--------|
| `AllowMulticolorSymbol<desktoptoolbarbutton.allowmulticolorsymbol>` | `Boolean</api/data_types/boolean>`                             |           |        |
| `ButtonStyle<desktoptoolbarbutton.buttonstyle>`                     | `ButtonStyles<desktoptoolbarbutton.buttonstyles>`              |           |        |
| `Caption<desktoptoolbarbutton.caption>`                             | `String</api/data_types/string>`                               |           |        |
| `Enabled<desktoptoolbarbutton.enabled>`                             | `Boolean</api/data_types/boolean>`                             |           |        |
| `Icon<desktoptoolbarbutton.Icon>`                                   | `Picture</api/graphics/picture>`                               |           |        |
| `Menu<desktoptoolbarbutton.menu>`                                   | `DesktopMenuItem</api/user_interface/desktop/desktopmenuitem>` |           |        |
| `Name<desktoptoolbarbutton.name>`                                   | `String</api/data_types/string>`                               |           |        |
| `Pressed<desktoptoolbarbutton.pressed>`                             | `Boolean</api/data_types/boolean>`                             |           |        |
| `Symbol<desktoptoolbarbutton.symbol>`                               | `String</api/data_types/string>`                               |           |        |
| `Tag<desktoptoolbarbutton.tag>`                                     | `Variant</api/data_types/variant>`                             |           |        |
| `Tooltip<desktoptoolbarbutton.tooltip>`                             | `String</api/data_types/string>`                               |           |        |

## Enumerations

<div id="desktoptoolbarbutton.buttonstyles">

<div class="rst-class">

forsearch

</div>

</div>

DesktopToolbarButton.ButtonStyles

### ButtonStyles

> Specifies the type of button.
>
> | enum             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
> |------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> | PushButton       | The ToolButton is a pushbutton.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
> | ToggleButton     | The ToolbarButton is a button that toggles between its normal and depressed state. It does not affect the state of any other Toggle buttons in the Toolbar. On macOS, only a single ToggleButton may be in the "Pressed" state at one time. Pressing one changes the state of the other toggle buttons, effectively making them work similarly to RadioButtons.                                                                                                                                                                            |
> | Separator        | The ToolbarButton is a separator. Not supported on macOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
> | DropDown         | The ToolbarButton is a drop-down menu. On Windows, an arrow is drawn by default. To specify the menu, assign it to the `Menu<desktoptoolbarbutton.menu>` property of the <span class="title-ref">DesktopToolbarButton</span> class. Handle the selected menu item in the `MenuItemSelected<desktoptoolbar.menuitemselected>` event of the `DesktopToolbar</api/user_interface/desktop/desktoptoolbar>` class. See the example for the ToolbarButton class.                                                                                 |
> | SeparateDropDown | The ToolbarButton is a drop-down menu with a separate down arrow on its right. There is room for the caption and the icon. To specify the menu, assign it to the `Menu<desktoptoolbarbutton.menu>` property of the <span class="title-ref">DesktopToolbarButton</span> class. Handle the selected menu item in the `MenuItemSelected<desktoptoolbar.menuitemselected>` event of the `DesktopToolbar</api/user_interface/desktop/desktoptoolbar>` class. See the example for the <span class="title-ref">DesktopToolbarButton</span> class. |
> | Space            | The ToolbarButton is a fixed-width space between ToolbarButtons. This is not supported on Windows, so no extra button or space appears.                                                                                                                                                                                                                                                                                                                                                                                                    |
> | FlexibleSpace    | The ToolbarButton is a variable-width space between ToolbarButtons. It right-aligns the buttons to its right as the window is resized. This is not supported on Windows, so no extra space or button will be inserted.                                                                                                                                                                                                                                                                                                                     |

## Property descriptions

<div id="desktoptoolbarbutton.allowmulticolorsymbol">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.AllowMulticolorSymbol

**AllowMulticolorSymbol** As `Boolean</api/data_types/boolean>`

> When `True</api/language/true>`, allows the symbol specified by the `Symbol<desktoptoolbarbutton.symbol>` property to render in its full color palette rather than as a monochrome template image. This property is only supported on macOS; it has no effect on other platforms. The default value is `False</api/language/false>`.

<div id="desktoptoolbarbutton.buttonstyle">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.ButtonStyle

**ButtonStyle** As `ButtonStyles<desktoptoolbarbutton.buttonstyles>`

> Determines the type of button.
>
> Get and set this property using the `DesktopToolbarButton<desktoptoolbarbutton.buttonstyles>` enumeration.

<div id="desktoptoolbarbutton.caption">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Caption

**Caption** As `String</api/data_types/string>`

> The caption of the ToolbarItem.
>
> This property can be set inside the IDE or programmatically.
>
> To set an accelerator character, precede the character in the Caption with an ampersand. In order to show an ampersand in the Caption, use two ampersands in a row.
>
> This code sets the caption of the ToolBarItem to "Bold".
>
> ``` xojo
> Me.Caption = "Bold"
> ```

<div id="desktoptoolbarbutton.enabled">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Enabled

**Enabled** As `Boolean</api/data_types/boolean>`

> `True</api/language/true>` if the **DesktopToolbarItem** is enabled.

<div id="desktoptoolbarbutton.icon">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Icon

**Icon** As `Picture</api/graphics/picture>`

> The picture to be displayed by the <span class="title-ref">DesktopToolbarButton</span>.
>
> This example adds icons to the Cities menu and each `DesktopMenuItem</api/user_interface/desktop/desktopmenuitem>` in the Opening event of the `DesktopToolbar</api/user_interface/desktop/desktoptoolbar>`.
>
> ``` xojo
> Var DropDownButton As New DesktopToolbarButton
> DropDownButton.ButtonStyle = DesktopToolbarButton.ButtonStyles.DropDownMenu
> DropDownButton.Caption = "Cities"
>
> ' create a menu
> Var myMenu As New DesktopMenuItem
> Var myMenuItem1 As New DesktopMenuItem
> Var myMenuItem2 As New DesktopMenuItem
> Var myMenuitem3 As New DesktopMenuItem
>
> DropDownButton.Name = "Cities Menu"
> myMenu.Text = "Cities"
> myMenu.Icon = IndiaImage
>
> myMenuItem1.Text = "Grand Blanc"
> myMenuItem2.Text = "Bad Axe"
> myMenuitem3.Text = "Flint"
> ' icons added to the project
> myMenuItem1.Icon = SaturnImage
> myMenuItem2.Icon = VenusImage
> myMenuItem3.Icon = UranusImage
> myMenu.AddMenu(myMenuItem1)
> myMenu.AddMenu(myMenuItem2)
> myMenu.AddMenu(myMenuItem3)
>
> ' assign the new menu to the toolbar button.
> DropDownButton.Menu = myMenu
>
> ' add to the toolbar
> Me.AddButton(DropDownButton)
> ```

<div id="desktoptoolbarbutton.menu">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Menu

**Menu** As `DesktopMenuItem</api/user_interface/desktop/desktopmenuitem>`

> The menu that is used with a button of style DropDown or SeparateDropDown. Use the `ButtonStyle<desktoptoolbarbutton.buttonstyle>` property to set the type of button.
>
> This example is in the <span class="title-ref">DesktopToolbarButton</span> example discussed on the page for this class. This code is in the Opening event of a DesktopToolbar. It builds the menu, attaches it to a DropDownButton, and adds it to the toolbar.
>
> ``` xojo
> DropDownButton = New DesktopToolbarButton
> DropDownButton.ButtonStyle = DesktopToolbarButton.ButtonStyles.DropDownMenu
> DropDownButton.Caption = "Cities"
>
> ' create a menu
> Var myMenu As New DesktopMenuItem
> Var myMenuItem1 As New DesktopMenuItem
> Var myMenuItem2 As New DesktopMenuItem
> Var myMenuitem3 As New DesktopMenuItem
>
> DropDownButton.Name = "Cities Menu"
> myMenu.Text = "Cities"
>
> myMenuItem1.Text = "Grand Blanc"
> myMenuItem2.Text = "Bad Axe"
> myMenuitem3.Text = "Flint"
> myMenu.AddMenu(myMenuItem1)
> myMenu.AddMenu(myMenuItem2)
> myMenu.AddMenu(myMenuItem3)
>
> ' assign the new menu to the toolitem..
> DropDownButton.Menu = myMenu
>
> ' add to the toolbar
> Me.AddButton(DropDownButton)
> ```

<div id="desktoptoolbarbutton.name">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Name

**Name** As `String</api/data_types/string>`

> The name of the **DesktopToolbarItem**.

<div id="desktoptoolbarbutton.pressed">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Pressed

**Pressed** As `Boolean</api/data_types/boolean>`

> `True</api/language/true>` if the <span class="title-ref">DesktopToolbarButton</span> was pressed. It can be used to set the toggled state of a toggle-style <span class="title-ref">DesktopToolbarButton</span> at runtime.

<div id="desktoptoolbarbutton.symbol">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Symbol

**Symbol** As `String</api/data_types/string>`

> A semicolon-separated list of symbol names to use as the button's icon. At runtime, Xojo tries each name in order and uses the first one it can resolve on the current platform. If no symbol can be resolved, the `Icon<desktoptoolbarbutton.icon>` property is used as a fallback. Symbols are always preferred over icons when a matching name is found.
>
> Platform support:
>
> - **macOS** — SF Symbols. See [Apple's SF Symbols documentation](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) for available names.
> - **Linux** — Freedesktop icon names. Availability depends on the active theme, but many names from the [Freedesktop Icon Naming Specification](https://specifications.freedesktop.org/icon-naming) are broadly supported.
> - **Windows** — Only supported when WinUI is enabled. See the [Windows.UI.Xaml.Controls.Symbol enumeration](https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.symbol) for available names.
>
> This example sets the symbol with fallbacks for cross-platform use:
>
> ``` xojo
> item.Symbol = "document-open-symbolic;doc;Document"
> ```

<div id="desktoptoolbarbutton.tag">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Tag

**Tag** As `Variant</api/data_types/variant>`

> A "hidden" value associated with the toolbar item.
>
> The tag is accessible via code when the user chooses the toolbar item but, unlike the Caption property, is not displayed in the toolbar.
>
> This example is in the Toolbar Opening event of the main window.
>
> ``` xojo
> Me.SaveButton.Tag = folderItemToSave
> ```

<div id="desktoptoolbarbutton.tooltip">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopToolbarButton.Tooltip

**Tooltip** As `String</api/data_types/string>`

> The tooltip that is displayed when the pointer is over the **DesktopToolbarItem**.

## Sample code

This code creates a <span class="title-ref">DesktopToolbarButton</span> of style Drop-down and adds it to the toolbar. The window has a property DropDownButton as <span class="title-ref">DesktopToolbarButton</span>. The `Opening<desktopcontrol.opening>` event of the Toolbar in the window has the following code:

``` xojo
Var dropDownButton As New DesktopToolbarButton
dropDownButton.ButtonStyle = DesktopToolbarButton.ButtonStyles.DropDownMenu
dropDownButton.Caption = "Cities"
dropDownButton.Name = "CitiesMenu"

' Create a menu
Var myMenu As New DesktopMenuItem
myMenu.AddMenu(New DesktopMenuItem("Grand Blanc"))
myMenu.AddMenu(New DesktopMenuItem("Bad Axe"))
myMenu.AddMenu(New DesktopMenuItem("Flint"))

' Assign the new menu to the toolitem..
dropDownButton.Menu = myMenu

' Add to the toolbar
Me.AddButton(dropDownButton)
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

The following code in the `Toolbar's</api/user_interface/desktop/desktoptoolbar>` MenuItemSelected event handles the menu selection.

``` xojo
Event MenuItemSelected(button As DesktopToolbarItem, selectedItem As DesktopMenuItem)
  Select Case selectedItem.Text
  Case "Grand Blanc"
    MessageBox("You chose Grand Blanc from the " + selectedItem.Name + " .")
  Case "Flint"
    MessageBox("You chose Flint from the " + selectedItem.Name + " .")
  Case "Bad Axe"
    MessageBox("you chose Bad Axe from the " + selectedItem.Name + " .")
  End Select
End Event
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

This code adds a toggle style button to the toolbar. This code is in the `Opening<desktopcontrol.opening>` event of the Toolbar:

``` xojo
Var toggleButton As New DesktopToolbarButton
toggleButton.ButtonStyle = DesktopToolbarButton.ButtonStyles.ToggleButton
toggleButton.Caption = "Toggle"
Me.AddButton(toggleButton)
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

This code will push a toggle style button that is the first button on a toolbar (code is in the `Opening<desktopcontrol.opening>` event handler of the Toolbar):

``` xojo
ToolButton.Pressed = Not DesktopToolbarButton.Pressed
```

## Compatibility

|                       |         |
|-----------------------|---------|
| **Project Types**     | Desktop |
| **Operating Systems** | All     |

<div class="seealso">

`DesktopToolbarItem</api/user_interface/desktop/desktoptoolbaritem>` parent class; `DesktopToolbar</api/user_interface/desktop/desktoptoolbar>` class.

</div>