AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-10 10:50:10 +00:00
Code Issues Projects Releases Wiki Activity

docs: Convert to markdown

Browse Source 
Specifically, switch to using markdown syntax for sections.
This commit is contained in:
Matthias Clasen 2014-02-02 00:29:00 -05:00
parent 16e38946bd
commit 09d1b28249
36 changed files with 648 additions and 1064 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
gdk/gdkwindow.c
View File

@ -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.
* 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.
* ## Composited Windows
*
* 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.
* <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>
*
* For rendering an offscreen window onto its embedder, the contents of the
* offscreen window are available as a surface, via
* ## 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>
*/

84
gtk/gtkaccelmap.c
View File

@ -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
*
* In order to avoid having some accelerators changed, they can be locked using
* gtk_accel_map_lock_path(). Unlocking is done using
* 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
* 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.
*/

36
gtk/gtkassistant.c
View File

@ -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"

40
gtk/gtkbindings.c
View File

@ -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 --- */

227
gtk/gtkbuilder.c
View File

@ -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.
* &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().
* 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.
* 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.
* 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.
* 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
*
* 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>
* |[
* <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"

76
gtk/gtkcellarea.c
View File

@ -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"

50
gtk/gtkcelllayout.c
View File

@ -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.
* 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
*
* <refsect2 id="GtkCellLayout-BUILDER-UI">
* <title>GtkCellLayouts as GtkBuildable</title>
* <para>
* 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 &lt;cell-packing&gt; attribute which
* can contain multiple &lt;property&gt; 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
* &lt;cell-packing&gt; attribute which can contain multiple
* &lt;property&gt; 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"

11
gtk/gtkcomboboxtext.c
View File

@ -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 &lt;items&gt; element
* and specifying &lt;item&gt; elements for each item. Each &lt;item&gt;
@ -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);

31
gtk/gtkcontainer.c
View File

@ -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 &lt;packing&gt; element for children, which can
* contain multiple &lt;property&gt; 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>
*/

304
gtk/gtkcssprovider.c
View File

@ -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
* '&num;' 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&num;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:
* |[
* /&ast; Theme labels that are descendants of a window &ast;/
* 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:
* |[
* /&ast; Theme all widgets defining the class entry &ast;/
* .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:
* |[
* /&ast; Theme any label within a notebook &ast;/
* 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:
* |[
* /&ast; Theme active (pressed) buttons &ast;/
* 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>&commat; Rules</title>
* <para>
*
* ## &commat; Rules
*
* GTK+'s CSS supports the &commat;import rule, in order to load another
* CSS style sheet in addition to the currently parsed one.
* </para>
* <example>
* <title>Using the &commat;import rule</title>
*
* An example for using the &commat;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 &commat;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 &commat;binding rule</title>
*
* An example for using the &commat;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 &commat;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(&commat;yellow), to(&commat;blue))</literallayout></para>
* </example>
* <example>
* <title>Another linear gradient</title>
* from(&commat;yellow), to(&commat;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, &commat;yellow),
* color-stop(0.2, &commat;blue),
* color-stop(1, &num;0f0))</literallayout></para>
* </example>
* <para>
* color-stop(1, &num;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(&commat;yellow), to(&commat;green))</literallayout></para>
* </example>
* <example>
* <title>Another radial gradient</title>
* from(&commat;yellow), to(&commat;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, &num;f00),
* color-stop (0.1, &num;a0f),
* color-stop (0.2, &commat;yellow),
* color-stop (1, &commat;green))</literallayout></para>
* </example>
* </refsect2>
* <refsect2 id="gtkcssprovider-shadows">
* <title>Text shadow</title>
* <para>
* color-stop (1, &commat;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;

23
gtk/gtkdialog.c
View File

@ -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" -->
* /&ast; Function to open a dialog box displaying the message provided. &ast;/
* 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 &lt;action-widgets&gt; element, which
* can contain multiple &lt;action-widget&gt; 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

22
gtk/gtkexpander.c
View File

@ -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 &lt;child&gt; element.
* A normal content child can be specified without specifying
* a &lt;child&gt; 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"

98
gtk/gtkfilechooser.c
View File

@ -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.
*/

18
gtk/gtkfilefilter.c
View File

@ -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 &lt;mime-types&gt;, &lt;patterns&gt; and
* &lt;applications&gt; elements and listing the rules within. Specifying
* a &lt;mime-type&gt; or &lt;pattern&gt; is the same
* supports adding rules using the &lt;mime-types&gt;, &lt;patterns&gt;
* and &lt;applications&gt; elements and listing the rules within.
* Specifying a &lt;mime-type&gt; or &lt;pattern&gt; 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"

11
gtk/gtkfontchooserdialog.c
View File

@ -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
*/

12
gtk/gtkframe.c
View File

@ -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 &lt;child&gt; element.
* A normal content child can be specified without specifying
* a &lt;child&gt; 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>
*/

14
gtk/gtkinfobar.c
View File

@ -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" -->
* /&ast; set up info bar &ast;/
* 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 &lt;action-widgets&gt; element, which
* can contain multiple &lt;action-widget&gt; 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

73
gtk/gtklabel.c
View File

@ -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 &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
* elements. the &lt;attribute&gt; 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 (<!-- -->);
* /&ast; Pressing Alt+H will activate this button &ast;/
* 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
* /&ast; Pressing Alt+H will activate this button &ast;/
* 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 (<!-- -->);
* /&ast; Pressing Alt+H will focus the entry &ast;/
* 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
* linkend="PangoMarkupFormat">markup format</link>.
* Here's how to create a label with a small font:
*
* ## 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:
* |[<!-- 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
* &mdash; such as error messages &mdash; 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="&lt;i&gt;Our&lt;/i&gt; 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

45
gtk/gtkliststore.c
View File

@ -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
* /&ast; Add a new row to the model &ast;/
* 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.
* *<!---->/
* /&ast; As the store will keep a copy of the string internally,
* &ast; we free some_data.
* &ast;/
* g_free (some_data);
* }
*
* // Modify a particular row
* /&ast; Modify a particular row &ast;/
* 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 &lt;columns&gt; element that may
* contain multiple &lt;column&gt; 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>
*/

14
gtk/gtkmenuitem.c
View File

@ -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 &lt;child&gt; 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>
*/

7
gtk/gtkmenushell.c
View File

@ -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"

11
gtk/gtkmenutoolbutton.c
View File

@ -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 &lt;child&gt; 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>
*/

22
gtk/gtkmessagedialog.c
View File

@ -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 '&percnt;s': &percnt;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 '&percnt;s': &percnt;s",
* "Error loading file '%s': %s",
* filename, g_strerror (errno));
*
* /&ast; Destroy the dialog when the user responds to it (e.g. clicks a button) &ast;/
@ -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

12
gtk/gtknotebook.c
View File

@ -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 &lt;child&gt; 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 &lt;child&gt;
* 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>
*/

7
gtk/gtkoverlay.c
View File

@ -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

27
gtk/gtkprintunixdialog.c
View File

@ -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>
*/

11
gtk/gtkrecentfilter.c
View File

@ -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 &lt;mime-types&gt;, &lt;patterns&gt; and
* &lt;applications&gt; 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"

4
gtk/gtkscale.c
View File

@ -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 &lt;marks&gt; element, which
* can contain multiple &lt;mark&gt; 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>
*/

55
gtk/gtkscrollable.c
View File

@ -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"

11
gtk/gtksizegroup.c
View File

@ -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
* &lt;object&gt; element with <literal>class="GtkSizeGroup"</literal>
* somewhere in the UI definition. The widgets that belong to the
@ -92,8 +91,7 @@
* contain multiple &lt;widget&gt; 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>
*/

117
gtk/gtkstylecontext.c
View File

@ -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

11
gtk/gtktexttagtable.c
View File

@ -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 &lt;child&gt; 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

10
gtk/gtktreestore.c
View File

@ -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 &lt;columns&gt; element that may
* contain multiple &lt;column&gt; 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

43
gtk/gtktreeview.c
View File

@ -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 &lt;child&gt; 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

100
gtk/gtkwidget.c
View File

@ -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)-&gt;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 &lt;accelerator&gt; 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 &lt;accessible&gt; 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 &lt;style&gt; 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
* &lt;template&gt; tag as a direct child of the toplevel &lt;interface&gt;
* tag. The &lt;template&gt; 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 &lt;template&gt; tag behaves as if
* it were added to the &lt;object&gt; tag defining @widget itself. You may set
* properties on @widget by inserting &lt;property&gt; tags into the &lt;template&gt;
* tag, and also add &lt;child&gt; tags to add children and extend @widget in the
* normal way you would with &lt;object&gt; tags.
* </para>
* <para>
*
* Additionally, &lt;object&gt; tags can also be added before and
* after the initial &lt;template&gt; tag in the normal way, allowing
* one to define auxilary objects which might be referenced by other
* widgets declared as children of the &lt;template&gt; 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)

19
gtk/gtkwindow.c
View File

@ -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 */