Desktop Toolbars
From Xojo Documentation
Contents
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
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
- This event handler is where your code handles button presses. The supplied Item parameter tells you the button that was pressed so that you can perform the appropriate action.
- This event handler is called when a button that has a drop-down menu has an item on the menu selected.
- The standard event where you would do any initialization, such as assigning icons or drop-down menus.
Properties
- Use the Visible property to hide or show the toolbar.
Methods
- Used to add a button to the end of the toolbar.
- Tells you the number of buttons on the toolbar.
- Used to add a button at a specific position on the toolbar.
- Allows you to directly access the buttons on the toolbar by specifying a zero-based index to a button.
- Used to remove a button from the toolbar.
ToolbarButton Class
A ToolbarButton 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 Pressed 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:
Below are the common properties for a ToolButton. Refer to ToolbarButton in the Language Reference for the complete list.
Properties
- The text that displays on the button.
- Assign the menu to display (only used by buttons with the Drop- down button or Separate dropdown button styles).
- Used to enable or disable a button.
- This is the tooltip that is displayed when the mouse hovers over the button.
- 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.
- The name you give the button can be accessed as a property of the toolbar when the toolbar has been added to a window.
- For toggle buttons, allows you to specify and check whether the button is pushed.
- 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 MenuItemSelected event handler on the toolbar is called.
- Separate Dropdown button: The ToolbarButton 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 Pressed event handler is called. To specify the menu, assign it to the Menu property of the ToolbarButton class. Handle the selected menu item in the MenuItemSelected 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.
Get and Set this property using the ButtonStyles enumeration.
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
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.
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:
Case "OpenButton"
MessageBox("Open clicked.")
Case "SaveButton"
MessageBox("Save clicked.")
End Select
If a dropdown menu item on a toolbar button was selected, the MenuItemSelected 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.
Here is a MenuItemSelected event handler for a Clipboard Dropdown button with three items in the menu:
Select Case selectedItem.Value
Case "Cut"
MessageBox("Chose Cut.")
Case "Copy"
MessageBox("Chose Copy.")
Case "Paste"
MessageBox("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.
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:
Var m As MenuItem
m = New MenuItem("Cut")
baseMenu.AddMenu(m)
m = New MenuItem("Copy")
baseMenu.AddMenu(m)
m = New MenuItem("Paste")
baseMenu.AddMenu(m)
Me.ClipButton.Menu = baseMenu
See Also
Toolbar, ToolbarButton classes; UserGuide:Toolbar Editor topic; Adding a Toolbar to a Window, Desktop Toolbars videos