` | `Variant` | | |
## Constants
The following class constants can be used to specify the style of the **ToolButton**.
| Class Constants | Description |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ToolStylePushButton | The **ToolButton** is a push button. Clicking the button calls the Action event of the toolbar. |
| ToolStyleToggleButton | The **ToolButton** toggles when pushed. Clicking the button calls the Action event of the toolbar. |
| ToolStyleSeparator | The **ToolButton** is a separator. (Supported on Windows and Linux only.) |
| ToolStyleDropDown | The **ToolButton** displays a drop-down menu when clicked. On Windows, the button displays with a drop-down indicator and clicking anywhere on the button displays the drop-down menu. On Linux this style works the same as ToolStyleSeparateDropDown. A drop-down indicator does not appear on macOS. The DropDownMenuAction event on the toolbar is called when a menu item is selected. |
| ToolStyleSeparateDropDown | The **ToolButton** displays a separate drop-down indicator in the button. Clicking this indicator displays the drop-down menu. Clicking the main button area calls the Action event for the toolbar. The DropDownMenuAction event on the toolbar is called when a menu item is selected. On macOS this style works the same as ToolStyleDropDown. |
| ToolStyleSpace | The **ToolButton** is a fixed-width space. (Supported on macOS and Linux only.) |
| ToolStyleFlexibleSpace | The **ToolButton** is a flexible space. (Supported on macOS and Linux only.) |
## Property descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Caption
**Caption** As `String`
forsearch
ToolButton.DropDownMenu
**DropDownMenu** As `MenuItem`
The drop-down menu that is used with a button of style DropDown or SeparateDropDown. Use the Style property to set the type of button.
This example is in the ToolButton example discussed on the page for this class. This code is in the Open event of the ToolButton. It builds the menu, attaches it to a DropDownButton, and appends it to the toolbar.
``` xojo
DropDownButton = New ToolButton
DropDownButton.Style = ToolButton.ToolStyleDropDown
DropDownButton.Caption = "Cities"
' create a menu
Dim myMenu As New MenuItem
Dim myMenuItem1 As New MenuItem
Dim myMenuItem2 As New MenuItem
Dim myMenuitem3 As New MenuItem
DropDownButton.Name = "Cities Menu"
myMenu.Text = "Cities"
myMenuItem1.Text = "Grand Blanc"
myMenuItem2.Text = "Bad Axe"
myMenuitem3.Text = "Flint"
myMenu.Append(myMenuItem1)
myMenu.Append(myMenuItem2)
myMenu.Append(myMenuItem3)
' assign the new menu to the toolitem..
DropDownButton.DropdownMenu = myMenu
' add to the toolbar
Me.Append(DropDownButton)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Enabled
**Enabled** As `Boolean`
`True` if the **ToolItem** is enabled.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.HelpTag
**HelpTag** As `String`
The help tip that is displayed when the pointer is over the **ToolItem**.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Icon
**Icon** As `Picture`
The picture to be displayed by the ToolButton.
This example adds icons to the Cities menu and each MenuItem in the Open event of the Toolbar.
``` xojo
DropDownButton = New ToolButton
DropDownButton.Style = ToolButton.ToolStyleDropDown
DropDownButton.Caption = "Cities"
' create a menu
Dim myMenu As New MenuItem
Dim myMenuItem1 As New MenuItem
Dim myMenuItem2 As New MenuItem
Dim myMenuitem3 As New MenuItem
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.Append(myMenuItem1)
myMenu.Append(myMenuItem2)
myMenu.Append(myMenuItem3)
' assign the new menu to the toolitem..
DropDownButton.DropdownMenu = myMenu
' add to the toolbar
Me.Append(DropDownButton)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Name
**Name** As `String`
The name of the **ToolItem**.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Pushed
**Pushed** As `Boolean`
True if the ToolButton was pushed. It can be used to set the toggled state of a toggle-style ToolButton at runtime.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Style
**Style** As `Integer`
Determines the type of button.
Use the following class constants:
| Class Constant | Description |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ToolStylePushButton | The ToolButton is a pushbutton. |
| ToolStyleToggleButton | The ToolButton 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 "Pushed" state at one time. Pushing one changes the state of the other toggle buttons, effectively making them work similarly to RadioButtons. |
| ToolStyleSeparator | The ToolButton is a separator. Not supported on macOS. |
| ToolStyleDropDown | The ToolButton is a drop-down menu. On Windows, an arrow is drawn by default. To specify the menu, assign it to the DropDownMenu property of the ToolButton class. Handle the selected menu item in the DropDownMenuAction event of the `Toolbar` class. See the example for the ToolButton class. |
| ToolStyleSeparateDropDown | The ToolButton 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 DropDownMenu property of the ToolButton class. Handle the selected menu item in the DropDownMenuAction event of the `Toolbar` class. See the example for the ToolButton class. |
| ToolStyleSpace | The ToolButton is a fixed-width space between ToolButtons. **This is not supported on Windows**, so no extra button or space appears. |
| ToolStyleFlexibleSpace | The ToolButton is a variable-width space between ToolButtons. 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. |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ToolButton.Tag
**Tag** As `Variant`
A “hidden” value associated with the tool item.
The tag is accessible via code when the user chooses the tool item but, unlike the Caption property, is not displayed in the toolbar.
This example is in the Toolbar Open event of the main window.
``` xojo
Me.SaveButton.Tag = folderItemToSave
```
## Sample code
This code creates a ToolButton of style Drop-down and adds it to the toolbar. The window has a property DropDownButton as ToolButton. The Open event of the Toolbar in the window has the following code:
``` xojo
Dim dropDownButton As New ToolButton
dropDownButton.Style = ToolButton.ToolStyleDropDown
dropDownButton.Caption = "Cities"
dropDownButton.Name = "CitiesMenu"
' Create a menu
Dim myMenu As New MenuItem
myMenu.Append(New MenuItem("Grand Blanc"))
myMenu.Append(New MenuItem("Bad Axe"))
myMenu.Append(New MenuItem("Flint"))
' Assign the new menu to the toolitem..
dropDownButton.DropDownMenu = myMenu
' Add to the toolbar
Me.Append(dropDownButton)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The following code in the `Toolbar's` DropDownMenuAction event handles the menu selection.
``` xojo
Event DropDownMenuAction(item As ToolItem, hitItem As MenuItem)
Select Case hitItem.Text
Case "Grand Blanc"
MsgBox("You chose Grand Blanc from the " + item.Name + " .")
Case "Flint"
MsgBox("You chose Flint from the " + item.Name + " .")
Case "Bad Axe"
MsgBox("you chose Bad Axe from the " + item.Name + " .")
End Select
End Event
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This code adds a toggle style button to the toolbar. This code is in the Open event of the Toolbar:
``` xojo
Dim toggleButton As New ToolButton
toggleButton.Style = ToolButton.ToolStyleToggleButton
toggleButton.Caption = "Toggle"
Me.Append(toggleButton)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This code will push a toggle style button that is the first button on a toolbar (code is in the Open event handler of the Toolbar):
``` xojo
ToolButton.Pushed = Not ToolButton.Pushed
```
## Compatibility
All project types on all supported operating systems.
## See also
`ToolbarItem` parent class; `Toolbar`, `ToolbarItem` classes.