* The position of a popover relative to the widget it is attached to
* can also be changed through gtk_popover_set_position().
*
- * By default, #GtkPopover performs a GTK+ grab, in order to ensure
- * input events get redirected to it while it is shown, and also so
- * the popover is dismissed in the expected situations (clicks outside
- * the popover, or the Esc key being pressed). If no such modal behavior
- * is desired on a popover, gtk_popover_set_autohide() may be called
- * on it to tweak its behavior.
+ * By default, #GtkPopover performs a grab, in order to ensure input events
+ * get redirected to it while it is shown, and also so the popover is dismissed
+ * in the expected situations (clicks outside the popover, or the Escape key
+ * being pressed). If no such modal behavior is desired on a popover,
+ * gtk_popover_set_autohide() may be called on it to tweak its behavior.
*
* ## GtkPopover as menu replacement
*
- * GtkPopover is often used to replace menus. To facilitate this, it
- * supports being populated from a #GMenuModel, using
- * gtk_popover_menu_new_from_model(). In addition to all the regular
- * menu model features, this function supports rendering sections in
- * the model in a more compact form, as a row of icon buttons instead
- * of menu items.
- *
- * To use this rendering, set the ”display-hint” attribute of the
- * section to ”horizontal-buttons” and set the icons of your items
- * with the ”verb-icon” attribute.
+ * GtkPopover is often used to replace menus. The best was to do this
+ * is to use the #GtkPopoverMenu subclass which supports being populated
+ * from a #GMenuModel with gtk_popover_menu_new_from_model().
*
* |[
* <section>
*
* The contents child node always gets the .background style class and
* the popover itself gets the .menu style class if the popover is
- * menu-like (ie #GtkPopoverMenu).
+ * menu-like (i.e. #GtkPopoverMenu).
*
- * Particular uses of GtkPopover, such as touch selection popups
- * or magnifiers in #GtkEntry or #GtkTextView get style classes
- * like .touch-selection or .magnifier to differentiate from
- * plain popovers.
+ * Particular uses of GtkPopover, such as touch selection popups or magnifiers
+ * in #GtkEntry or #GtkTextView get style classes like .touch-selection or .magnifier
+ * to differentiate from plain popovers.
*
* When styling a popover directly, the popover node should usually
* not have any background.
*
* Note that, in order to accomplish appropriate arrow visuals, #GtkPopover uses
- * custom drawing for the arrow node. This makes it possible for the arrow to change
- * its shape dynamically, but it also limits the possibilities of styling it using CSS.
- * In particular, the arrow gets drawn over the content node's border so they look
- * like one shape, which means that the border-width of the content node and the arrow
- * node should be the same. The arrow also does not support any border shape other than
- * solid, no border-radius, only one border width (border-bottom-width is used) and no box-shadow.
+ * custom drawing for the arrow node. This makes it possible for the arrow to
+ * change its shape dynamically, but it also limits the possibilities of styling
+ * it using CSS. In particular, the arrow gets drawn over the content node's
+ * border so they look like one shape, which means that the border-width of
+ * the content node and the arrow node should be the same. The arrow also does
+ * not support any border shape other than solid, no border-radius, only one
+ * border width (border-bottom-width is used) and no box-shadow.
*/
#include "config.h"
* @Title: GtkPopoverMenu
*
* GtkPopoverMenu is a subclass of #GtkPopover that treats its
- * children like menus and allows switching between them. It is
- * meant to be used primarily together with #GtkModelButton, but
- * any widget can be used, such as #GtkSpinButton or #GtkScale.
- * In this respect, GtkPopoverMenu is more flexible than popovers
- * that are created from a #GMenuModel with gtk_popover_new_from_model().
+ * children like menus and allows switching between them. It
+ * can open submenus as traditional, nested submenus, or in a
+ * more touch-friendly sliding fashion.
*
- * To add a child as a submenu, use gtk_popover_menu_add_submenu().
- * To let the user open this submenu, add a #GtkModelButton whose
- * #GtkModelButton:menu-name property is set to the name you've given
- * to the submenu.
+ * GtkPopoverMenu is meant to be used primarily with menu models,
+ * using gtk_popover_menu_new_from_model(). If you need to put other
+ * widgets such as #GtkSpinButton or #GtkSwitch into a popover,
+ * use a #GtkPopover.
*
- * To add a named submenu in a ui file, set the #GtkWidget:name property
- * of the widget that you are adding as a child of the popover menu.
+ * In addition to all the regular menu model features, this function
+ * supports rendering sections in the model in a more compact form,
+ * as a row of image buttons instead of menu items.
*
- * By convention, the first child of a submenu should be a #GtkModelButton
- * to switch back to the parent menu. Such a button should use the
- * #GtkModelButton:inverted and #GtkModelButton:centered properties
- * to achieve a title-like appearance and place the submenu indicator
- * at the opposite side. To switch back to the main menu, use "main"
- * as the menu name.
- *
- * # Example
- *
- * |[
- * <object class="GtkPopoverMenu">
- * <child>
- * <object class="GtkBox">
- * <property name="visible">True</property>
- * <property name="margin">10</property>
- * <child>
- * <object class="GtkModelButton">
- * <property name="visible">True</property>
- * <property name="action-name">win.frob</property>
- * <property name="text" translatable="yes">Frob</property>
- * </object>
- * </child>
- * <child>
- * <object class="GtkModelButton">
- * <property name="visible">True</property>
- * <property name="menu-name">more</property>
- * <property name="text" translatable="yes">More</property>
- * </object>
- * </child>
- * </object>
- * </child>
- * <child>
- * <object class="GtkBox">
- * <property name="visible">True</property>
- * <property name="margin">10</property>
- * <property name="name">more</property>
- * <child>
- * <object class="GtkModelButton">
- * <property name="visible">True</property>
- * <property name="action-name">win.foo</property>
- * <property name="text" translatable="yes">Foo</property>
- * </object>
- * </child>
- * <child>
- * <object class="GtkModelButton">
- * <property name="visible">True</property>
- * <property name="action-name">win.bar</property>
- * <property name="text" translatable="yes">Bar</property>
- * </object>
- * </child>
- * </object>
- * </child>
- * </object>
- * ]|
+ * To use this rendering, set the ”display-hint” attribute of the
+ * section to ”horizontal-buttons” and set the icons of your items
+ * with the ”verb-icon” attribute.
*
* # CSS Nodes
*
return popover;
}
-/**
+/*<private>
* gtk_popover_menu_open_submenu:
* @popover: a #GtkPopoverMenu
* @name: the name of the menu to switch to
* @model. The popover is pointed to the @relative_to widget.
*
* The created buttons are connected to actions found in the
- * #GtkApplicationWindow to which the popover belongs - typically
- * by means of being attached to a widget that is contained within
- * the #GtkApplicationWindows widget hierarchy.
- *
- * Actions can also be added using gtk_widget_insert_action_group()
- * on the menus attach widget or on any of its parent widgets.
+ * action groups that are accessible from the @relative-to widget.
+ * This includes the #GtkApplicationWindow to which the popover
+ * belongs. Actions can also be added using gtk_widget_insert_action_group()
+ * on the @relative-to widget or on any of its parent widgets.
*
* The only flag that is supported currently is
* #GTK_POPOVER_MENU_NESTED, which makes GTK create traditional,
return popover;
}
+/**
+ * gtk_popover_menu_set_model:
+ * @popover: a #GtkPopoverMenu
+ * @model: (nullable): a #GtkMenuModel, or %NULL
+ *
+ * Sets a new menu model on @popover.
+ *
+ * The existing contents of @popover are removed, and
+ * the @popover is populated with new contents according
+ * to @model.
+ */
void
gtk_popover_menu_set_menu_model (GtkPopoverMenu *popover,
GMenuModel *model)
}
}
+/**
+ * gtk_popover_menu_get_menu_model:
+ * @popover: a #GtkPopoverMenu
+ *
+ * Returns the menu model used to populate the popover.
+ *
+ * Returns: the menu model of @popover
+ */
GMenuModel *
gtk_popover_menu_get_menu_model (GtkPopoverMenu *popover)
{
projects / gtk4.git / commitdiff