UserGuide

Desktop Toolbars

From Xojo Documentation

Toolbars appear at the top of a window and provide quick access to commonly used functionality. You create toolbars by adding them to your project using the Insert ↠ Toolbar command on the toolbar or menu. Select the toolbar in the Navigator to edit it.

Toolbar Editor

The UserGuide:Toolbar Editor is used to design your toolbar. You can add buttons to the toolbar, which can have one of the following styles:

  • Push button
  • Separator
  • Toggle button
  • Dropdown button
  • Separate dropdown button
  • Space
  • Flexible space
Toolbar Editor

To add a button to the toolbar, click the "Add Tool Item" button in the Toolbar Editor toolbar. Use the Inspector to change the properties of the buttons that you add to the toolbar.

For best results, you should ensure that all your toolbar icons are the same size. Some platforms will size all icons to that of the icon on the first button in the toolbar.

After adding items to the toolbar, you can reorder them by dragging an item to the left or right. You can preview the toolbar on other platforms by clicking one of the Toolbar preview mode buttons in the Toolbar toolbar.

To add a toolbar to a Window, select the Window and then drag the toolbar from the Navigator onto the Window layout. The toolbar will appear at the bottom in the Shelf area.

You can have multiple toolbars in your app, but you can only add a single toolbar to each window.

Toolbar Class

Below are commonly used events, properties and methods for the Toolbar. Refer to Toolbar in the Language Reference for the complete list.

Events

Action

The Action event handler is where your code handles button presses. The supplied Item parameter tells you the button that was clicked so that you can perform the appropriate action.

DropDownMenuAction

This event handler is called when a button that has a drop-down menu has an item on the menu selected.

Open

The standard event where you would do any initialization, such as assigning icons or drop-down menus.

Properties

Visible

Use the Visible property to hide or show the toolbar.

Methods

Append

Used to add a button to the end of the toolbar.

Count

Tells you the number of buttons on the toolbar.

Insert

Used to insert a button at a specific position on the toolbar.

Item

Allows you to directly access the buttons on the toolbar by specifying a zero-based index to a button.

Remove

Used to remove a button from the toolbar.

Tool Button Class

A ToolButton is a button that you add to the toolbar. When the user clicks a button (that is clickable, not all styles can be clicked), the toolbar Action event handler is called.

Each button that you add to the toolbar in the Toolbar Editor is accessible as a property of the toolbar. For example, if you add a button called EditButton to the Toolbar, you can access it by referring to it by name:

Toolbar1.EditButton.Visible = False

Below are the common properties for a ToolButton. Refer to ToolButton in the Language Reference for the complete list.

Properties

Caption

The text that displays on the button.

DropDownMenu

Assign the menu to display (only used by buttons with the Drop- down button or Separate dropdown button styles).

Enabled

Used to enable or disable a button.

HelpTag

This is the tooltip that is displayed when the mouse hovers over the button.

Icon

The icon for the button. You can use any size icon you like, but for best results all the icons for all your buttons should be the same size. 32x32 is a common button size.

Name

The name you give the button can be accessed as a property of the toolbar when the toolbar has been added to a window.

Pushed

For toggle buttons, allows you to specify and check whether the button is pushed.

Style

The style describes how the button works. There are several styles:
  • Push button: Works like a standard button. The user can click it.
  • Separator: A separator is a vertical line in the toolbar. The user cannot click a separator. Not supported on macOS 10.7 and later.
  • Toggle button: A toggle button retains it selection when clicked. The behavior of multiple toggle buttons varies by platform. On Mac, only one toggle button may be selected at one time. On Windows, multiple toggle buttons may be selected at one time.
  • Dropdown Button: This is a Push button with an attached menu. Clicking the button displays the menu. On Windows an arrow is drawn next to the button icon to indicate there is a menu. You can only specify the menu in code, usually the Open event handler for the toolbar. When the user selects an item from the menu, the DropDownAction event handler on the toolbar is called.
  • Separate Dropdown button: The ToolButton is a drop-down menu with a separate down arrow on its right. Use the Caption and Icon properties to assign the Toggle button’s label and icon. The user can click on the button separately from the menu. When the user clicks just the button, the Action event handler is called. 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. Supports Windows and Linux only. On Mac, this style behaves the same as Dropdown button.
  • Space: Creates a space in the toolbar. The user cannot click the space. Supported on Mac and Linux.
  • Flexible space: Creates a variable-width space that is used to right-align buttons on the toolbar. All buttons that are to the right of the Flexible space appear on the right-hand side of the toolbar. Supported on Mac and Linux.

Adding a Toolbar to a Window

To add a toolbar to a window, you drag it from the Navigator to the Window Layout Editor. The toolbar is added to the Shelf. When your application runs, the toolbar is automatically added to the top of the window and your controls are shifted down accordingly. On Mac, if the window is not wide enough to show all the toolbar buttons, an "overflow" icon displays which can be clicked to allow you to still access the other toolbar icons that do not fit.

You cannot directly edit the toolbar on the Window. Select the Toolbar in the Navigator to go back to the Toolbar Editor and make changes.

Adding multiple toolbars to a window is not supported.

Toolbar Usage

Desktop Toolbars

Handling Toolbar Button Presses

When any toolbar button is pressed, the Action event handler for the toolbar itself is called. This event supplies an item parameter that contains the information about which button was pressed.

Toolbar in Desktop App

For example, here is the Action event handler for a simple toolbar with Open and Save buttons. It tests the Name property for each button to see which one was selected:

Select Case Item.Name
Case "OpenButton"
MsgBox("Open clicked.")
Case "SaveButton"
MsgBox("Save clicked.")
End Select

If a dropdown menu item on a toolbar button was selected, the DropDownMenuAction event handler is called with a parameter telling you what menu was selected.

You'll need to add any items for the dropdown menu in code, refer to the next section for an example.

Toolbar with DropDown Menu

Here is a DropDownMenuAction event handler for a Clipboard Dropdown button with three items in the menu:

If item.Name = "ClipButton" Then
Select Case hitItem.Text
Case "Cut"
MsgBox("Chose Cut.")
Case "Copy"
MsgBox("Chose Copy.")
Case "Paste"
MsgBox("Chose Paste.")
End Select
End If

Adding Toolbar Buttons in Code

In addition to setting up the toolbar using the Toolbar Editor, you can also do all the toolbar setup programmatically. You need to do this if you are using either of the Dropdown buttons as you can only specify the menu in code.

Adding a Toolbar to a Window

You might also want to do this if you have buttons you want to dynamically enable or disable, or even show or hide.

This code in the toolbar Open event handler adds a menu to a Dropdown button:

Dim baseMenu As New MenuItem
Dim m as MenuItem
m = New MenuItem("Cut")
baseMenu.Append(m)
m = New MenuItem("Copy")
baseMenu.Append(m)
m = New MenuItem("Paste")
baseMenu.Append(m)
Me.ClipButton.DropdownMenu = baseMenu

See Also

Toolbar, ToolButton classes; UserGuide:Toolbar Editor topic; Adding a Toolbar to a Window, Desktop Toolbars videos