CtkImageMenuItem: CTK+ 3 Reference Manual

## CtkImageMenuItem CtkImageMenuItem — Widget for a menu item with an icon |

## Functions

void | ctk_image_menu_item_set_image ()
CtkWidget * | ctk_image_menu_item_get_image ()
CtkWidget * | ctk_image_menu_item_new ()
CtkWidget * | ctk_image_menu_item_new_from_stock ()
CtkWidget * | ctk_image_menu_item_new_with_label ()
CtkWidget * | ctk_image_menu_item_new_with_mnemonic ()
gboolean | ctk_image_menu_item_get_use_stock ()
void | ctk_image_menu_item_set_use_stock ()
gboolean | ctk_image_menu_item_get_always_show_image ()
void | ctk_image_menu_item_set_always_show_image ()
void | ctk_image_menu_item_set_accel_group ()

## Properties

CtkAccelGroup * | accel-group | Write
gboolean | always-show-image | Read / Write / Construct
CtkWidget * | image | Read / Write
gboolean | use-stock | Read / Write / Construct

## Types and Values

struct | CtkImageMenuItem
struct | CtkImageMenuItemClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── CtkWidget
                ╰── CtkContainer
                    ╰── CtkBin
                        ╰── CtkMenuItem
                            ╰── CtkImageMenuItem

## Implemented Interfaces

CtkImageMenuItem implements AtkImplementorIface, CtkBuildable, CtkActivatable and CtkActionable.

## Includes

    #include <ctk/ctk.h>

## Description

A CtkImageMenuItem is a menu item which has an icon next to the text label.

This is functionally equivalent to:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    CtkWidget *box = ctk_box_new (CTK_ORIENTATION_HORIZONTAL, 6);
    CtkWidget *icon = ctk_image_new_from_icon_name ("folder-music-symbolic", CTK_ICON_SIZE_MENU);
    CtkWidget *label = ctk_label_new ("Music");
    CtkWidget *menu_item = ctk_menu_item_new ();

    ctk_container_add (CTK_CONTAINER (box), icon);
    ctk_container_add (CTK_CONTAINER (box), label);

    ctk_container_add (CTK_CONTAINER (menu_item), box);

    ctk_widget_show_all (menu_item);

Note that the user may disable display of menu icons using the “ctk-menu-images” setting, so make sure to still fill in the text label. If you want to ensure that your menu items show an icon you are strongly encouraged to use a CtkMenuItem with a CtkImage instead.

An alternative way, if you want to display an icon in a menu item, you should use CtkMenuItem and pack a CtkBox with a CtkImage and a CtkLabel instead. You should also consider using CtkBuilder and the XML GMenu description for creating menus, by following the GMenu guide. You should consider using icons in menu items only sparingly, and for "objects" (or "nouns") elements only, like bookmarks, files, and links; "actions" (or "verbs") should not have icons.

Furthermore, if you would like to display keyboard accelerator, you must pack the accel label into the box using `ctk_box_pack_end()` and align the label, otherwise the accelerator will not display correctly. The following code snippet adds a keyboard accelerator to the menu item, with a key binding of Ctrl+M:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    CtkWidget *box = ctk_box_new (CTK_ORIENTATION_HORIZONTAL, 6);
    CtkWidget *icon = ctk_image_new_from_icon_name ("folder-music-symbolic", CTK_ICON_SIZE_MENU);
    CtkWidget *label = ctk_accel_label_new ("Music");
    CtkWidget *menu_item = ctk_menu_item_new ();
    CtkAccelGroup *accel_group = ctk_accel_group_new ();

    ctk_container_add (CTK_CONTAINER (box), icon);

    ctk_label_set_use_underline (CTK_LABEL (label), TRUE);
    ctk_label_set_xalign (CTK_LABEL (label), 0.0);

    ctk_widget_add_accelerator (menu_item, "activate", accel_group,
                                CDK_KEY_m, CDK_CONTROL_MASK, CTK_ACCEL_VISIBLE);
    ctk_accel_label_set_accel_widget (CTK_ACCEL_LABEL (label), menu_item);

    ctk_box_pack_end (CTK_BOX (box), label, TRUE, TRUE, 0);

    ctk_container_add (CTK_CONTAINER (menu_item), box);

    ctk_widget_show_all (menu_item);

## Functions

### ctk_image_menu_item_set_image ()

    void
    ctk_image_menu_item_set_image (CtkImageMenuItem *image_menu_item,
                                   CtkWidget *image);

Sets the image of `image_menu_item` to the given widget. Note that it depends on the show-menu-images setting whether the image will be displayed or not.

#### Parameters

image_menu_item | a CtkImageMenuItem. |
image | a widget to set as the image for the menu item. | [allow-none]

### ctk_image_menu_item_get_image ()

    CtkWidget *
    ctk_image_menu_item_get_image (CtkImageMenuItem *image_menu_item);

Gets the widget that is currently set as the image of `image_menu_item` . See `ctk_image_menu_item_set_image()`.

#### Parameters

image_menu_item | a CtkImageMenuItem |

#### Returns

the widget set as image of `image_menu_item` .

[transfer none]

### ctk_image_menu_item_new ()

    CtkWidget *
    ctk_image_menu_item_new (void);

Creates a new CtkImageMenuItem with an empty label.

#### Returns

a new CtkImageMenuItem

### ctk_image_menu_item_new_from_stock ()

    CtkWidget *
    ctk_image_menu_item_new_from_stock (const gchar *stock_id,
                                        CtkAccelGroup *accel_group);

Creates a new CtkImageMenuItem containing the image and text from a stock item. Some stock ids have preprocessor macros like CTK_STOCK_OK and CTK_STOCK_APPLY.

If you want this menu item to have changeable accelerators, then pass in `NULL` for accel_group. Next call `ctk_menu_item_set_accel_path()` with an appropriate path for the menu item, use `ctk_stock_lookup()` to look up the standard accelerator for the stock item, and if one is found, call `ctk_accel_map_add_entry()` to register it.

#### Parameters

stock_id | the name of the stock item. |
accel_group | the CtkAccelGroup to add the menu items accelerator to, or `NULL`. | [allow-none]

#### Returns

a new CtkImageMenuItem.

### ctk_image_menu_item_new_with_label ()

    CtkWidget *
    ctk_image_menu_item_new_with_label (const gchar *label);

Creates a new CtkImageMenuItem containing a label.

#### Parameters

label | the text of the menu item. |

#### Returns

a new CtkImageMenuItem.

### ctk_image_menu_item_new_with_mnemonic ()

    CtkWidget *
    ctk_image_menu_item_new_with_mnemonic (const gchar *label);

Creates a new CtkImageMenuItem 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 menu item, with an underscore in front of the mnemonic character |

#### Returns

a new CtkImageMenuItem

### ctk_image_menu_item_get_use_stock ()

    gboolean
    ctk_image_menu_item_get_use_stock (CtkImageMenuItem *image_menu_item);

Checks whether the label set in the menuitem is used as a stock id to select the stock item for the item.

#### Parameters

image_menu_item | a CtkImageMenuItem |

#### Returns

`TRUE` if the label set in the menuitem is used as a stock id to select the stock item for the item

Since: 2.16

### ctk_image_menu_item_set_use_stock ()

    void
    ctk_image_menu_item_set_use_stock (CtkImageMenuItem *image_menu_item,
                                       gboolean use_stock);

If `TRUE`, the label set in the menuitem is used as a stock id to select the stock item for the item.

#### Parameters

image_menu_item | a CtkImageMenuItem |
use_stock | `TRUE` if the menuitem should use a stock item |

Since: 2.16

### ctk_image_menu_item_get_always_show_image ()

    gboolean
    ctk_image_menu_item_get_always_show_image
                                   (CtkImageMenuItem *image_menu_item);

Returns whether the menu item will ignore the “ctk-menu-images” setting and always show the image, if available.

#### Parameters

image_menu_item | a CtkImageMenuItem |

#### Returns

`TRUE` if the menu item will always show the image

Since: 2.16

### ctk_image_menu_item_set_always_show_image ()

    void
    ctk_image_menu_item_set_always_show_image
                                   (CtkImageMenuItem *image_menu_item,
                                    gboolean always_show);

If `TRUE`, the menu item will ignore the “ctk-menu-images” setting and always show the image, if available.

Use this property if the menuitem would be useless or hard to use without the image.

#### Parameters

image_menu_item | a CtkImageMenuItem |
always_show | `TRUE` if the menuitem should always show the image |

Since: 2.16

### ctk_image_menu_item_set_accel_group ()

    void
    ctk_image_menu_item_set_accel_group (CtkImageMenuItem *image_menu_item,
                                         CtkAccelGroup *accel_group);

Specifies an `accel_group` to add the menu items accelerator to (this only applies to stock items so a stock item must already be set, make sure to call `ctk_image_menu_item_set_use_stock()` and `ctk_menu_item_set_label()` with a valid stock item first).

If you want this menu item to have changeable accelerators then you shouldnt need this (see `ctk_image_menu_item_new_from_stock()`).

#### Parameters

image_menu_item | a CtkImageMenuItem |
accel_group | the CtkAccelGroup |

Since: 2.16

## Types and Values

### struct CtkImageMenuItem

    struct CtkImageMenuItem;

### struct CtkImageMenuItemClass

    struct CtkImageMenuItemClass {
      CtkMenuItemClass parent_class;
    };

#### Members

## Property Details

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

      “accel-group”              CtkAccelGroup *

The Accel Group to use for stock accelerator keys

Owner: CtkImageMenuItem

Flags: Write

Since: 2.16

### The `“always-show-image”` property

      “always-show-image”        gboolean

If `TRUE`, the menu item will always show the image, if available.

Use this property only if the menuitem would be useless or hard to use without the image.

Owner: CtkImageMenuItem

Flags: Read / Write / Construct

Default value: FALSE

Since: 2.16

### The `“image”` property

      “image”                    CtkWidget *

Child widget to appear next to the menu text.

Owner: CtkImageMenuItem

Flags: Read / Write

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

      “use-stock”                gboolean

If `TRUE`, the label set in the menuitem is used as a stock id to select the stock item for the item.

Owner: CtkImageMenuItem

Flags: Read / Write / Construct

Default value: FALSE

Since: 2.16