About all my projects
Gnome::Gtk3::MenuButton

Gnome::Gtk3::MenuButton

A widget that shows a popup when clicked on

No caption

Description

The Gnome::Gtk3::MenuButton widget is used to display a popup when clicked on. This popup can be provided either as a Gnome::Gtk3::Menu, a Gnome::Gtk3::Popover or an abstract MenuModel.

The Gnome::Gtk3::MenuButton widget can hold any valid child widget. That is, it can hold almost any other standard Gnome::Gtk3::Widget. The most commonly used child is Gnome::Gtk3::Image. If no widget is explicitely added to the Gnome::Gtk3::MenuButton, a Gnome::Gtk3::Image is automatically created, using an arrow image oriented according to direction or the generic "view-context-menu" 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

No caption

  • halign = center

No caption

  • halign = end

No caption

Direction = Up

  • halign = start

No caption

  • halign = center

No caption

  • halign = end

No caption

Direction = Left

  • valign = start

No caption

  • valign = center

No caption

  • valign = end

No caption

Direction = Right

  • valign = start

No caption

  • valign = center

No caption

  • valign = end

No caption

Css Nodes

Gnome::Gtk3::MenuButton has a single CSS node with name button. To differentiate it from a plain Gnome::Gtk3::Button, it gets the .popup style class.

Synopsis

Declaration

unit class Gnome::Gtk3::MenuButton;
also is Gnome::Gtk3::ToggleButton;

Uml Diagram

No caption

Inheriting this class

Inheriting is done in a special way in that it needs a call from new() to get the native object created by the class you are inheriting from.

use Gnome::Gtk3::MenuButton:api<1>;

unit class MyGuiClass;
also is Gnome::Gtk3::MenuButton;

submethod new ( |c ) {
  # let the Gnome::Gtk3::MenuButton class process the options
  self.bless( :GtkMenuButton, |c);
}

submethod BUILD ( ... ) {
  ...
}

Methods

new

default, no options

Creates a new Gnome::Gtk3::MenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another Gnome::Gtk3::Widget should you wish to.

multi method new ( )

:native-object

Create an object using a native object from elsewhere. See also Gnome::GObject::Object.

multi method new ( N-GObject :$native-object! )

:build-id

Create an object using a native object from a builder. See also Gnome::GObject::Object.

multi method new ( Str :$build-id! )

get-align-widget

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

Returns: a Gnome::Gtk3::Widget value or undefined

method get-align-widget ( --> N-GObject )

get-direction

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

Returns: a Gnome::Gtk3::ArrowType value

method get-direction ( --> GtkArrowType )

get-menu-model

Returns the Gnome::Gio::MenuModel used to generate the popup.

Returns: a Gnome::Gio::MenuModel or an invalid object.

method get-menu-model ( --> Gnome::Gio::MenuModel )

get-popover

Returns the Gnome::Gtk3::Popover that pops out of the button. If the button is not using a Gnome::Gtk3::Popover, this function returns an invalid popover object.

method get-popover ( --> Gnome::Gtk3::Popover )

get-popup

Returns the Gnome::Gtk3::Menu that pops out of the button. If the button does not use a Gnome::Gtk3::Menu, this function returns an invalid menu object.

method get-popup ( --> Gnome::Gtk3::Menu )

get-use-popover

Returns whether a Gnome::Gtk3::Popover or a Gnome::Gtk3::Menu will be constructed from the menu model.

Returns: True if using a Gnome::Gtk3::Popover

method get-use-popover ( --> Bool )

set-align-widget

Sets the Gnome::Gtk3::Widget to use to line the menu with when popped up. Note that the $align-widget must contain the Gnome::Gtk3::MenuButton itself.

Setting it to undefined 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.

method set-align-widget ( N-GObject $align_widget )

  • N-GObject $align_widget; a Gnome::Gtk3::Widget

set-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).

method set-direction ( GtkArrowType $direction )

  • GtkArrowType $direction; a Gnome::Gtk3::ArrowType

set-menu-model

Sets the Gnome::Gio::MenuModel from which the popup will be constructed, or undefined to dissociate any existing menu model and disable the button.

Depending on the value of use-popover, either a Gnome::Gtk3::Menu will be created, or a Gnome::Gtk3::Popover. 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 undefined.

method set-menu-model ( N-GObject $menu_model )

  • N-GObject $menu_model; a Gnome::Gio::MenuModel, or undefined to unset and disable the button

set-popover

Sets the Gnome::Gtk3::Popover that will be popped up when the menu-button is clicked, or undefined 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 undefined.

method set-popover ( N-GObject $popover )

  • N-GObject $popover; a Gnome::Gtk3::Popover, or undefined to unset and disable the button

set-popup

Sets the Gnome::Gtk3::Menu that will be popped up when the menu-button is clicked, or undefined 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 undefined.

method set-popup ( N-GObject $menu )

  • N-GObject $menu; a Gnome::Gtk3::Menu, or undefined to unset and disable the button

set-use-popover

Sets whether to construct a Gnome::Gtk3::Popover instead of Gnome::Gtk3::Menu when set-menu-model() is called. Note that this property is only consulted when a new menu model is set.

method set-use-popover ( Bool $use_popover )

  • Bool $use_popover; True to construct a popover from the menu model

_gtk_menu_button_new

Creates a new Gnome::Gtk3::MenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another Gnome::Gtk3::Widget should you wish to.

Returns: The newly created Gnome::Gtk3::MenuButton widget

method _gtk_menu_button_new ( --> N-GObject )

Properties

An example of using a string type property of a Gnome::Gtk3::Label object. This is just showing how to set/read a property, not that it is the best way to do it. This is because a) The class initialization often provides some options to set some of the properties and b) the classes provide many methods to modify just those properties. In the case below one can use new(:label('my text label')) or .set-text('my text label').

my Gnome::Gtk3::Label $label .= new;
my Gnome::GObject::Value $gv .= new(:init(G_TYPE_STRING));
$label.get-property( 'label', $gv);
$gv.set-string('my text label');

Supported properties

Align with: align-widget

The Gnome::Gtk3::Widget to use to align the menu with.

Widget type: GTK_TYPE_CONTAINER

The Gnome::GObject::Value type of property align-widget is G_TYPE_OBJECT.

Direction: direction

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

Widget type: GTK_TYPE_ARROW_TYPE

The Gnome::GObject::Value type of property direction is G_TYPE_ENUM.

The Gnome::Gio::MenuModel from which the popup will be created. Depending on the use-popover property, that may be a menu or a popover.

See set-menu-model() for the interaction with the popup property.

Widget type: G_TYPE_MENU_MODEL

The Gnome::GObject::Value type of property menu-model is G_TYPE_OBJECT.

Popover: popover

The Gnome::Gtk3::Popover that will be popped up when the button is clicked.

Widget type: GTK_TYPE_POPOVER

The Gnome::GObject::Value type of property popover is G_TYPE_OBJECT.

Popup: popup

The Gnome::Gtk3::Menu that will be popped up when the button is clicked.

Widget type: GTK_TYPE_MENU

The Gnome::GObject::Value type of property popup is G_TYPE_OBJECT.

Use a popover: use-popover

Whether to construct a Gnome::Gtk3::Popover from the menu model, or a Gnome::Gtk3::Menu.

The Gnome::GObject::Value type of property use-popover is G_TYPE_BOOLEAN.

[gtk_] menu_button_new

Creates a new Gnome::Gtk3::MenuButton widget with downwards-pointing arrow as the only child. You can replace the child widget with another Gnome::Gtk3::Widget should you wish to.

Returns: The newly created Gnome::Gtk3::MenuButton widget

Since: 3.6

method gtk_menu_button_new ( --> N-GObject  )

[[gtk_] menu_button_] set_popup

Sets the Gnome::Gtk3::Menu that will be popped up when the button is clicked, or Any to disable the button. If menu-model or popover are set, they will be set to Any.

Since: 3.6

method gtk_menu_button_set_popup ( N-GObject $menu )

  • N-GObject $menu; (allow-none): a Gnome::Gtk3::Menu

[[gtk_] menu_button_] get_popup

Returns the Gnome::Gtk3::Menu that pops out of the button. If the button does not use a Gnome::Gtk3::Menu, this function returns Any.

Returns: (nullable) (transfer none): a Gnome::Gtk3::Menu or Any

Since: 3.6

method gtk_menu_button_get_popup ( --> N-GObject  )

[[gtk_] menu_button_] set_popover

Sets the Gnome::Gtk3::Popover that will be popped up when the button is clicked, or Any to disable the button. If menu-model or popup are set, they will be set to Any.

Since: 3.12

method gtk_menu_button_set_popover ( N-GObject $popover )

  • N-GObject $popover; (allow-none): a Gnome::Gtk3::Popover

[[gtk_] menu_button_] get_popover

Returns the Gnome::Gtk3::Popover that pops out of the button. If the button is not using a Gnome::Gtk3::Popover, this function returns Any.

Returns: (nullable) (transfer none): a Gnome::Gtk3::Popover or Any

Since: 3.12

method gtk_menu_button_get_popover ( --> N-GObject  )

[[gtk_] menu_button_] set_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

method gtk_menu_button_set_direction ( GtkArrowType $direction )

  • GtkArrowType $direction; a Gnome::Gtk3::ArrowType

[[gtk_] menu_button_] get_direction

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

Returns: a Gnome::Gtk3::ArrowType value

Since: 3.6

method gtk_menu_button_get_direction ( --> GtkArrowType  )

[[gtk_] menu_button_] set_menu_model

Sets the N-GObject from which the popup will be constructed, or Any to disable the button.

Depending on the value of use-popover, either a Gnome::Gtk3::Menu will be created with gtk_menu_new_from_model(), or a Gnome::Gtk3::Popover 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, their content will be lost and replaced by the newly created popup.

Since: 3.6

method gtk_menu_button_set_menu_model ( N-GObject $menu_model )

  • N-GObject $menu_model; (allow-none): a N-GObject

[[gtk_] menu_button_] get_menu_model

Returns the N-GObject used to generate the popup.

Returns: (nullable) (transfer none): a N-GObject or Any

Since: 3.6

method gtk_menu_button_get_menu_model ( --> N-GObject  )

[[gtk_] menu_button_] set_align_widget

Sets the Gnome::Gtk3::Widget to use to line the menu with when popped up. Note that the align_widget must contain the Gnome::Gtk3::MenuButton itself.

Setting it to Any 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

method gtk_menu_button_set_align_widget ( N-GObject $align_widget )

  • N-GObject $align_widget; (allow-none): a Gnome::Gtk3::Widget

[[gtk_] menu_button_] get_align_widget

Returns the parent Gnome::Gtk3::Widget to use to line up with menu.

Returns: (nullable) (transfer none): a Gnome::Gtk3::Widget value or Any

Since: 3.6

method gtk_menu_button_get_align_widget ( --> N-GObject  )

[[gtk_] menu_button_] set_use_popover

Sets whether to construct a Gnome::Gtk3::Popover instead of Gnome::Gtk3::Menu when gtk_menu_button_set_menu_model() is called. Note that this property is only consulted when a new menu model is set.

Since: 3.12

method gtk_menu_button_set_use_popover ( Int $use_popover )

  • Int $use_popover; 1 to construct a popover from the menu model

[[gtk_] menu_button_] get_use_popover

Returns whether a Gnome::Gtk3::Popover or a Gnome::Gtk3::Menu will be constructed from the menu model.

Returns: 1 if using a Gnome::Gtk3::Popover

Since: 3.12

method gtk_menu_button_get_use_popover ( --> Int  )

Properties

An example of using a string type property of a Gnome::Gtk3::Label object. This is just showing how to set/read a property, not that it is the best way to do it. This is because a) The class initialization often provides some options to set some of the properties and b) the classes provide many methods to modify just those properties. In the case below one can use new(:label('my text label')) or gtk_label_set_text('my text label').

my Gnome::Gtk3::Label $label .= new;
my Gnome::GObject::Value $gv .= new(:init(G_TYPE_STRING));
$label.g-object-get-property( 'label', $gv);
$gv.g-value-set-string('my text label');

Supported properties

The Gnome::Gtk3::Menu that will be popped up when the button is clicked. Since: 3.6 Widget type: GTK_TYPE_MENU

The Gnome::GObject::Value type of property popup is G_TYPE_OBJECT.

The N-GObject 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. Since: 3.6 Widget type: G_TYPE_MENU_MODEL

The Gnome::GObject::Value type of property menu-model is G_TYPE_OBJECT.

Align with

The Gnome::Gtk3::Widget to use to align the menu with. Since: 3.6 Widget type: GTK_TYPE_CONTAINER

The Gnome::GObject::Value type of property align-widget is G_TYPE_OBJECT.

Direction

The Gnome::Gtk3::ArrowType representing the direction in which the menu or popover will be popped out. Since: 3.6 Widget type: GTK_TYPE_ARROW_TYPE

The Gnome::GObject::Value type of property direction is G_TYPE_ENUM.

Use a popover

Whether to construct a Gnome::Gtk3::Popover from the menu model, or a Gnome::Gtk3::Menu. Since: 3.12

The Gnome::GObject::Value type of property use-popover is G_TYPE_BOOLEAN.

Popover

The Gnome::Gtk3::Popover that will be popped up when the button is clicked. Since: 3.12 Widget type: GTK_TYPE_POPOVER

The Gnome::GObject::Value type of property popover is G_TYPE_OBJECT.