[gtk+] docs: Convert to markdown
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk+] docs: Convert to markdown
- Date: Sun, 2 Feb 2014 05:30:40 +0000 (UTC)
commit 09d1b28249af38448be0b52d00dd9924adac5d1c
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 2 00:29:00 2014 -0500
docs: Convert to markdown
Specifically, switch to using markdown syntax for sections.
gdk/gdkwindow.c | 56 ++++-----
gtk/gtkaccelmap.c | 84 ++++++-------
gtk/gtkassistant.c | 36 +++---
gtk/gtkbindings.c | 40 +++---
gtk/gtkbuilder.c | 237 ++++++++++++++++-------------------
gtk/gtkcellarea.c | 76 ++++-------
gtk/gtkcelllayout.c | 50 +++----
gtk/gtkcomboboxtext.c | 11 +-
gtk/gtkcontainer.c | 31 ++---
gtk/gtkcssprovider.c | 304 +++++++++++++++++---------------------------
gtk/gtkdialog.c | 23 ++--
gtk/gtkexpander.c | 22 +--
gtk/gtkfilechooser.c | 100 ++++++---------
gtk/gtkfilefilter.c | 18 +--
gtk/gtkfontchooserdialog.c | 11 +-
gtk/gtkframe.c | 12 +-
gtk/gtkinfobar.c | 14 +--
gtk/gtklabel.c | 71 ++++------
gtk/gtkliststore.c | 45 +++----
gtk/gtkmenuitem.c | 14 +--
gtk/gtkmenushell.c | 7 +-
gtk/gtkmenutoolbutton.c | 11 +-
gtk/gtkmessagedialog.c | 22 ++--
gtk/gtknotebook.c | 12 +-
gtk/gtkoverlay.c | 7 +-
gtk/gtkprintunixdialog.c | 27 +---
gtk/gtkrecentfilter.c | 11 +-
gtk/gtkscale.c | 4 +-
gtk/gtkscrollable.c | 55 +++-----
gtk/gtksizegroup.c | 11 +-
gtk/gtkstylecontext.c | 117 ++++-------------
gtk/gtktexttagtable.c | 11 +-
gtk/gtktreestore.c | 10 +-
gtk/gtktreeview.c | 43 ++-----
gtk/gtkwidget.c | 100 +++++----------
gtk/gtkwindow.c | 19 +--
36 files changed, 653 insertions(+), 1069 deletions(-)
---
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 897f097..f5c4f42 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -56,40 +56,36 @@
* A #GdkWindow is a (usually) rectangular region on the screen.
* It's a low-level object, used to implement high-level objects such as
* #GtkWidget and #GtkWindow on the GTK+ level. A #GtkWindow is a toplevel
- * window, the thing a user might think of as a "window" with a titlebar and
- * so on; a #GtkWindow may contain many #GdkWindows. For example, each
- * #GtkButton has a #GdkWindow associated with it.
- *
- * <refsect2 id="COMPOSITED-WINDOWS">
- * <title>Composited Windows</title>
- * <para>
- * Normally, the windowing system takes care of rendering the contents of a
- * child window onto its parent window. This mechanism can be intercepted by
- * calling gdk_window_set_composited() on the child window. For a
- * <firstterm>composited</firstterm> window it is the responsibility of the
- * application to render the window contents at the right spot.
- * </para>
- * </refsect2>
- * <refsect2 id="OFFSCREEN-WINDOWS">
- * <title>Offscreen Windows</title>
- * <para>
- * Offscreen windows are more general than composited windows, since they allow
- * not only to modify the rendering of the child window onto its parent, but
- * also to apply coordinate transformations.
- *
- * To integrate an offscreen window into a window hierarchy, one has to call
- * gdk_offscreen_window_set_embedder() and handle a number of signals. The
- * #GdkWindow::pick-embedded-child signal on the embedder window is used to
- * select an offscreen child at given coordinates, and the
- * #GdkWindow::to-embedder and #GdkWindow::from-embedder signals on the
- * offscreen window are used to translate coordinates between the embedder and
- * the offscreen window.
- *
- * For rendering an offscreen window onto its embedder, the contents of the
- * offscreen window are available as a surface, via
+ * window, the thing a user might think of as a "window" with a titlebar
+ * and so on; a #GtkWindow may contain many #GdkWindows. For example,
+ * each #GtkButton has a #GdkWindow associated with it.
+ *
+ * ## Composited Windows
+ *
+ * <para id="COMPOSITED-WINDOWS">Normally, the windowing system takes care of rendering the contents
+ * of a child window onto its parent window. This mechanism can be
+ * intercepted by calling gdk_window_set_composited() on the child
+ * window. For a <firstterm>composited</firstterm> window it is the
+ * responsibility of the application to render the window contents at
+ * the right spot.</para>
+ *
+ * ## Offscreen Windows
+ *
+ * <para id="OFFSCREEN-WINDOWS">Offscreen windows are more general than composited windows, since
+ * they allow not only to modify the rendering of the child window onto
+ * its parent, but also to apply coordinate transformations.</para>
+ *
+ * To integrate an offscreen window into a window hierarchy, one has
+ * to call gdk_offscreen_window_set_embedder() and handle a number of
+ * signals. The #GdkWindow::pick-embedded-child signal on the embedder
+ * window is used to select an offscreen child at given coordinates,
+ * and the #GdkWindow::to-embedder and #GdkWindow::from-embedder signals
+ * on the offscreen window are used to translate coordinates between
+ * the embedder and the offscreen window.
+ *
+ * For rendering an offscreen window onto its embedder, the contents
+ * of the offscreen window are available as a surface, via
* gdk_offscreen_window_get_surface().
- * </para>
- * </refsect2>
*/
diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index f6baf08..b764533 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -48,61 +48,53 @@
* "low-level". You'll want to use them if you're manually creating menus that
* should have user-configurable accelerators.
*
- * Accelerator is uniquely defined by:
- *
- * <itemizedlist>
- * <listitem><para>accelerator path</para></listitem>
- * <listitem><para>accelerator key</para></listitem>
- * <listitem><para>accelerator modifiers</para></listitem>
- * </itemizedlist>
+ * An accelerator is uniquely defined by:
+ * - accelerator path
+ * - accelerator key
+ * - accelerator modifiers
*
* The accelerator path must consist of
* "<WINDOWTYPE>/Category1/Category2/.../Action", where WINDOWTYPE
- * should be a unique application-specific identifier that corresponds to the
- * kind of window the accelerator is being used in, e.g. "Gimp-Image",
- * "Abiword-Document" or "Gnumeric-Settings".
- * The "Category1/.../Action" portion is most appropriately chosen by the action
- * the accelerator triggers, i.e. for accelerators on menu items, choose the
- * item's menu path, e.g. "File/Save As", "Image/View/Zoom" or
- * "Edit/Select All". So a full valid accelerator path may look like:
- * "<Gimp-Toolbox>/File/Dialogs/Tool Options...".
+ * should be a unique application-specific identifier that corresponds
+ * to the kind of window the accelerator is being used in, e.g.
+ * "Gimp-Image", "Abiword-Document" or "Gnumeric-Settings".
+ * The "Category1/.../Action" portion is most appropriately chosen by
+ * the action the accelerator triggers, i.e. for accelerators on menu
+ * items, choose the item's menu path, e.g. "File/Save As",
+ * "Image/View/Zoom" or "Edit/Select All". So a full valid accelerator
+ * path may look like: "<Gimp-Toolbox>/File/Dialogs/Tool Options...".
*
- * All accelerators are stored inside one global #GtkAccelMap that can be
- * obtained using gtk_accel_map_get(). See <link
+ * All accelerators are stored inside one global #GtkAccelMap that can
+ * be obtained using gtk_accel_map_get(). See <link
* linkend="monitoring-changes">Monitoring changes</link> for additional
* details.
*
- * <refsect2 id="manipulating-accelerators">
- * <title>Manipulating accelerators</title>
- * <para>
- * New accelerators can be added using gtk_accel_map_add_entry(). To search for
- * specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of
- * existing accelerators should be done using gtk_accel_map_change_entry().
+ * ## Manipulating accelerators
+ *
+ * New accelerators can be added using gtk_accel_map_add_entry().
+ * To search for specific accelerator, use gtk_accel_map_lookup_entry().
+ * Modifications of existing accelerators should be done using
+ * gtk_accel_map_change_entry().
*
- * In order to avoid having some accelerators changed, they can be locked using
- * gtk_accel_map_lock_path(). Unlocking is done using
+ * In order to avoid having some accelerators changed, they can be
+ * locked using gtk_accel_map_lock_path(). Unlocking is done using
* gtk_accel_map_unlock_path().
- * </para>
- * </refsect2>
- * <refsect2 id="saving-and-loading">
- * <title>Saving and loading accelerator maps</title>
- * <para>
- * Accelerator maps can be saved to and loaded from some external resource. For
- * simple saving and loading from file, gtk_accel_map_save() and
- * gtk_accel_map_load() are provided. Saving and loading can also be done by
- * providing file descriptor to gtk_accel_map_save_fd() and
- * gtk_accel_map_load_fd().
- * </para>
- * </refsect2>
- * <refsect2 id="monitoring-changes">
- * <title>Monitoring changes</title>
- * <para>
- * #GtkAccelMap object is only useful for monitoring changes of accelerators. By
- * connecting to #GtkAccelMap::changed signal, one can monitor changes of all
- * accelerators. It is also possible to monitor only single accelerator path by
- * using it as a detail of the #GtkAccelMap::changed signal.
- * </para>
- * </refsect2>
+ *
+ * ## Saving and loading accelerator maps
+ *
+ * Accelerator maps can be saved to and loaded from some external
+ * resource. For simple saving and loading from file,
+ * gtk_accel_map_save() and gtk_accel_map_load() are provided.
+ * Saving and loading can also be done by providing file descriptor
+ * to gtk_accel_map_save_fd() and gtk_accel_map_load_fd().
+ *
+ * ## Monitoring changes
+ *
+ * #GtkAccelMap object is only useful for monitoring changes of
+ * accelerators. By connecting to #GtkAccelMap::changed signal, one
+ * can monitor changes of all accelerators. It is also possible to
+ * monitor only single accelerator path by using it as a detail of
+ * the #GtkAccelMap::changed signal.
*/
diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index 80cb199..e0b3fe5 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -27,31 +27,29 @@
* @Title: GtkAssistant
*
* A #GtkAssistant is a widget used to represent a generally complex
- * operation splitted in several steps, guiding the user through its pages
- * and controlling the page flow to collect the necessary data.
+ * operation splitted in several steps, guiding the user through its
+ * pages and controlling the page flow to collect the necessary data.
*
- * The design of GtkAssistant is that it controls what buttons to show and
- * to make sensitive, based on what it knows about the page sequence and
- * the <link linkend="GtkAssistantPageType">type</link> of each page, in
- * addition to state information like the page
- * <link linkend="gtk-assistant-set-page-complete">completion</link> and
- * <link linkend="gtk-assistant-commit">committed</link> status.
+ * The design of GtkAssistant is that it controls what buttons to show
+ * and to make sensitive, based on what it knows about the page sequence
+ * and the <link linkend="GtkAssistantPageType">type</link> of each page,
+ * in addition to state information like the page
+ * <link linkend="gtk-assistant-set-page-complete">completion</link>
+ * and <link linkend="gtk-assistant-commit">committed</link> status.
*
* If you have a case that doesn't quite fit in #GtkAssistants way of
- * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type
- * and handle buttons yourself.
+ * handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page
+ * type and handle buttons yourself.
*
- * <refsect2 id="GtkAssistant-BUILDER-UI">
- * <title>GtkAssistant as GtkBuildable</title>
- * <para>
- * The GtkAssistant implementation of the GtkBuildable interface exposes the
- * @action_area as internal children with the name "action_area".
+ * ## GtkAssistant as GtkBuildable
*
- * To add pages to an assistant in GtkBuilder, simply add it as a
- * <child> to the GtkAssistant object, and set its child properties
+ * The GtkAssistant implementation of the #GtkBuildable interface
+ * exposes the @action_area as internal children with the name
+ * "action_area".
+ *
+ * To add pages to an assistant in #GtkBuilder, simply add it as a
+ * child to the GtkAssistant object, and set its child properties
* as necessary.
- * </para>
- * </refsect2>
*/
#include "config.h"
diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c
index 5dcc968..53cb489 100644
--- a/gtk/gtkbindings.c
+++ b/gtk/gtkbindings.c
@@ -47,27 +47,27 @@
* with high key binding configurability which requires no application
* or toolkit side changes.
*
- * <refsect2 id="gtk-bindings-install">
- * <title>Installing a key binding</title>
- * <para>
+ * ## Installing a key binding
+ *
* A CSS file binding consists of a 'binding-set' definition and a match
* statement to apply the binding set to specific widget types. Details
* on the matching mechanism are described under
* <link linkend="gtkcssprovider-selectors">Selectors</link>
- * in the #GtkCssProvider documentation. Inside the binding set definition,
- * key combinations are bound to one or more specific signal emissions on
- * the target widget. Key combinations are strings consisting of an optional
- * #GdkModifierType name and <link linkend="gdk3-Keyboard-Handling">key names</link>
+ * in the #GtkCssProvider documentation. Inside the binding set
+ * definition, key combinations are bound to one or more specific
+ * signal emissions on the target widget. Key combinations are strings
+ * consisting of an optional #GdkModifierType name and
+ * <link linkend="gdk3-Keyboard-Handling">key names</link>
* such as those defined in <filename><gdk/gdkkeysyms.h></filename>
* or returned from gdk_keyval_name(), they have to be parsable by
* gtk_accelerator_parse(). Specifications of signal emissions consist
* of a string identifying the signal name, and a list of signal specific
* arguments in parenthesis.
- * </para>
- * <para>
+ *
* For example for binding Control and the left or right cursor keys
- * of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so movement
- * occurs in 3-character steps), the following binding can be used:
+ * of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so
+ * movement occurs in 3-character steps), the following binding can be
+ * used:
* |[
* @binding-set MoveCursor3
* {
@@ -79,11 +79,9 @@
* gtk-key-bindings: MoveCursor3;
* }
* ]|
- * </para>
- * </refsect2>
- * <refsect2 id="gtk-bindings-unbind">
- * <title>Unbinding existing key bindings</title>
- * <para>
+ *
+ * ## Unbinding existing key bindings
+ *
* GTK+ already defines a number of useful bindings for the widgets
* it provides. Because custom bindings set up in CSS files take
* precedence over the default bindings shipped with GTK+, overriding
@@ -108,10 +106,10 @@
* from the bindings set "MoveCursor3" to be deleted, so when
* "<Control>Right" or "<Control>Left" are pressed, no
* binding for these keys is found in binding set "MoveCursor3".
- * GTK+ will thus continue to search for matching key bindings, and will
- * eventually lookup and find the default GTK+ bindings for entries which
- * implement word movement. To keep GTK+ from activating its default
- * bindings, the "unbind" keyword can be used like this:
+ * GTK+ will thus continue to search for matching key bindings, and
+ * will eventually lookup and find the default GTK+ bindings for
+ * entries which implement word movement. To keep GTK+ from activating
+ * its default bindings, the "unbind" keyword can be used like this:
* |[
* @binding-set MoveCursor3
* {
@@ -129,8 +127,6 @@
* so the key presses are not consumed by this widget. As usual, further
* processing of the key presses, e.g. by an entry's parent widget, is
* now possible.
- * </para>
- * </refsect2>
*/
/* --- defines --- */
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index f53f210..e3b1fb4 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -56,108 +56,115 @@
* The function gtk_builder_connect_signals() and variants thereof can be
* used to connect handlers to the named signals in the description.
*
- * <refsect2 id="BUILDER-UI">
- * <title>GtkBuilder UI Definitions</title>
- * <para>
- * GtkBuilder parses textual descriptions of user interfaces which are specified
- * in an XML format which can be roughly described by the RELAX NG schema below.
- * We refer to these descriptions as <firstterm>GtkBuilder UI definitions</firstterm>
- * or just <firstterm>UI definitions</firstterm> if the context is clear. Do not
- * confuse GtkBuilder UI Definitions with
- * <link linkend="XML-UI">GtkUIManager UI Definitions</link>, which are more
- * limited in scope. It is common to use <filename>.ui</filename> as the filename extension for files
containing GtkBuilder UI definitions.
- * </para>
+ * ## GtkBuilder UI Definitions
+ *
+ * GtkBuilder parses textual descriptions of user interfaces which are
+ * specified in an XML format which can be roughly described by the
+ * RELAX NG schema below. We refer to these descriptions as
+ * <firstterm>GtkBuilder UI definitions</firstterm> or just
+ * <firstterm>UI definitions</firstterm> if the context is clear.
+ * Do not confuse GtkBuilder UI Definitions with
+ * <link linkend="XML-UI">GtkUIManager UI Definitions</link>, which
+ * are more limited in scope. It is common to use <filename>.ui</filename>
+ * as the filename extension for files containing GtkBuilder UI
+ * definitions.
* |[
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gtk/gtkbuilder.rnc">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* ]|
- * <para>
- * 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 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, 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 out if the version
- * requirements are not met.
+ * 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 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, the "lib" attribute specifies
+ * the widget library in question (currently the only supported value
+ * s "gtk+") and the "version" attribute specifies 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>
* element is specified by the "class" attribute. If the type has not been
- * loaded yet, GTK+ tries to find the _get_type(<!-- -->) 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(<!-- -->) explictly with the "type-func" attribute.
+ * 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 allows to use an object that has been
- * constructed by a #GtkUIManager in another part of the UI definition by
- * specifying the id of the #GtkUIManager in the "constructor" attribute and the
- * name of the object in the "id" attribute.
+ * constructed by a #GtkUIManager in another part of the UI definition
+ * by specifying the id of the #GtkUIManager in the "constructor"
+ * attribute and the name of the object in the "id" attribute.
*
* Objects may be given a name with the "id" attribute, which allows the
* 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.
- * </para>
- * <para>
+ * 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.
+ *
* Setting properties of objects is pretty straightforward with 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) to find a translation
- * for the value. This happens before the value is parsed, so it can be used for
- * properties of any type, but it is probably most useful for string properties.
- * It is also possible to specify a context to disambiguate short strings, and
- * comments which may help the translators.
- *
- * GtkBuilder can parse textual representations for the most common property
- * types: characters, strings, integers, floating-point numbers, booleans
- * (strings like "TRUE", "t", "yes", "y", "1" are interpreted as %TRUE, strings
- * like "FALSE, "f", "no", "n", "0" are interpreted as %FALSE), enumerations
- * (can be specified by their name, nick or integer value), flags (can be
- * specified by their name, nick, integer value, optionally combined with "|",
- * e.g. "GTK_VISIBLE|GTK_REALIZED") and colors (in a format understood by
- * gdk_color_parse()). Pixbufs can be specified as a filename of an image file to load.
- * Objects can be referred to by their name and by default refer to objects declared
- * in the local xml fragment and objects exposed via gtk_builder_expose_object().
+ * <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)
+ * to find a translation for the value. This happens before the value
+ * is parsed, so it can be used for properties of any type, but it is
+ * probably most useful for string properties. It is also possible to
+ * specify a context to disambiguate short strings, and comments which
+ * may help the translators.
+ *
+ * GtkBuilder can parse textual representations for the most common
+ * property types: characters, strings, integers, floating-point numbers,
+ * booleans (strings like "TRUE", "t", "yes", "y", "1" are interpreted
+ * as %TRUE, strings like "FALSE, "f", "no", "n", "0" are interpreted
+ * as %FALSE), enumerations (can be specified by their name, nick or
+ * integer value), flags (can be specified by their name, nick, integer
+ * value, optionally combined with "|", e.g. "GTK_VISIBLE|GTK_REALIZED")
+ * and colors (in a format understood by gdk_color_parse()). Pixbufs can
+ * be specified as a filename of an image file to load. Objects can be
+ * referred to by their name and by default refer to objects declared
+ * in the local xml fragment and objects exposed via
+ * gtk_builder_expose_object().
*
- * In general, GtkBuilder allows forward references to objects &mdash declared
- * in the local xml; an object doesn't have to be constructed before it can be referred to.
- * The exception to this rule is that an object has to be constructed before
- * it can be used as the value of a construct-only property.
- *
- * 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 passing
- * a custom #GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). The
- * remaining attributes, "after", "swapped" and "object", have the same meaning
- * as the corresponding parameters of the g_signal_connect_object() or
- * g_signal_connect_data() functions. A "last_modification_time" attribute
- * is also allowed, but it does not have a meaning to the builder.
- *
- * Sometimes it is necessary to refer to widgets which have implicitly 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" propery 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>. The possible values
- * for the "type" attribute are described in the sections describing the
- * widget-specific portions of UI definitions.
- * </para>
- * <example>
- * <title>A GtkBuilder UI Definition</title>
+ * In general, GtkBuilder allows forward references to objects --
+ * declared in the local xml; an object doesn't have to be constructed
+ * before it can be referred to. The exception to this rule is that an
+ * object has to be constructed before it can be used as the value of
+ * a construct-only property.
+ *
+ * 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 passing a custom #GtkBuilderConnectFunc to
+ * gtk_builder_connect_signals_full(). The remaining attributes, "after",
+ * "swapped" and "object", have the same meaning as the corresponding
+ * parameters of the g_signal_connect_object() or
+ * g_signal_connect_data() functions. A "last_modification_time"
+ * attribute is also allowed, but it does not have a meaning to the
+ * builder.
+ *
+ * Sometimes it is necessary to refer to widgets which have implicitly
+ * 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"
+ * propery 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>.
+ * The possible values for the "type" attribute are described in the
+ * sections describing the widget-specific portions of UI definitions.
+ *
+ * ## A GtkBuilder UI Definition
+ *
* |[
* <interface>
* <object class="GtkDialog" id="dialog1">
@@ -181,47 +188,19 @@
* </object>
* </interface>
* ]|
- * </example>
- * <para>
- * 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 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.
- *
- * These XML fragments are explained in the documentation of the respective
- * objects, see
- * <link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>,
- * <link linkend="GtkLabel-BUILDER-UI">GtkLabel</link>,
- * <link linkend="GtkWindow-BUILDER-UI">GtkWindow</link>,
- * <link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>,
- * <link linkend="GtkDialog-BUILDER-UI">GtkDialog</link>,
- * <link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link>,
- * <link linkend="GtkColorSelectionDialog-BUILDER-UI">GtkColorSelectionDialog</link>,
- * <link linkend="GtkFontSelectionDialog-BUILDER-UI">GtkFontSelectionDialog</link>,
- * <link linkend="GtkExpander-BUILDER-UI">GtkExpander</link>,
- * <link linkend="GtkFrame-BUILDER-UI">GtkFrame</link>,
- * <link linkend="GtkListStore-BUILDER-UI">GtkListStore</link>,
- * <link linkend="GtkTreeStore-BUILDER-UI">GtkTreeStore</link>,
- * <link linkend="GtkNotebook-BUILDER-UI">GtkNotebook</link>,
- * <link linkend="GtkSizeGroup-BUILDER-UI">GtkSizeGroup</link>,
- * <link linkend="GtkTreeView-BUILDER-UI">GtkTreeView</link>,
- * <link linkend="GtkUIManager-BUILDER-UI">GtkUIManager</link>,
- * <link linkend="GtkActionGroup-BUILDER-UI">GtkActionGroup</link>.
- * <link linkend="GtkMenuItem-BUILDER-UI">GtkMenuItem</link>,
- * <link linkend="GtkMenuToolButton-BUILDER-UI">GtkMenuToolButton</link>,
- * <link linkend="GtkAssistant-BUILDER-UI">GtkAssistant</link>,
- * <link linkend="GtkScale-BUILDER-UI">GtkScale</link>,
- * <link linkend="GtkComboBoxText-BUILDER-UI">GtkComboBoxText</link>,
- * <link linkend="GtkRecentFilter-BUILDER-UI">GtkRecentFilter</link>,
- * <link linkend="GtkFileFilter-BUILDER-UI">GtkFileFilter</link>,
- * <link linkend="GtkTextTagTable-BUILDER-UI">GtkTextTagTable</link>.
- * </para>
- * <para>
- * Additionally, since 3.10 a special <template> tag has been added to the format
- * allowing one to <link linkend="GtkWidget-BUILDER-TEMPLATES">define a widget class's components</link>.
- * </para>
- * </refsect2>
+ *
+ * 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 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.
+ *
+ * These XML fragments are explained in the documentation of the
+ * respective objects.
+ *
+ * Additionally, since 3.10 a special <template> tag has been
+ * added to the format allowing one to define a widget class's components.
*/
#include "config.h"
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index ae19c18..8ae91eb 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -35,9 +35,8 @@
* Usually users dont have to interact with the #GtkCellArea directly
* unless they are implementing a cell-layouting widget themselves.
*
- * <refsect2 id="cell-area-geometry-management">
- * <title>Requesting area sizes</title>
- * <para>
+ * ## Requesting area sizes
+ *
* As outlined in <link linkend="geometry-management">GtkWidget's
* geometry management section</link>, GTK+ uses a height-for-width
* geometry management system to compute the sizes of widgets and user
@@ -72,9 +71,7 @@
*
* In order to request the width of all the rows at the root level
* of a #GtkTreeModel one would do the following:
- * <example>
- * <title>Requesting the width of a handful of GtkTreeModel rows</title>
- * |[<!-- language="C" -->
+ * |[<!-- language="C" -->
* GtkTreeIter iter;
* gint minimum_width;
* gint natural_width;
@@ -88,8 +85,7 @@
* valid = gtk_tree_model_iter_next (model, &iter);
* }
* gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);
- * ]|
- * </example>
+ * ]|
* Note that in this example it's not important to observe the
* returned minimum and natural width of the area for each row
* unless the cell-layouting object is actually interested in the
@@ -102,15 +98,13 @@
* exceedingly large amount of rows. The #GtkCellLayout widget in
* that case would calculate the required width of the rows in an
* idle or timeout source (see g_timeout_add()) and when the widget
- * is requested its actual width in #GtkWidgetClass.get_preferred_width(<!-- -->)
+ * is requested its actual width in #GtkWidgetClass.get_preferred_width()
* it can simply consult the width accumulated so far in the
* #GtkCellAreaContext object.
*
* A simple example where rows are rendered from top to bottom and
* take up the full width of the layouting widget would look like:
- * <example>
- * <title>A typical get_preferred_width(<!-- -->) implementation</title>
- * |[<!-- language="C" -->
+ * |[<!-- language="C" -->
* static void
* foo_get_preferred_width (GtkWidget *widget,
* gint *minimum_size,
@@ -123,8 +117,7 @@
*
* gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size);
* }
- * ]|
- * </example>
+ * ]|
* In the above example the Foo widget has to make sure that some
* row sizes have been calculated (the amount of rows that Foo judged
* was appropriate to request space for in a single timeout iteration)
@@ -140,9 +133,7 @@
*
* In order to request the height for width of all the rows at the
* root level of a #GtkTreeModel one would do the following:
- * <example>
- * <title>Requesting the height for width of a handful of GtkTreeModel rows</title>
- * |[<!-- language="C" -->
+ * |[<!-- language="C" -->
* GtkTreeIter iter;
* gint minimum_height;
* gint natural_height;
@@ -164,8 +155,7 @@
*
* valid = gtk_tree_model_iter_next (model, &iter);
* }
- * ]|
- * </example>
+ * ]|
* Note that in the above example we would need to cache the heights
* returned for each row so that we would know what sizes to render the
* areas for each row. However we would only want to really cache the
@@ -180,26 +170,22 @@
* synchronously. The reasoning here is that any layouting widget is
* at least capable of synchronously calculating enough height to fill
* the screen height (or scrolled window height) in response to a single
- * call to #GtkWidgetClass.get_preferred_height_for_width(<!-- -->). Returning
+ * call to #GtkWidgetClass.get_preferred_height_for_width(). Returning
* a perfect height for width that is larger than the screen area is
* inconsequential since after the layouting receives an allocation
* from a scrolled window it simply continues to drive the scrollbar
* values while more and more height is required for the row heights
* that are calculated in the background.
- * </para>
- * </refsect2>
- * <refsect2 id="cell-area-rendering">
- * <title>Rendering Areas</title>
- * <para>
+ *
+ * ## Rendering Areas
+ *
* Once area sizes have been aquired at least for the rows in the
* visible area of the layouting widget they can be rendered at
* #GtkWidgetClass.draw() time.
*
* A crude example of how to render all the rows at the root level
* runs as follows:
- * <example>
- * <title>Requesting the width of a handful of GtkTreeModel rows</title>
- * |[<!-- language="C" -->
+ * |[<!-- language="C" -->
* GtkAllocation allocation;
* GdkRectangle cell_area = { 0, };
* GtkTreeIter iter;
@@ -222,19 +208,16 @@
*
* valid = gtk_tree_model_iter_next (model, &iter);
* }
- * ]|
- * </example>
+ * ]|
* Note that the cached height in this example really depends on how
* the layouting widget works. The layouting widget might decide to
* give every row its minimum or natural height or, if the model content
* is expected to fit inside the layouting widget without scrolling, it
* would make sense to calculate the allocation for each row at
* #GtkWidget::size-allocate time using gtk_distribute_natural_allocation().
- * </para>
- * </refsect2>
- * <refsect2 id="cell-area-events-and-focus">
- * <title>Handling Events and Driving Keyboard Focus</title>
- * <para>
+ *
+ * ## Handling Events and Driving Keyboard Focus
+ *
* Passing events to the area is as simple as handling events on any
* normal widget and then passing them to the gtk_cell_area_event()
* API as they come in. Usually #GtkCellArea is only interested in
@@ -262,9 +245,7 @@
*
* A basic example of how the #GtkWidgetClass.focus() virtual method
* should be implemented:
- * <example>
- * <title>Implementing keyboard focus navigation</title>
- * |[<!-- language="C" -->
+ * |[<!-- language="C" -->
* static gboolean
* foo_focus (GtkWidget *widget,
* GtkDirectionType direction)
@@ -320,18 +301,15 @@
* }
* return have_focus;
* }
- * ]|
- * </example>
+ * ]|
* Note that the layouting widget is responsible for matching the
* GtkDirectionType values to the way it lays out its cells.
- * </para>
- * </refsect2>
- * <refsect2 id="cell-properties">
- * <title>Cell Properties</title>
- * <para>
- * The #GtkCellArea introduces cell properties
- * for #GtkCellRenderers in very much the same way that #GtkContainer
- * introduces <link linkend="child-properties">child properties</link>
+ *
+ * ## Cell Properties
+ *
+ * The #GtkCellArea introduces cell properties for #GtkCellRenderers
+ * in very much the same way that #GtkContainer introduces
+ * <link linkend="child-properties">child properties</link>
* for #GtkWidgets. This provides some general interfaces for defining
* the relationship cell areas have with their cells. For instance in a
* #GtkCellAreaBox a cell might "expand" and receive extra space when
@@ -348,8 +326,6 @@
* gtk_cell_area_cell_set() or gtk_cell_area_cell_set_valist(). To obtain
* the value of a cell property, use gtk_cell_area_cell_get_property(),
* gtk_cell_area_cell_get() or gtk_cell_area_cell_get_valist().
- * </para>
- * </refsect2>
*/
#include "config.h"
diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c
index 1bd5070..777a32c 100644
--- a/gtk/gtkcelllayout.c
+++ b/gtk/gtkcelllayout.c
@@ -21,22 +21,21 @@
* @Title: GtkCellLayout
*
* #GtkCellLayout is an interface to be implemented by all objects which
- * want to provide a #GtkTreeViewColumn<!-- -->-like API for packing cells, setting
- * attributes and data funcs.
+ * want to provide a #GtkTreeViewColumn like API for packing cells,
+ * setting attributes and data funcs.
*
- * One of the notable features provided by implementations of GtkCellLayout
- * are attributes. Attributes let you set the properties
+ * One of the notable features provided by implementations of
+ * GtkCellLayout are attributes. Attributes let you set the properties
* in flexible ways. They can just be set to constant values like regular
* properties. But they can also be mapped to a column of the underlying
* tree model with gtk_cell_layout_set_attributes(), which means that the value
- * of the attribute can change from cell to cell as they are rendered by the
- * cell renderer. Finally, it is possible to specify a function with
- * gtk_cell_layout_set_cell_data_func() that is called to determine the value
- * of the attribute for each cell that is rendered.
- *
- * <refsect2 id="GtkCellLayout-BUILDER-UI">
- * <title>GtkCellLayouts as GtkBuildable</title>
- * <para>
+ * of the attribute can change from cell to cell as they are rendered by
+ * the cell renderer. Finally, it is possible to specify a function with
+ * gtk_cell_layout_set_cell_data_func() that is called to determine the
+ * value of the attribute for each cell that is rendered.
+ *
+ * ## GtkCellLayouts as GtkBuildable
+ *
* Implementations of GtkCellLayout which also implement the GtkBuildable
* interface (#GtkCellView, #GtkIconView, #GtkComboBox,
* #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects
@@ -46,8 +45,7 @@
* a name attribute which specifies a property of the cell renderer; the
* content of the element is the attribute value.
*
- * <example>
- * <title>A UI definition fragment specifying attributes</title>
+ * This is an example of a UI definition fragment specifying attributes:
* |[
* <object class="GtkCellView">
* <child>
@@ -58,15 +56,15 @@
* </child>"
* </object>
* ]|
- * </example>
- *
- * Furthermore for implementations of GtkCellLayout that use a #GtkCellArea
- * to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea)
- * <link linkend="cell-properties">cell properties</link> 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.
- * <example>
- * <title>A UI definition fragment specifying cell properties</title>
+ *
+ * Furthermore for implementations of GtkCellLayout that use a
+ * #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use
+ * a GtkCellArea) <link linkend="cell-properties">cell properties</link>
+ * 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.
+ *
+ * Here is a UI definition fragment specifying cell properties:
* |[
* <object class="GtkTreeViewColumn">
* <child>
@@ -78,13 +76,9 @@
* </child>"
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*
- * <refsect2>
- * <title>Subclassing GtkCellLayout implementations</title>
- * <para>
+ * ## Subclassing GtkCellLayout implementations
+ *
* When subclassing a widget that implements #GtkCellLayout like
* #GtkIconView or #GtkComboBox, there are some considerations related
* to the fact that these widgets internally use a #GtkCellArea.
@@ -128,8 +122,6 @@
* to support alternative cell areas, you can do so by moving the
* problematic calls out of init() and into a constructor()
* for your class.
- * </para>
- * </refsect2>
*/
#include "config.h"
diff --git a/gtk/gtkcomboboxtext.c b/gtk/gtkcomboboxtext.c
index 80325b6..3fecdc9 100644
--- a/gtk/gtkcomboboxtext.c
+++ b/gtk/gtkcomboboxtext.c
@@ -52,9 +52,8 @@
* You should not call gtk_combo_box_set_model() or attempt to pack more cells
* into this combo box via its GtkCellLayout interface.
*
- * <refsect2 id="GtkComboBoxText-BUILDER-UI">
- * <title>GtkComboBoxText as GtkBuildable</title>
- * <para>
+ * ## 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>
@@ -62,8 +61,7 @@
* also supports the regular translation attributes "translatable",
* "context" and "comments".
*
- * <example>
- * <title>A UI definition fragment specifying GtkComboBoxText items</title>
+ * Here is a a UI definition fragment specifying GtkComboBoxText items:
* |[
* <object class="GtkComboBoxText">
* <items>
@@ -73,9 +71,6 @@
* </items>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
static void gtk_combo_box_text_buildable_interface_init (GtkBuildableIface *iface);
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index bd8d059..805fbb2 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -78,9 +78,8 @@
* children in a horizontal row, and a #GtkGrid arranges the widgets it contains
* in a two-dimensional grid.
*
- * <refsect2 id="container-geometry-management">
- * <title>Height for width geometry management</title>
- * <para>
+ * ## Height for width geometry management
+ *
* GTK+ uses a height-for-width (and width-for-height) geometry management system.
* Height-for-width means that a widget can change how much vertical space it needs,
* depending on the amount of horizontal space that it is given (and similar for
@@ -151,7 +150,7 @@
*
* Height for width requests are generally implemented in terms of a virtual allocation
* of widgets in the input orientation. Assuming an height-for-width request mode, a container
- * would implement the get_preferred_height_for_width(<!-- -->) virtual function by first calling
+ * would implement the get_preferred_height_for_width() virtual function by first calling
* gtk_widget_get_preferred_width() for each of its children.
*
* For each potential group of children that are lined up horizontally, the values returned by
@@ -180,11 +179,9 @@
*
* See <link linkend="geometry-management">GtkWidget's geometry management section</link>
* to learn more about implementing height-for-width geometry management for widgets.
- * </para>
- * </refsect2>
- * <refsect2 id="child-properties">
- * <title>Child properties</title>
- * <para>
+ *
+ * ## Child properties
+ *
* GtkContainer introduces child properties.
* These are object properties that are not specific
* to either the container or the contained widget, but rather to their relation.
@@ -202,17 +199,15 @@
* gtk_container_child_get_property(), gtk_container_child_get() or
* gtk_container_child_get_valist(). To emit notification about child property
* changes, use gtk_widget_child_notify().
- * </para>
- * </refsect2>
- * <refsect2 id="GtkContainer-BUILDER-UI">
- * <title>GtkContainer as GtkBuildable</title>
- * <para>
+ *
+ * ## GtkContainer as GtkBuildable
+ *
* The GtkContainer implementation of the GtkBuildable interface
* supports a <packing> element for children, which can
* contain multiple <property> elements that specify
* child properties for the child.
- * <example>
- * <title>Child properties in UI definitions</title>
+ *
+ * An example of child properties in UI definitions:
* |[
* <object class="GtkVBox">
* <child>
@@ -223,12 +218,10 @@
* </child>
* </object>
* ]|
- * </example>
+ *
* 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.
- * </para>
- * </refsect2>
*/
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index cfccb9e..2848438 100644
--- a/gtk/gtkcssprovider.c
+++ b/gtk/gtkcssprovider.c
@@ -55,9 +55,8 @@
* It is able to parse <ulink url="http://www.w3.org/TR/CSS2";>CSS</ulink>-like
* input in order to style widgets.
*
- * <refsect2 id="gtkcssprovider-files">
- * <title>Default files</title>
- * <para>
+ * ## Default files
+ *
* An application can cause GTK+ to parse a specific CSS style sheet by
* calling gtk_css_provider_load_from_file() and adding the provider with
* gtk_style_context_add_provider() or gtk_style_context_add_provider_for_screen().
@@ -71,61 +70,52 @@
* (see the #GtkSettings:gtk-theme-name setting) and <replaceable>datadir</replaceable>
* is the prefix configured when GTK+ was compiled, unless overridden by the
* <envar>GTK_DATA_PREFIX</envar> environment variable.
- * </para>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-stylesheets">
- * <title>Style sheets</title>
- * <para>
+ *
+ * ## Style sheets
+ *
* The basic structure of the style sheets understood by this provider is
* a series of statements, which are either rule sets or '@-rules', separated
* by whitespace.
- * </para>
- * <para>
+ *
* A rule set consists of a selector and a declaration block, which is
* a series of declarations enclosed in curly braces ({ and }). The
* declarations are separated by semicolons (;). Multiple selectors can
* share the same declaration block, by putting all the separators in
* front of the block, separated by commas.
- * </para>
- * <example><title>A rule set with two selectors</title>
+ *
+ * An example of a rule set with two selectors:
* |[
* GtkButton, GtkEntry {
* color: #ff00ea;
* font: Comic Sans 12
* }
* ]|
- * </example>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-selectors">
- * <title>Selectors</title>
- * <para>
- * Selectors work very similar to the way they do in CSS, with widget class
+ *
+ * ## Selectors
+ *
+ * <para id="gtkcssprovider-selectors">Selectors work very similar to the way they do in CSS, with widget
class
* names taking the role of element names, and widget names taking the role
* of IDs. When used in a selector, widget names must be prefixed with a
* '#' character. The '*' character represents the so-called universal
- * selector, which matches any widget.
- * </para>
- * <para>
+ * selector, which matches any widget.</para>
+ *
* To express more complicated situations, selectors can be combined in
* various ways:
- * <itemizedlist>
- * <listitem><para>To require that a widget satisfies several conditions,
+ * - To require that a widget satisfies several conditions,
* combine several selectors into one by concatenating them. E.g.
* <literal>GtkButton#button1</literal> matches a GtkButton widget
- * with the name button1.</para></listitem>
- * <listitem><para>To only match a widget when it occurs inside some other
+ * with the name button1.
+ * - To only match a widget when it occurs inside some other
* widget, write the two selectors after each other, separated by whitespace.
* E.g. <literal>GtkToolBar GtkButton</literal> matches GtkButton widgets
- * that occur inside a GtkToolBar.</para></listitem>
- * <listitem><para>In the previous example, the GtkButton is matched even
+ * that occur inside a GtkToolBar.
+ * - In the previous example, the GtkButton is matched even
* if it occurs deeply nested inside the toolbar. To restrict the match
* to direct children of the parent widget, insert a '>' character between
* the two selectors. E.g. <literal>GtkNotebook > GtkLabel</literal> matches
- * GtkLabel widgets that are direct children of a GtkNotebook.</para></listitem>
- * </itemizedlist>
- * </para>
- * <example>
- * <title>Widget classes and names in selectors</title>
+ * GtkLabel widgets that are direct children of a GtkNotebook.
+ *
+ * An example of widget classes and names in selectors:
* |[
* /* Theme labels that are descendants of a window */
* GtkWindow GtkLabel {
@@ -160,25 +150,21 @@
* background-color: #f0a810
* }
* ]|
- * </example>
- * <para>
+ *
* Widgets may also define style classes, which can be used for matching.
* When used in a selector, style classes must be prefixed with a '.'
* character.
- * </para>
- * <para>
+ *
* Refer to the documentation of individual widgets to learn which
* style classes they define and see <xref linkend="gtkstylecontext-classes"/>
* for a list of all style classes used by GTK+ widgets.
- * </para>
- * <para>
+ *
* Note that there is some ambiguity in the selector syntax when it comes
* to differentiation widget class names from regions. GTK+ currently treats
* a string as a widget class name if it contains any uppercase characters
* (which should work for more widgets with names like GtkLabel).
- * </para>
- * <example>
- * <title>Style classes in selectors</title>
+ *
+ * An example for style classes in selectors:
* |[
* /* Theme all widgets defining the class entry */
* .entry {
@@ -190,29 +176,25 @@
* color: #900185
* }
* ]|
- * </example>
- * <para>
+ *
* In complicated widgets like e.g. a GtkNotebook, it may be desirable
* to style different parts of the widget differently. To make this
* possible, container widgets may define regions, whose names
* may be used for matching in selectors.
- * </para>
- * <para>
+ *
* Some containers allow to further differentiate between regions by
* applying so-called pseudo-classes to the region. For example, the
* tab region in GtkNotebook allows to single out the first or last
* tab by using the :first-child or :last-child pseudo-class.
* When used in selectors, pseudo-classes must be prefixed with a
* ':' character.
- * </para>
- * <para>
+ *
* Refer to the documentation of individual widgets to learn which
* regions and pseudo-classes they define and see
* <xref linkend="gtkstylecontext-classes"/> for a list of all regions
* used by GTK+ widgets.
- * </para>
- * <example>
- * <title>Regions in selectors</title>
+ *
+ * An example for regions in selectors:
* |[
* /* Theme any label within a notebook */
* GtkNotebook GtkLabel {
@@ -231,16 +213,14 @@
* color: #89d012;
* }
* ]|
- * </example>
- * <para>
+ *
* Another use of pseudo-classes is to match widgets depending on their
* state. This is conceptually similar to the :hover, :active or :focus
* pseudo-classes in CSS. The available pseudo-classes for widget states
* are :active, :prelight (or :hover), :insensitive, :selected, :focused
* and :inconsistent.
- * </para>
- * <example>
- * <title>Styling specific widget states</title>
+ *
+ * And example for styling specific widget states:
* |[
* /* Theme active (pressed) buttons */
* GtkButton:active {
@@ -275,45 +255,37 @@
* background-color: #20395a;
* }
* ]|
- * </example>
- * <para>
+ *
* Widget state pseudoclasses may only apply to the last element
* in a selector.
- * </para>
- * <para>
+ *
* To determine the effective style for a widget, all the matching rule
* sets are merged. As in CSS, rules apply by specificity, so the rules
* whose selectors more closely match a widget path will take precedence
* over the others.
- * </para>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-rules">
- * <title>@ Rules</title>
- * <para>
+ *
+ * ## @ Rules
+ *
* GTK+'s CSS supports the @import rule, in order to load another
* CSS style sheet in addition to the currently parsed one.
- * </para>
- * <example>
- * <title>Using the @import rule</title>
+ *
+ * An example for using the @import rule:
* |[
* @import url ("path/to/common.css");
* ]|
- * </example>
- * <para id="css-binding-set">
+ *
* In order to extend key bindings affecting different widgets, GTK+
* supports the @binding-set rule to parse a set of bind/unbind
* directives, see #GtkBindingSet for the supported syntax. Note that
* the binding sets defined in this way must be associated with rule sets
* by setting the gtk-key-bindings style property.
- * </para>
- * <para>
+ *
* Customized key bindings are typically defined in a separate
* <filename>gtk-keys.css</filename> CSS file and GTK+ loads this file
* according to the current key theme, which is defined by the
* #GtkSettings:gtk-key-theme-name setting.
- * </para>
- * <example>
- * <title>Using the @binding rule</title>
+ *
+ * An example for using the @binding rule:
* |[
* @binding-set binding-set1 {
* bind "<alt>Left" { "move-cursor" (visual-positions, -3, 0) };
@@ -330,15 +302,13 @@
* gtk-key-bindings: binding-set1, binding-set2;
* }
* ]|
- * </example>
- * <para>
+ *
* GTK+ also supports an additional @define-color rule, in order
* to define a color name which may be used instead of color numeric
* representations. Also see the #GtkSettings:gtk-color-scheme setting
* for a way to override the values of these named colors.
- * </para>
- * <example>
- * <title>Defining colors</title>
+ *
+ * An example for defining colors:
* |[
* @define-color bg_color #f9a039;
*
@@ -346,18 +316,15 @@
* background-color: @bg_color;
* }
* ]|
- * </example>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-symbolic-colors">
- * <title>Symbolic colors</title>
- * <para>
+ *
+ * ## Symbolic colors
+ *
* Besides being able to define color names, the CSS parser is also able
* to read different color expressions, which can also be nested, providing
* a rich language to define colors which are derived from a set of base
* colors.
- * </para>
- * <example>
- * <title>Using symbolic colors</title>
+ *
+ * An example for using symbolic colors:
* |[
* @define-color entry-color shade (@bg_color, 0.7);
*
@@ -371,10 +338,8 @@
* 0.8);
* }
* ]|
- * </example>
- * <para>
- * The various ways to express colors in GTK+ CSS are:
- * </para>
+ *
+ * The various ways to express colors in GTK+ CSS are:
* <informaltable>
* <tgroup cols="3">
* <thead>
@@ -445,13 +410,11 @@
* </tbody>
* </tgroup>
* </informaltable>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-gradients">
- * <title>Gradients</title>
- * <para>
+ *
+ * ## Gradients
+ *
* Linear or radial Gradients can be used as background images.
- * </para>
- * <para>
+ *
* A linear gradient along the line from (@start_x, @start_y) to
* (@end_x, @end_y) is specified using the syntax
* <literallayout>-gtk-gradient (linear,
@@ -466,26 +429,23 @@
* The color-stop can be repeated multiple times to add more than one color
* stop. 'from (@color)' and 'to (@color)' can be used as abbreviations for
* color stops with position 0 and 1, respectively.
- * </para>
- * <example>
- * <title>A linear gradient</title>
+ *
+ * An example for a linear gradient:
* <inlinegraphic fileref="gradient1.png" format="PNG"/>
- * <para>This gradient was specified with
+ * This gradient was specified with
* <literallayout>-gtk-gradient (linear,
* left top, right bottom,
- * from(@yellow), to(@blue))</literallayout></para>
- * </example>
- * <example>
- * <title>Another linear gradient</title>
+ * from(@yellow), to(@blue))</literallayout>
+ *
+ * Another example for a linear gradient:
* <inlinegraphic fileref="gradient2.png" format="PNG"/>
- * <para>This gradient was specified with
+ * This gradient was specified with
* <literallayout>-gtk-gradient (linear,
* 0 0, 0 1,
* color-stop(0, @yellow),
* color-stop(0.2, @blue),
- * color-stop(1, #0f0))</literallayout></para>
- * </example>
- * <para>
+ * color-stop(1, #0f0))</literallayout>
+ *
* A radial gradient along the two circles defined by (@start_x, @start_y,
* @start_radius) and (@end_x, @end_y, @end_radius) is specified using the
* syntax
@@ -496,63 +456,53 @@
* ...)</literallayout>
* where @start_radius and @end_radius are floating point numbers and
* the other parameters are as before.
- * </para>
- * <example>
- * <title>A radial gradient</title>
+ *
+ * An example of a radial gradient:
* <inlinegraphic fileref="gradient3.png" format="PNG"/>
- * <para>This gradient was specified with
+ * This gradient was specified with
* <literallayout>-gtk-gradient (radial,
* center center, 0,
* center center, 1,
- * from(@yellow), to(@green))</literallayout></para>
- * </example>
- * <example>
- * <title>Another radial gradient</title>
+ * from(@yellow), to(@green))</literallayout>
+ *
+ * Another example of a radial gradient:
* <inlinegraphic fileref="gradient4.png" format="PNG"/>
- * <para>This gradient was specified with
+ * This gradient was specified with
* <literallayout>-gtk-gradient (radial,
* 0.4 0.4, 0.1,
* 0.6 0.6, 0.7,
* color-stop (0, #f00),
* color-stop (0.1, #a0f),
* color-stop (0.2, @yellow),
- * color-stop (1, @green))</literallayout></para>
- * </example>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-shadows">
- * <title>Text shadow</title>
- * <para>
+ * color-stop (1, @green))</literallayout>
+ *
+ * ## Text shadow
+ *
* A shadow list can be applied to text or symbolic icons, using the CSS3
* text-shadow syntax, as defined in
* <ulink url="http://www.w3.org/TR/css3-text/#text-shadow";>the CSS3 specification</ulink>.
- * </para>
- * <para>
+ *
* A text shadow is specified using the syntax
* <literallayout>text-shadow: @horizontal_offset @vertical_offset [ @blur_radius ] @color</literallayout>
* The offset of the shadow is specified with the @horizontal_offset and @vertical_offset
* parameters. The optional blur radius is parsed, but it is currently not rendered by
* the GTK+ theming engine.
- * </para>
- * <para>
+ *
* To set a shadow on an icon, use the icon-shadow property instead,
* with the same syntax.
- * </para>
- * <para>
+ *
* To set multiple shadows on an element, you can specify a comma-separated list
* of shadow elements in the text-shadow or icon-shadow property. Shadows are
* always rendered front-back, i.e. the first shadow specified is on top of the
* others. Shadows can thus overlay each other, but they can never overlay the
* text or icon itself, which is always rendered on top of the shadow layer.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Box shadow</title>
- * <para>
+ *
+ * ## Box shadow
+ *
* Themes can apply shadows on framed elements using the CSS3 box-shadow syntax,
* as defined in
* <ulink url="http://www.w3.org/TR/css3-background/#the-box-shadow";>the CSS3 specification</ulink>.
- * </para>
- * <para>
+ *
* A box shadow is specified using the syntax
* <literallayout>box-shadow: [ @inset ] @horizontal_offset @vertical_offset [ @blur_radius ] [ @spread ]
@color</literallayout>
* A positive offset will draw a shadow that is offset to the right (down) of the box,
@@ -562,51 +512,44 @@
* the GTK+ theming engine.
* The inset parameter defines whether the drop shadow should be rendered inside or outside
* the box canvas.
- * </para>
- * <para>
+ *
* To set multiple box-shadows on an element, you can specify a comma-separated list
* of shadow elements in the box-shadow property. Shadows are always rendered
* front-back, i.e. the first shadow specified is on top of the others, so they may
* overlap other boxes or other shadows.
- * </para>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-border-image">
- * <title>Border images</title>
- * <para>
+ *
+ * ## Border images
+ *
* Images and gradients can also be used in slices for the purpose of creating
* scalable borders.
* For more information, see the CSS3 documentation for the border-image property,
* which can be found <ulink url="http://www.w3.org/TR/css3-background/#border-images";>here</ulink>.
- * </para>
+ *
* <inlinegraphic fileref="slices.png" format="PNG"/>
- * <para>
+ *
* The parameters of the slicing process are controlled by
* four separate properties. Note that you can use the
* <literallayout>border-image</literallayout> shorthand property
* to set values for the three properties at the same time.
- * </para>
- * <para>
+ *
* <literallayout>border-image-source: url(@path)
* (or border-image-source: -gtk-gradient(...))</literallayout>:
* Specifies the source of the border image, and it can either
* be an URL or a gradient (see above).
- * </para>
- * <para>
+ *
* <literallayout>border-image-slice: @top @right @bottom @left</literallayout>
* The sizes specified by the @top, @right, @bottom and @left parameters
* are the offsets, in pixels, from the relevant edge where the image
* should be "cut off" to build the slices used for the rendering
* of the border.
- * </para>
- * <para>
+ *
* <literallayout>border-image-width: @top @right @bottom @left</literallayout>
* The sizes specified by the @top, @right, @bottom and @left parameters
* are inward distances from the border box edge, used to specify the
* rendered size of each slice determined by border-image-slice.
* If this property is not specified, the values of border-width will
* be used as a fallback.
- * </para>
- * <para>
+ *
* <literallayout>border-image-repeat: [stretch|repeat|round|space] ?
* [stretch|repeat|round|space]</literallayout>
* Specifies how the image slices should be rendered in the area
@@ -625,31 +568,25 @@
* If two options are specified, the first one affects
* the horizontal behaviour and the second one the vertical behaviour.
* If only one option is specified, it affects both.
- * </para>
- * <example>
- * <title>A border image</title>
+ *
+ * An example of a border image:
* <inlinegraphic fileref="border1.png" format="PNG"/>
- * <para>This border image was specified with
+ * This border image was specified with
* <literallayout>url("gradient1.png") 10 10 10 10</literallayout>
- * </para>
- * </example>
- * <example>
- * <title>A repeating border image</title>
+ *
+ * An example of a repeating border image:
* <inlinegraphic fileref="border2.png" format="PNG"/>
- * <para>This border image was specified with
+ * This border image was specified with
* <literallayout>url("gradient1.png") 10 10 10 10 repeat</literallayout>
- * </para>
- * </example>
- * <example>
- * <title>A stretched border image</title>
+ *
+ * An example of a stretched border image:
* <inlinegraphic fileref="border3.png" format="PNG"/>
- * <para>This border image was specified with
+ * This border image was specified with
* <literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout>
- * </para>
- * </example>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-transitions">
- * <para>Styles can specify transitions that will be used to create a gradual
+ *
+ * ## Transitions
+ *
+ * Styles can specify transitions that will be used to create a gradual
* change in the appearance when a widget state changes. The following
* syntax is used to specify transitions:
* <literallayout>@duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?</literallayout>
@@ -673,19 +610,15 @@
* <figure><title>Ease-out transition</title>
* <graphic fileref="ease-out.png" format="PNG"/>
* </figure>
- * </para>
- * </refsect2>
- * <refsect2 id="gtkcssprovider-properties">
- * <title>Supported properties</title>
- * <para>
+ *
+ * ## Supported properties
+ *
* Properties are the part that differ the most to common CSS,
* not all properties are supported (some are planned to be
* supported eventually, some others are meaningless or don't
* map intuitively in a widget based environment).
- * </para>
- * <para>
+ *
* The currently supported properties are:
- * </para>
* <informaltable>
* <tgroup cols="4">
* <thead>
@@ -953,7 +886,7 @@
* </tbody>
* </tgroup>
* </informaltable>
- * <para>
+ *
* GtkThemingEngines can register their own, engine-specific style properties
* with the function gtk_theming_engine_register_property(). These properties
* can be set in CSS like other properties, using a name of the form
@@ -962,9 +895,8 @@
* name of the property. Style properties that have been registered by widgets
* using gtk_widget_class_install_style_property() can also be set in this
* way, using the widget class name for <replaceable>namespace</replaceable>.
- * </para>
- * <example>
- * <title>Using engine-specific style properties</title>
+ *
+ * An example for using engine-specific style properties:
* |[
* * {
* engine: clearlooks;
@@ -973,8 +905,6 @@
* -clearlooks-colorize-scrollbar: false;
* }
* ]|
- * </example>
- * </refsect2>
*/
typedef struct GtkCssRuleset GtkCssRuleset;
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 7c63818..51a5d94 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -63,8 +63,8 @@
*
* #GtkDialog boxes are created with a call to gtk_dialog_new() or
* gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is
- * recommended; it allows you to set the dialog title, some convenient flags,
- * and add simple buttons.
+ * recommended; it allows you to set the dialog title, some convenient
+ * flags, and add simple buttons.
*
* If 'dialog' is a newly created dialog, the two primary areas of the
* window can be accessed through gtk_dialog_get_content_area() and
@@ -96,8 +96,8 @@
* use #GtkMessageDialog to save yourself some effort. But you'd need to
* create the dialog contents manually if you had more than a simple message
* in the dialog.
- * <example>
- * <title>Simple GtkDialog usage</title>
+ *
+ * An example for simple GtkDialog usage:
* |[<!-- language="C" -->
* /* Function to open a dialog box displaying the message provided. */
* void
@@ -127,22 +127,19 @@
* gtk_widget_show_all (dialog);
* }
* ]|
- * </example>
*
- * <refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title>
- * <para>
+ * ## GtkDialog as GtkBuildable
+ *
* The GtkDialog implementation of the #GtkBuildable interface exposes the
* @vbox and @action_area as internal children with the names "vbox" and
* "action_area".
- * </para>
- * <para>
+ *
* 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).
- * </para>
- * <example>
- * <title>A #GtkDialog UI definition fragment.</title>
+ *
+ * An example of a #GtkDialog UI definition fragment:
* |[
* <object class="GtkDialog" id="dialog1">
* <child internal-child="vbox">
@@ -165,8 +162,6 @@
* </action-widgets>
* </object>
* ]|
- * </example>
- * </refsect2>
*/
struct _GtkDialogPrivate
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index c8b1566..41c6979 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -32,9 +32,8 @@
* to add it to the expander. When the expander is toggled, it will take
* care of showing and hiding the child automatically.
*
- * <refsect2 id="expander-special-usage">
- * <title>Special Usage</title>
- * <para>
+ * ## Special Usage
+ *
* There are situations in which you may prefer to show and hide the
* expanded widget yourself, such as when you want to actually create
* the widget at expansion time. In this case, create a #GtkExpander
@@ -42,7 +41,7 @@
* #GtkExpander:expanded property which can be used to monitor
* its expansion state. You should watch this property with a signal
* connection as follows:
- * </para>
+ *
* |[<!-- language="C" -->
* expander = gtk_expander_new_with_mnemonic ("_More Options");
* g_signal_connect (expander, "notify::expanded",
@@ -69,18 +68,16 @@
* }
* }
* ]|
- * </refsect2>
- * <refsect2 id="GtkExpander-BUILDER-UI">
- * <title>GtkExpander as GtkBuildable</title>
- * <para>
+ *
+ * ## GtkExpander as GtkBuildable
+ *
* 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.
- * </para>
- * <example>
- * <title>A UI definition fragment with GtkExpander</title>
+ *
+ * An example of a UI definition fragment with GtkExpander:
* |[
* <object class="GtkExpander">
* <child type="label">
@@ -91,9 +88,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </refsect2>
- *
*/
#include "config.h"
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index eee7976..68aa4c4 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -43,34 +43,20 @@
* In the default implementation these are displayed in the left pane. It
* may be a bit confusing at first that these shortcuts come from various
* sources and in various flavours, so lets explain the terminology here:
- * <variablelist>
- * <varlistentry>
- * <term>Bookmarks</term>
- * <listitem>
- * are created by the user, by dragging folders from the
- * right pane to the left pane, or by using the "Add". Bookmarks
- * can be renamed and deleted by the user.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>Shortcuts</term>
- * <listitem>
- * can be provided by the application. For example, a Paint program may
- * want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the
- * user.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>Volumes</term>
- * <listitem>
- * are provided by the underlying filesystem abstraction. They are
- * the "roots" of the filesystem.
- * </listitem>
- * </varlistentry>
- * </variablelist>
- *
- * <refsect2 id="gtkfilechooser-encodings">
- * <title>File Names and Encodings</title>
+ *
+ * - Bookmarks: are created by the user, by dragging folders from the
+ * right pane to the left pane, or by using the "Add". Bookmarks
+ * can be renamed and deleted by the user.
+ *
+ * - Shortcuts: can be provided by the application. For example, a Paint
+ * program may want to add a shortcut for a Clipart folder. Shortcuts
+ * cannot be modified by the user.
+ *
+ * - Volumes: are provided by the underlying filesystem abstraction. They are
+ * the "roots" of the filesystem.
+ *
+ * ## File Names and Encodings
+ *
* When the user is finished selecting files in a
* #GtkFileChooser, your program can get the selected names
* either as filenames or as URIs. For URIs, the normal escaping
@@ -80,27 +66,24 @@
* <envar>G_FILENAME_ENCODING</envar> environment variable.
* Please see the GLib documentation for more details about this
* variable.
- * <note>
- * This means that while you can pass the result of
- * gtk_file_chooser_get_filename() to
- * open(2) or fopen(3), you may not be able to
- * directly set it as the text of a #GtkLabel widget unless you
- * convert it first to UTF-8, which all GTK+ widgets expect.
- * You should use g_filename_to_utf8() to convert filenames
- * into strings that can be passed to GTK+ widgets.
- * </note>
- * </refsect2>
- * <refsect2 id="gtkfilechooser-preview">
- * <title>Adding a Preview Widget</title>
- * <para>
+ *
+ * This means that while you can pass the result of
+ * gtk_file_chooser_get_filename() to open() or fopen(),
+ * you may not be able to directly set it as the text of a
+ * #GtkLabel widget unless you convert it first to UTF-8,
+ * which all GTK+ widgets expect. You should use g_filename_to_utf8()
+ * to convert filenames into strings that can be passed to GTK+
+ * widgets.
+ *
+ * ## Adding a Preview Widget
+ *
* You can add a custom preview widget to a file chooser and then
* get notification about when the preview needs to be updated.
* To install a preview widget, use
* gtk_file_chooser_set_preview_widget(). Then, connect to the
* #GtkFileChooser::update-preview signal to get notified when
* you need to update the contents of the preview.
- * </para>
- * <para>
+ *
* Your callback should use
* gtk_file_chooser_get_preview_filename() to see what needs
* previewing. Once you have generated the preview for the
@@ -108,9 +91,8 @@
* gtk_file_chooser_set_preview_widget_active() with a boolean
* flag that indicates whether your callback could successfully
* generate a preview.
- * </para>
- * <example id="example-gtkfilechooser-preview">
- * <title>Sample Usage</title>
+ *
+ * <para id="gtkfilechooser-preview">An example for using a preview widget:</para>
* |[<!-- language="C" -->
* {
* GtkImage *preview;
@@ -146,20 +128,17 @@
* gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
* }
* ]|
- * </example>
- * </refsect2>
- * <refsect2 id="gtkfilechooser-extra">
- * <title>Adding Extra Widgets</title>
- * <para>
+ *
+ * ## Adding Extra Widgets
+ *
* You can add extra widgets to a file chooser to provide options
* that are not present in the default design. For example, you
* can add a toggle button to give the user the option to open a
* file in read-only mode. You can use
* gtk_file_chooser_set_extra_widget() to insert additional
* widgets in a file chooser.
- * </para>
- * <example id="example-gtkfilechooser-extra">
- * <title>Sample Usage</title>
+ *
+ * An example for adding extra widgets:
* |[<!-- language="C" -->
*
* GtkWidget *toggle;
@@ -171,14 +150,11 @@
* gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
* }
* ]|
- * </example>
- * <note>
- * If you want to set more than one extra widget in the file
- * chooser, you can a container such as a #GtkBox or a #GtkGrid
- * and include your widgets in it. Then, set the container as
- * the whole extra widget.
- * </note>
- * </refsect2>
+ *
+ * If you want to set more than one extra widget in the file
+ * chooser, you can a container such as a #GtkBox or a #GtkGrid
+ * and include your widgets in it. Then, set the container as
+ * the whole extra widget.
*/
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index fb4fc66..cf57597 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -38,18 +38,17 @@
* see gtk_file_chooser_add_filter(), but it is also possible
* to manually use a filter on a file with gtk_file_filter_filter().
*
- * <refsect2 id="GtkFileFilter-BUILDER-UI">
- * <title>GtkFileFilter as GtkBuildable</title>
- * <para>
+ * ## 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> is the same
+ * supports adding rules using the <mime-types>, <patterns>
+ * and <applications> elements and listing the rules within.
+ * Specifying a <mime-type> or <pattern> is the same
* as calling gtk_recent_filter_add_mime_type()
* or gtk_recent_filter_add_pattern().
*
- * <example>
- * <title>A UI definition fragment specifying GtkFileFilter rules</title>
+ * An example of a UI definition fragment specifying GtkFileFilter
+ * rules:
* |[
* <object class="GtkFileFilter">
* <mime-types>
@@ -62,9 +61,6 @@
* </patterns>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
#include "config.h"
diff --git a/gtk/gtkfontchooserdialog.c b/gtk/gtkfontchooserdialog.c
index 7400a5f..17c575e 100644
--- a/gtk/gtkfontchooserdialog.c
+++ b/gtk/gtkfontchooserdialog.c
@@ -54,12 +54,11 @@ struct _GtkFontChooserDialogPrivate
* The #GtkFontChooserDialog widget is a dialog for selecting a font.
* It implements the #GtkFontChooser interface.
*
- * <refsect2 id="GtkFontChooserDialog-BUILDER-UI">
- * <title>GtkFontChooserDialog as GtkBuildable</title>
- * The GtkFontChooserDialog implementation of the GtkBuildable interface
- * exposes the buttons with the names
- * "select_button" and "cancel_button".
- * </refsect2>
+ * ## GtkFontChooserDialog as GtkBuildable
+ *
+ * The GtkFontChooserDialog implementation of the #GtkBuildable
+ * interface exposes the buttons with the names "select_button"
+ * and "cancel_button".
*
* Since: 3.2
*/
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c
index 3e302c3..32b35a6 100644
--- a/gtk/gtkframe.c
+++ b/gtk/gtkframe.c
@@ -45,17 +45,15 @@
* top side of the frame. The position of the
* label can be controlled with gtk_frame_set_label_align().
*
- * <refsect2 id="GtkFrame-BUILDER-UI">
- * <title>GtkFrame as GtkBuildable</title>
- * <para>
+ * ## GtkFrame as GtkBuildable
+ *
* 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.
- * </para>
- * <example>
- * <title>A UI definition fragment with GtkFrame</title>
+ *
+ * An example of a UI definition fragment with GtkFrame:
* |[
* <object class="GtkFrame">
* <child type="label">
@@ -66,8 +64,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </refsect2>
*/
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index 5d6dee4..07fa6d4 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -72,8 +72,7 @@
* by using gtk_info_bar_set_message_type(). GTK+ may use the message type
* to determine how the message is displayed.
*
- * <example>
- * <title>Simple GtkInfoBar usage.</title>
+ * A simple example for using a GtkInfoBar:
* |[<!-- language="C" -->
* /* set up info bar */
* info_bar = gtk_info_bar_new ();
@@ -98,22 +97,17 @@
* GTK_MESSAGE_ERROR);
* gtk_widget_show (info_bar);
* ]|
- * </example>
*
- * <refsect2 id="GtkInfoBar-BUILDER-UI">
- * <title>GtkInfoBar as GtkBuildable</title>
- * <para>
+ * ## GtkInfoBar as GtkBuildable
+ *
* The GtkInfoBar implementation of the GtkBuildable interface exposes
* the content area and action area as internal children with the names
* "content_area" and "action_area".
- * </para>
- * <para>
+ *
* 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).
- * </para>
- * </refsect2>
*/
enum
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 91e8b53..acff4b5 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -67,16 +67,14 @@
* implies, most labels are used to label another widget such as a
* #GtkButton, a #GtkMenuItem, or a #GtkComboBox.
*
- * <refsect2 id="GtkLabel-BUILDER-UI">
- * <title>GtkLabel as GtkBuildable</title>
- * <para>
+ * ## 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,
* start and end and allows you to specify #PangoAttribute values for this label.
*
- * <example>
- * <title>A UI definition fragment specifying Pango attributes</title>
+ * An example of a UI definition fragment specifying Pango attributes:
* |[
* <object class="GtkLabel">
* <attributes>
@@ -85,17 +83,15 @@
* </attributes>
* </object>
* ]|
- * </example>
+ *
* The start and end attributes specify the range of characters to which the
* Pango attribute applies. If start and end are not specified, the attribute is
* applied to the whole text. Note that specifying ranges does not make much
* sense with translatable attributes. Use markup embedded in the translatable
* content instead.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Mnemonics</title>
- * <para>
+ *
+ * ## Mnemonics
+ *
* Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
* underlined characters in the label, used for keyboard navigation.
* Mnemonics are created by providing a string with an underscore before
@@ -110,8 +106,8 @@
* the label is inside a button:
*
* |[<!-- language="C" -->
- * // Pressing Alt+H will activate this button
- * button = gtk_button_new (<!-- -->);
+ * /* Pressing Alt+H will activate this button */
+ * button = gtk_button_new ();
* label = gtk_label_new_with_mnemonic ("_Hello");
* gtk_container_add (GTK_CONTAINER (button), label);
* ]|
@@ -120,7 +116,7 @@
* already inside:
*
* |[<!-- language="C" -->
- * // Pressing Alt+H will activate this button
+ * /* Pressing Alt+H will activate this button */
* button = gtk_button_new_with_mnemonic ("_Hello");
* ]|
*
@@ -129,21 +125,19 @@
* gtk_label_set_mnemonic_widget():
*
* |[<!-- language="C" -->
- * // Pressing Alt+H will focus the entry
- * entry = gtk_entry_new (<!-- -->);
+ * /* Pressing Alt+H will focus the entry */
+ * entry = gtk_entry_new ();
* label = gtk_label_new_with_mnemonic ("_Hello");
* gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
* ]|
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Markup (styled text)</title>
- * <para>
- * To make it easy to format text in a label (changing colors, fonts,
- * etc.), label text can be provided in a simple <link
+ *
+ * ## Markup (styled text)
+ *
+ * To make it easy to format text in a label (changing colors,
+ * fonts, etc.), label text can be provided in a simple <link
* linkend="PangoMarkupFormat">markup format</link>.
- * Here's how to create a label with a small font:
*
+ * Here's how to create a label with a small font:
* |[<!-- language="C" -->
* label = gtk_label_new (NULL);
* gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
@@ -167,18 +161,16 @@
* to [0, %G_MAXINT)). The reason is that specifying the start_index and
* end_index for a #PangoAttribute requires knowledge of the exact string
* being displayed, so translations will cause problems.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Selectable labels</title>
+ *
+ * ## Selectable labels
+ *
* Labels can be made selectable with gtk_label_set_selectable().
* Selectable labels allow the user to copy the label contents to
* the clipboard. Only labels that contain useful-to-copy information
* — such as error messages — should be made selectable.
- * </refsect2>
- * <refsect2 id="label-text-layout">
- * <title>Text layout</title>
- * <para>
+ *
+ * ## Text layout
+ *
* A label can contain any number of paragraphs, but will have
* performance problems if it contains more than a small number.
* Paragraphs are separated by newlines or other paragraph separators
@@ -200,30 +192,25 @@
* is used as the natural width. Even if max-width-chars specified, wrapping
* labels will be rewrapped to use all of the available width.
*
- * <note><para>
* Note that the interpretation of #GtkLabel:width-chars and
* #GtkLabel:max-width-chars has changed a bit with the introduction of
* <link linkend="geometry-management">width-for-height geometry management.</link>
- * </para></note>
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Links</title>
- * <para>
+ *
+ * ## Links
+ *
* Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
* to regular Pango markup. The markup for links is borrowed from HTML, using the
* <tag>a</tag> with href and title attributes. GTK+ renders links similar to the
* way they appear in web browsers, with colored, underlined text. The title
- * attribute is displayed as a tooltip on the link. An example looks like this:
+ * attribute is displayed as a tooltip on the link.
*
+ * An example looks like this:
* |[<!-- language="C" -->
* gtk_label_set_markup (label, "Go to the <a href="http://www.gtk.org"; title="<i>Our</i>
website">GTK+ website</a> for more...");
* ]|
*
* It is possible to implement custom handling for links and their tooltips with
* the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
- * </para>
- * </refsect2>
*/
struct _GtkLabelPrivate
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 09891e7..5465eb1 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -46,15 +46,14 @@
* The #GtkListStore can accept most GObject types as a column type, though
* it can't accept all custom types. Internally, it will keep a copy of
* data passed in (such as a string or a boxed pointer). Columns that
- * accept #GObject<!-- -->s are handled a little differently. The
+ * accept #GObjects are handled a little differently. The
* #GtkListStore will keep a reference to the object instead of copying the
* value. As a result, if the object is modified, it is up to the
* application writer to call gtk_tree_model_row_changed() to emit the
* #GtkTreeModel::row_changed signal. This most commonly affects lists with
- * #GdkPixbuf<!-- -->s stored.
+ * #GdkPixbufs stored.
*
- * <example>
- * <title>Creating a simple list store.</title>
+ * An example for creating a simple list store:
* |[<!-- language="C" -->
* enum {
* COLUMN_STRING,
@@ -80,7 +79,7 @@
*
* some_data = get_some_data (i);
*
- * // Add a new row to the model
+ * /* Add a new row to the model */
* gtk_list_store_append (list_store, &iter);
* gtk_list_store_set (list_store, &iter,
* COLUMN_STRING, some_data,
@@ -88,13 +87,13 @@
* COLUMN_BOOLEAN, FALSE,
* -1);
*
- * /<!---->* As the store will keep a copy of the string internally, we
- * * free some_data.
- * *<!---->/
+ * /* As the store will keep a copy of the string internally,
+ * * we free some_data.
+ * */
* g_free (some_data);
* }
*
- * // Modify a particular row
+ * /* Modify a particular row */
* path = gtk_tree_path_new_from_string ("4");
* gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
* &iter,
@@ -105,20 +104,19 @@
* -1);
* }
* ]|
- * </example>
*
- * <refsect2>
- * <title>Performance Considerations</title>
- * Internally, the #GtkListStore was implemented with a linked list with a
- * tail pointer prior to GTK+ 2.6. As a result, it was fast at data
+ * ## Performance Considerations
+ *
+ * Internally, the #GtkListStore was implemented with a linked list with
+ * a tail pointer prior to GTK+ 2.6. As a result, it was fast at data
* insertion and deletion, and not fast at random data access. The
* #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means
* that #GtkTreeIter<!-- -->s can be cached while the row exists. Thus, if
* access to a particular row is needed often and your code is expected to
* run on older versions of GTK+, it is worth keeping the iter around.
- * </refsect2>
- * <refsect2>
- * <title>Atomic Operations</title>
+ *
+ * ## Atomic Operations
+ *
* It is important to note that only the methods
* gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv()
* are atomic, in the sense that the row is being appended to the store and the
@@ -133,10 +131,9 @@
* to append rows to the #GtkListStore will cause the
* #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the
* function must be prepared for that.
- * </refsect2>
- * <refsect2 id="GtkListStore-BUILDER-UI">
- * <title>GtkListStore as GtkBuildable</title>
- * <para>
+ *
+ * ## 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
@@ -155,8 +152,7 @@
* and common wisdom is to separate the two, as far as possible.
* <!-- FIXME a bit inconclusive -->
*
- * <example>
- * <title>A UI Definition fragment for a list store</title>
+ * An example of a UI Definition fragment for a list store:
* |[<!-- language="C" -->
* <object class="GtkListStore">
* <columns>
@@ -178,9 +174,6 @@
* </data>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 4740f40..6d365c1 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -64,22 +64,20 @@
* GtkMenuItem has direct functions to set the label and its mnemonic.
* For more advanced label settings, you can fetch the child widget from the GtkBin.
*
- * <example>
- * <title>Setting markup and accelerator on a MenuItem</title>
+ * An example for setting markup and accelerator on a MenuItem:
* |[<!-- language="C" -->
* GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item));
* gtk_label_set_markup (GTK_LABEL (child), "<i>new label</i> with <b>markup</b>");
* gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0);
* ]|
- * </example>
*
- * <refsect2 id="GtkMenuItem-BUILDER-UI">
- * <title>GtkMenuItem as GtkBuildable</title>
+ * ## GtkMenuItem as GtkBuildable
+ *
* The GtkMenuItem implementation of the #GtkBuildable interface
* supports adding a submenu by specifying "submenu" as the "type"
* attribute of a <child> element.
- * <example>
- * <title>A UI definition fragment with submenus</title>
+ *
+ * An example of UI definition fragment with submenus:
* |[
* <object class="GtkMenuItem">
* <child type="submenu">
@@ -87,8 +85,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </refsect2>
*/
diff --git a/gtk/gtkmenushell.c b/gtk/gtkmenushell.c
index 113bb4a..e1eb806 100644
--- a/gtk/gtkmenushell.c
+++ b/gtk/gtkmenushell.c
@@ -35,9 +35,8 @@
* user to perform application functions. A #GtkMenuItem can have a
* submenu associated with it, allowing for nested hierarchical menus.
*
- * <refsect2 id="GtkMenuShell-Terminology">
- * <title>Terminology</title>
- * <para>
+ * ## Terminology
+ *
* A menu item can be "selected", this means that it is displayed
* in the prelight state, and if it has a submenu, that submenu
* will be popped up.
@@ -55,8 +54,6 @@
* a selected menu item.) The current menu is the menu that
* contains the current menu item. It will always have a GTK
* grab and receive all key presses.
- * </para>
- * </refsect2>
*/
#include "config.h"
diff --git a/gtk/gtkmenutoolbutton.c b/gtk/gtkmenutoolbutton.c
index 7d9eae4..6269a83 100644
--- a/gtk/gtkmenutoolbutton.c
+++ b/gtk/gtkmenutoolbutton.c
@@ -48,15 +48,13 @@
* Use gtk_menu_tool_button_new() to create a new
* #GtkMenuToolButton.
*
- * <refsect2 id="GtkMenuToolButton-BUILDER-UI">
- * <title>GtkMenuToolButton as GtkBuildable</title>
- * <para>
+ * ## GtkMenuToolButton as GtkBuildable
+ *
* The GtkMenuToolButton implementation of the GtkBuildable interface
* supports adding a menu by specifying "menu" as the "type"
* attribute of a <child> element.
*
- * <example>
- * <title>A UI definition fragment with menus</title>
+ * An example for a UI definition fragment with menus:
* |[
* <object class="GtkMenuToolButton">
* <child type="menu">
@@ -64,9 +62,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 5fe1724..2c96334 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -57,28 +57,28 @@
* you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
* makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
* returns when any dialog button is clicked.
- * <example>
- * <title>A modal dialog.</title>
+ *
+ * An example for using a modal dialog:
* |[<!-- language="C" -->
* dialog = gtk_message_dialog_new (main_application_window,
* GTK_DIALOG_DESTROY_WITH_PARENT,
* GTK_MESSAGE_ERROR,
* GTK_BUTTONS_CLOSE,
- * "Error loading file '%s': %s",
+ * "Error loading file '%s': %s",
* filename, g_strerror (errno));
* gtk_dialog_run (GTK_DIALOG (dialog));
* gtk_widget_destroy (dialog);
* ]|
- * </example>
+ *
* You might do a non-modal #GtkMessageDialog as follows:
- * <example>
- * <title>A non-modal dialog.</title>
+ *
+ * An example for a non-modal dialog:
* |[<!-- language="C" -->
* dialog = gtk_message_dialog_new (main_application_window,
* GTK_DIALOG_DESTROY_WITH_PARENT,
* GTK_MESSAGE_ERROR,
* GTK_BUTTONS_CLOSE,
- * "Error loading file '%s': %s",
+ * "Error loading file '%s': %s",
* filename, g_strerror (errno));
*
* /* Destroy the dialog when the user responds to it (e.g. clicks a button) */
@@ -86,15 +86,11 @@
* G_CALLBACK (gtk_widget_destroy),
* dialog);
* ]|
- * </example>
*
- * <refsect2 id="GtkMessageDialog-BUILDER-UI">
- * <title>GtkMessageDialog as GtkBuildable</title>
- * <para>
+ * ## GtkMessageDialog as GtkBuildable
+ *
* The GtkMessageDialog implementation of the GtkBuildable interface exposes
* the message area as an internal child with the name "message_area".
- * </para>
- * </refsect2>
*/
struct _GtkMessageDialogPrivate
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 8e431a4..1092ab0 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -64,9 +64,8 @@
* will be a popup menu allowing the users to switch pages.
* (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable())
*
- * <refsect2 id="GtkNotebook-BUILDER-UI">
- * <title>GtkNotebook as GtkBuildable</title>
- * <para>
+ * ## GtkNotebook as GtkBuildable
+ *
* The GtkNotebook implementation of the #GtkBuildable interface
* supports placing children into tabs by specifying "tab" as the
* "type" attribute of a <child> element. Note that the content
@@ -77,9 +76,8 @@
* To add a child widget in the notebooks action area, specify
* "action-start" or "action-end" as the "type" attribute of the <child>
* element.
- * </para>
- * <example>
- * <title>A UI definition fragment with GtkNotebook</title>
+ *
+ * An example of a UI definition fragment with GtkNotebook:
* |[
* <object class="GtkNotebook">
* <child>
@@ -94,8 +92,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </refsect2>
*/
diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c
index 3fae8a1..4205153 100644
--- a/gtk/gtkoverlay.c
+++ b/gtk/gtkoverlay.c
@@ -46,14 +46,11 @@
* More complicated placement of overlays is possible by connecting
* to the #GtkOverlay::get-child-position signal.
*
- * <refsect2 id="GtkOverlay-BUILDER-UI">
- * <title>GtkOverlay as GtkBuildable</title>
- * <para>
+ * ## GtkOverlay as GtkBuildable
+ *
* The GtkOverlay implementation of the GtkBuildable interface
* supports placing a child as an overlay by specifying "overlay" as
* the "type" attribute of a <tag class="starttag">child</tag> element.
- * </para>
- * </refsect2>
*/
struct _GtkOverlayPrivate
diff --git a/gtk/gtkprintunixdialog.c b/gtk/gtkprintunixdialog.c
index 4891cd4..a9b115c 100644
--- a/gtk/gtkprintunixdialog.c
+++ b/gtk/gtkprintunixdialog.c
@@ -76,30 +76,18 @@
* gtk_print_job_new().
*
* #GtkPrintUnixDialog uses the following response values:
- * <variablelist>
- * <varlistentry><term>%GTK_RESPONSE_OK</term>
- * <listitem><para>for the "Print" button</para></listitem>
- * </varlistentry>
- * <varlistentry><term>%GTK_RESPONSE_APPLY</term>
- * <listitem><para>for the "Preview" button</para></listitem>
- * </varlistentry>
- * <varlistentry><term>%GTK_RESPONSE_CANCEL</term>
- * <listitem><para>for the "Cancel" button</para></listitem>
- * </varlistentry>
- * </variablelist>
- *
- * <!-- FIXME example here -->
+ * - %GTK_RESPONSE_OK: for the "Print" button
+ * - %GTK_RESPONSE_APPLY: for the "Preview" button
+ * - %GTK_RESPONSE_CANCEL: for the "Cancel" button
*
* Printing support was added in GTK+ 2.10.
*
- * <refsect2 id="GtkPrintUnixDialog-BUILDER-UI">
- * <title>GtkPrintUnixDialog as GtkBuildable</title>
- * <para>
+ * ## GtkPrintUnixDialog as GtkBuildable
+ *
* The GtkPrintUnixDialog implementation of the GtkBuildable interface exposes its
* @notebook internal children with the name "notebook".
*
- * <example>
- * <title>A #GtkPrintUnixDialog UI definition fragment.</title>
+ * An example of a #GtkPrintUnixDialog UI definition fragment:
* |[
* <object class="GtkPrintUnixDialog" id="dialog1">
* <child internal-child="notebook">
@@ -122,9 +110,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
diff --git a/gtk/gtkrecentfilter.c b/gtk/gtkrecentfilter.c
index a62b0fc..e5077eb 100644
--- a/gtk/gtkrecentfilter.c
+++ b/gtk/gtkrecentfilter.c
@@ -40,9 +40,8 @@
*
* Recently used files are supported since GTK+ 2.10.
*
- * <refsect2 id="GtkRecentFilter-BUILDER-UI">
- * <title>GtkRecentFilter as GtkBuildable</title>
- * <para>
+ * ## GtkRecentFilter as GtkBuildable
+ *
* The GtkRecentFilter implementation of the GtkBuildable interface
* supports adding rules using the <mime-types>, <patterns> and
* <applications> elements and listing the rules within. Specifying
@@ -50,8 +49,7 @@
* as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern()
* or gtk_recent_filter_add_application().
*
- * <example>
- * <title>A UI definition fragment specifying GtkRecentFilter rules</title>
+ * An example of a UI definition fragment specifying GtkRecentFilter rules:
* |[
* <object class="GtkRecentFilter">
* <mime-types>
@@ -69,9 +67,6 @@
* </applications>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
#include "config.h"
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 3f2c593..589b106 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -61,14 +61,14 @@
* applications that want to show an undeterminate value on the scale, without
* changing the layout of the application (such as movie or music players).
*
- * <refsect2 id="GtkScale-BUILDER-UI"><title>GtkScale as GtkBuildable</title>
+ * ## GtkScale as GtkBuildable
+ *
* GtkScale supports a custom <marks> element, which
* can contain multiple <mark> elements. The "value" and "position"
* attributes have the same meaning as gtk_scale_add_mark() parameters of the
* same name. If the element is not empty, its content is taken as the markup
* to show at the mark. It can be translated with the usual "translatable and
* "context" attributes.
- * </refsect2>
*/
diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c
index 3c7c76f..0ed52e7 100644
--- a/gtk/gtkscrollable.c
+++ b/gtk/gtkscrollable.c
@@ -26,44 +26,27 @@
* To implement this interface you should override the
* #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
*
- * <refsect2>
- * <title>Creating a scrollable widget</title>
- * <para>
+ * ## Creating a scrollable widget
+ *
* All scrollable widgets should do the following.
*
- * <orderedlist>
- * <listitem>
- * <para>
- * When a parent widget sets the scrollable child widget's adjustments, the widget should populate the
adjustments'
- * #GtkAdjustment:lower, #GtkAdjustment:upper,
- * #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
- * #GtkAdjustment:page-size properties and connect to the
- * #GtkAdjustment::value-changed signal.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * Because its preferred size is the size for a fully expanded widget,
- * the scrollable widget must be able to cope with underallocations.
- * This means that it must accept any value passed to its
- * #GtkWidgetClass.size_allocate() function.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * When the parent allocates space to the scrollable child widget, the widget should update
- * the adjustments' properties with new values.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * When any of the adjustments emits the #GtkAdjustment::value-changed signal,
- * the scrollable widget should scroll its contents.
- * </para>
- * </listitem>
- * </orderedlist>
- * </para>
- * </refsect2>
+ * - When a parent widget sets the scrollable child widget's adjustments,
+ * the widget should populate the adjustments'
+ * #GtkAdjustment:lower, #GtkAdjustment:upper,
+ * #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
+ * #GtkAdjustment:page-size properties and connect to the
+ * #GtkAdjustment::value-changed signal.
+ *
+ * - Because its preferred size is the size for a fully expanded widget,
+ * the scrollable widget must be able to cope with underallocations.
+ * This means that it must accept any value passed to its
+ * #GtkWidgetClass.size_allocate() function.
+ *
+ * - When the parent allocates space to the scrollable child widget,
+ * the widget should update the adjustments' properties with new values.
+ *
+ * - When any of the adjustments emits the #GtkAdjustment::value-changed signal,
+ * the scrollable widget should scroll its contents.
*/
#include "config.h"
diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c
index e98cfef..0d495fe 100644
--- a/gtk/gtksizegroup.c
+++ b/gtk/gtksizegroup.c
@@ -82,9 +82,8 @@
* by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well
* as widgets that grow (such as ellipsizing text) need no such considerations.
*
- * <refsect2 id="GtkSizeGroup-BUILDER-UI">
- * <title>GtkSizeGroup as GtkBuildable</title>
- * <para>
+ * ## GtkSizeGroup as GtkBuildable
+ *
* Size groups can be specified in a UI definition by placing an
* <object> element with <literal>class="GtkSizeGroup"</literal>
* somewhere in the UI definition. The widgets that belong to the
@@ -92,8 +91,7 @@
* contain multiple <widget> elements, one for each member
* of the size group. The name attribute gives the id of the widget.
*
- * <example>
- * <title>A UI definition fragment with GtkSizeGroup</title>
+ * An example of a UI definition fragment with GtkSizeGroup:
* |[
* <object class="GtkSizeGroup">
* <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
@@ -103,9 +101,6 @@
* </widgets>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 859a007..249a505 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -75,21 +75,18 @@
* #GtkSettings:gtk-theme-name setting or a hierarchy change in the rendered
* widget.
*
- * <refsect2 id="gtkstylecontext-animations">
- * <title>Transition animations</title>
- * <para>
+ * ## Transition animations
+ *
* #GtkStyleContext has built-in support for state change transitions.
* Note that these animations respect the #GtkSettings:gtk-enable-animations
* setting.
- * </para>
- * <para>
+ *
* For simple widgets where state changes affect the whole widget area,
* calling gtk_style_context_notify_state_change() with a %NULL region
* is sufficient to trigger the transition animation. And GTK+ already
* does that when gtk_widget_set_state() or gtk_widget_set_state_flags()
* are called.
- * </para>
- * <para>
+ *
* If a widget needs to declare several animatable regions (i.e. not
* affecting the whole widget area), its #GtkWidget::draw signal handler
* needs to wrap the render operations for the different regions with
@@ -98,9 +95,8 @@
* identifier for the region which must be unique within the style context.
* For simple widgets with a fixed set of animatable regions, using an
* enumeration works well:
- * </para>
- * <example>
- * <title>Using an enumeration to identify animatable regions</title>
+ *
+ * An example for Using an enumeration to identify animatable regions:
* |[<!-- language="C" -->
* enum {
* REGION_ENTRY,
@@ -129,15 +125,13 @@
* ...
* }
* ]|
- * </example>
- * <para>
+ *
* For complex widgets with an arbitrary number of animatable regions, it
* is up to the implementation to come up with a way to uniquely identify
* each animatable region. Using pointers to internal structs is one way
* to achieve this:
- * </para>
- * <example>
- * <title>Using struct pointers to identify animatable regions</title>
+ *
+ * An example for using struct pointers to identify animatable regions:
* |[<!-- language="C" -->
* void
* notebook_draw_tab (GtkWidget *widget,
@@ -149,13 +143,11 @@
* gtk_style_context_pop_animatable_region (context);
* }
* ]|
- * </example>
- * <para>
+ *
* The widget also needs to notify the style context about a state change
* for a given animatable region so the animation is triggered.
- * </para>
- * <example>
- * <title>Triggering a state change animation on a region</title>
+ *
+ * An example for triggering a state change animation on a region:
* |[<!-- language="C" -->
* gboolean
* notebook_motion_notify (GtkWidget *widget,
@@ -174,70 +166,17 @@
* ...
* }
* ]|
- * </example>
- * <para>
+ *
* gtk_style_context_notify_state_change() accepts %NULL region IDs as a
* special value, in this case, the whole widget area will be updated
* by the animation.
- * </para>
- * </refsect2>
- * <refsect2 id="gtkstylecontext-classes">
- * <title>Style classes and regions</title>
- * <para>
- * Widgets can add style classes to their context, which can be used
- * to associate different styles by class (see <xref linkend="gtkcssprovider-selectors"/>). Theme engines
can also use style classes to vary their
- * rendering. GTK+ has a number of predefined style classes:
- * #GTK_STYLE_CLASS_CELL,
- * #GTK_STYLE_CLASS_ENTRY,
- * #GTK_STYLE_CLASS_BUTTON,
- * #GTK_STYLE_CLASS_COMBOBOX_ENTRY,
- * #GTK_STYLE_CLASS_CALENDAR,
- * #GTK_STYLE_CLASS_SLIDER,
- * #GTK_STYLE_CLASS_BACKGROUND,
- * #GTK_STYLE_CLASS_RUBBERBAND,
- * #GTK_STYLE_CLASS_TOOLTIP,
- * #GTK_STYLE_CLASS_MENU,
- * #GTK_STYLE_CLASS_MENUBAR,
- * #GTK_STYLE_CLASS_MENUITEM,
- * #GTK_STYLE_CLASS_TOOLBAR,
- * #GTK_STYLE_CLASS_PRIMARY_TOOLBAR,
- * #GTK_STYLE_CLASS_INLINE_TOOLBAR,
- * #GTK_STYLE_CLASS_RADIO,
- * #GTK_STYLE_CLASS_CHECK,
- * #GTK_STYLE_CLASS_TROUGH,
- * #GTK_STYLE_CLASS_SCROLLBAR,
- * #GTK_STYLE_CLASS_SCALE,
- * #GTK_STYLE_CLASS_SCALE_HAS_MARKS_ABOVE,
- * #GTK_STYLE_CLASS_SCALE_HAS_MARKS_BELOW,
- * #GTK_STYLE_CLASS_HEADER,
- * #GTK_STYLE_CLASS_ACCELERATOR,
- * #GTK_STYLE_CLASS_GRIP,
- * #GTK_STYLE_CLASS_DOCK,
- * #GTK_STYLE_CLASS_PROGRESSBAR,
- * #GTK_STYLE_CLASS_SPINNER,
- * #GTK_STYLE_CLASS_EXPANDER,
- * #GTK_STYLE_CLASS_SPINBUTTON,
- * #GTK_STYLE_CLASS_NOTEBOOK,
- * #GTK_STYLE_CLASS_VIEW,
- * #GTK_STYLE_CLASS_SIDEBAR,
- * #GTK_STYLE_CLASS_IMAGE,
- * #GTK_STYLE_CLASS_HIGHLIGHT,
- * #GTK_STYLE_CLASS_FRAME,
- * #GTK_STYLE_CLASS_DND,
- * #GTK_STYLE_CLASS_PANE_SEPARATOR,
- * #GTK_STYLE_CLASS_SEPARATOR,
- * #GTK_STYLE_CLASS_INFO,
- * #GTK_STYLE_CLASS_WARNING,
- * #GTK_STYLE_CLASS_QUESTION,
- * #GTK_STYLE_CLASS_ERROR,
- * #GTK_STYLE_CLASS_HORIZONTAL,
- * #GTK_STYLE_CLASS_VERTICAL,
- * #GTK_STYLE_CLASS_TOP,
- * #GTK_STYLE_CLASS_BOTTOM,
- * #GTK_STYLE_CLASS_LEFT,
- * #GTK_STYLE_CLASS_RIGHT,
- * </para>
- * <para>
+ *
+ * ## Style classes and regions
+ *
+ * <para id="gtkstylecontext-classes">Widgets can add style classes to their context, which can be used
+ * to associate different styles by class (see <xref linkend="gtkcssprovider-selectors"/>).
+ * Theme engines can also use style classes to vary their rendering.</para>
+ *
* Widgets can also add regions with flags to their context.
* The regions used by GTK+ widgets are:
* <informaltable>
@@ -278,19 +217,16 @@
* </tbody>
* </tgroup>
* </informaltable>
- * </para>
- * </refsect2>
- * <refsect2 id="gtkstylecontext-custom-styling">
- * <title>Custom styling in UI libraries and applications</title>
- * <para>
+ *
+ * ## Custom styling in UI libraries and applications
+ *
* If you are developing a library with custom #GtkWidget<!-- -->s that
* render differently than standard components, you may need to add a
* #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK
* priority, either a #GtkCssProvider or a custom object implementing the
* #GtkStyleProvider interface. This way theming engines may still attempt
* to style your UI elements in a different way if needed so.
- * </para>
- * <para>
+ *
* If you are using custom styling on an applications, you probably want then
* to make your style information prevail to the theme's, so you must use
* a #GtkStyleProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
@@ -298,14 +234,11 @@
* <filename><replaceable>XDG_CONFIG_HOME</replaceable>/gtk-3.0/gtk.css</filename> will
* still take precedence over your changes, as it uses the
* %GTK_STYLE_PROVIDER_PRIORITY_USER priority.
- * </para>
- * <para>
+ *
* If a custom theming engine is needed, you probably want to implement a
* #GtkStyleProvider yourself so it points to your #GtkThemingEngine
* implementation, as #GtkCssProvider uses gtk_theming_engine_load()
* which loads the theming engine module from the standard paths.
- * </para>
- * </refsect2>
*/
/* When these change we do a full restyling. Otherwise we try to figure out
diff --git a/gtk/gtktexttagtable.c b/gtk/gtktexttagtable.c
index ee1907b..4032af0 100644
--- a/gtk/gtktexttagtable.c
+++ b/gtk/gtktexttagtable.c
@@ -44,15 +44,13 @@
* conceptual overview</link> which gives an overview of all the objects and
* data types related to the text widget and how they work together.
*
- * <refsect2 id="GtkTextTagTable-BUILDER-UI">
- * <title>GtkTextTagTables as GtkBuildable</title>
- * <para>
+ * ## GtkTextTagTables as GtkBuildable
+ *
* The GtkTextTagTable implementation of the GtkBuildable interface
* supports adding tags by specifying "tag" as the "type"
* attribute of a <child> element.
*
- * <example>
- * <title>A UI definition fragment specifying tags</title>
+ * An example of a UI definition fragment specifying tags:
* |[
* <object class="GtkTextTagTable">
* <child type="tag">
@@ -60,9 +58,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
struct _GtkTextTagTablePrivate
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index 6f25ca0..5f02731 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -41,14 +41,14 @@
* <link linkend="gtk3-GtkTreeView-drag-and-drop">drag and drop</link>
* interfaces.
*
- * <refsect2 id="GtkTreeStore-BUILDER-UI">
- * <title>GtkTreeStore as GtkBuildable</title>
+ * ## GtkTreeStore as GtkBuildable
+ *
* The GtkTreeStore 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" attribute specifies the data type for the column.
- * <example>
- * <title>A UI Definition fragment for a tree store</title>
+ *
+ * An example of a UI Definition fragment for a tree store:
* |[
* <object class="GtkTreeStore">
* <columns>
@@ -58,8 +58,6 @@
* </columns>
* </object>
* ]|
- * </example>
- * </refsect2>
*/
struct _GtkTreeStorePrivate
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 43956f1..6533308 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -78,30 +78,15 @@
* These are:
*
* <inlinegraphic fileref="tree-view-coordinates.png" format="PNG"></inlinegraphic>
- * <variablelist><title>Coordinate systems in GtkTreeView API</title>
- * <varlistentry><term>Widget coordinates</term>
- * <listitem>
- * <para>
- * Coordinates relative to the widget (usually <literal>widget->window</literal>).
- * </para>
- * </listitem>
- * </varlistentry>
- * <varlistentry><term>Bin window coordinates</term>
- * <listitem>
- * <para>
- * Coordinates relative to the window that GtkTreeView renders to.
- * </para>
- * </listitem>
- * </varlistentry>
- * <varlistentry><term>Tree coordinates</term>
- * <listitem>
- * <para>
- * Coordinates relative to the entire scrollable area of GtkTreeView. These
- * coordinates start at (0, 0) for row 0 of the tree.
- * </para>
- * </listitem>
- * </varlistentry>
- * </variablelist>
+ *
+ * Coordinate systems in GtkTreeView API:
+ *
+ * - Widget coordinates: Coordinates relative to the widget (usually <literal>widget->window</literal>).
+ *
+ * - Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to.
+ *
+ * - Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. These
+ * coordinates start at (0, 0) for row 0 of the tree.
*
* Several functions are available for converting between the different
* coordinate systems. The most common translations are between widget and bin
@@ -110,13 +95,13 @@
* (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords()
* (and vice versa).
*
- * <refsect2 id="GtkTreeView-BUILDER-UI">
- * <title>GtkTreeView as GtkBuildable</title>
+ * ## GtkTreeView as GtkBuildable
+ *
* The GtkTreeView implementation of the GtkBuildable interface accepts
* #GtkTreeViewColumn objects as <child> elements and exposes the
* internal #GtkTreeSelection in UI definitions.
- * <example>
- * <title>A UI definition fragment with GtkTreeView</title>
+ *
+ * An example of a UI definition fragment with GtkTreeView:
* |[
* <object class="GtkTreeView" id="treeview">
* <property name="model">liststore1</property>
@@ -138,8 +123,6 @@
* </child>
* </object>
* ]|
- * </example>
- * </refsect2>
*/
enum
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d4bb18b..b817dc7 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -77,26 +77,23 @@
* GtkWidget is the base class all widgets in GTK+ derive from. It manages the
* widget lifecycle, states and style.
*
- * <refsect2 id="geometry-management">
- * <title>Height-for-width Geometry Management</title>
- * <para>
- * GTK+ uses a height-for-width (and width-for-height) geometry management
+ * ## Height-for-width Geometry Management
+ *
+ * <para id="geometry-management">GTK+ uses a height-for-width (and width-for-height) geometry management
* system. Height-for-width means that a widget can change how much
* vertical space it needs, depending on the amount of horizontal space
* that it is given (and similar for width-for-height). The most common
* example is a label that reflows to fill up the available width, wraps
- * to fewer lines, and therefore needs less height.
+ * to fewer lines, and therefore needs less height.</para>
*
* Height-for-width geometry management is implemented in GTK+ by way
* of five virtual methods:
- * <itemizedlist>
- * <listitem>#GtkWidgetClass.get_request_mode()</listitem>
- * <listitem>#GtkWidgetClass.get_preferred_width()</listitem>
- * <listitem>#GtkWidgetClass.get_preferred_height()</listitem>
- * <listitem>#GtkWidgetClass.get_preferred_height_for_width()</listitem>
- * <listitem>#GtkWidgetClass.get_preferred_width_for_height()</listitem>
- * <listitem>#GtkWidgetClass.get_preferred_height_and_baseline_for_width()</listitem>
- * </itemizedlist>
+ * - #GtkWidgetClass.get_request_mode()
+ * - #GtkWidgetClass.get_preferred_width()
+ * - #GtkWidgetClass.get_preferred_height()
+ * - #GtkWidgetClass.get_preferred_height_for_width()
+ * - #GtkWidgetClass.get_preferred_width_for_height()
+ * - #GtkWidgetClass.get_preferred_height_and_baseline_for_width()
*
* There are some important things to keep in mind when implementing
* height-for-width and when using it in container implementations.
@@ -177,7 +174,6 @@
*
* And in #GtkWidgetClass.get_preferred_width_for_height() it will simply return
* the minimum and natural width:
- *
* |[<!-- language="C" -->
* static void
* foo_widget_get_preferred_width_for_height (GtkWidget *widget, gint for_height,
@@ -201,13 +197,10 @@
* compute width. Or when deciding how to use an allocation, the widget
* may need to know its natural size. In these cases, the widget should
* be careful to call its virtual methods directly, like this:
- * <example>
- * <title>Widget calling its own size request method.</title>
- * |[<!-- language="C" -->
+ * |[<!-- language="C" -->
* GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget),
* &min, &natural);
- * ]|
- * </example>
+ * ]|
*
* It will not work to use the wrapper functions, such as
* gtk_widget_get_preferred_width() inside your own size request
@@ -243,11 +236,8 @@
* If this has a value other than -1 you need to align the widget such that the baseline
* appears at the position.
*
- * </para>
- * </refsect2>
- * <refsect2 id="style-properties">
- * <title>Style Properties</title>
- * <para>
+ * ## Style Properties
+ *
* #GtkWidget introduces <firstterm>style
* properties</firstterm> - these are basically object properties that are stored
* not on the object, but in the style object associated to the widget. Style
@@ -255,38 +245,32 @@
* This mechanism is used for configuring such things as the location of the
* scrollbar arrows through the theme, giving theme authors more control over the
* look of applications without the need to write a theme engine in C.
- * </para>
- * <para>
+ *
* Use gtk_widget_class_install_style_property() to install style properties for
* a widget class, gtk_widget_class_find_style_property() or
* gtk_widget_class_list_style_properties() to get information about existing
* style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or
* gtk_widget_style_get_valist() to obtain the value of a style property.
- * </para>
- * </refsect2>
- * <refsect2 id="GtkWidget-BUILDER-UI">
- * <title>GtkWidget as GtkBuildable</title>
- * <para>
+ *
+ * ## GtkWidget as GtkBuildable
+ *
* The GtkWidget implementation of the GtkBuildable interface supports a
* custom <accelerator> element, which has attributes named key,
* modifiers and signal and allows to specify accelerators.
- * </para>
- * <example>
- * <title>A UI definition fragment specifying an accelerator</title>
+ *
+ * An example of a UI definition fragment specifying an accelerator:
* |[
* <object class="GtkButton">
* <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/>
* </object>
* ]|
- * </example>
- * <para>
+ *
* In addition to accelerators, #GtkWidget also support a
* custom <accessible> element, which supports actions and relations.
* Properties on the accessible implementation of an object can be set by accessing the
* internal child "accessible" of a #GtkWidget.
- * </para>
- * <example>
- * <title>A UI definition fragment specifying an accessible</title>
+ *
+ * An example of a UI definition fragment specifying an accessible:
* |[
* <object class="GtkButton" id="label1"/>
* <property name="label">I am a Label for a Button</property>
@@ -303,12 +287,9 @@
* </child>
* </object>
* ]|
- * </example>
- * <para>
+ *
* Finally, GtkWidget allows style information such as style classes to
* be associated with widgets, using the custom <style> element:
- * <example>
- * <title>A UI definition fragment specifying an style class</title>
* |[
* <object class="GtkButton" id="button1">
* <style>
@@ -317,26 +298,20 @@
* </style>
* </object>
* ]|
- * </example>
- * </para>
- * </refsect2>
- * <refsect2 id="GtkWidget-BUILDER-TEMPLATES">
- * <title>Building composite widgets from template XML</title>
- * <para>
+ *
+ * ## Building composite widgets from template XML
+ *
* GtkWidget exposes some facilities to automate the proceedure
* of creating composite widgets using #GtkBuilder interface description
* language.
- * </para>
- * <para>
+ *
* To create composite widgets with #GtkBuilder XML, one must associate
* the interface description with the widget class at class initialization
* time using gtk_widget_class_set_template().
- * </para>
- * <para>
+ *
* The interface description semantics expected in composite template descriptions
* is slightly different from regulare #GtkBuilder XML.
- * </para>
- * <para>
+ *
* Unlike regular interface descriptions, gtk_widget_class_set_template() will expect a
* <template> tag as a direct child of the toplevel <interface>
* tag. The <template> tag must specify the "class" attribute which
@@ -345,23 +320,19 @@
* is ignored by the GtkBuilder but required for Glade to introspect what kind
* of properties and internal children exist for a given type when the actual
* type does not exist.
- * </para>
- * <para>
+ *
* The XML which is contained inside the <template> tag behaves as if
* it were added to the <object> tag defining @widget itself. You may set
* properties on @widget by inserting <property> tags into the <template>
* tag, and also add <child> tags to add children and extend @widget in the
* normal way you would with <object> tags.
- * </para>
- * <para>
+ *
* Additionally, <object> tags can also be added before and
* after the initial <template> tag in the normal way, allowing
* one to define auxilary objects which might be referenced by other
* widgets declared as children of the <template> tag.
- * </para>
- * <para>
- * <example>
- * <title>A GtkBuilder Template Definition</title>
+ *
+ * An example of a GtkBuilder Template Definition:
* |[
* <interface>
* <template class="FooWidget" parent="GtkBox">
@@ -380,9 +351,6 @@
* </template>
* </interface>
* ]|
- * </example>
- * </para>
- * </refsect2>
*/
#define GTK_STATE_FLAGS_DO_PROPAGATE (GTK_STATE_FLAG_INSENSITIVE|GTK_STATE_FLAG_BACKDROP)
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index dd756de..132617a 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -89,35 +89,30 @@
* control whether a window has a resize grip, use
* gtk_window_set_has_resize_grip().
*
- * <refsect2 id="GtkWindow-BUILDER-UI">
- * <title>GtkWindow as GtkBuildable</title>
- * <para>
+ * ## GtkWindow as GtkBuildable
+ *
* The GtkWindow implementation of the GtkBuildable interface supports a
* custom <tag class="starttag">accel-groups</tag> element, which supports
* any number of <tag class="starttag">group</tag> elements representing the
* #GtkAccelGroup objects you want to add to your window (synonymous with
* gtk_window_add_accel_group().
- * </para>
- * <example>
- * <title>A UI definition fragment with accel groups</title>
+ *
+ * An example of a UI definition fragment with accel groups:
* |[
* <object class="GtkWindow">
* <accel-groups>
* <group name="accelgroup1"/>
* </accel-groups>
* </object>
- * <!-- -->
+ *
* ...
- * <!-- -->
+ *
* <object class="GtkAccelGroup" id="accelgroup1"/>
* ]|
- * </example>
- * <para>
+ *
* The GtkWindow implementation of the GtkBuildable interface
* supports setting a child as the titlebar by specifying "titlebar" as
* the "type" attribute of a <tag class="starttag">child</tag> element.
- * </para>
- * </refsect2>
*/
#define MNEMONICS_DELAY 300 /* ms */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
