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.
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.
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.
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.
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).
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.
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.
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.
Since: 3.6
Property Details
The “align-widget” property
“align-widget” GtkContainer *
The GtkWidget to use to align the menu with.
Owner: GtkMenuButton
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.
Owner: GtkMenuButton
Flags: Read / Write
Default value: GTK_ARROW_DOWN
Since: 3.6
The “popover” property
“popover” GtkPopover *
The GtkPopover that will be popped up when the button is clicked.
Owner: GtkMenuButton
Flags: Read / Write
Since: 3.12
The “popup” property
“popup” GtkMenu *
The GtkMenu that will be popped up when the button is clicked.
Owner: GtkMenuButton
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.
Owner: GtkMenuButton
Flags: Read / Write
Default value: TRUE
Since: 3.12