CtkMenuItem: CTK+ 3 Reference Manual

## CtkMenuItem CtkMenuItem — The widget used for item in menus |

## Functions

CtkWidget * | ctk_menu_item_new ()
CtkWidget * | ctk_menu_item_new_with_label ()
CtkWidget * | ctk_menu_item_new_with_mnemonic ()
void | ctk_menu_item_set_right_justified ()
gboolean | ctk_menu_item_get_right_justified ()
const gchar * | ctk_menu_item_get_label ()
void | ctk_menu_item_set_label ()
gboolean | ctk_menu_item_get_use_underline ()
void | ctk_menu_item_set_use_underline ()
void | ctk_menu_item_set_submenu ()
CtkWidget * | ctk_menu_item_get_submenu ()
void | ctk_menu_item_set_accel_path ()
const gchar * | ctk_menu_item_get_accel_path ()
void | ctk_menu_item_select ()
void | ctk_menu_item_deselect ()
void | ctk_menu_item_activate ()
void | ctk_menu_item_toggle_size_request ()
void | ctk_menu_item_toggle_size_allocate ()
gboolean | ctk_menu_item_get_reserve_indicator ()
void | ctk_menu_item_set_reserve_indicator ()

## Properties

char * | accel-path | Read / Write
char * | label | Read / Write
gboolean | right-justified | Read / Write
CtkMenu * | submenu | Read / Write
gboolean | use-underline | Read / Write

## Signals

void | activate | Action
void | activate-item | Run First
void | deselect | Run First
void | select | Run First
void | toggle-size-allocate | Run First
void | toggle-size-request | Run First

## Types and Values

struct | CtkMenuItem
struct | CtkMenuItemClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── CtkWidget
                ╰── CtkContainer
                    ╰── CtkBin
                        ╰── CtkMenuItem
                            ├── CtkCheckMenuItem
                            ├── CtkImageMenuItem
                            ├── CtkSeparatorMenuItem
                            ╰── CtkTearoffMenuItem

## Implemented Interfaces

CtkMenuItem implements AtkImplementorIface, CtkBuildable, CtkActivatable and CtkActionable.

## Includes

    #include <ctk/ctk.h>

## Description

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

As a CtkMenuItem derives from CtkBin it can hold any valid child widget, although only a few are really useful.

By default, a CtkMenuItem sets a CtkAccelLabel as its child. CtkMenuItem has direct functions to set the label and its mnemonic. For more advanced label settings, you can fetch the child widget from the CtkBin.

An example for setting markup and accelerator on a MenuItem:

    1
    2
    3
    4
    5
    CtkWidget *menu_item = ctk_menu_item_new_with_label ("Example Menu Item");

    CtkWidget *child = ctk_bin_get_child (CTK_BIN (menu_item));
    ctk_label_set_markup (CTK_LABEL (child), "<i>new label</i> with <b>markup</b>");
    ctk_accel_label_set_accel (CTK_ACCEL_LABEL (child), CDK_KEY_1, 0);

### CtkMenuItem as CtkBuildable

The CtkMenuItem implementation of the CtkBuildable interface supports adding a submenu by specifying “submenu” as the “type” attribute of a <child> element.

An example of UI definition fragment with submenus:

    1
    2
    3
    4
    5
    <object class="CtkMenuItem">
      <child type="submenu">
        <object class="CtkMenu"/>
      </child>
    </object>

### CSS nodes

    1
    2
    3
    menuitem
    ├── <child>
    ╰── [arrow.right]

CtkMenuItem has a single CSS node with name menuitem. If the menuitem has a submenu, it gets another CSS node with name arrow, which has the .left or .right style class.

## Functions

### ctk_menu_item_new ()

    CtkWidget *
    ctk_menu_item_new (void);

Creates a new CtkMenuItem.

#### Returns

the newly created CtkMenuItem

### ctk_menu_item_new_with_label ()

    CtkWidget *
    ctk_menu_item_new_with_label (const gchar *label);

Creates a new CtkMenuItem whose child is a CtkLabel.

#### Parameters

label | the text for the label |

#### Returns

the newly created CtkMenuItem

### ctk_menu_item_new_with_mnemonic ()

    CtkWidget *
    ctk_menu_item_new_with_mnemonic (const gchar *label);

Creates a new CtkMenuItem containing a label.

The label will be created using `ctk_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 CtkMenuItem

### ctk_menu_item_set_right_justified ()

    void
    ctk_menu_item_set_right_justified (CtkMenuItem *menu_item,
                                       gboolean right_justified);

`ctk_menu_item_set_right_justified` has been deprecated since version 3.2 and should not be used in newly-written code.

If you insist on using it, use `ctk_widget_set_hexpand()` and `ctk_widget_set_halign()`.

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 CtkMenuItem. |
right_justified | if `TRUE` the menu item will appear at the far right if added to a menu bar |

### ctk_menu_item_get_right_justified ()

    gboolean
    ctk_menu_item_get_right_justified (CtkMenuItem *menu_item);

`ctk_menu_item_get_right_justified` has been deprecated since version 3.2 and should not be used in newly-written code.

See `ctk_menu_item_set_right_justified()`

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

#### Parameters

menu_item | a CtkMenuItem |

#### Returns

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

### ctk_menu_item_get_label ()

    const gchar *
    ctk_menu_item_get_label (CtkMenuItem *menu_item);

Sets `text` on the `menu_item` label

#### Parameters

menu_item | a CtkMenuItem |

#### 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

### ctk_menu_item_set_label ()

    void
    ctk_menu_item_set_label (CtkMenuItem *menu_item,
                             const gchar *label);

Sets `text` on the `menu_item` label

#### Parameters

menu_item | a CtkMenuItem |
label | the text you want to set |

Since: 2.16

### ctk_menu_item_get_use_underline ()

    gboolean
    ctk_menu_item_get_use_underline (CtkMenuItem *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 CtkMenuItem |

#### Returns

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

Since: 2.16

### ctk_menu_item_set_use_underline ()

    void
    ctk_menu_item_set_use_underline (CtkMenuItem *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 CtkMenuItem |
setting | `TRUE` if underlines in the text indicate mnemonics |

Since: 2.16

### ctk_menu_item_set_submenu ()

    void
    ctk_menu_item_set_submenu (CtkMenuItem *menu_item,
                               CtkWidget *submenu);

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

#### Parameters

menu_item | a CtkMenuItem |
submenu | the submenu, or `NULL`. | [allow-none][type Ctk.Menu]

### ctk_menu_item_get_submenu ()

    CtkWidget *
    ctk_menu_item_get_submenu (CtkMenuItem *menu_item);

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

#### Parameters

menu_item | a CtkMenuItem |

#### Returns

submenu for this menu item, or `NULL` if none.

[nullable][transfer none]

### ctk_menu_item_set_accel_path ()

    void
    ctk_menu_item_set_accel_path (CtkMenuItem *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 persistent storage (see `ctk_accel_map_save()` on this). To set up a default accelerator for this menu item, call `ctk_accel_map_add_entry()` with the same `accel_path` . See also `ctk_accel_map_add_entry()` on the specifics of accelerator paths, and `ctk_menu_set_accel_path()` for a more convenient variant of this function.

This function is basically a convenience wrapper that handles calling `ctk_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 `ctk_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 CtkMenuItem |
accel_path | accelerator path, corresponding to this menu item’s functionality, or `NULL` to unset the current path. | [allow-none]

### ctk_menu_item_get_accel_path ()

    const gchar *
    ctk_menu_item_get_accel_path (CtkMenuItem *menu_item);

Retrieve the accelerator path that was previously set on `menu_item` .

See `ctk_menu_item_set_accel_path()` for details.

#### Parameters

menu_item | a valid CtkMenuItem |

#### Returns

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

[nullable][transfer none]

Since: 2.14

### ctk_menu_item_select ()

    void
    ctk_menu_item_select (CtkMenuItem *menu_item);

Emits the “select” signal on the given item.

#### Parameters

menu_item | the menu item |

### ctk_menu_item_deselect ()

    void
    ctk_menu_item_deselect (CtkMenuItem *menu_item);

Emits the “deselect” signal on the given item.

#### Parameters

menu_item | the menu item |

### ctk_menu_item_activate ()

    void
    ctk_menu_item_activate (CtkMenuItem *menu_item);

Emits the “activate” signal on the given item

#### Parameters

menu_item | the menu item |

### ctk_menu_item_toggle_size_request ()

    void
    ctk_menu_item_toggle_size_request (CtkMenuItem *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. | [inout]

### ctk_menu_item_toggle_size_allocate ()

    void
    ctk_menu_item_toggle_size_allocate (CtkMenuItem *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. |

### ctk_menu_item_get_reserve_indicator ()

    gboolean
    ctk_menu_item_get_reserve_indicator (CtkMenuItem *menu_item);

Returns whether the `menu_item` reserves space for the submenu indicator, regardless if it has a submenu or not.

#### Parameters

menu_item | a CtkMenuItem |

#### Returns

`TRUE` if `menu_item` always reserves space for the submenu indicator

Since: 3.0

### ctk_menu_item_set_reserve_indicator ()

    void
    ctk_menu_item_set_reserve_indicator (CtkMenuItem *menu_item,
                                         gboolean reserve);

Sets whether the `menu_item` should reserve space for the submenu indicator, regardless if it actually has a submenu or not.

There should be little need for applications to call this functions.

#### Parameters

menu_item | a CtkMenuItem |
reserve | the new value |

Since: 3.0

## Types and Values

### struct CtkMenuItem

    struct CtkMenuItem;

### struct CtkMenuItemClass

    struct CtkMenuItemClass {
      CtkBinClass parent_class;

      /* If the following flag is true, then we should always
       * hide the menu when the MenuItem is activated. Otherwise,
       * it is up to the caller. For instance, when navigating
       * a menu with the keyboard, <Space> doesn't hide, but
       * <Return> does.
       */
      guint hide_on_activate : 1;

      void (* activate)             (CtkMenuItem *menu_item);
      void (* activate_item)        (CtkMenuItem *menu_item);
      void (* toggle_size_request)  (CtkMenuItem *menu_item,
                                     gint        *requisition);
      void (* toggle_size_allocate) (CtkMenuItem *menu_item,
                                     gint         allocation);
      void (* set_label)            (CtkMenuItem *menu_item,
                                     const gchar *label);
      const gchar * (* get_label)   (CtkMenuItem *menu_item);

      void (* select)               (CtkMenuItem *menu_item);
      void (* deselect)             (CtkMenuItem *menu_item);
    };

#### Members

guint `hide_on_activate` : 1; | If `TRUE`, then we should always hide the menu when the `CtkMenuItem` is activated. Otherwise, it is up to the caller. |
`activate` () | Signal emitted when the item is activated. |
`activate_item` () | Signal emitted when the item is activated, but also if the menu item has a submenu. |
`toggle_size_request` () |  |
`toggle_size_allocate` () |  |
`set_label` () | Sets `text` on the CtkMenuItem label |
`get_label` () | Gets `text` from the CtkMenuItem label |
`select` () | Signal emitted when the item is selected. |
`deselect` () | Signal emitted when the item is deselected. |

## Property Details

### The `“accel-path”` property

      “accel-path”               char *

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.

Owner: CtkMenuItem

Flags: Read / Write

Default value: NULL

Since: 2.14

### The `“label”` property

      “label”                    char *

The text for the child label.

Owner: CtkMenuItem

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.

Owner: CtkMenuItem

Flags: Read / Write

Default value: FALSE

Since: 2.14

### The `“submenu”` property

      “submenu”                  CtkMenu *

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

Owner: CtkMenuItem

Flags: Read / Write

Since: 2.12

### The `“use-underline”` property

      “use-underline”            gboolean

`TRUE` if underlines in the text indicate mnemonics.

Owner: CtkMenuItem

Flags: Read / Write

Default value: FALSE

Since: 2.16

## Signal Details

### The `“activate”` signal

    void
    user_function (CtkMenuItem *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 (CtkMenuItem *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 `“deselect”` signal

    void
    user_function (CtkMenuItem *ctkmenuitem,
                   gpointer     user_data)

Flags: Run First

### The `“select”` signal

    void
    user_function (CtkMenuItem *ctkmenuitem,
                   gpointer     user_data)

Flags: Run First

### The `“toggle-size-allocate”` signal

    void
    user_function (CtkMenuItem *ctkmenuitem,
                   int          arg1,
                   gpointer     user_data)

Flags: Run First

### The `“toggle-size-request”` signal

    void
    user_function (CtkMenuItem *ctkmenuitem,
                   gpointer     arg1,
                   gpointer     user_data)

Flags: Run First

## See Also

CtkBin, CtkMenuShell