GtkMenuButton

GtkMenuButton — A widget that shows a popup when clicked on

Properties

GtkWidget * align-widget Read / Write
GtkArrowType direction Read / Write
gboolean has-frame Read / Write
gchar * icon-name Read / Write
gchar * label Read / Write
GMenuModel * menu-model Read / Write
GtkPopover * popover Read / Write
gboolean use-underline Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkMenuButton

Implemented Interfaces

GtkMenuButton implements AtkImplementorIface, GtkBuildable and GtkConstraintTarget.

Includes

#include <gtk/gtk.h>

Description

The GtkMenuButton widget is used to display a popup when clicked on. This popup can be provided either as a GtkPopover or as an abstract GMenuModel.

The GtkMenuButton widget can show either an icon (set with the “icon-name” property) or a label (set with the “label” property). If neither is explicitly set, a GtkImage is automatically created, using an arrow image oriented according to “direction” or the generic “open-menu-symbolic” icon if the direction is not set.

The positioning of the popup is determined by the “direction” property of the menu button.

For menus, the “halign” and “valign” properties of the menu are also taken into account. For example, when the direction is GTK_ARROW_DOWN and the horizontal alignment is GTK_ALIGN_START, the menu will be positioned below the button, with the starting edge (depending on the text direction) of the menu aligned with the starting edge of the button. If there is not enough space below the button, the menu is popped up above the button instead. If the alignment would move part of the menu offscreen, it is “pushed in”.

Direction = Down

  • halign = start

  • halign = center

  • halign = end

Direction = Up

  • halign = start

  • halign = center

  • halign = end

Direction = Left

  • valign = start

  • valign = center

  • valign = end

Direction = Right

  • valign = start

  • valign = center

  • valign = end

CSS nodes

GtkMenuButton has a single CSS node with name button. To differentiate it from a plain GtkButton, it gets the .popup style class.

Functions

gtk_menu_button_new ()

GtkWidget *
gtk_menu_button_new (void);

Creates a new GtkMenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another GtkWidget should you wish to.

Returns

The newly created GtkMenuButton widget


gtk_menu_button_set_popover ()

void
gtk_menu_button_set_popover (GtkMenuButton *menu_button,
                             GtkWidget *popover);

Sets the GtkPopover that will be popped up when the menu_button is clicked, or NULL to dissociate any existing popover and disable the button.

If “menu-model” is set, the menu model is dissociated from the menu_button , and the property is set to NULL.

Parameters

menu_button

a GtkMenuButton

 

popover

a GtkPopover, or NULL to unset and disable the button.

[nullable]

gtk_menu_button_get_popover ()

GtkPopover *
gtk_menu_button_get_popover (GtkMenuButton *menu_button);

Returns the GtkPopover that pops out of the button. If the button is not using a GtkPopover, this function returns NULL.

Parameters

menu_button

a GtkMenuButton

 

Returns

a GtkPopover or NULL.

[nullable][transfer none]


gtk_menu_button_set_menu_model ()

void
gtk_menu_button_set_menu_model (GtkMenuButton *menu_button,
                                GMenuModel *menu_model);

Sets the GMenuModel from which the popup will be constructed, or NULL to dissociate any existing menu model and disable the button.

A GtkPopover will be created from the menu model with gtk_popover_menu_new_from_model(). Actions will be connected as documented for this function.

If “popover” is already set, it will be dissociated from the menu_button , and the property is set to NULL.

Parameters

menu_button

a GtkMenuButton

 

menu_model

a GMenuModel, or NULL to unset and disable the button.

[nullable]

gtk_menu_button_get_menu_model ()

GMenuModel *
gtk_menu_button_get_menu_model (GtkMenuButton *menu_button);

Returns the GMenuModel used to generate the popup.

Parameters

menu_button

a GtkMenuButton

 

Returns

a GMenuModel or NULL.

[nullable][transfer none]


gtk_menu_button_set_direction ()

void
gtk_menu_button_set_direction (GtkMenuButton *menu_button,
                               GtkArrowType direction);

Sets the direction in which the popup will be popped up, as well as changing the arrow’s direction. The child will not be changed to an arrow if it was customized.

If the does not fit in the available space in the given direction, GTK+ will its best to keep it inside the screen and fully visible.

If you pass GTK_ARROW_NONE for a direction , the popup will behave as if you passed GTK_ARROW_DOWN (although you won’t see any arrows).

Parameters

menu_button

a GtkMenuButton

 

direction

a GtkArrowType

 

gtk_menu_button_get_direction ()

GtkArrowType
gtk_menu_button_get_direction (GtkMenuButton *menu_button);

Returns the direction the popup will be pointing at when popped up.

Parameters

menu_button

a GtkMenuButton

 

Returns

a GtkArrowType value


gtk_menu_button_set_align_widget ()

void
gtk_menu_button_set_align_widget (GtkMenuButton *menu_button,
                                  GtkWidget *align_widget);

Sets the GtkWidget to use to line the menu with when popped up. Note that the align_widget must contain the GtkMenuButton itself.

Setting it to NULL means that the menu will be aligned with the button itself.

Note that this property is only used with menus currently, and not for popovers.

Parameters

menu_button

a GtkMenuButton

 

align_widget

a GtkWidget.

[allow-none]

gtk_menu_button_get_align_widget ()

GtkWidget *
gtk_menu_button_get_align_widget (GtkMenuButton *menu_button);

Returns the parent GtkWidget to use to line up with menu.

Parameters

menu_button

a GtkMenuButton

 

Returns

a GtkWidget value or NULL.

[nullable][transfer none]


gtk_menu_button_set_icon_name ()

void
gtk_menu_button_set_icon_name (GtkMenuButton *menu_button,
                               const char *icon_name);

Sets the name of an icon to show inside the menu button.

Parameters

menu_button

a GtkMenuButton

 

icon_name

the icon name

 

gtk_menu_button_get_icon_name ()

const char *
gtk_menu_button_get_icon_name (GtkMenuButton *menu_button);

Gets the name of the icon shown in the button.

Parameters

menu_button

a GtkMenuButton

 

Returns

the name of the icon shown in the button


gtk_menu_button_set_label ()

void
gtk_menu_button_set_label (GtkMenuButton *menu_button,
                           const char *label);

Sets the label to show inside the menu button.

Parameters

menu_button

a GtkMenuButton

 

label

the label

 

gtk_menu_button_get_label ()

const char *
gtk_menu_button_get_label (GtkMenuButton *menu_button);

Gets the label shown in the button

Parameters

menu_button

a GtkMenuButton

 

Returns

the label shown in the button


gtk_menu_button_set_has_frame ()

void
gtk_menu_button_set_has_frame (GtkMenuButton *menu_button,
                               gboolean has_frame);

Sets the style of the button.

Parameters

menu_button

a GtkMenuButton

 

has_frame

whether the button should have a visible frame

 

gtk_menu_button_get_has_frame ()

gboolean
gtk_menu_button_get_has_frame (GtkMenuButton *menu_button);

Returns whether the button has a frame.

Parameters

menu_button

a GtkMenuButton

 

Returns

TRUE if the button has a frame


gtk_menu_button_get_use_underline ()

gboolean
gtk_menu_button_get_use_underline (GtkMenuButton *menu_button);

Returns whether an embedded underline in the text indicates a mnemonic. See gtk_menu_button_set_use_underline().

Parameters

menu_button

a GtkMenuButton

 

Returns

TRUE whether an embedded underline in the text indicates the mnemonic accelerator keys.


gtk_menu_button_set_use_underline ()

void
gtk_menu_button_set_use_underline (GtkMenuButton *menu_button,
                                   gboolean use_underline);

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

Parameters

menu_button

a GtkMenuButton

 

use_underline

TRUE if underlines in the text indicate mnemonics

 

gtk_menu_button_popup ()

void
gtk_menu_button_popup (GtkMenuButton *menu_button);

Pop up the menu.

Parameters

menu_button

a GtkMenuButton

 

gtk_menu_button_popdown ()

void
gtk_menu_button_popdown (GtkMenuButton *menu_button);

Dismiss the menu.

Parameters

menu_button

a GtkMenuButton

 

GtkMenuButtonCreatePopupFunc ()

void
(*GtkMenuButtonCreatePopupFunc) (GtkMenuButton *menu_button,
                                 gpointer user_data);

User-provided callback function to create a popup for menu_button on demand. This function is called when the popup of menu_button is shown, but none has been provided via gtk_menu_button_set_popover() or gtk_menu_button_set_menu_model().

Parameters

menu_button

the GtkMenuButton

 

gtk_menu_button_set_create_popup_func ()

void
gtk_menu_button_set_create_popup_func (GtkMenuButton *menu_button,
                                       GtkMenuButtonCreatePopupFunc func,
                                       gpointer user_data,
                                       GDestroyNotify destroy_notify);

Sets func to be called when a popup is about to be shown. func should use one of

  • gtk_menu_button_set_popover()

  • gtk_menu_button_set_menu_model()

to set a popup for menu_button . If func is non-NULL, menu_button will always be sensitive.

Using this function will not reset the menu widget attached to menu_button . Instead, this can be done manually in func .

Parameters

menu_button

a GtkMenuButton

 

func

function to call when a popuop is about to be shown, but none has been provided via other means, or NULL to reset to default behavior.

[nullable]

user_data

user data to pass to func .

[closure]

destroy_notify

destroy notify for user_data .

[nullable]

Types and Values

GtkMenuButton

typedef struct _GtkMenuButton GtkMenuButton;

enum GtkArrowType

Used to indicate the direction in which an arrow should point.

Members

GTK_ARROW_UP

Represents an upward pointing arrow.

 

GTK_ARROW_DOWN

Represents a downward pointing arrow.

 

GTK_ARROW_LEFT

Represents a left pointing arrow.

 

GTK_ARROW_RIGHT

Represents a right pointing arrow.

 

GTK_ARROW_NONE

No arrow.

 

Property Details

The “align-widget” property

  “align-widget”             GtkWidget *

The GtkWidget to use to align the menu with.

Owner: GtkMenuButton

Flags: Read / Write


The “direction” property

  “direction”                GtkArrowType

The GtkArrowType representing the direction in which the menu or popover will be popped out.

Owner: GtkMenuButton

Flags: Read / Write

Default value: GTK_ARROW_DOWN


The “has-frame” property

  “has-frame”                gboolean

Whether the button has a frame.

Owner: GtkMenuButton

Flags: Read / Write

Default value: TRUE


The “icon-name” property

  “icon-name”                gchar *

The name of the icon used to automatically populate the button.

Owner: GtkMenuButton

Flags: Read / Write

Default value: NULL


The “label” property

  “label”                    gchar *

The label for the button.

Owner: GtkMenuButton

Flags: Read / Write

Default value: NULL


The “menu-model” property

  “menu-model”               GMenuModel *

The GMenuModel from which the popup will be created.

See gtk_menu_button_set_menu_model() for the interaction with the “popup” property.

Owner: GtkMenuButton

Flags: Read / Write


The “popover” property

  “popover”                  GtkPopover *

The GtkPopover that will be popped up when the button is clicked.

Owner: GtkMenuButton

Flags: Read / Write


The “use-underline” property

  “use-underline”            gboolean

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

Owner: GtkMenuButton

Flags: Read / Write

Default value: FALSE