GNOME.org
 

[gtk/kill-tree-menu: 41/43] docs: Rewrite popover menu docs

commit b06331218da519d1f96f6b9ffdaefbb4506f5714
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Dec 29 19:44:31 2019 -0500

    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().
  *
  * |[
  * <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"
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
- *
- * |[
- * <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)
 {
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",
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]