Creating a Pop-up Menu

For most widgets, you need to create your own pop-up menu. In this section, you are going to learn how to supply a pop-up menu to a Gtk.ProgressBar widget. The pop-up menu we are going to implement is presented in Figure 10-1.

In most cases, you want to use button-press-event to detect when the user wants the pop-up menu to be shown. This allows you to check whether the right mouse button was clicked. If the right mouse button was clicked, Gdk.EventButton’s button member is equal to 3.

However, Gtk.Widget also provides the popup-menu signal, which is activated when the user presses built-in key accelerators to activate the pop-up menu. Most users use the mouse to activate pop-up menus, so this is not usually a factor in GTK+ applications. Nevertheless, if you would like to handle this signal as well, you should create a third function that displays the pop-up menu that is called by both callback functions.

New menus are created with Gtk.Menu.new(). The menu is initialized with no initial content, so the next step is to create menu items.

In most cases, you do not need to use the Gtk.MenuItem.new(), because a menu item with no content is not of much use. If you use that function to initialize the menu item, you have to construct each aspect of the menu in code instead of allowing GTK+ to handle the specifics.

The other type of basic menu item is Gtk.SeparatorMenuItem, which places a generic separator at its location. You can use Gtk.SeparatorMenuItem.new() to create a new separator menu item.

Separators are extremely important when designing a menu structure, because they organize menu items into groups so that the user can easily find the appropriate item. For example, in the File menu, menu items are often organized into groups that open files, save files, print files, and close the application. Rarely should you have many menu items listed without a separator in between them (e.g., a list of recent files might appear without a separator). In most cases, you should group similar menu items together and place a separator between adjacent groups.

After the menu items are created, you need to connect each menu item to the activate signal, which is emitted when the user selects the item. Alternatively, you can use the activate-item signal, which is also emitted when a submenu of the given menu item is displayed. There is no discernable difference between the two unless the menu item expands into a submenu.

Each activate and activate-item callback function receives the Gtk.MenuItem widget that initiated the action and any data you need to pass to the function. In Listing 10-2, three menu item callback functions are provided to pulse the progress bar, fill it to 100 percent complete, and clear all progress.

Additionally, you can use menu.prepend() or menu.insert() add a menu item to the beginning of the menu or insert it into an arbitrary position respectively. Positions accepted by menu.insert() begin with an index of zero.

The last parameter of menu.attach_to_widget() accepts a Gtk.MenuDetachFunc, which can call a specific function when the menu is detached from the widget.

Pop-up Menu Callback Methods

In Listing 10-2 all parameters were set to None except for the mouse button that was clicked to cause the event (event ➤ button) and the time when the event occurred (event.time). If the pop-up menu was activated by something other than a button, you should supply 0 to the button parameter.

Usually, parent_menu_shell, parent_menu_item, func, and func_data are set to None, because they are used when the menu is a part of a menu bar structure. The parent_menu_shell widget is the menu shell that contains the item that caused the pop-up initialization. Alternatively, you can supply parent_menu_item, which is the menu item that caused the pop-up initialization.

Gtk.MenuPositionFunc is a function that decides at what position on the screen the menu should be drawn. It accepts func_data as an optional last parameter. These parameters are not frequently used in applications, so they can safely be set to None. In our example, the pop-up menu was already associated with the progress bar, so it is drawn in the correct location.

The Status Bar Widget

While the status bar can only display one message at a time, the widget actually stores a stack of messages. The currently displayed message is on the top of the stack. When you pop a message from the stack, the previous message is displayed. If there are no more strings left on the stack after you pop a message from the top, no message is displayed on the status bar.

The context identifier is a unique unsigned integer that is associated with a context description string. This identifier is used for all messages of a specific type, which allows you to categorize messages on the stack.

For example, if your status bar holds hyperlinks and IP addresses, you could create two context identifiers from the strings “URL” and “IP”. When you push or pop messages to and from the stack, you have to specify a context identifier. This allows separate parts of your application to push and pop messages to and from the status bar message stack without affecting each other.

Menu Item Information

One useful role of the status bar is to give the user more information about the menu item the mouse cursor is currently hovering over. An example of this was shown in Figure 10-2, which is a screenshot of the progress bar pop-up menu application in Listing 10-4.

When implementing status bar hints, you first need to figure out what signals are necessary. We want to be able to add a message to the status bar when the mouse cursor moves over the menu item and remove it when the mouse cursor leaves. From this description, using "enter-notify-event" and "leave-notify-event" is a good solution.

Since the GTK+ 3 interface to Python 3 does not implement the get_data() and set_data() methods on GTK+ objects, we need to subclass the Gtk.MenuItem class to implement the corresponding Python 3 attributes. This methodology is used on some other examples in this book as well.

One advantage of using these two signals is that we only need one callback function, because the prototype for each receives a Gdk.EventProximity object. From this object, we can discern between Gdk.EventType.ENTER_NOTIFY and Gdk.EventType.LEAVE_NOTIFY events. You want to return False from the callback function, because you do not want to prevent GTK+ from handling the event; you only want to enhance what is performed when it is emitted.

Then, with statusbar.push(), the message can be added to the status bar under the "MenuItemHints" context identifier. This message is placed on the top of the stack and displayed to the user. You may want to consider processing all GTK+ events after calling this method, since the user interface should reflect the changes immediately.

However, if the event type is Gdk.EventType.LEAVE_NOTIFY, you need to remove the last menu item message that was added with the same context identifier. The most recent message can be removed from the stack with statusbar.pop().

Submenus

Submenus are very useful if you have a list of very specific options that would clutter an otherwise organized menu structure. When using a submenu, you can use the “activate-item” signal provided by the Gtk.MenuItem widget, which is emitted when the menu item displays its submenu.

In addition to Gtk.MenuItem and menu item separators, there are three other types of menu item objects: image, check, and radio menu items; these are covered in the remainder of this section.

Image Menu Items

Gtk.ImageMenuItem is very similar to its parent class Gtk.MenuItem except it shows a small image to the left of the menu item label. There are four functions provided for creating a new image menu item.

The second parameter of this function accepts an accelerator group, which is set to the default accelerator of the stock item. If you want to manually set the keyboard accelerator for the menu item as we did in Listing 10-3, you can specify None for this parameter.

Also, GTK+ provides Gtk.ImageMenuItem.new_with_mnemonic(), which creates an image menu item with a mnemonic label. As with the previous method, you have to set the image property after the menu item is created.

Check Menu Items

Gtk.CheckMenuItem allows you to create a menu item that displays a check symbol beside the label, depending on whether its Boolean active property is True or False. This would allow the user to view whether an option is activated or deactivated.

As with Gtk.MenuItem, three initialization functions are provided.

As previously stated, the current state of the check menu item is held by the active property of the widget. GTK+ provides two functions, checkmenuitem.set_active() and checkmenuitem.get_active() to set and retrieve the active value.

As with all check button widgets, you are able to use the "toggled" signal, which is emitted when the user toggles the state of the menu item. GTK+ takes care of updating the state of the check button, so this signal is simply to allow you to update your application to reflect the changed value.

Gtk.CheckMenuItem also provides checkmenuitem.set_inconsistent(), which alters the inconsistent property of the menu item. When set to True, the check menu item displays a third “in between” state that is neither active nor inactive. This can show the user that a choice must be made that has yet to be set or that the property is both set and unset for different parts of a selection.

Radio Menu Items

Gtk.RadioMenuItem is a widget derived from Gtk.CheckMenuItem. It is rendered as a radio button instead of a check button by setting check menu item’s draw-as-radio property to True. Radio menu items work the same way as normal radio buttons.

Toggle Tool Buttons

Gtk.ToggleToolButton is derived from Gtk.ToolButton, and therefore only implements initialization and toggle abilities. Toggle tool buttons provide the functionality of a Gtk.ToggleButton widget in the form of a toolbar item. It allows the user to view whether the option is set or unset.

Toggle tool buttons are tool buttons that remain depressed when the active property is set to True. You can use the toggled signal to receive notification when the state of the toggle button has been changed.

Radio Tool Buttons

Gtk.RadioToolButton is derived from Gtk.ToggleToolButton, so it inherits the “active” property and "toggled" signal. Therefore, the widget only needs to give a way for you to create new radio tool buttons and add them to a radio group.

Gtk.RadioToolButton inherits functions from Gtk.ToolButton, which provides functions and properties that can then set the label of the radio tool button, if necessary.

Gtk.RadioToolButton provides one property, group, which is another radio tool button that belongs to the radio group. This allows you to link all of the radio buttons together so that only one is selected at a time.

Menu Tool Buttons

Gtk.MenuToolButton, derived from Gtk.ToggleToolButton, allows you to attach a menu to a tool button. The widget places an arrow beside the image and label that provides access to the associated menu. For example, you could use Gtk.MenuToolButton to add a list of recently opened files to a toolbar button. Figure 10-6 is a screenshot of a menu tool button that is used for this purpose.

What makes Gtk.MenuToolButton unique is that an arrow to the right of the tool button provides the user with access to a menu. The tool button’s menu is set with menutoolbutton.set_menu() or by setting the menu property to a Gtk.Menu widget. This menu is displayed to the user when the arrow is clicked.

Creating XML Files

Every menu and item tag should have a unique ID associated with it so that you can access that item directly from your code. While not necessary, you should always add the name property to every menu and item. The name property can access the actual widget.

Each <menu> can have any number of <item> children. Both of these tags must be closed according to normal XML rules. If a tag does not have a closing tag (e.g., <menu/>), you must place a forward slash character (/) at the end of the tag so the parser knows the tag has ended.

Each <menu> and <item> tags can have other children as well, such as the <section> and <attribute> tags. The <section> tag organizes <item> tags. The <attribute> tags are used to describe (i.e., add properties) to both <menu> and <item> tags.

The <attribute> tag has multiple purposes but one purpose common to all <item> tags is the one containing the label property. This property supplies the label string that is visible on the <item>. In this case, the <item> tags correspond to a Gtk.MenuItem label attribute specifies the string that appears in the menu item.

Another <attribute> tag that appears with each <item> tags is the action attribute. This tag specifies the action to be taken when the <item> is clicked. The action specified is closely tied to the Gtk.Application and the Gtk.ApplicationWindow class (or their subclasses). The target of each action specifies which class instance—the Gtk.ApplicationWindow or the Gtk.Application—creates the Gio.SimpleAction and connects it to a method in the same class instance for processing the action. You can think of the <attribute> action tag as a kind of signal name that is an alias for the real signal to be processed.

The action attribute is applied to all elements except top-level widgets and separators. When loading the UI file to associate a Gtk.Action object to each element, Gtk.Builder uses the action attributes. Gtk.Action holds information about how the item is drawn and what callback method should be called, if any, when the item is activated.

Separators can be placed in a menu with the <separator/> tag. You do not need to provide name or action information for separators, because a generic Gtk.SeparatorMenuItem is added.

Each toolbar can contain any number of <toolitem> elements. Tool items are specified in the same manner as menu items, with an action ("action") and an ID. You can use the ID for elements in separate UI files, but you should not use the same names if, for example, the toolbar and menu bar are located in the same file.

However, you can and should use the same action for multiple elements. This causes each element to be drawn in the same way and to be connected to the same callback method. The advantage of this is that you need to define only one Gtk.Action for each item type. For example, the same action is used for the Cut element in the UI files in Listing 10-8 through 10-10.

The last type of top-level widget supported by UI files is the pop-up menu, denoted by the <popup> tag. Since a pop-up menu is the same thing as a normal menu, you can still use <menuitem> elements as children.

Loading XML Files

After you create your UI files, you need to load them into your application and retrieve the necessary widgets. To do this, you need to utilize the functionality provided by Gtk.ActionGroup and Gtk.Builder.

Gtk.ActionGroup is a set of items with name, stock identifier, label, keyboard accelerator, tooltip, and callback methods. The name of the each action can be set to an action parameter from a UI file to associate it with a UI element.

Gtk.Builder is a class that allows you to dynamically load one or more user interface definitions. It automatically creates an accelerator group based on associated action groups and allows you to reference widgets based on the "ID" parameter from the UI file.

In Listing 10-11, Gtk.UIManager loads the menu bar and toolbar from the UI files in Listing 10-10. The resulting application is shown in Figure 10-7.

Exercise 1: Toolbars

In Chapter 8, you created a simple text editor using the Gtk.TextView widget. In this exercise, expand on that application and provide a toolbar for actions instead of a vertical box filled with Gtk.Button widgets.

Although manual toolbar creation is possible, in most applications, you want to utilize the Gtk.Builder method for toolbar creation. Therefore, use that method in this exercise. You should also create your own with Gtk.IconFactory.

Oftentimes, it is advantageous for an application to provide the toolbar as a child of a handle box. Do this for your text editor, placing the toolbar above the text view. Also, set up the toolbar so that the textual descriptor is shown below every tool button.

This first exercise taught you how to build your own toolbars. It also showed you how to use the Gtk.HandleBox container. In the next exercise, you reimplement the Text Editor application with a menu bar.

Exercise 2: Menu Bars

In this exercise, implement the same application as in Exercise 1, except use a menu bar this time. You should continue to use Gtk.Builder, but the menu does not need to be contained by a Gtk.HandleBox.

Since tooltips are not shown for menu items automatically, use a status bar to provide more information about each item. The menu bar should contain two menus: File and Edit. You should also provide a Quit menu item in the File menu.