Xojo Menus

Introduction

Apps use menus to give users access to the available actions offered by the application. In Xojo, you can use three different types of menus: MenuBar menus, Toolbar menus and Contextual menus. This lesson discusses the use of these three types applied to our Account example.

MenuBar menu

Create a menu with the Menu Editor

The Menubar menu is the standard main menu that appears almost always at the top of the screen. When creating a new desktop project, Xojo will always add a minimal menu (MainMenuBar) to the application.

All items of MainMenuBar are globally available from all methods in the App.

The Xojo Menu Editor is a very convenient and easy tool to edit the MainMenuBar. You can open the Menu Editor by selecting MainMenuBar in the project browser (see previous screenshot).

File, Edit and Help are first level menu items available in the standard menu. The first level menu item Accounts have been added to this menu (with the first icon in the list).

The menu items SavingsAccount, CheckingAccount and RetirementAccount have been added to the first level Accounts menu item (with the second icon in the list).

In the inspector, you need to define the Nameof the control (e.g. SavingsAccountItem) and the Textthat will be displayed (e.g.SavingsAccount). An Icon and a Shortcut can also be added.

How to set actions on a menu item?

To illustrate the use of menus, I have removed the DesktopPopupMenu (AccountPopup) from the previous lesson and will use the selected menu item to run the program. This is the new design:

Now the menu is available, but no actions are defined yet when selecting any of the new menu items. An action can be defined via a Menu Handler.

A Menu Handler can be added via the Insert button on top of the Xojo screen. In the Inspector, select the menu item from the drop-down list for which you want to define an action (e.g. CheckingAccountItem).

In the coding pane, you can then define the action associated with the selected menu item.

//Menu Handler for CheckingAccountItem
SelectedMenuItem = CheckingAccountItem.Text
ProcessSelection
Return True

SelectedMenuItem is a new private String Property belonging to AccountWindow. The Textproperty of the CheckingAccountItemmenu item is a String containing the text displayed in the menu. In the above code, the SelectedMenuItem Property will contain the String “CheckingAccount”.

Identical menu handlers should be added for the SavingsAccountItem and the RetirementAccountItem.

The new method named ProcessSelection uses the private property named SelectedMenuItem to determine which data should be retrieved from the database and shown in TransactionList.

//ProcessSelection
ChangeActiveAccount

Var rs As RowSet = ReadDBData
PopulateListBox(rs) 

Var balance As Currency = CalculateBalance 
ActiveAccount.UpdateBalance(balance)
ShowBalance

Also, the ReadDBData method, the ShowBalance method and the ChangeActiveAccount method now use the value stored in the property SelectedMenuItem.

//ReadDBData
Var rs As RowSet
Var sql As String = "SELECT AccountName, AccountDeposit, AccountWithdraw  FROM Accounts WHERE AccountName =  ?;" 
Try
  rs = App.db.SelectSQL(sql, selectedMenuItem)
Catch error As DatabaseException
  Messagebox("DB Select error "+error.Message)
  Quit
End Try
Return rs

//ShowBalance
BalanceLabel.Text = "The balance of the " + selectedMenuItem + " is: " + _ 
ActiveAccount.GetBalance.ToString(Locale.Current)

//ChangeActiveAccount
Select Case SelectedMenuItem
Case "CheckingAccount"
  ActiveAccount = CheckingAccount
Case "SavingsAccount"
  ActiveAccount = SavingsAccount
Case "RetirementAccount"
  ActiveAccount = RetirementAccount
End 

Toolbar menu

How to create a Toolbar menu?

Xojo also offers the ability to add a toolbar to any window in the application. A toolbar can be added by selecting the Toolbar control in the library and adding it to your project. A Toolbar object (e.g. Toolbar1) can then be dragged into a window. The name of the Toolbar object in AccountWindow was then changed to AccountToolbar.

AccountToolbar can be edited afterwards with the Menu Editor to add buttons and menu items to the toolbar. However, it is also possible to construct a menu using code. This will be illustrated in this part of the lesson.

The following code is available in the Opening event of AccountToolbar:

//AccountToolbar Opening event
Var accountsButton As New DesktopToolbarButton
accountsButton.Caption = "Accounts"
accountsButton.Icon = image1
accountsButton.ButtonStyle = DesktopToolbarButton.ButtonStyles.DropDownMenu

Var accountsMenu As New DesktopMenuItem
accountsMenu.AddMenu(New DesktopMenuItem("CheckingAccount"))
accountsMenu.AddMenu(New DesktopMenuItem("RetirementAccount"))
accountsMenu.AddMenu(New DesktopMenuItem("SavingsAccount"))

accountsButton.Menu = accountsMenu

Me.AddButton(accountsButton)

A toolbar consists of a series of buttons. A toolbar button can support one action or can support multiple actions through an underlying menu structure. In our example, we have one button that refers to the three types of accounts.

In the first part of the code above, we create a toolbar button named accountsButton with the Caption Accounts and with image1 as the Icon. Image1 is an image added to the project. The ButtonStyle is a DropDownMenu. Other button styles are PushButton, ToggleButton, Space, Flexible Space and so on.

In the second part of the code, we create the underlying menu structure accountsMenu consisting of three menu items: CheckingAccount, RetirementAccount and SavingsAccount. Menu items are always objects of the class DesktopMenuItem.

The AddMenu method adds a DesktopMenuItem to a DesktopMenuItem menu.

In the third part of the code, we define the menu (accountsMenu) as a dropdown menu of accountsButton.

The Menu property of a DesktopToolbarButton is used to assign a dropdown menu.

In the fourth part of the code, we add the button (accountsButton) to the AccountToolbar (Me refers to the object to which the Opening event applies).

The AddButton method is used to add a DesktopToolbarButtonto a toolbar.

How to handle a selection?

The MenuItemSelected event of AccountToolbar is available to handle a selection of a dropdown menu item. The local variable selectedItem (parameter of the event named MenuItemSelected) refers to the selected item. The Text property of selectedItem contains the text shown in the menu. This is the code used:

//MenuItemSelected(item As DesktopToolbarItem, selectedItem As DesktopMenuItem)
SelectedMenuItem = selectedItem.Text
ProcessSelection

The property selectedMenuItem receives the text of the item that was selected in the menu. As you may recall from the discussion of the MenuBar menu, further processing is done by the method called ProcessSelection. Our program still works fully, but now with the Toolbar menu.

Contextual Menu

A Contextual menu appears when a user right-clicks on a control. In the screenshot above, the user has called up a contextual menu related to the DesktopListBox control.

How to create a Contextual menu?

A contextual menu can be created via an event called ConstructContextualMenu. This event can be selected via our DesktopListBox named TransactionList .

The following piece of code was added to the event ConstructContextualMenu:

//ConstructContextualMenu(base As DesktopMenuItem, x As Integer, y As Integer) As Boolean
base.AddMenu(New DesktopMenuItem("Sort Deposit column"))
base.AddMenu(New DesktopMenuItem("Sort Withdraw column"))
Return True

In the code above, DesktopMenuItems are added with the AddMenu method to the DesktopMenuItem parameter base. base is a parameter of the event ConstructContextualMenu and is the initial menu object. All items added to base will be displayed.

How to handle a selection?

The event ContextualMenuItemSelected will be triggered by the selection of an item in a contextual menu. The Text property of selectedItem (parameter of the ContextualMenuItemSelected event) contains the text displayed in the selected item.

//ContextualMenuItemSelected(selectedItem As DesktopMenuItem) As Boolean
Select Case selectedItem.Text
Case "Sort Deposit column"
  Me.ColumnSortDirectionAt(1) = DesktopListBox.SortDirections.Descending
  Me.SortingColumn = 1
  Me.Sort
Case "Sort Withdraw column"
  Me.ColumnSortDirectionAt(2) = DesktopListBox.SortDirections.Descending
  Me.SortingColumn = 2
  Me.Sort
End Select
Return True

To sort a column in a Listbox, the column number must be defined via the SortingColumn property and the sorting order (Descending or Ascending) via the ColumnSortDirectionAt method. The sorting itself is done by the method Sort .

Property	Type	Description
SortingColumn	Integer	The column of the ListBox to be sorted

Method	Type	Description
ColumnSortDirectionAt	Integer	Assigns a sort direction to the specified column (ascending/descending)
Sort		Sorts the ListBox based on the values assigned to ColumnSortDirectionAt and SortingColumn

Column numbers of a DesktopListBox begin at zero (0).