From 3bbcaa9e8fb7ffa787f6e30d5649bad4f5afa4cb Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 29 Apr 2020 20:27:32 -0400 Subject: [PATCH] docs: Move menu model docs It makes more sense to document the menu model XML format in the GtkPopoverMenu docs than in GtkApplicationWindow. --- gtk/gtkapplicationwindow.c | 45 ++---------------------- gtk/gtkpopovermenu.c | 70 ++++++++++++++++++++++++++++++++++---- 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 * * |[ @@ -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 `` element, which contains one or more `` - * elements. Each `` element contains `` and `` - * elements with a mandatory name attribute. `` elements have the - * same content model as ``. Instead of ``, you can use `` or `
` - * elements. - * - * Attribute values can be translated using gettext, like other #GtkBuilder - * content. `` 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 `` element, which contains one or more `` + * elements. Each `` element contains `` and `` + * elements with a mandatory name attribute. `` elements have the + * same content model as ``. Instead of ``, you can use `` or `
` + * elements. + * + * |[ + * + *
+ * + * _New Window + * app.new + * + * + * _About Sunny + * app.about + * + * + * _Quit + * app.quit + * + *
+ * + * ]| + * + * Attribute values can be translated using gettext, like other #GtkBuilder + * content. `` 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 *