GtkMenuButton: GTK+ 3 Reference Manual

## GtkMenuButton GtkMenuButton — A widget that shows a popup when clicked on |

## Functions

GtkWidget * | gtk_menu_button_new ()
void | gtk_menu_button_set_popup ()
GtkMenu * | gtk_menu_button_get_popup ()
void | gtk_menu_button_set_popover ()
GtkPopover * | gtk_menu_button_get_popover ()
void | gtk_menu_button_set_menu_model ()
GMenuModel * | gtk_menu_button_get_menu_model ()
void | gtk_menu_button_set_use_popover ()
gboolean | gtk_menu_button_get_use_popover ()
void | gtk_menu_button_set_direction ()
GtkArrowType | gtk_menu_button_get_direction ()
void | gtk_menu_button_set_align_widget ()
GtkWidget * | gtk_menu_button_get_align_widget ()

## Properties

GtkContainer * | align-widget | Read / Write
GtkArrowType | direction | Read / Write
GMenuModel * | menu-model | Read / Write
GtkPopover * | popover | Read / Write
GtkMenu * | popup | Read / Write
gboolean | use-popover | Read / Write

## Types and Values

struct | GtkMenuButton
enum | GtkArrowType

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkButton
                            ╰── GtkToggleButton
                                ╰── GtkMenuButton

## Implemented Interfaces

GtkMenuButton implements AtkImplementorIface, GtkBuildable, GtkActionable and GtkActivatable.

## 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 GtkMenu, a GtkPopover or an abstract GMenuModel.

The GtkMenuButton widget can hold any valid child widget. That is, it can hold almost any other standard GtkWidget. The most commonly used child is GtkImage. If no widget is explicitely added to the GtkMenuButton, 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

Since: 3.6

### gtk_menu_button_set_popup ()

    void
    gtk_menu_button_set_popup (GtkMenuButton *menu_button,
                               GtkWidget *menu);

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

If “menu-model” or “popover” are set, those objects are dissociated from the `menu_button` , and those properties are set to `NULL`.

#### Parameters

menu_button | a GtkMenuButton |
menu | a GtkMenu, or `NULL` to unset and disable the button. | [nullable]

Since: 3.6

### gtk_menu_button_get_popup ()

    GtkMenu *
    gtk_menu_button_get_popup (GtkMenuButton *menu_button);

Returns the GtkMenu that pops out of the button. If the button does not use a GtkMenu, this function returns `NULL`.

#### Parameters

menu_button | a GtkMenuButton |

#### Returns

a GtkMenu or `NULL`.

[nullable][transfer none]

Since: 3.6

### 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” or “popup” are set, those objects are dissociated from the `menu_button` , and those properties are set to `NULL`.

#### Parameters

menu_button | a GtkMenuButton |
popover | a GtkPopover, or `NULL` to unset and disable the button. | [nullable]

Since: 3.12

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

Since: 3.12

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

Depending on the value of “use-popover”, either a GtkMenu will be created with `gtk_menu_new_from_model()`, or a GtkPopover with `gtk_popover_new_from_model()`. In either case, actions will be connected as documented for these functions.

If “popup” or “popover” are already set, those widgets are dissociated from the `menu_button` , and those properties are set to `NULL`.

#### Parameters

menu_button | a GtkMenuButton |
menu_model | a GMenuModel, or `NULL` to unset and disable the button. | [nullable]

Since: 3.6

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

Since: 3.6

### gtk_menu_button_set_use_popover ()

    void
    gtk_menu_button_set_use_popover (GtkMenuButton *menu_button,
                                     gboolean use_popover);

Sets whether to construct a GtkPopover instead of GtkMenu when `gtk_menu_button_set_menu_model()` is called. Note that this property is only consulted when a new menu model is set.

#### Parameters

menu_button | a GtkMenuButton |
use_popover | `TRUE` to construct a popover from the menu model |

Since: 3.12

### gtk_menu_button_get_use_popover ()

    gboolean
    gtk_menu_button_get_use_popover (GtkMenuButton *menu_button);

Returns whether a GtkPopover or a GtkMenu will be constructed from the menu model.

#### Parameters

menu_button | a GtkMenuButton |

#### Returns

`TRUE` if using a GtkPopover

Since: 3.12

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

Since: 3.6

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

Since: 3.6

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

Since: 3.6

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

Since: 3.6

## Types and Values

### struct GtkMenuButton

    struct 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. Since 2.10. |

## Property Details

### The `“align-widget”` property

      “align-widget”             GtkContainer *

The GtkWidget to use to align the menu with.

Flags: Read / Write

Since: 3.6

### The `“direction”` property

      “direction”                GtkArrowType

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

Flags: Read / Write

Default value: GTK_ARROW_DOWN

Since: 3.6

### The `“menu-model”` property

      “menu-model”               GMenuModel *

The GMenuModel from which the popup will be created. Depending on the “use-popover” property, that may be a menu or a popover.

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

Flags: Read / Write

Since: 3.6

### The `“popover”` property

      “popover”                  GtkPopover *

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

Flags: Read / Write

Since: 3.12

### The `“popup”` property

      “popup”                    GtkMenu *

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

Flags: Read / Write

Since: 3.6

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

      “use-popover”              gboolean

Whether to construct a GtkPopover from the menu model, or a GtkMenu.

Flags: Read / Write

Default value: TRUE

Since: 3.12