Commit 09d1b282 authored by Matthias Clasen's avatar Matthias Clasen

docs: Convert to markdown

Specifically, switch to using markdown syntax for sections.
parent 16e38946
......@@ -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>
*/
......
......@@ -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
* "&lt;WINDOWTYPE&gt;/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:
* "&lt;Gimp-Toolbox&gt;/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: "&lt;Gimp-Toolbox&gt;/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.
*/
......
......@@ -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
* &lt;child&gt; 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"
......
......@@ -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>&lt;gdk/gdkkeysyms.h&gt;</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
* "&lt;Control&gt;Right" or "&lt;Control&gt;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 --- */
......
......@@ -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 &lt;interface&gt;. 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
* &lt;object&gt; elements, which can contain &lt;property&gt; elements to set
* properties, &lt;signal&gt; elements which connect signals to handlers, and
* &lt;child&gt; 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 &lt;child&gt; element contains an &lt;object&gt; element which
* describes the child object. The target toolkit version(s) are described by
* &lt;requires&gt; 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
* "&lt;major&gt;.&lt;minor&gt;". The builder will error out if the version
* requirements are not met.
* The toplevel element is &lt;interface&gt;. 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 &lt;object&gt; elements, which can contain
* &lt;property&gt; elements to set properties, &lt;signal&gt; elements
* which connect signals to handlers, and &lt;child&gt; 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 &lt;child&gt; element contains an &lt;object&gt; element which
* describes the child object. The target toolkit version(s) are
* described by &lt;requires&gt; 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 "&lt;major&gt;.&lt;minor&gt;". The builder will error
* out if the version requirements are not met.
*
* Typically, the specific kind of object represented by an &lt;object&gt;
* 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
* &lt;property&gt; 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().
* &lt;property&gt; 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 &lt;signal&gt; 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 &lt;child&gt; element
* to a true value. Note that GtkBuilder still requires an &lt;object&gt;
* 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 &lt;child&gt;. 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 &lt;signal&gt; 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 &lt;child&gt; element to a true value. Note that
* GtkBuilder still requires an &lt;object&gt; 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 &lt;child&gt;.
* 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 &lt;child&gt; element gets parsed by the custom tag
* handler of the parent object, while a custom element in an &lt;object&gt;
* 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 &lt;template&gt; 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 &lt;child&gt; element gets
* parsed by the custom tag handler of the parent object, while a custom
* element in an &lt;object&gt; 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 &lt;template&gt; tag has been
* added to the format allowing one to define a widget class's components.
*/
#include "config.h"
......
......@@ -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"
......
......@@ -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>