Class

ToolButton (deprecated)

Warning

This item was deprecated in version 2019r2. Please use ToolbarButton as a replacement.

Description

A button for a Toolbar. Use the ToolButton class to create the items in cross-platform toolbars.

Properties

Name	Type	Read-Only	Shared
Caption	String
DropDownMenu	MenuItem
Enabled	Boolean
HelpTag	String
Icon	Picture
Name	String
Pushed	Boolean
Style	Integer
Tag	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

ToolButton.Caption

Caption As String

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.

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)

ToolButton.Enabled

Enabled As Boolean

True if the ToolItem is enabled.

ToolButton.HelpTag

HelpTag As String

The help tip that is displayed when the pointer is over the ToolItem.

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.

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)

ToolButton.Name

Name As String

The name of the ToolItem.

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.

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.

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.

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:

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.

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:

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):

ToolButton.Pushed = Not ToolButton.Pushed

Compatibility

All project types on all supported operating systems.