Merge branch 'matthiasc/for-master' into 'master'

docs: Move menu model docs

See merge request GNOME/gtk!1799

2 files changed, 66 insertions, 49 deletions

diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 6695cc4b36..6f17e65f3f 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -76,6 +76,9 @@
  * menu, then it will automatically be included in the menubar or in the
  * windows client-side decorations.
  *
+ * See #GtkPopoverMenu for information about the XML language
+ * used by #GtkBuilder for menu models.
+ *
  * ## A GtkApplicationWindow with a menubar
  *
  * |[<!-- language="C" -->
@@ -101,48 +104,6 @@
  *
  * GtkWidget *window = gtk_application_window_new (app);
  * ]|
- *
- * ## Handling fallback yourself
- *
- * [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/master/examples/sunny.c)
- *
- * The XML format understood by #GtkBuilder for #GMenuModel consists
- * of a toplevel `<menu>` element, which contains one or more `<item>`
- * elements. Each `<item>` element contains `<attribute>` and `<link>`
- * elements with a mandatory name attribute. `<link>` elements have the
- * same content model as `<menu>`. Instead of `<link name="submenu>` or
- * `<link name="section">`, you can use `<submenu>` or `<section>`
- * elements.
- *
- * Attribute values can be translated using gettext, like other #GtkBuilder
- * content. `<attribute>` elements can be marked for translation with a
- * `translatable="yes"` attribute. It is also possible to specify message
- * context and translator comments, using the context and comments attributes.
- * To make use of this, the #GtkBuilder must have been given the gettext
- * domain to use.
- *
- * The following attributes are used when constructing menu items:
- * - "label": a user-visible string to display
- * - "action": the prefixed name of the action to trigger
- * - "target": the parameter to use when activating the action
- * - "icon" and "verb-icon": names of icons that may be displayed
- * - "submenu-action": name of an action that may be used to determine
- *      if a submenu can be opened
- * - "hidden-when": a string used to determine when the item will be hidden.
- *      Possible values include "action-disabled", "action-missing", "macos-menubar".
- *
- * The following attributes are used when constructing sections:
- * - "label": a user-visible string to use as section heading
- * - "display-hint": a string used to determine special formatting for the section.
- *     Possible values include "horizontal-buttons", "circular-buttons" and "inline-buttons". They all indicate that section should be
- *     displayed as a horizontal row of buttons.
- * - "text-direction": a string used to determine the #GtkTextDirection to use
- *     when "display-hint" is set to "horizontal-buttons". Possible values
- *     include "rtl", "ltr", and "none".
- *
- * The following attributes are used when constructing submenus:
- * - "label": a user-visible string to display
- * - "icon": icon name to display
  */
 
 typedef GSimpleActionGroupClass GtkApplicationWindowActionsClass;
diff --git a/gtk/gtkpopovermenu.c b/gtk/gtkpopovermenu.c
index acb2bc7179..d9faf80f7b 100644
--- a/gtk/gtkpopovermenu.c
+++ b/gtk/gtkpopovermenu.c
@@ -51,15 +51,71 @@
  * 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.
+ * use a plain #GtkPopover.
  *
- * 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.
+ * ## Menu models
  *
- * 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.
+ * The XML format understood by #GtkBuilder for #GMenuModel consists
+ * of a toplevel `<menu>` element, which contains one or more `<item>`
+ * elements. Each `<item>` element contains `<attribute>` and `<link>`
+ * elements with a mandatory name attribute. `<link>` elements have the
+ * same content model as `<menu>`. Instead of `<link name="submenu>` or
+ * `<link name="section">`, you can use `<submenu>` or `<section>`
+ * elements.
+ *
+ * |[<!--language: xml -->
+ * <menu id='app-menu'>
+ *   <section>
+ *     <item>
+ *       <attribute name='label' translatable='yes'>_New Window</attribute>
+ *       <attribute name='action'>app.new</attribute>
+ *     </item>
+ *     <item>
+ *       <attribute name='label' translatable='yes'>_About Sunny</attribute>
+ *       <attribute name='action'>app.about</attribute>
+ *     </item>
+ *     <item>
+ *       <attribute name='label' translatable='yes'>_Quit</attribute>
+ *       <attribute name='action'>app.quit</attribute>
+ *     </item>
+ *   </section>
+ * </menu>
+ * ]|
+ *
+ * Attribute values can be translated using gettext, like other #GtkBuilder
+ * content. `<attribute>` elements can be marked for translation with a
+ * `translatable="yes"` attribute. It is also possible to specify message
+ * context and translator comments, using the context and comments attributes.
+ * To make use of this, the #GtkBuilder must have been given the gettext
+ * domain to use.
+ *
+ * The following attributes are used when constructing menu items:
+ * - "label": a user-visible string to display
+ * - "action": the prefixed name of the action to trigger
+ * - "target": the parameter to use when activating the action
+ * - "icon" and "verb-icon": names of icons that may be displayed
+ * - "submenu-action": name of an action that may be used to determine
+ *      if a submenu can be opened
+ * - "hidden-when": a string used to determine when the item will be hidden.
+ *      Possible values include "action-disabled", "action-missing", "macos-menubar".
+ *      This is mainly useful for exported menus, see gtk_application_set_menubar().
+ *
+ * The following attributes are used when constructing sections:
+ * - "label": a user-visible string to use as section heading
+ * - "display-hint": a string used to determine special formatting for the section.
+ *     Possible values include "horizontal-buttons", "circular-buttons" and "inline-buttons". They all indicate that section should be
+ *     displayed as a horizontal row of buttons.
+ * - "text-direction": a string used to determine the #GtkTextDirection to use
+ *     when "display-hint" is set to "horizontal-buttons". Possible values
+ *     include "rtl", "ltr", and "none".
+ *
+ * The following attributes are used when constructing submenus:
+ * - "label": a user-visible string to display
+ * - "icon": icon name to display
+ *
+ * Menu items will also show accelerators, which are usually associated
+ * with actions via gtk_application_set_accels_for_action(),
+ * gtk_widget_add_binding_action() or gtk_shortcut_controller_add_shortcut().
  *
  * # CSS Nodes
  *