UserGuide

iOS Toolbars

From Xojo Documentation

A view can have a Navigation Bar, which displays at the top of the view, or a toolbar which displays at the bottom of the view. In a horizontally regular environment, a navigation bar can also display within a view that doesn’t extend across the screen, such as one pane of a split view controller.

To add a Tool Button to the Navigation Bar, drag a Tool Button from the Library to the the top part of the View. If the Navigation Bar is not visible, then the NavigationBarVisible property will automatically be turned ON. Tool Buttons can be added to the left or right side of the Navigation Bar.

To add a Tool Button to the Tool Bar, drag a Tool Button from the Library to the bottom part of the View.

Toolbar Buttons on the Navigation Bar and Toolbar

You can also add Tool Buttons to a Navigation Bar or Tool Bar via code as shown below. Refer to Handling Toolbar Button Presses to determine what toolbar button was pressed.

Navigation Bar

To display the Navigation Bar, set the NavigationBarVisible property to True. You can do this in the Inspector for the view or in code, usually in the Open event handler for the view:

NavigationBarVisible = True

Buttons can be placed on the left side or right side of the Navigation Bar. To add buttons, use the LeftNavigationToolbar and RightNavigationToolbar properties. These properties return a toolbar (iOSToolbar) which has several methods you can use to add the buttons. Typically you will set up the toolbar in the Open event handler of the view. This code adds a save button to the right navigation toolbar:

RightNavigationToolbar.Add(iOSToolButton.NewPlain("Save"))

Breaking this command apart, you can see the Add method of iOSToobar is called to add the button. The Add method has a parameter for the button (iOSToolButton) to add. The button is created by calling the NewPlain shared method of iOSToolButton to create a plain button with the caption of "Save".

The iOSToolButton class has many shared methods you can use for creating different types of buttons (and spaces). You can create buttons with a text caption or with an icon, but not both.

If you are using an icon, note that only the mask of the icon is used. Multicolor icons are not used on iOS, so the mask is used with the standard OS tint color applied to it. Toolbar icons should be a maximum of about 66x66, but you can refer to the Apple Docs on Icon Sizes for more information.

This example adds a button using an image that was added to the project:

Dim b As iOSToolButton
b = iOSToolButton.NewPlain(ButtonImage) // ButtonImage is an image in the project
LeftNavigationToolbar.Add(b)

You can also add buttons that use one of the default system images. Use the NewSystemItem shared method of iOSToolButton along with the Types enumeration to choose the system icon you want to use. This example adds a button using the SystemRefresh icon:

// Create the button
Dim button As iOSToolButton
button = iOSToolButton.NewSystemItem(iOSToolButton.Types.SystemRefresh)

// Add it to the view
RightNavigationToolbar.Add(button)

Toolbar

To display a toolbar (which appears at the bottom of the view), add buttons to it using the Toolbar property of the view the same way you did with the Navigation Bar properties above. This example adds the SystemAdd button to the toolbar:

Toolbar.Add(iOSToolButton.NewSystemItem(iOSToolButton.Types.SystemAdd))

Handling Toolbar Button Presses

You use the ToolbarPressed event handler to check which toolbar button was pressed. This event handler is called for toolbar buttons that are pressed on either the Navigation Bar or the Toolbar. You are supplied with one parameter, which is the button that was pressed. You can then check this button to determine what was pressed so you can call the appropriate code.

This code checks to see if a system button was pressed and if not, then checks the caption of the button to see what was pressed:

Select Case button.Type
Case iOSToolButton.Types.SystemEdit
// Edit
Case Else
Select Case button.Caption
Case "Report"
// Show report
End Select
End Select

If you've added toolbar buttons using the Layout Editor, you can more easily check which button was pressed by using its name. For example, if you have an EditButton and a SaveButton on the Navigation toolbar, you can check to see which was pressed with this code:

Select Case button
Case EditButton
// Edit was pressed
Case SaveButton
// Save was pressed
End Select

Toolbar Organization

Regardless of which toolbar you are using (Navigation Bar or Toolbar), you can control the buttons and their positions. For the Navigation Bar, keep in mind that you do not have a lot of room to work with (since the view title appears in the center) so only a few buttons can be displayed on each side. With the Toolbar, you have the entire width of the device, so you have more flexibility.

The examples above all used the Add method of iOSToolbar to add buttons. This adds buttons from left to right, with the new button appear to the right of the last button added.

You can also use the Insert method to add a button at a specific position. You can also remove all the buttons at once or remove individual buttons (RemoveAll, RemoveAllByValue, RemoveByIndex, RemoveByValue).

In addition to adding buttons as shown above, the iOSToolButton class lets you add two types of special "space" buttons: FixedSpace and FlexibleSpace. These are not actual buttons since they cannot be clicked but they do take up space on the toolbar. They are used to give your buttons separation or to force some buttons to always appear on the right side of the toolbar.

See Also

iOSToolbar, iOSToolButton, iOSView classes; UserGuide:iOS UI topic