mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-12 20:00:09 +00:00
docs: Rewrite popover menu docs
These were outdated and did not reflect current api.
This commit is contained in:
Matthias Clasen
parent
9b165c8bec
commit
b06331218d
@ -33,25 +33,17 @@
|
||||
* 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>
|
||||
@ -85,23 +77,23 @@
|
||||
*
|
||||
* 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"
|
||||
|
||||
@ -43,74 +43,22 @@
|
||||
* @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
|
||||
*
|
||||
@ -539,7 +487,7 @@ gtk_popover_menu_new (GtkWidget *relative_to)
|
||||
return popover;
|
||||
}
|
||||
|
||||
/**
|
||||
/*<private>
|
||||
* gtk_popover_menu_open_submenu:
|
||||
* @popover: a #GtkPopoverMenu
|
||||
* @name: the name of the menu to switch to
|
||||
@ -617,12 +565,10 @@ gtk_popover_menu_new_from_model (GtkWidget *relative_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,
|
||||
@ -647,6 +593,17 @@ gtk_popover_menu_new_from_model_full (GtkWidget *relative_to,
|
||||
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)
|
||||
@ -670,6 +627,14 @@ gtk_popover_menu_set_menu_model (GtkPopoverMenu *popover,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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)
|
||||
{
|
||||
|
||||
@ -24,9 +24,11 @@
|
||||
* @Short_description: A menu bar with popovers
|
||||
* @See_also: #GtkPopover, #GtkPopoverMenu, #GMenuModel
|
||||
*
|
||||
* The #GtkPopoverBar presents a horizontal bar of items that pop
|
||||
* up popover menus when clicked. The only way to create instances
|
||||
* of GtkPopoverBar is from a #GMenuModel.
|
||||
* GtkPopoverMenuBar presents a horizontal bar of items that pop
|
||||
* up popover menus when clicked.
|
||||
*
|
||||
* The only way to create instances of GtkPopoverMenuBar is
|
||||
* from a #GMenuModel.
|
||||
*
|
||||
* # CSS nodes
|
||||
*
|
||||
@ -589,8 +591,7 @@ gtk_popover_menu_bar_class_init (GtkPopoverMenuBarClass *klass)
|
||||
*
|
||||
* The #GMenuModel from which the menu bar is created.
|
||||
*
|
||||
* The model should only contain submenus as toplevel
|
||||
* items.
|
||||
* The model should only contain submenus as toplevel elements.
|
||||
*/
|
||||
bar_props[PROP_MENU_MODEL] =
|
||||
g_param_spec_object ("menu-model",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user