manpagez: man pages & more
html files: gtk2
Home | html | info | man

GtkMenuItem

GtkMenuItem — The widget used for item in menus

Properties

gchar * accel-path Read / Write
gchar * label Read / Write
gboolean right-justified Read / Write
GtkMenu * submenu Read / Write
gboolean use-underline Read / Write

Types and Values

struct GtkMenuItem

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkItem
                            ╰── GtkMenuItem
                                ├── GtkCheckMenuItem
                                ├── GtkImageMenuItem
                                ├── GtkSeparatorMenuItem
                                ╰── GtkTearoffMenuItem

Implemented Interfaces

GtkMenuItem implements AtkImplementorIface, GtkBuildable and GtkActivatable.

Includes

#include <gtk/gtk.h>

Description

The GtkMenuItem widget and the derived widgets are the only valid childs for menus. Their function is to correctly handle highlighting, alignment, events and submenus.

As it derives from GtkBin it can hold any valid child widget, altough only a few are really useful.

GtkMenuItem as GtkBuildable

The GtkMenuItem implementation of the GtkBuildable interface supports adding a submenu by specifying "submenu" as the "type" attribute of a <child> element.

Example 27. A UI definition fragment with submenus

1
2
3
4
5
<object class="GtkMenuItem">
  <child type="submenu">
    <object class="GtkMenu"/>
  </child>
</object>

Functions

gtk_menu_item_new ()

GtkWidget *
gtk_menu_item_new (void);

Creates a new GtkMenuItem.

Returns

the newly created GtkMenuItem


gtk_menu_item_new_with_label ()

GtkWidget *
gtk_menu_item_new_with_label (const gchar *label);

Creates a new GtkMenuItem whose child is a GtkLabel.

Parameters

label

the text for the label

 

Returns

the newly created GtkMenuItem


gtk_menu_item_new_with_mnemonic ()

GtkWidget *
gtk_menu_item_new_with_mnemonic (const gchar *label);

Creates a new GtkMenuItem containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the mnemonic for the menu item.

Parameters

label

The text of the button, with an underscore in front of the mnemonic character

 

Returns

a new GtkMenuItem


gtk_menu_item_set_right_justified ()

void
gtk_menu_item_set_right_justified (GtkMenuItem *menu_item,
                                   gboolean right_justified);

Sets whether the menu item appears justified at the right side of a menu bar. This was traditionally done for "Help" menu items, but is now considered a bad idea. (If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the left.)

Parameters

menu_item

a GtkMenuItem.

 

right_justified

if TRUE the menu item will appear at the far right if added to a menu bar.

 

gtk_menu_item_get_right_justified ()

gboolean
gtk_menu_item_get_right_justified (GtkMenuItem *menu_item);

Gets whether the menu item appears justified at the right side of the menu bar.

Parameters

menu_item

a GtkMenuItem

 

Returns

TRUE if the menu item will appear at the far right if added to a menu bar.


gtk_menu_item_get_label ()

const gchar *
gtk_menu_item_get_label (GtkMenuItem *menu_item);

Sets text on the menu_item label

Parameters

menu_item

a GtkMenuItem

 

Returns

The text in the menu_item label. This is the internal string used by the label, and must not be modified.

Since: 2.16


gtk_menu_item_set_label ()

void
gtk_menu_item_set_label (GtkMenuItem *menu_item,
                         const gchar *label);

Sets text on the menu_item label

Parameters

menu_item

a GtkMenuItem

 

label

the text you want to set

 

Since: 2.16


gtk_menu_item_get_use_underline ()

gboolean
gtk_menu_item_get_use_underline (GtkMenuItem *menu_item);

Checks if an underline in the text indicates the next character should be used for the mnemonic accelerator key.

Parameters

menu_item

a GtkMenuItem

 

Returns

TRUE if an embedded underline in the label indicates the mnemonic accelerator key.

Since: 2.16


gtk_menu_item_set_use_underline ()

void
gtk_menu_item_set_use_underline (GtkMenuItem *menu_item,
                                 gboolean setting);

If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

Parameters

menu_item

a GtkMenuItem

 

setting

TRUE if underlines in the text indicate mnemonics

 

Since: 2.16


gtk_menu_item_set_submenu ()

void
gtk_menu_item_set_submenu (GtkMenuItem *menu_item,
                           GtkWidget *submenu);

Sets or replaces the menu item's submenu, or removes it when a NULL submenu is passed.

Parameters

menu_item

a GtkMenuItem

 

submenu

the submenu, or NULL.

[allow-none]

gtk_menu_item_get_submenu ()

GtkWidget *
gtk_menu_item_get_submenu (GtkMenuItem *menu_item);

Gets the submenu underneath this menu item, if any. See gtk_menu_item_set_submenu().

Parameters

menu_item

a GtkMenuItem

 

Returns

submenu for this menu item, or NULL if none.

[transfer none]


gtk_menu_item_remove_submenu ()

void
gtk_menu_item_remove_submenu (GtkMenuItem *menu_item);

gtk_menu_item_remove_submenu has been deprecated since version 2.12 and should not be used in newly-written code.

gtk_menu_item_remove_submenu() is deprecated and should not be used in newly written code. Use gtk_menu_item_set_submenu() instead.

Removes the widget's submenu.

Parameters

menu_item

a GtkMenuItem

 

gtk_menu_item_set_accel_path ()

void
gtk_menu_item_set_accel_path (GtkMenuItem *menu_item,
                              const gchar *accel_path);

Set the accelerator path on menu_item , through which runtime changes of the menu item's accelerator caused by the user can be identified and saved to persistant storage (see gtk_accel_map_save() on this). To setup a default accelerator for this menu item, call gtk_accel_map_add_entry() with the same accel_path . See also gtk_accel_map_add_entry() on the specifics of accelerator paths, and gtk_menu_set_accel_path() for a more convenient variant of this function.

This function is basically a convenience wrapper that handles calling gtk_widget_set_accel_path() with the appropriate accelerator group for the menu item.

Note that you do need to set an accelerator on the parent menu with gtk_menu_set_accel_group() for this to work.

Note that accel_path string will be stored in a GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string().

Parameters

menu_item

a valid GtkMenuItem

 

accel_path

accelerator path, corresponding to this menu item's functionality, or NULL to unset the current path.

[allow-none]

gtk_menu_item_get_accel_path ()

const gchar *
gtk_menu_item_get_accel_path (GtkMenuItem *menu_item);

Retrieve the accelerator path that was previously set on menu_item .

See gtk_menu_item_set_accel_path() for details.

Parameters

menu_item

a valid GtkMenuItem

 

Returns

the accelerator path corresponding to this menu item's functionality, or NULL if not set

Since: 2.14


gtk_menu_item_select ()

void
gtk_menu_item_select (GtkMenuItem *menu_item);

Emits the "select" signal on the given item. Behaves exactly like gtk_item_select.

Parameters

menu_item

the menu item

 

gtk_menu_item_deselect ()

void
gtk_menu_item_deselect (GtkMenuItem *menu_item);

Emits the "deselect" signal on the given item. Behaves exactly like gtk_item_deselect.

Parameters

menu_item

the menu item

 

gtk_menu_item_activate ()

void
gtk_menu_item_activate (GtkMenuItem *menu_item);

Emits the "activate" signal on the given item

Parameters

menu_item

the menu item

 

gtk_menu_item_toggle_size_request ()

void
gtk_menu_item_toggle_size_request (GtkMenuItem *menu_item,
                                   gint *requisition);

Emits the "toggle_size_request" signal on the given item.

Parameters

menu_item

the menu item

 

requisition

the requisition to use as signal data.

 

gtk_menu_item_toggle_size_allocate ()

void
gtk_menu_item_toggle_size_allocate (GtkMenuItem *menu_item,
                                    gint allocation);

Emits the "toggle_size_allocate" signal on the given item.

Parameters

menu_item

the menu item.

 

allocation

the allocation to use as signal data.

 

gtk_menu_item_right_justify()

#define gtk_menu_item_right_justify(menu_item) gtk_menu_item_set_right_justified ((menu_item), TRUE)

gtk_menu_item_right_justify is deprecated and should not be used in newly-written code.

Sets the menu item to be right-justified. Only useful for menu bars.

Parameters

menu_item

the menu item

 

Types and Values

struct GtkMenuItem

struct GtkMenuItem;

Property Details

The “accel-path” property

  “accel-path”               gchar *

Sets the accelerator path of the menu item, through which runtime changes of the menu item's accelerator caused by the user can be identified and saved to persistant storage.

Flags: Read / Write

Default value: NULL

Since: 2.14


The “label” property

  “label”                    gchar *

The text for the child label.

Flags: Read / Write

Default value: ""

Since: 2.16


The “right-justified” property

  “right-justified”          gboolean

Sets whether the menu item appears justified at the right side of a menu bar.

Flags: Read / Write

Default value: FALSE

Since: 2.14


The “submenu” property

  “submenu”                  GtkMenu *

The submenu attached to the menu item, or NULL if it has none.

Flags: Read / Write

Since: 2.12


The “use-underline” property

  “use-underline”            gboolean

TRUE if underlines in the text indicate mnemonics

Flags: Read / Write

Default value: FALSE

Since: 2.16

Style Property Details

The “arrow-scaling” style property

  “arrow-scaling”            gfloat

Amount of space used up by arrow, relative to the menu item's font size.

Flags: Read

Allowed values: [0,2]

Default value: 0.8


The “arrow-spacing” style property

  “arrow-spacing”            gint

Space between label and arrow.

Flags: Read

Allowed values: >= 0

Default value: 10


The “horizontal-padding” style property

  “horizontal-padding”       gint

Padding to left and right of the menu item.

Flags: Read

Allowed values: >= 0

Default value: 3


The “selected-shadow-type” style property

  “selected-shadow-type”     GtkShadowType

Shadow type when item is selected.

Flags: Read

Default value: GTK_SHADOW_NONE


The “toggle-spacing” style property

  “toggle-spacing”           gint

Space between icon and label.

Flags: Read

Allowed values: >= 0

Default value: 5


The “width-chars” style property

  “width-chars”              gint

The minimum desired width of the menu item in characters.

Flags: Read

Allowed values: >= 0

Default value: 12

Since: 2.14

Signal Details

The “activate” signal

void
user_function (GtkMenuItem *menuitem,
               gpointer     user_data)

Emitted when the item is activated.

Parameters

menuitem

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “activate-item” signal

void
user_function (GtkMenuItem *menuitem,
               gpointer     user_data)

Emitted when the item is activated, but also if the menu item has a submenu. For normal applications, the relevant signal is "activate".

Parameters

menuitem

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “toggle-size-allocate” signal

void
user_function (GtkMenuItem *menuitem,
               gint         arg1,
               gpointer     user_data)

Parameters

menuitem

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “toggle-size-request” signal

void
user_function (GtkMenuItem *menuitem,
               gpointer     arg1,
               gpointer     user_data)

Parameters

menuitem

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

See Also

GtkBin

for how to handle the child.

GtkItem

is the abstract class for all sorts of items.

GtkMenuShell

is always the parent of GtkMenuItem.

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.