From b06331218da519d1f96f6b9ffdaefbb4506f5714 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 29 Dec 2019 19:44:31 -0500 Subject: [PATCH] docs: Rewrite popover menu docs These were outdated and did not reflect current api. --- gtk/gtkpopover.c | 46 +++++++---------- gtk/gtkpopovermenu.c | 109 ++++++++++++++-------------------------- gtk/gtkpopovermenubar.c | 11 ++-- 3 files changed, 62 insertions(+), 104 deletions(-) diff --git a/gtk/gtkpopover.c b/gtk/gtkpopover.c index 4761e8bb1b..bcda0fdd50 100644 --- a/gtk/gtkpopover.c +++ b/gtk/gtkpopover.c @@ -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(). * * |[ *
@@ -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" diff --git a/gtk/gtkpopovermenu.c b/gtk/gtkpopovermenu.c index dc3212b533..06f24532e8 100644 --- a/gtk/gtkpopovermenu.c +++ b/gtk/gtkpopovermenu.c @@ -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 - * - * |[ - * - * - * - * True - * 10 - * - * - * True - * win.frob - * Frob - * - * - * - * - * True - * more - * More - * - * - * - * - * - * - * True - * 10 - * more - * - * - * True - * win.foo - * Foo - * - * - * - * - * True - * win.bar - * Bar - * - * - * - * - * - * ]| + * 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; } -/** +/* * 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) { diff --git a/gtk/gtkpopovermenubar.c b/gtk/gtkpopovermenubar.c index 94f9dbe3d4..c1c6a1704f 100644 --- a/gtk/gtkpopovermenubar.c +++ b/gtk/gtkpopovermenubar.c @@ -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",