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

## Functions

GtkWidget * | gtk_menu_button_new ()
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_direction ()
GtkArrowType | gtk_menu_button_get_direction ()
void | gtk_menu_button_set_align_widget ()
GtkWidget * | gtk_menu_button_get_align_widget ()
void | gtk_menu_button_set_icon_name ()
const char * | gtk_menu_button_get_icon_name ()
void | gtk_menu_button_set_label ()
const char * | gtk_menu_button_get_label ()
void | gtk_menu_button_set_has_frame ()
gboolean | gtk_menu_button_get_has_frame ()
gboolean | gtk_menu_button_get_use_underline ()
void | gtk_menu_button_set_use_underline ()
void | gtk_menu_button_popup ()
void | gtk_menu_button_popdown ()
void | (*GtkMenuButtonCreatePopupFunc) ()
void | gtk_menu_button_set_create_popup_func ()

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

| GtkMenuButton
enum | GtkArrowType

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