Commit ff46ea64 authored by Emmanuele Bassi's avatar Emmanuele Bassi 👣
Browse files

docs: Escape the XML tags in the Widget class description

While gtk-doc doesn't care, this isn't really valid Markdown as the
GtkBuilder custom XML tags will be considered valid markup and embedded
as they are, breaking the HTML output.
parent a4066188
Pipeline #309792 passed with stages
in 34 minutes and 17 seconds
......@@ -56,19 +56,20 @@
* # GtkActionGroup as GtkBuildable # {#GtkActionGroup-BUILDER-UI}
*
* The #GtkActionGroup implementation of the #GtkBuildable interface accepts
* #GtkAction objects as <child> elements in UI definitions.
* #GtkAction objects as `<child>` elements in UI definitions.
*
* Note that it is probably more common to define actions and action groups
* in the code, since they are directly related to what the code can do.
*
* The GtkActionGroup implementation of the GtkBuildable interface supports
* a custom <accelerator> element, which has attributes named “key“ and
* a custom `<accelerator>` element, which has attributes named “key“ and
* “modifiers“ and allows to specify accelerators. This is similar to the
* <accelerator> element of #GtkWidget, the main difference is that
* `<accelerator>` element of #GtkWidget, the main difference is that
* it doesn’t allow you to specify a signal.
*
* ## A #GtkDialog UI definition fragment. ##
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkActionGroup" id="actiongroup">
* <child>
* <object class="GtkAction" id="About">
......
......@@ -72,8 +72,8 @@
*
* # GtkIconFactory as GtkBuildable # {#GtkIconFactory-BUILDER-UI}
*
* GtkIconFactory supports a custom <sources> element, which can contain
* multiple <source> elements. The following attributes are allowed:
* GtkIconFactory supports a custom `<sources>` element, which can contain
* multiple `<source>` elements. The following attributes are allowed:
*
* - stock-id
*
......
......@@ -41,9 +41,9 @@
* #GtkRecentChooserMenu.
*
* To construct a submenu showing recently used files, use a #GtkRecentAction
* as the action for a <menuitem>. To construct a menu toolbutton showing
* as the action for a `<menuitem>`. To construct a menu toolbutton showing
* the recently used files in the popup menu, use a #GtkRecentAction as the
* action for a <toolitem> element.
* action for a `<toolitem>` element.
*/
......
......@@ -56,16 +56,16 @@
* @Title: GtkUIManager
* @See_also: #GtkBuilder
*
* A #GtkUIManager constructs a user interface (menus and toolbars) from
* one or more UI definitions, which reference actions from one or more
* action groups.
*
* > GtkUIManager is deprecated since GTK+ 3.10. To construct user interfaces
* > from XML definitions, you should use #GtkBuilder, #GMenuModel, et al. To
* > work with actions, use #GAction, #GtkActionable et al. These newer classes
* > support richer functionality and integration with various desktop shells.
* > It should be possible to migrate most/all functionality from GtkUIManager.
*
* A #GtkUIManager constructs a user interface (menus and toolbars) from
* one or more UI definitions, which reference actions from one or more
* action groups.
*
* # UI Definitions # {#XML-UI}
*
* The UI definitions are specified in an XML format which can be
......@@ -126,7 +126,7 @@
*
* # A UI definition #
*
* |[
* |[<!-- language="xml" -->
* <ui>
* <menubar>
* <menu name="FileMenu" action="FileMenuAction">
......@@ -213,7 +213,7 @@
*
* Every action has an accelerator path. Accelerators are installed together
* with menuitem proxies, but they can also be explicitly added with
* <accelerator> elements in the UI definition. This makes it possible to
* `<accelerator>` elements in the UI definition. This makes it possible to
* have accelerators for actions even if they have no visible proxies.
*
* # Smart Separators # {#Smart-Separators}
......@@ -246,10 +246,10 @@
* # GtkUIManager as GtkBuildable # {#GtkUIManager-BUILDER-UI}
*
* The GtkUIManager implementation of the GtkBuildable interface accepts
* GtkActionGroup objects as <child> elements in UI definitions.
* GtkActionGroup objects as `<child>` elements in UI definitions.
*
* A GtkUIManager UI definition as described above can be embedded in
* an GtkUIManager <object> element in a GtkBuilder UI definition.
* an GtkUIManager `<object>` element in a GtkBuilder UI definition.
*
* The widgets that are constructed by a GtkUIManager can be embedded in
* other parts of the constructed user interface with the help of the
......@@ -257,7 +257,7 @@
*
* ## An embedded GtkUIManager UI definition
*
* |[
* |[<!-- language="xml" -->
* <object class="GtkUIManager" id="uiman">
* <child>
* <object class="GtkActionGroup" id="actiongroup">
......@@ -1096,10 +1096,10 @@ gtk_ui_manager_get_accel_group (GtkUIManager *manager)
* Looks up a widget by following a path.
* The path consists of the names specified in the XML description of the UI.
* separated by “/”. Elements which don’t have a name or action attribute in
* the XML (e.g. <popup>) can be addressed by their XML element name
* the XML (e.g. `<popup>`) can be addressed by their XML element name
* (e.g. "popup"). The root element ("/ui") can be omitted in the path.
*
* Note that the widget found by following a path that ends in a <menu>;
* Note that the widget found by following a path that ends in a `<menu>`;
* element is the menuitem to which the menu is attached, not the menu it
* manages.
*
......@@ -1937,7 +1937,7 @@ add_ui_from_string (GtkUIManager *manager,
* @error: return location for an error
*
* Parses a string containing a [UI definition][XML-UI] and merges it with
* the current contents of @manager. An enclosing <ui> element is added if
* the current contents of @manager. An enclosing `<ui>` element is added if
* it is missing.
*
* Returns: The merge id for the merged UI. The merge id can be used
......
......@@ -236,7 +236,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
* @data: (out): return location for user data that will be passed in
* to parser functions
*
* This is called for each unknown element under <child>.
* This is called for each unknown element under `<child>`.
*
* Returns: %TRUE if a object has a custom implementation, %FALSE
* if it doesn't.
......
......@@ -58,15 +58,15 @@ typedef struct _GtkBuildableIface GtkBuildableIface;
* is created.
* @construct_child: Constructs a child of a buildable that has been
* specified as “constructor” in the UI definition. #GtkUIManager implements
* this to reference to a widget created in a <ui> tag which is outside
* this to reference to a widget created in a `<ui>` tag which is outside
* of the normal GtkBuilder UI definition hierarchy. A reference to the
* constructed object is returned and becomes owned by the caller.
* @custom_tag_start: Implement this if the buildable needs to parse
* content below <child>. To handle an element, the implementation
* content below `<child>`. To handle an element, the implementation
* must fill in the @parser and @user_data and return %TRUE.
* #GtkWidget implements this to parse keyboard accelerators specified
* in <accelerator> elements. #GtkContainer implements it to map
* properties defined via <packing> elements to child properties.
* in `<accelerator>` elements. #GtkContainer implements it to map
* properties defined via `<packing>` elements to child properties.
* Note that @user_data must be freed in @custom_tag_end or @custom_finished.
* @custom_tag_end: Called for the end tag of each custom element that is
* handled by the buildable (see @custom_tag_start).
......
......@@ -69,25 +69,25 @@
*
* [RELAX NG Compact Syntax](https://gitlab.gnome.org/GNOME/gtk/-/blob/gtk-3-24/gtk/gtkbuilder.rnc)
*
* The toplevel element is <interface>. It optionally takes a “domain”
* The toplevel element is `<interface>`. It optionally takes a “domain”
* attribute, which will make the builder look for translated strings
* using dgettext() in the domain specified. This can also be done by
* calling gtk_builder_set_translation_domain() on the builder.
* Objects are described by <object> elements, which can contain
* <property> elements to set properties, <signal> elements which
* connect signals to handlers, and <child> elements, which describe
* Objects are described by `<object>` elements, which can contain
* `<property>` elements to set properties, `<signal>` elements which
* connect signals to handlers, and `<child>` elements, which describe
* child objects (most often widgets inside a container, but also e.g.
* actions in an action group, or columns in a tree model). A <child>
* element contains an <object> element which describes the child object.
* The target toolkit version(s) are described by <requires> elements,
* actions in an action group, or columns in a tree model). A `<child>`
* element contains an `<object>` element which describes the child object.
* The target toolkit version(s) are described by `<requires>` elements,
* the “lib” attribute specifies the widget library in question (currently
* the only supported value is “gtk+”) and the “version” attribute specifies
* the target version in the form <major>.<minor>. The builder will error
* the target version in the form `<major>.<minor>`. The builder will error
* out if the version requirements are not met.
*
* Typically, the specific kind of object represented by an <object>
* Typically, the specific kind of object represented by an `<object>`
* element is specified by the “class” attribute. If the type has not
* been loaded yet, GTK+ tries to find the get_type() function from the
* been loaded yet, GTK+ tries to find the `get_type()` function from the
* class name by applying heuristics. This works in most cases, but if
* necessary, it is possible to specify the name of the get_type() function
* explictly with the "type-func" attribute. As a special case, GtkBuilder
......@@ -100,10 +100,10 @@
* application to retrieve them from the builder with gtk_builder_get_object().
* An id is also necessary to use the object as property value in other
* parts of the UI definition. GTK+ reserves ids starting and ending
* with ___ (3 underscores) for its own purposes.
* with `___` (3 underscores) for its own purposes.
*
* Setting properties of objects is pretty straightforward with the
* <property> element: the “name” attribute specifies the name of the
* `<property>` element: the “name” attribute specifies the name of the
* property, and the content of the element specifies the value.
* If the “translatable” attribute is set to a true value, GTK+ uses
* gettext() (or dgettext() if the builder has a translation domain set)
......@@ -141,7 +141,7 @@
* Internally builder implements this using GBinding objects.
* For more information see g_object_bind_property()
*
* Signal handlers are set up with the <signal> element. The “name”
* Signal handlers are set up with the `<signal>` element. The “name”
* attribute specifies the name of the signal, and the “handler” attribute
* specifies the function to connect to the signal. By default, GTK+ tries
* to find the handler using g_module_symbol(), but this can be changed by
......@@ -157,19 +157,19 @@
* been constructed by GTK+ as part of a composite widget, to set
* properties on them or to add further children (e.g. the @vbox of
* a #GtkDialog). This can be achieved by setting the “internal-child”
* property of the <child> element to a true value. Note that GtkBuilder
* still requires an <object> element for the internal child, even if it
* property of the `<child>` element to a true value. Note that GtkBuilder
* still requires an `<object>` element for the internal child, even if it
* has already been constructed.
*
* A number of widgets have different places where a child can be added
* (e.g. tabs vs. page content in notebooks). This can be reflected in
* a UI definition by specifying the “type” attribute on a <child>
* a UI definition by specifying the “type” attribute on a `<child>`
* The possible values for the “type” attribute are described in the
* sections describing the widget-specific portions of UI definitions.
*
* # A GtkBuilder UI Definition
*
* |[
* |[<!-- language="xml" -->
* <interface>
* <object class="GtkDialog" id="dialog1">
* <child internal-child="vbox">
......@@ -195,14 +195,14 @@
*
* Beyond this general structure, several object classes define their
* own XML DTD fragments for filling in the ANY placeholders in the DTD
* above. Note that a custom element in a <child> element gets parsed by
* above. Note that a custom element in a `<child>` element gets parsed by
* the custom tag handler of the parent object, while a custom element in
* an <object> element gets parsed by the custom tag handler of the object.
* an `<object>` element gets parsed by the custom tag handler of the object.
*
* These XML fragments are explained in the documentation of the
* respective objects.
*
* Additionally, since 3.10 a special <template> tag has been added
* Additionally, since 3.10 a special `<template>` tag has been added
* to the format allowing one to define a widget class’s components.
* See the [GtkWidget documentation][composite-templates] for details.
*/
......
......@@ -39,33 +39,34 @@
* Implementations of GtkCellLayout which also implement the GtkBuildable
* interface (#GtkCellView, #GtkIconView, #GtkComboBox,
* #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects
* as <child> elements in UI definitions. They support a custom <attributes>
* element for their children, which can contain multiple <attribute>
* elements. Each <attribute> element has a name attribute which specifies
* as `<child>` elements in UI definitions. They support a custom `<attributes>`
* element for their children, which can contain multiple `<attribute>`
* elements. Each `<attribute>` element has a name attribute which specifies
* a property of the cell renderer; the content of the element is the
* attribute value.
*
* This is an example of a UI definition fragment specifying attributes:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkCellView">
* <child>
* <object class="GtkCellRendererText"/>
* <attributes>
* <attribute name="text">0</attribute>
* </attributes>
* </child>"
* </child>
* </object>
* ]|
*
* Furthermore for implementations of GtkCellLayout that use a #GtkCellArea
* to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea)
* [cell properties][cell-properties] can also be defined in the format by
* specifying the custom <cell-packing> attribute which can contain multiple
* <property> elements defined in the normal way.
* specifying the custom `<cell-packing>` attribute which can contain multiple
* `<property>` elements defined in the normal way.
*
* Here is a UI definition fragment specifying cell properties:
*
* |[
* |[<!-- language="xml" -->
* <object class="GtkTreeViewColumn">
* <child>
* <object class="GtkCellRendererText"/>
......@@ -73,7 +74,7 @@
* <property name="align">True</property>
* <property name="expand">False</property>
* </cell-packing>
* </child>"
* </child>
* </object>
* ]|
*
......
......@@ -55,13 +55,14 @@
* # GtkComboBoxText as GtkBuildable
*
* The GtkComboBoxText implementation of the GtkBuildable interface supports
* adding items directly using the <items> element and specifying <item>
* elements for each item. Each <item> element can specify the “id”
* adding items directly using the `<items>` element and specifying `<item>`
* elements for each item. Each `<item>` element can specify the “id”
* corresponding to the appended text and also supports the regular
* translation attributes “translatable”, “context” and “comments”.
*
* Here is a UI definition fragment specifying GtkComboBoxText items:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkComboBoxText">
* <items>
* <item translatable="yes" id="factory">Factory</item>
......
......@@ -241,19 +241,20 @@
* # GtkContainer as GtkBuildable
*
* The GtkContainer implementation of the GtkBuildable interface supports
* a <packing> element for children, which can contain multiple <property>
* a `<packing>` element for children, which can contain multiple `<property>`
* elements that specify child properties for the child.
*
* Since 2.16, child properties can also be marked as translatable using
* the same “translatable”, “comments” and “context” attributes that are used
* for regular properties.
*
* Since 3.16, containers can have a <focus-chain> element containing multiple
* <widget> elements, one for each child that should be added to the focus
* Since 3.16, containers can have a `<focus-chain>` element containing multiple
* `<widget>` elements, one for each child that should be added to the focus
* chain. The ”name” attribute gives the id of the widget.
*
* An example of these properties in UI definitions:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkBox">
* <child>
* <object class="GtkEntry" id="entry1"/>
......
......@@ -141,21 +141,22 @@
* @vbox and @action_area as internal children with the names “vbox” and
* “action_area”.
*
* GtkDialog supports a custom <action-widgets> element, which can contain
* multiple <action-widget> elements. The “response” attribute specifies a
* GtkDialog supports a custom `<action-widgets>` element, which can contain
* multiple `<action-widget>` elements. The “response” attribute specifies a
* numeric response, and the content of the element is the id of widget
* (which should be a child of the dialogs @action_area). To mark a response
* as default, set the “default“ attribute of the <action-widget> element
* as default, set the “default“ attribute of the `<action-widget>` element
* to true.
*
* GtkDialog supports adding action widgets by specifying “action“ as
* the “type“ attribute of a <child> element. The widget will be added
* the “type“ attribute of a `<child>` element. The widget will be added
* either to the action area or the headerbar of the dialog, depending
* on the “use-header-bar“ property. The response id has to be associated
* with the action widget using the <action-widgets> element.
* with the action widget using the `<action-widgets>` element.
*
* An example of a #GtkDialog UI definition fragment:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkDialog" id="dialog1">
* <child type="action">
* <object class="GtkButton" id="button_cancel"/>
......
......@@ -77,11 +77,12 @@
*
* The GtkExpander implementation of the GtkBuildable interface supports
* placing a child in the label position by specifying “label” as the
* “type” attribute of a <child> element. A normal content child can be
* specified without specifying a <child> type attribute.
* “type” attribute of a `<child>` element. A normal content child can be
* specified without specifying a `<child>` type attribute.
*
* An example of a UI definition fragment with GtkExpander:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkExpander">
* <child type="label">
* <object class="GtkLabel" id="expander-label"/>
......
......@@ -41,14 +41,15 @@
* # GtkFileFilter as GtkBuildable
*
* The GtkFileFilter implementation of the GtkBuildable interface
* supports adding rules using the <mime-types>, <patterns> and
* <applications> elements and listing the rules within. Specifying
* a <mime-type> or <pattern> has the same effect as as calling
* supports adding rules using the `<mime-types>`, `<patterns>` and
* `<applications>` elements and listing the rules within. Specifying
* a `<mime-type>` or `<pattern>` has the same effect as as calling
* gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern().
*
* An example of a UI definition fragment specifying GtkFileFilter
* rules:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkFileFilter">
* <mime-types>
* <mime-type>text/plain</mime-type>
......
......@@ -53,13 +53,14 @@
*
* # GtkFrame as GtkBuildable
*
* The GtkFrame implementation of the GtkBuildable interface supports
* The GtkFrame implementation of the #GtkBuildable interface supports
* placing a child in the label position by specifying “label” as the
* “type” attribute of a <child> element. A normal content child can
* be specified without specifying a <child> type attribute.
* “type” attribute of a `<child>` element. A normal content child can
* be specified without specifying a `<child>` type attribute.
*
* An example of a UI definition fragment with GtkFrame:
* |[
* An example of a UI definition fragment with `GtkFrame`:
*
* |[<!-- language="xml" -->
* <object class="GtkFrame">
* <child type="label">
* <object class="GtkLabel" id="frame-label"/>
......
......@@ -118,8 +118,8 @@
* the content area and action area as internal children with the names
* “content_area” and “action_area”.
*
* GtkInfoBar supports a custom <action-widgets> element, which can contain
* multiple <action-widget> elements. The “response” attribute specifies a
* GtkInfoBar supports a custom `<action-widgets>` element, which can contain
* multiple `<action-widget>` elements. The “response” attribute specifies a
* numeric response, and the content of the element is the id of widget
* (which should be a child of the dialogs @action_area).
*
......
......@@ -98,13 +98,14 @@
* # GtkLabel as GtkBuildable
*
* The GtkLabel implementation of the GtkBuildable interface supports a
* custom <attributes> element, which supports any number of <attribute>
* elements. The <attribute> element has attributes named “name“, “value“,
* custom `<attributes>` element, which supports any number of `<attribute>`
* elements. The `<attribute>` element has attributes named “name“, “value“,
* “start“ and “end“ and allows you to specify #PangoAttribute values for
* this label.
*
* An example of a UI definition fragment specifying Pango attributes:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkLabel">
* <attributes>
* <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
......
......@@ -92,8 +92,8 @@
* # GtkLevelBar as GtkBuildable
*
* The GtkLevelBar implementation of the GtkBuildable interface supports a
* custom <offsets> element, which can contain any number of <offset> elements,
* each of which must have name and value attributes.
* custom `<offsets>` element, which can contain any number of `<offset>` elements,
* each of which must have "name" and "value" attributes.
*
* # CSS nodes
*
......
......@@ -68,7 +68,7 @@
*
* The GtkListBox implementation of the #GtkBuildable interface supports
* setting a child as the placeholder by specifying “placeholder” as the “type”
* attribute of a <child> element. See gtk_list_box_set_placeholder() for info.
* attribute of a `<child>` element. See gtk_list_box_set_placeholder() for info.
*
* # CSS nodes
*
......
......@@ -54,6 +54,7 @@
* #GdkPixbufs stored.
*
* An example for creating a simple list store:
*
* |[<!-- language="C" -->
* enum {
* COLUMN_STRING,
......@@ -134,14 +135,14 @@
* # GtkListStore as GtkBuildable
*
* The GtkListStore implementation of the GtkBuildable interface allows
* to specify the model columns with a <columns> element that may contain
* multiple <column> elements, each specifying one model column. The “type”
* to specify the model columns with a `<columns>` element that may contain
* multiple `<column>` elements, each specifying one model column. The “type”
* attribute specifies the data type for the column.
*
* Additionally, it is possible to specify content for the list store
* in the UI definition, with the <data> element. It can contain multiple
* <row> elements, each specifying to content for one row of the list model.
* Inside a <row>, the <col> elements specify the content for individual cells.
* in the UI definition, with the `<data>` element. It can contain multiple
* `<row>` elements, each specifying to content for one row of the list model.
* Inside a `<row>`, the `<col>` elements specify the content for individual cells.
*
* Note that it is probably more common to define your models in the code,
* and one might consider it a layering violation to specify the content of
......@@ -149,7 +150,8 @@
* is to separate the two, as far as possible.
*
* An example of a UI Definition fragment for a list store:
* |[<!-- language="C" -->
*
* |[<!-- language="xml" -->
* <object class="GtkListStore">
* <columns>
* <column type="gchararray"/>
......
......@@ -70,6 +70,7 @@
* For more advanced label settings, you can fetch the child widget from the GtkBin.
*
* An example for setting markup and accelerator on a MenuItem:
*
* |[<!-- language="C" -->
* GtkWidget *menu_item = gtk_menu_item_new_with_label ("Example Menu Item");
*
......@@ -82,10 +83,11 @@
*
* The GtkMenuItem implementation of the #GtkBuildable interface supports
* adding a submenu by specifying “submenu” as the “type” attribute of
* a <child> element.
* a `<child>` element.
*
* An example of UI definition fragment with submenus:
* |[
*
* |[<!-- language="xml" -->
* <object class="GtkMenuItem">
* <child type="submenu">
* <object class="GtkMenu"/>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment