Commit a79626b7 authored by Carlos Garnacho's avatar Carlos Garnacho

Add theming docs

Both API and file format is documented, there's still missing
a migration doc though.
parent 59b0fa81
......@@ -22,6 +22,8 @@ CFILE_GLOB=$(top_srcdir)/gtk/*.c
# Header files to ignore when scanning
IGNORE_HFILES= \
fnmatch.h \
gtk9slice.h \
gtkanimationdescription.h \
gtkdebug.h \
gtkbuilderprivate.h \
gtkdndcursors.h \
......@@ -77,6 +79,7 @@ IGNORE_HFILES= \
gtktexttagprivate.h \
gtktexttypes.h \
gtktextutil.h \
gtktimeline.h \
gtkthemes.h \
gtktrayicon.h \
gtktreedatalist.h \
......
......@@ -51,6 +51,15 @@
<xi:include href="xml/filesystem.xml" />
</part>
<part id="theming">
<title>Theming in GTK+</title>
<xi:include href="xml/gtkwidgetpath.xml" />
<xi:include href="xml/gtkstyleprovider.xml" />
<xi:include href="xml/gtkstylecontext.xml" />
<xi:include href="xml/gtkcssprovider.xml" />
<xi:include href="xml/gtkthemingengine.xml" />
</part>
<part id="gtkobjects">
<title>GTK+ Widgets and Objects</title>
......
......@@ -881,6 +881,7 @@ gtk_container_set_resize_mode
gtk_container_check_resize
gtk_container_foreach
gtk_container_get_children
gtk_container_get_path_for_child
gtk_container_set_reallocate_redraws
gtk_container_get_focus_child
gtk_container_set_focus_child
......@@ -4950,6 +4951,11 @@ gtk_widget_get_mapped
gtk_widget_get_requisition
gtk_widget_device_is_shadowed
<SUBSECTION>
gtk_widget_get_path
gtk_widget_get_style_context
gtk_widget_reset_style
<SUBSECTION>
gtk_requisition_new
gtk_requisition_copy
......@@ -5246,6 +5252,242 @@ GTK_INTERFACE_AGE
GTK_CHECK_VERSION
</SECTION>
<SECTION>
<FILE>gtkwidgetpath</FILE>
<TITLE>GtkWidgetPath</TITLE>
GtkWidgetPath
gtk_widget_path_append_type
gtk_widget_path_copy
gtk_widget_path_free
gtk_widget_path_get_widget_type
gtk_widget_path_has_parent
gtk_widget_path_is_type
gtk_widget_path_iter_add_class
gtk_widget_path_iter_add_region
gtk_widget_path_iter_clear_classes
gtk_widget_path_iter_clear_regions
gtk_widget_path_iter_get_name
gtk_widget_path_iter_get_widget_type
gtk_widget_path_iter_has_class
gtk_widget_path_iter_has_name
gtk_widget_path_iter_has_qclass
gtk_widget_path_iter_has_qname
gtk_widget_path_iter_has_qregion
gtk_widget_path_iter_has_region
gtk_widget_path_iter_list_classes
gtk_widget_path_iter_list_regions
gtk_widget_path_iter_remove_class
gtk_widget_path_iter_remove_region
gtk_widget_path_iter_set_name
gtk_widget_path_iter_set_widget_type
gtk_widget_path_length
gtk_widget_path_new
gtk_widget_path_prepend_type
</SECTION>
<SECTION>
<FILE>gtkstyleprovider</FILE>
<TITLE>GtkStyleProvider</TITLE>
GtkStyleProviderIface
GtkStyleProvider
GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
GTK_STYLE_PROVIDER_PRIORITY_DEFAULT
GTK_STYLE_PROVIDER_PRIORITY_FALLBACK
GTK_STYLE_PROVIDER_PRIORITY_SETTINGS
GTK_STYLE_PROVIDER_PRIORITY_USER
gtk_style_provider_get_icon_factory
gtk_style_provider_get_style
gtk_style_provider_get_style_property
<SUBSECTION Standard>
GTK_TYPE_STYLE_PROVIDER
GTK_STYLE_PROVIDER
GTK_IS_STYLE_PROVIDER
GTK_STYLE_PROVIDER_GET_IFACE
<SUBSECTION Private>
gtk_style_provider_get_type
</SECTION>
<SECTION>
<FILE>gtksymboliccolor</FILE>
<TITLE>GtkSymbolicColor</TITLE>
GtkSymbolicColor
GtkGradient
gtk_symbolic_color_new_literal
gtk_symbolic_color_new_mix
gtk_symbolic_color_new_name
gtk_symbolic_color_new_shade
gtk_symbolic_color_resolve
gtk_symbolic_color_ref
gtk_symbolic_color_unref
gtk_gradient_new_linear
gtk_gradient_new_radial
gtk_gradient_add_color_stop
gtk_gradient_resolve
gtk_gradient_ref
gtk_gradient_unref
<SUBSECTION Standard>
GTK_TYPE_GRADIENT
GTK_TYPE_SYMBOLIC_COLOR
<SUBSECTION Private>
gtk_symbolic_color_get_type
gtk_gradient_get_type
</SECTION>
<SECTION>
<FILE>gtkstyleset</FILE>
<TITLE>GtkStyleSet</TITLE>
GtkStyleSet
gtk_style_set_clear
gtk_style_set_get
gtk_style_set_get_property
gtk_style_set_get_valist
gtk_style_set_lookup_color
gtk_style_set_lookup_property
gtk_style_set_map_color
gtk_style_set_merge
gtk_style_set_new
gtk_style_set_register_property
gtk_style_set_set
gtk_style_set_set_property
gtk_style_set_set_valist
gtk_style_set_unset_property
<SUBSECTION Standard>
GTK_TYPE_STYLE_SET
GTK_IS_STYLE_SET
GTK_IS_STYLE_SET_CLASS
GTK_STYLE_SET
GTK_STYLE_SET_CLASS
GTK_STYLE_SET_GET_CLASS
<SUBSECTION Private>
gtk_style_set_get_type
</SECTION>
<SECTION>
<FILE>gtkstylecontext</FILE>
<TITLE>GtkStyleContext</TITLE>
GtkStyleContext
gtk_style_context_add_provider
gtk_style_context_add_provider_for_screen
gtk_style_context_get
gtk_style_context_get_direction
gtk_style_context_get_junction_sides
gtk_style_context_get_path
gtk_style_context_get_property
gtk_style_context_get_screen
gtk_style_context_get_state
gtk_style_context_get_style
gtk_style_context_get_style_property
gtk_style_context_get_style_valist
gtk_style_context_get_valist
gtk_style_context_has_class
gtk_style_context_has_region
gtk_style_context_invalidate
gtk_style_context_is_state_set
gtk_style_context_list_classes
gtk_style_context_list_regions
gtk_style_context_lookup_color
gtk_style_context_lookup_icon_set
gtk_style_context_notify_state_change
gtk_style_context_pop_animatable_region
gtk_style_context_push_animatable_region
gtk_style_context_remove_provider
gtk_style_context_remove_provider_for_screen
gtk_style_context_reset_widgets
gtk_style_context_restore
gtk_style_context_save
gtk_style_context_set_class
gtk_style_context_set_direction
gtk_style_context_set_junction_sides
gtk_style_context_set_path
gtk_style_context_set_region
gtk_style_context_set_screen
gtk_style_context_set_state
gtk_style_context_state_transition_start
gtk_style_context_state_transition_stop
gtk_style_context_state_transition_update
gtk_style_context_unset_class
gtk_style_context_unset_region
<SUBSECTION>
gtk_render_arrow
gtk_render_background
gtk_render_check
gtk_render_expander
gtk_render_extension
gtk_render_focus
gtk_render_frame
gtk_render_frame_gap
gtk_render_handle
gtk_render_layout
gtk_render_line
gtk_render_option
gtk_render_progress
gtk_render_slider
<SUBSECTION Standard>
GTK_TYPE_STYLE_CONTEXT
GTK_STYLE_CONTEXT
GTK_STYLE_CONTEXT_CLASS
GTK_STYLE_CONTEXT_GET_CLASS
GTK_IS_STYLE_CONTEXT
GTK_IS_STYLE_CONTEXT_CLASS
<SUBSECTION Private>
gtk_style_context_get_type
</SECTION>
<SECTION>
<FILE>gtkcssprovider</FILE>
<TITLE>GtkCssProvider</TITLE>
GtkCssProvider
gtk_css_provider_get_default
gtk_css_provider_get_named
gtk_css_provider_load_from_data
gtk_css_provider_load_from_file
gtk_css_provider_load_from_path
gtk_css_provider_new
<SUBSECTION Standard>
GTK_TYPE_CSS_PROVIDER
GTK_CSS_PROVIDER
GTK_CSS_PROVIDER_CLASS
GTK_CSS_PROVIDER_GET_CLASS
GTK_IS_CSS_PROVIDER
GTK_IS_CSS_PROVIDER_CLASS
<SUBSECTION Private>
gtk_css_provider_get_type
</SECTION>
<SECTION>
<FILE>gtkthemingengine</FILE>
<TITLE>GtkThemingEngine</TITLE>
GtkThemingEngineClass
GtkThemingEngine
gtk_theming_engine_get
gtk_theming_engine_get_direction
gtk_theming_engine_get_junction_sides
gtk_theming_engine_get_path
gtk_theming_engine_get_property
gtk_theming_engine_get_screen
gtk_theming_engine_get_state
gtk_theming_engine_get_style
gtk_theming_engine_get_style_property
gtk_theming_engine_get_style_valist
gtk_theming_engine_get_valist
gtk_theming_engine_has_class
gtk_theming_engine_has_region
gtk_theming_engine_is_state_set
gtk_theming_engine_load
gtk_theming_engine_register_property
<SUBSECTION Standard>
GTK_THEMING_ENGINE
GTK_THEMING_ENGINE_CLASS
GTK_THEMING_ENGINE_GET_CLASS
GTK_IS_THEMING_ENGINE
GTK_IS_THEMING_ENGINE_CLASS
<SUBSECTION Private>
GTK_TYPE_THEMING_ENGINE
gtk_theming_engine_get_type
</SECTION>
<SECTION>
<FILE>gtkstyle</FILE>
<TITLE>GtkStyle</TITLE>
......
......@@ -47,6 +47,7 @@ gtk_color_selection_get_type
gtk_combo_box_get_type
gtk_combo_box_text_get_type
gtk_container_get_type
gtk_css_provider_get_type
gtk_dialog_get_type
gtk_drawing_area_get_type
gtk_editable_get_type
......@@ -141,6 +142,8 @@ gtk_statusbar_get_type
gtk_status_icon_get_type
gtk_switch_get_type
gtk_style_get_type
gtk_style_context_get_type
gtk_style_provider_get_type
gtk_table_get_type
gtk_tearoff_menu_item_get_type
gtk_text_buffer_get_type
......@@ -150,6 +153,7 @@ gtk_text_mark_get_type
gtk_text_tag_get_type
gtk_text_tag_table_get_type
gtk_text_view_get_type
gtk_theming_engine_get_type
gtk_toggle_action_get_type
gtk_toggle_button_get_type
gtk_toggle_tool_button_get_type
......
......@@ -180,6 +180,7 @@
#include <gtk/gtkstyleset.h>
#include <gtk/gtkstyle.h>
#include <gtk/gtkswitch.h>
#include <gtk/gtksymboliccolor.h>
#include <gtk/gtktable.h>
#include <gtk/gtktearoffmenuitem.h>
#include <gtk/gtktextbuffer.h>
......
......@@ -44,4 +44,4 @@ GtkAnimationDescription * gtk_animation_description_from_string (const gchar *st
G_END_DECLS
#endif /* __GTK_ANIMATION_DESC_H__ */
#endif /* __GTK_ANIMATION_DESCRIPTION_H__ */
......@@ -3232,6 +3232,16 @@ _gtk_container_get_reallocate_redraws (GtkContainer *container)
return container->priv->reallocate_redraws;
}
/**
* gtk_container_get_path_for_child:
* @container: a #GtkContainer
* @child: a child of @container
*
* Returns a newly created widget path representing all the widget hierarchy
* from the toplevel down to @child (this one not being included).
*
* Returns: A newly created #GtkWidgetPath
**/
GtkWidgetPath *
gtk_container_get_path_for_child (GtkContainer *container,
GtkWidget *child)
......
......@@ -30,6 +30,360 @@
#include "gtk9slice.h"
#include "gtkcssprovider.h"
/**
* SECTION:gtkcssprovider
* @Short_description: CSS-like styling for widgets
* @Title: GtkCssProvider
* @See_also: #GtkStyleContext, #GtkStyleProvider
*
* #GtkCssProvider is an object implementing #GtkStyleProvider, it is able
* to parse CSS-like input in order to style widgets.
*
* <refsect2 id="gtkcssprovider-selectors">
* <title>Widget selectors</title>
* <para>
* Selectors work in a really similar way than in common CSS, widget object
* names act as HTML tags:
* </para>
* <example>
* <title>Widgets in selectors</title>
* <programlisting>
* /&ast; Theme labels that are descendants of a window &ast;/
* GtkWindow GtkLabel {
* background-color: &num;898989;
* }
*
* /&ast; Theme notebooks, and anything that's within these &ast;/
* GtkNotebook {
* background-color: &num;a939f0;
* }
*
* /&ast; Theme combo boxes, and entries that
* are direct children of a notebook &ast;/
* GtkComboBox,
* GtkNotebook > GtkEntry {
* background-color: &num;1209a2;
* }
*
* /&ast; Theme any widget within a GtkBin &ast;/
* GtkBin * {
* font-name: Sans 20;
* }
* </programlisting>
* </example>
* <para>
* Widget names may be matched in CSS as well:
* </para>
* <example>
* <title>Widget names in selectors</title>
* <programlisting>
* /&ast; Theme a label named title-label &ast;/
* GtkLabel&num;title-label {
* font-name: Sans 15;
* }
*
* /&ast; Theme any widget named main-entry &ast;/
* &num;main-entry {
* background-color: &num;f0a810;
* }
* </programlisting>
* </example>
* <para>
* Widgets may also define different classes, so these can be matched
* in CSS:
* </para>
* <example>
* <title>Widget names in selectors</title>
* <programlisting>
* /&ast; Theme all widgets defining the class entry &ast;/
* .entry {
* foreground-color: &num;39f1f9;
* }
*
* /&ast; Theme spinbuttons' entry &ast;/
* GtkSpinButton.entry {
* foreground-color: &num;900185;
* }
* </programlisting>
* </example>
* <para>
* Container widgets may define regions, these region names may be
* referenced in CSS, it's also possible to apply :nth-child
* pseudo-class information if the widget implementation provides
* such data.
* </para>
* <example>
* <title>Region names in containers</title>
* <programlisting>
* /&ast; Theme any label within a notebook &ast;/
* GtkNotebook GtkLabel {
* foreground-color: &num;f90192;
* }
*
* /&ast; Theme labels within notebook tabs &ast;/
* GtkNotebook tab:nth-child GtkLabel {
* foreground-color: &num;703910;
* }
*
* /&ast; Theme labels in the any first notebook
* tab, both selectors are equivalent &ast;/
* GtkNotebook tab:nth-child(first) GtkLabel,
* GtkNotebook tab:first-child GtkLabel {
* foreground-color: &num;89d012;
* }
* </programlisting>
* </example>
* <para>
* Widget states may be matched as pseudoclasses.
* Given the needed widget states differ from the
* offered pseudoclasses in CSS, some are unsupported,
* and some custom ones have been added.
* </para>
* <example>
* <title>Styling specific widget states</title>
* <programlisting>
* /&ast; Theme active (pressed) buttons &ast;/
* GtkButton:active {
* background-color: &num;0274d9;
* }
*
* /&ast; Theme buttons with the mouse pointer on it &ast;/
* GtkButton:hover,
* GtkButton:prelight {
* background-color: &num;3085a9;
* }
*
* /&ast; Theme insensitive widgets, both are equivalent &ast;/
* :insensitive,
* *:insensitive {
* background-color: &num;320a91;
* }
*
* /&ast; Theme selection colors in entries &ast;/
* GtkEntry:selected {
* background-color: &num;56f9a0;
* }
*
* /&ast; Theme focused labels &ast;/
* GtkLabel:focused {
* background-color: &num;b4940f;
* }
*
* /&ast; Theme inconsistent checkbuttons &ast;/
* GtkCheckButton:inconsistent {
* background-color: &num;20395a;
* }
* </programlisting>
* </example>
* <para>
* Widget state pseudoclasses may only apply to the
* last element in a selector.
* </para>
* <para>
* All the mentioned elements may be combined to create
* complex selectors that match specific widget paths.
* As in CSS, rules apply by specificity, so the selectors
* describing the best a widget path will take precedence
* over the others.
* </para>
* </refsect2>
* <refsect2 id="gtkcssprovider-rules">
* <title>&commat; rules</title>
* <para>
* GTK+'s CSS supports the &commat;import rule, in order
* to load another CSS file in addition to the currently
* parsed one.
* </para>
* <example>
* <title>Using the &commat;import rule</title>
* <programlisting>
* &commat;import url (path/to/common.css)
* </programlisting>
* </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.
* </para>
* <example>
* <title>Defining colors</title>
* <programlisting>
* &commat;define-color bg_color &num;f9a039;
*
* &ast; {
* background-color: &commat;bg_color;
* }
* </programlisting>
* </example>
* </refsect2>
* <refsect2 id="gtkcssprovider-symbolic-colors">
* <title>Symbolic colors</title>
* <para>
* Besides being able to define color names, the CSS
* parser is also able to read different color modifiers,
* which can also be nested, providing a rich language
* to define colors starting from other colors.
* </para>
* <example>
* <title>Using symbolic colors</title>
* <programlisting>
* &commat;define-color entry-color shade (&commat;bg_color, 0.7);
*
* GtkEntry {
* background-color: @entry-color;
* }
*
* GtkEntry:focused {
* background-color: mix (&commat;entry-color,
* shade (&num;fff, 0.5),
* 0.8);
* }
* </programlisting>
* </example>
* </refsect2>
* <refsect2 id="gtkcssprovider-properties">
* <title>Supported properties</title>
* <para>
* 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>
* There is also a difference in shorthand properties, for
* example in common CSS it is fine to define a font through
* the different @font-family, @font-style, @font-size
* properties, meanwhile in GTK+'s CSS only the canonical
* @font property would be supported.
* </para>
* <para>
* The currently supported properties are:
* </para>
* <informaltable>
* <tgroup cols="4">
* <thead>
* <row>
* <entry>Property name</entry>
* <entry>Syntax</entry>
* <entry>Maps to</entry>
* <entry>Examples</entry>
* </row>
* </thead>
* <tbody>
* <row>
* <entry>engine</entry>
* <entry><programlisting>engine-name</programlisting></entry>
* <entry>#GtkThemingEngine</entry>
* <entry><programlisting>engine: clearlooks;</programlisting></entry>
* </row>
* <row>
* <entry>background-color</entry>
* <entry morerows="3"><programlisting>color</programlisting></entry>
* <entry morerows="3">#GdkColor</entry>
* <entry morerows="3">
* <programlisting>
* background-color: &num;fff;
* foreground-color: @color-name;
* text-color: shade (@color-name, 0.5);
* base-color: mix (@color-name, &num;f0f, 0.8);</programlisting>
* </entry>
* </row>
* <row>
* <entry>foreground-color</entry>
* </row>
* <row>
* <entry>text-color</entry>
* </row>
* <row>
* <entry>base-color</entry>
* </row>
* <row>
* <entry>font</entry>
* <entry><programlisting>family [style] [size]</programlisting></entry>
* <entry>#PangoFontDescription</entry>
* <entry><programlisting>font: Sans 15;</programlisting></entry>
* </row>
* <row>
* <entry>margin</entry>
* <entry morerows="1">
* <programlisting>
* width
* vertical-width horizontal-width
* top-width horizontal-width bottom-width
* top-width right-width bottom-width left-width
* </programlisting>
* </entry>
* <entry morerows="1">#GtkBorder</entry>
* <entry morerows="1">
* <programlisting>
* margin: 5;
* margin: 5 10;
* margin: 5 10 3;
* margin: 5 10 3 5;</programlisting>
* </entry>
* </row>
* <row>
* <entry>padding</entry>
* </row>
* <row>
* <entry>background-image</entry>
* <entry>
* <programlisting>
* -gtk-gradient (linear,
* starting-x-position starting-y-position,
* ending-x-position ending-y-position,
* [ [from|to] (color) |
* color-stop (percentage, color) ] )
*
* -gtk-gradient (radial,
* starting-x-position starting-y-position, starting-radius,
* ending-x-position ending-y-position, ending-radius,
* [ [from|to] (color) |
* color-stop (percentage, color) ]* )</programlisting>
* </entry>
* <entry>#cairo_pattern_t</entry>
* <entry>
* <programlisting>
* -gtk-gradient (linear,
* top left, top right,
* from (&num;fff), to (&num;000));
* -gtk-gradient (linear, 0.0 0.5, 0.5 1.0,
* from (&num;fff),
* color-stop (0.5, &num;f00),
* to (&num;000));
* -gtk-gradient (radial,
* center center, 0.2,
* center center, 0.8,
* color-stop (0.0, &num;fff),
* color-stop (1.0, &num;000));</programlisting>
* </entry>
* </row>
* <row>
* <entry>border-image</entry>
* <entry><programlisting>url([path]) top-distance right-distance bottom-distance left-distance horizontal-option vertical-option</programlisting></entry>
* <entry></entry>
* <entry>
* <programlisting>
* border-image: url (/path/to/image.png) 3 4 3 4 stretch;
* border-image: url (/path/to/image.png) 3 4 4 3 repeat stretch;</programlisting>
* </entry>
* </row>
* <row>
* <entry>transition</entry>
* <entry><programlisting>duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out]</programlisting></entry>
* <entry></entry>
* <entry>
* <programlisting>
* transition: 150ms ease-in-out;
* transition: 1s linear;</programlisting>
* </entry>
* </row>
* </tbody>
* </tgroup>
* </informaltable>
* </refsect2>
*/
typedef struct GtkCssProviderPrivate GtkCssProviderPrivate;
typedef struct SelectorElement SelectorElement;
typedef struct SelectorPath SelectorPath;
......@@ -753,6 +1107,13 @@ gtk_css_provider_finalize (GObject *object)
G_OBJECT_CLASS (gtk_css_provider_parent_class)->finalize (object);
}
/**
* gtk_css_provider_new:
*
* Returns a newly created #GtkCssProvider.
*
* Returns: A new #GtkCssProvider
**/
GtkCssProvider *
gtk_css_provider_new (void)
{
......@@ -2235,6 +2596,18 @@ parse_stylesheet (GtkCssProvider *css_provider)
return TRUE;
}
/**
* gtk_css_provider_load_from_data:
* @css_provider: a #GtkCssProvider
* @data: CSS data loaded in memory
* @length: the length of @data in bytes, or -1 for NUL terminated strings
* @error: (out) (allow-none): return location for a #GError, or %NULL
*
* Loads @data into @css_provider, making it clear any previously loaded
* information.
*
* Returns: %TRUE if the data could be loaded.
**/
gboolean
gtk_css_provider_load_from_data (GtkCssProvider *css_provider,
const gchar *data,
......@@ -2265,6 +2638,17 @@ gtk_css_provider_load_from_data (GtkCssProvider *css_provider,
return TRUE;
}
/**
* gtk_css_provider_load_from_file:
* @css_provider: a #GtkCssProvider
* @file: #GFile pointing to a file to load
* @error: (out) (allow-none): return location for a #GError, or %NULL
*
* Loads the data contained in @file into @css_provider, making it
* clear any previously loaded information.
*
* Returns: %TRUE if the data could be loaded.
**/
gboolean
gtk_css_provider_load_from_file (GtkCssProvider *css_provider,
GFile *file,
......@@ -2352,6 +2736,17 @@ gtk_css_provider_load_from_path_internal (GtkCssProvider *css_provider,
return TRUE;