HildonAppMenu

HildonAppMenu — Application menu for Hildon applications.

Synopsis

                    HildonAppMenu;
GtkWidget*          hildon_app_menu_new                 (void);
void                hildon_app_menu_append              (HildonAppMenu *menu,
                                                         GtkButton *item);
void                hildon_app_menu_prepend             (HildonAppMenu *menu,
                                                         GtkButton *item);
void                hildon_app_menu_insert              (HildonAppMenu *menu,
                                                         GtkButton *item,
                                                         gint position);
void                hildon_app_menu_reorder_child       (HildonAppMenu *menu,
                                                         GtkButton *item,
                                                         gint position);
void                hildon_app_menu_add_filter          (HildonAppMenu *menu,
                                                         GtkButton *filter);
GList*              hildon_app_menu_get_items           (HildonAppMenu *menu);
GList*              hildon_app_menu_get_filters         (HildonAppMenu *menu);
void                hildon_app_menu_popup               (HildonAppMenu *menu,
                                                         GtkWindow *parent_window);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----HildonAppMenu

Implemented Interfaces

HildonAppMenu implements AtkImplementorIface and GtkBuildable.

Style Properties

  "external-border"          guint                 : Read
  "filter-group-width"       gint                  : Read
  "filter-vertical-spacing"  guint                 : Read
  "horizontal-spacing"       guint                 : Read
  "inner-border"             guint                 : Read
  "vertical-spacing"         guint                 : Read

Signals

  "changed"                                        : Run Last / Action

Description

HildonAppMenu is an application menu for applications in the Hildon framework.

This menu opens from the top of the screen and contains a number of entries (GtkButton) organized in one or two columns, depending on the size of the screen (the number of columns changes automatically if the screen is resized). Entries are added left to right and top to bottom.

Besides that, HildonAppMenu can contain a group of filter buttons (GtkToggleButton or GtkRadioButton). Filters are meant to change the way data is presented in the application, rather than change the layout of the menu itself. For example, a file manager can have filters to decide the order used to display a list of files (name, date, size, etc.).

To use a HildonAppMenu, add it to a HildonWindow using hildon_window_set_app_menu(). The menu will appear when the user presses the window title bar. Alternatively, you can show it by hand using hildon_app_menu_popup().

The menu will be automatically hidden when one of its buttons is clicked. Use g_signal_connect_after() when connecting callbacks to buttons to make sure that they're called after the menu disappears. Alternatively, you can add the button to the menu before connecting any callback.

Although implemented with a GtkWindow, HildonAppMenu behaves like a normal ref-counted widget, so g_object_ref(), g_object_unref(), g_object_ref_sink() and friends will behave just like with any other non-toplevel widget.

Example 14. Creating a HildonAppMenu

GtkWidget *win;
HildonAppMenu *menu;
GtkWidget *button;
GtkWidget *filter;

win = hildon_stackable_window_new ();
menu = HILDON_APP_MENU (hildon_app_menu_new ());

// Create a button and add it to the menu
button = gtk_button_new_with_label ("Menu command one");
g_signal_connect_after (button, "clicked", G_CALLBACK (button_one_clicked), userdata);
hildon_app_menu_append (menu, GTK_BUTTON (button));

// Another button
button = gtk_button_new_with_label ("Menu command two");
g_signal_connect_after (button, "clicked", G_CALLBACK (button_two_clicked), userdata);
hildon_app_menu_append (menu, GTK_BUTTON (button));

// Create a filter and add it to the menu
filter = gtk_radio_button_new_with_label (NULL, "Filter one");
gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
g_signal_connect_after (filter, "clicked", G_CALLBACK (filter_one_clicked), userdata);
hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));

// Add a new filter
filter = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (filter), "Filter two");
gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (filter), FALSE);
g_signal_connect_after (filter, "clicked", G_CALLBACK (filter_two_clicked), userdata);
hildon_app_menu_add_filter (menu, GTK_BUTTON (filter));

// Show all menu items
gtk_widget_show_all (GTK_WIDGET (menu));

// Add the menu to the window
hildon_window_set_app_menu (HILDON_WINDOW (win), menu);


Details

HildonAppMenu

typedef struct _HildonAppMenu HildonAppMenu;

hildon_app_menu_new ()

GtkWidget*          hildon_app_menu_new                 (void);

Creates a new HildonAppMenu.

Returns : A HildonAppMenu.

Since 2.2

hildon_app_menu_append ()

void                hildon_app_menu_append              (HildonAppMenu *menu,
                                                         GtkButton *item);

Adds item to the end of the menu's item list.

menu : A HildonAppMenu
item : A GtkButton to add to the HildonAppMenu

Since 2.2

hildon_app_menu_prepend ()

void                hildon_app_menu_prepend             (HildonAppMenu *menu,
                                                         GtkButton *item);

Adds item to the beginning of the menu's item list.

menu : A HildonAppMenu
item : A GtkButton to add to the HildonAppMenu

Since 2.2

hildon_app_menu_insert ()

void                hildon_app_menu_insert              (HildonAppMenu *menu,
                                                         GtkButton *item,
                                                         gint position);

Adds item to menu at the position indicated by position.

menu : A HildonAppMenu
item : A GtkButton to add to the HildonAppMenu
position : The position in the item list where item is added (from 0 to n-1).

Since 2.2

hildon_app_menu_reorder_child ()

void                hildon_app_menu_reorder_child       (HildonAppMenu *menu,
                                                         GtkButton *item,
                                                         gint position);

Moves a GtkButton to a new position within HildonAppMenu.

menu : A HildonAppMenu
item : A GtkButton to move
position : The new position to place item (from 0 to n-1).

Since 2.2

hildon_app_menu_add_filter ()

void                hildon_app_menu_add_filter          (HildonAppMenu *menu,
                                                         GtkButton *filter);

Adds the filter to menu.

menu : A HildonAppMenu
filter : A GtkButton to add to the HildonAppMenu.

Since 2.2

hildon_app_menu_get_items ()

GList*              hildon_app_menu_get_items           (HildonAppMenu *menu);

Returns a list of all items (regular items, not filters) contained in menu.

menu : a HildonAppMenu
Returns : a newly-allocated list containing the items in menu

Since 2.2

hildon_app_menu_get_filters ()

GList*              hildon_app_menu_get_filters         (HildonAppMenu *menu);

Returns a list of all filters contained in menu.

menu : a HildonAppMenu
Returns : a newly-allocated list containing the filters in menu

Since 2.2

hildon_app_menu_popup ()

void                hildon_app_menu_popup               (HildonAppMenu *menu,
                                                         GtkWindow *parent_window);

Displays a menu on top of a window and makes it available for selection.

menu : a HildonAppMenu
parent_window : a GtkWindow

Since 2.2

Style Property Details

The "external-border" style property

  "external-border"          guint                 : Read

Border between the right and left edges of the menu and the screen edges (in horizontal mode).

Default value: 50

The "filter-group-width" style property

  "filter-group-width"       gint                  : Read

Total width of the group of filter buttons, or -1 to use the natural size request.

Allowed values: >= -1

Default value: 444

The "filter-vertical-spacing" style property

  "filter-vertical-spacing"  guint                 : Read

Vertical spacing between filters and menu items.

Default value: 8

The "horizontal-spacing" style property

  "horizontal-spacing"       guint                 : Read

Horizontal spacing between each menu item. Does not apply to filter buttons.

Default value: 16

The "inner-border" style property

  "inner-border"             guint                 : Read

Border between menu edges and buttons.

Default value: 16

The "vertical-spacing" style property

  "vertical-spacing"         guint                 : Read

Vertical spacing between each menu item. Does not apply to filter buttons.

Default value: 16

Signal Details

The "changed" signal

void                user_function                      (HildonAppMenu *widget,
                                                        gpointer       user_data)      : Run Last / Action

The HildonAppMenu::changed signal is emitted whenever an item or filter is added or removed from the menu.

widget : the widget that received the signal
user_data : user data set when the signal handler was connected.

Since 2.2

Generated by GTK-Doc V1.10