diff options
36 files changed, 658 insertions, 1074 deletions
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index 897f09787e..f5c4f421ac 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 f6baf08505..b7645331f8 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 80cb1993d1..e0b3fe5472 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 5dcc968bcb..53cb489854 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 f53f2103fc..e3b1fb4656 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 ae19c18020..8ae91ebc75 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 1bd5070f48..777a32cd38 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 80325b64c3..3fecdc9497 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 bd8d059210..805fbb2a20 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 cfccb9e883..28484382ce 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 7c638189e8..51a5d94046 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 c8b15664a7..41c6979095 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 eee7976659..68aa4c4e18 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 fb4fc66bd7..cf57597e06 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 7400a5fba9..17c575e978 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 3e302c32a5..32b35a6c5a 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 5d6dee4f34..07fa6d4722 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 91e8b533ef..acff4b5263 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 09891e7cd5..5465eb1334 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 4740f40ee5..6d365c161d 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 113bb4acf0..e1eb806334 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 7d9eae47d2..6269a83a38 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 5fe172461f..2c96334955 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 8e431a4736..1092ab0d2b 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 3fae8a187d..4205153095 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 4891cd4f0b..a9b115c293 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 a62b0fc901..e5077eb93b 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 3f2c5932ef..589b106ee0 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 3c7c76fcc6..0ed52e785f 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 e98cfef43c..0d495fee8f 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 859a007c20..249a50575d 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 ee1907b832..4032af04c2 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 6f25ca0626..5f02731d82 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 43956f1f44..653330894a 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 d4bb18b2d4..b817dc7031 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 dd756deaf2..132617ae44 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 */ |