PyMaemo/UI tutorial/Menus

Line 157: Line 157:
When you use a GtkMenu in your Hildon application, consider how many menu items you are going to use, because screen space is limited. Also consider the fact that in the interests of keeping the UI clear, submenus are not allowed.
When you use a GtkMenu in your Hildon application, consider how many menu items you are going to use, because screen space is limited. Also consider the fact that in the interests of keeping the UI clear, submenus are not allowed.
 +
 +
[[Category:Python]]

Revision as of 15:55, 11 February 2010

Contents

Menus

Hildon applications use menus in a completely different way from the traditional application menus - Hildon applications does not have a menu bar.

Each window has an attached menu that activates when the user presses the window title area. Also, unlike typical menus in desktop applications, view menus do not follow a hierarchical structure. This menu, attached to a view, is called Touch View Menu.

Additionally Hildon provides Context menus, but they should be avoided whenever possible.


Touch view menu

The HildonAppmenu is a widget that acts like a menu in the windows of a Hildon application.

This widget opens at the top of the screen, obscuring the topmost window, and contains several entries organized in one or two columns, depending on screen orientation. Besides entries, application menus can also contain a group of filter buttons.

The entries are GtkButtons. Assign an action to the menu item for when they are activated.

Filters are toggle buttons that can be used for presentation/sorting purposes. For example, sorting alphabetically a list of contacts or changing the size of icons in a list.

To create a HildonAppMenu, use the following command:

   hildon.AppMenu()

When the application menu is created, add entries to the menu by using the following functions:

   def append(self, item)
   def prepend(self, item)
   def insert(self, item, position)
   

These functions allow you to append, prepend an entry or add it in a certain position (from 0 to N-1, where N is the number of menus).

It is important to keep the UI simple. Try to create the menu as short as possible and avoid adding unnecessary options. An application menu with more than 10 items probably will not have a good appearance.

To add filter buttons, use the following:

   def add_filter(self, filter)

Again, be careful with the number of filters that you add to the application menu. More than 4 might not be well displayed, even less, depending on the length of the labels. Filters should be grouped and act as radio buttons, that is, for any filter, at least another filter with a different/opposite action must exist. Actually, GtkRadioButtons can be easily used to accomplish this by having them grouped (using gtk_radio_button_new_from_widget() like the next example shows) and by not drawing their indicator - with the function gtk_toggle_button_set_mode().

When the menu is properly created and filled up with entries and filters, add the menu to a HildonWindow. To set and retrieve a window's menu, use the following functions:

   def set_app_menu(self, menu)
   def get_app_menu(self)

The following example shows how to create and set up an application menu.

Example 3.1. Example of a Hildon application menu

   # Based on C code from:
   # "Hildon Tutorial" version 2009-04-28
   # Example 3.1, "Example of a Hildon application menu"
   
   import sys
   
   import gtk
   import hildon
   
   def menu_button_clicked(button, label):
       buttontext = button.get_label()
       text = "Last option selected:\n%s" % buttontext
       label.set_text(text)
       print >>sys.stderr, "Button clicked: %s" % buttontext
   
   def create_menu(label):
       menu = hildon.AppMenu()
   
       for i in xrange(1, 6):
           # Create menu entries
           button = hildon.GtkButton(gtk.HILDON_SIZE_AUTO)
           command_id = "Menu command %d" % i
           button.set_label(command_id)
   
           # Attach callback to clicked signal
           button.connect("clicked", menu_button_clicked, label)
   
           # Add entry to the view menu
           menu.append(button)
   
       # Create filters
       button = hildon.GtkRadioButton(gtk.HILDON_SIZE_AUTO, None)
       button.set_label("filter one")
       button.connect("clicked", menu_button_clicked, label)
       menu.add_filter(button)
       button.set_mode(False)
   
       button = hildon.GtkRadioButton(gtk.HILDON_SIZE_AUTO, button)
       button.set_label("filter two")
       button.connect("clicked", menu_button_clicked, label)
       menu.add_filter(button)
       button.set_mode(False)
   
       menu.show_all()
   
       return menu
   
   def main():
       win = hildon.StackableWindow()
   
       # Create and pack labels
       label = gtk.Label("This is an example of the\nHildonAppMenu widget.\n\n"
                         "Click on the titlebar\nto pop up the menu.")
       label2 = gtk.Label("No menu option has been selected yet.")
   
       label.set_justify(gtk.JUSTIFY_CENTER)
       label2.set_justify(gtk.JUSTIFY_CENTER)
   
       vbox = gtk.VBox(False, 10)
   
       vbox.pack_start(label, True, True, 0)
       vbox.pack_start(label2, True, True, 0)
   
       # Create menu
       menu = create_menu(label2)
   
       # Attach menu to the window
       win.set_app_menu(menu)
   
       # Add label's box to window
       win.add(vbox)
   
       win.connect("delete_event", gtk.main_quit)
   
       win.show_all()
   
       gtk.main()
   
   if __name__ == "__main__":
       main()


Each entry and filter button in this example is attached to a function that simply changes a label in the main window.

Application menus and views

The previous example had only one view. In applications with several views, you can attach a different menu to each view and add only the options that are relevant to the displayed view.

The function hildon_window_set_app_menu()allows to set a menu to a HildonWindow and its descendant HildonStackableWindow widget.

   window.set_app_menu(menu)


Note that submenus are not supported by view menus. Usually a menu item that would have suboptions in a desktop application is implemented as a new subview in a Hildon application.

A callback function for a complex menu entry can create a new hildon.StackableWindow to accomplish the task that the option refers to. The new window can contain a different view menu that aggregates buttons to perform the action. The buttons can even reside in the window area.

Context menu

The Context menu is usually invoked through a long press over an item on the screen, like holding a finger over an image thumbnail. The menu must contain commands directly related to the chosen item.

Avoid using context menus, because they are a hidden and inconvenient way of interacting with the UI. Use HildonAppMenus instead.

To create a GtkMenu in a Hildon application, use the following function instead of gtk_menu_new():

   gtk.Menu()

This function creates a GtkMenu that allows Hildon specific styling.

When you use a GtkMenu in your Hildon application, consider how many menu items you are going to use, because screen space is limited. Also consider the fact that in the interests of keeping the UI clear, submenus are not allowed.