diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 1de3259a6d..c14a42725c 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -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 \ diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 5963787271..0daebefb01 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -51,6 +51,15 @@ + + Theming in GTK+ + + + + + + + GTK+ Widgets and Objects diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 2ec9ae874e..0406de2c19 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -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 + +gtk_widget_get_path +gtk_widget_get_style_context +gtk_widget_reset_style + gtk_requisition_new gtk_requisition_copy @@ -5246,6 +5252,242 @@ GTK_INTERFACE_AGE GTK_CHECK_VERSION +
+gtkwidgetpath +GtkWidgetPath +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 +
+ +
+gtkstyleprovider +GtkStyleProvider +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 + +GTK_TYPE_STYLE_PROVIDER +GTK_STYLE_PROVIDER +GTK_IS_STYLE_PROVIDER +GTK_STYLE_PROVIDER_GET_IFACE + +gtk_style_provider_get_type +
+ +
+gtksymboliccolor +GtkSymbolicColor +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 + +GTK_TYPE_GRADIENT +GTK_TYPE_SYMBOLIC_COLOR + +gtk_symbolic_color_get_type +gtk_gradient_get_type +
+ +
+gtkstyleset +GtkStyleSet +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 + +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 + +gtk_style_set_get_type +
+ +
+gtkstylecontext +GtkStyleContext +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 + + +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 + + +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 + +gtk_style_context_get_type +
+ +
+gtkcssprovider +GtkCssProvider +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 + +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 + +gtk_css_provider_get_type +
+ +
+gtkthemingengine +GtkThemingEngine +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 + +GTK_THEMING_ENGINE +GTK_THEMING_ENGINE_CLASS +GTK_THEMING_ENGINE_GET_CLASS +GTK_IS_THEMING_ENGINE +GTK_IS_THEMING_ENGINE_CLASS + +GTK_TYPE_THEMING_ENGINE +gtk_theming_engine_get_type +
+
gtkstyle GtkStyle diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types index 6b43eccf7f..c385a37c48 100644 --- a/docs/reference/gtk/gtk3.types +++ b/docs/reference/gtk/gtk3.types @@ -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 diff --git a/gtk/gtk.h b/gtk/gtk.h index 02de38d9d1..92b4c7d21d 100644 --- a/gtk/gtk.h +++ b/gtk/gtk.h @@ -180,6 +180,7 @@ #include #include #include +#include #include #include #include diff --git a/gtk/gtkanimationdescription.h b/gtk/gtkanimationdescription.h index 14537edbf1..7770df2f02 100644 --- a/gtk/gtkanimationdescription.h +++ b/gtk/gtkanimationdescription.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__ */ diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 8c09ba2514..1be4ab2926 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -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) diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c index d4faf8873b..83f9cad5a3 100644 --- a/gtk/gtkcssprovider.c +++ b/gtk/gtkcssprovider.c @@ -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. + * + * + * Widget selectors + * + * Selectors work in a really similar way than in common CSS, widget object + * names act as HTML tags: + * + * + * Widgets in selectors + * + * /* Theme labels that are descendants of a window */ + * GtkWindow GtkLabel { + * background-color: #898989; + * } + * + * /* Theme notebooks, and anything that's within these */ + * GtkNotebook { + * background-color: #a939f0; + * } + * + * /* Theme combo boxes, and entries that + * are direct children of a notebook */ + * GtkComboBox, + * GtkNotebook > GtkEntry { + * background-color: #1209a2; + * } + * + * /* Theme any widget within a GtkBin */ + * GtkBin * { + * font-name: Sans 20; + * } + * + * + * + * Widget names may be matched in CSS as well: + * + * + * Widget names in selectors + * + * /* Theme a label named title-label */ + * GtkLabel#title-label { + * font-name: Sans 15; + * } + * + * /* Theme any widget named main-entry */ + * #main-entry { + * background-color: #f0a810; + * } + * + * + * + * Widgets may also define different classes, so these can be matched + * in CSS: + * + * + * Widget names in selectors + * + * /* Theme all widgets defining the class entry */ + * .entry { + * foreground-color: #39f1f9; + * } + * + * /* Theme spinbuttons' entry */ + * GtkSpinButton.entry { + * foreground-color: #900185; + * } + * + * + * + * 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. + * + * + * Region names in containers + * + * /* Theme any label within a notebook */ + * GtkNotebook GtkLabel { + * foreground-color: #f90192; + * } + * + * /* Theme labels within notebook tabs */ + * GtkNotebook tab:nth-child GtkLabel { + * foreground-color: #703910; + * } + * + * /* Theme labels in the any first notebook + * tab, both selectors are equivalent */ + * GtkNotebook tab:nth-child(first) GtkLabel, + * GtkNotebook tab:first-child GtkLabel { + * foreground-color: #89d012; + * } + * + * + * + * 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. + * + * + * Styling specific widget states + * + * /* Theme active (pressed) buttons */ + * GtkButton:active { + * background-color: #0274d9; + * } + * + * /* Theme buttons with the mouse pointer on it */ + * GtkButton:hover, + * GtkButton:prelight { + * background-color: #3085a9; + * } + * + * /* Theme insensitive widgets, both are equivalent */ + * :insensitive, + * *:insensitive { + * background-color: #320a91; + * } + * + * /* Theme selection colors in entries */ + * GtkEntry:selected { + * background-color: #56f9a0; + * } + * + * /* Theme focused labels */ + * GtkLabel:focused { + * background-color: #b4940f; + * } + * + * /* Theme inconsistent checkbuttons */ + * GtkCheckButton:inconsistent { + * background-color: #20395a; + * } + * + * + * + * Widget state pseudoclasses may only apply to the + * last element in a selector. + * + * + * 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. + * + * + * + * @ rules + * + * GTK+'s CSS supports the @import rule, in order + * to load another CSS file in addition to the currently + * parsed one. + * + * + * Using the @import rule + * + * @import url (path/to/common.css) + * + * + * + * GTK+ also supports an additional @define-color + * rule, in order to define a color name which may be used + * instead of color numeric representations. + * + * + * Defining colors + * + * @define-color bg_color #f9a039; + * + * * { + * background-color: @bg_color; + * } + * + * + * + * + * Symbolic colors + * + * 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. + * + * + * Using symbolic colors + * + * @define-color entry-color shade (@bg_color, 0.7); + * + * GtkEntry { + * background-color: @entry-color; + * } + * + * GtkEntry:focused { + * background-color: mix (@entry-color, + * shade (#fff, 0.5), + * 0.8); + * } + * + * + * + * + * 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). + * + * + * 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. + * + * + * The currently supported properties are: + * + * + * + * + * + * Property name + * Syntax + * Maps to + * Examples + * + * + * + * + * engine + * engine-name + * #GtkThemingEngine + * engine: clearlooks; + * + * + * background-color + * color + * #GdkColor + * + * + * background-color: #fff; + * foreground-color: @color-name; + * text-color: shade (@color-name, 0.5); + * base-color: mix (@color-name, #f0f, 0.8); + * + * + * + * foreground-color + * + * + * text-color + * + * + * base-color + * + * + * font + * family [style] [size] + * #PangoFontDescription + * font: Sans 15; + * + * + * margin + * + * + * width + * vertical-width horizontal-width + * top-width horizontal-width bottom-width + * top-width right-width bottom-width left-width + * + * + * #GtkBorder + * + * + * margin: 5; + * margin: 5 10; + * margin: 5 10 3; + * margin: 5 10 3 5; + * + * + * + * padding + * + * + * background-image + * + * + * -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) ]* ) + * + * #cairo_pattern_t + * + * + * -gtk-gradient (linear, + * top left, top right, + * from (#fff), to (#000)); + * -gtk-gradient (linear, 0.0 0.5, 0.5 1.0, + * from (#fff), + * color-stop (0.5, #f00), + * to (#000)); + * -gtk-gradient (radial, + * center center, 0.2, + * center center, 0.8, + * color-stop (0.0, #fff), + * color-stop (1.0, #000)); + * + * + * + * border-image + * url([path]) top-distance right-distance bottom-distance left-distance horizontal-option vertical-option + * + * + * + * 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; + * + * + * + * transition + * duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] + * + * + * + * transition: 150ms ease-in-out; + * transition: 1s linear; + * + * + * + * + * + * + */ + 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; } +/** + * gtk_css_provider_load_from_path: + * @css_provider: a #GtkCssProvider + * @path: the path of a filename to load, in the GLib filename encoding + * @error: (out) (allow-none): return location for a #GError, or %NULL + * + * Loads the data contained in @path into @css_provider, making it clear + * any previously loaded information. + * + * Returns: %TRUE if the data could be loaded. + **/ gboolean gtk_css_provider_load_from_path (GtkCssProvider *css_provider, const gchar *path, @@ -2364,6 +2759,15 @@ gtk_css_provider_load_from_path (GtkCssProvider *css_provider, TRUE, error); } +/** + * gtk_css_provider_get_default: + * + * Returns the provider containing the style settings used as a + * fallback for all widgets. + * + * Returns: (transfer none): The provider used for fallback styling. + * This memory is owned by GTK+, and you must not free it. + **/ GtkCssProvider * gtk_css_provider_get_default (void) { @@ -2457,6 +2861,16 @@ css_provider_get_theme_dir (void) return path; } +/** + * gtk_css_provider_get_named: + * @name: A theme name + * @variant: variant to load, for example, "dark", or %NULL for the default + * + * + * + * Returns: (transfer none): The provider used for fallback styling. + * This memory is owned by GTK+, and you must not free it. + **/ GtkCssProvider * gtk_css_provider_get_named (const gchar *name, const gchar *variant) diff --git a/gtk/gtkcssprovider.h b/gtk/gtkcssprovider.h index 2c6d283342..ebfc36ddc8 100644 --- a/gtk/gtkcssprovider.h +++ b/gtk/gtkcssprovider.h @@ -31,16 +31,16 @@ G_BEGIN_DECLS #define GTK_IS_CSS_PROVIDER_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), GTK_TYPE_CSS_PROVIDER)) #define GTK_CSS_PROVIDER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_CSS_PROVIDER, GtkCssProviderClass)) -typedef struct GtkCssProvider GtkCssProvider; -typedef struct GtkCssProviderClass GtkCssProviderClass; +typedef struct _GtkCssProvider GtkCssProvider; +typedef struct _GtkCssProviderClass GtkCssProviderClass; -struct GtkCssProvider +struct _GtkCssProvider { GObject parent_instance; gpointer priv; }; -struct GtkCssProviderClass +struct _GtkCssProviderClass { GObjectClass parent_class; }; diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h index a1fc4f49bf..85c8c561ae 100644 --- a/gtk/gtkenums.h +++ b/gtk/gtkenums.h @@ -560,6 +560,16 @@ typedef enum GTK_SCROLL_NATURAL } GtkScrollablePolicy; +/** + * GtkStateFlags: + * @GTK_STATE_FLAG_ACTIVE: Widget is active. + * @GTK_STATE_FLAG_PRELIGHT: Widget has a mouse pointer over it. + * @GTK_STATE_FLAG_SELECTED: Widget is selected. + * @GTK_STATE_FLAG_INCONSISTENT: Widget is inconsistent. + * @GTK_STATE_FLAG_FOCUSED: Widget has the keyboard focus. + * + * Describes a widget state. + */ typedef enum { GTK_STATE_FLAG_ACTIVE = 1 << 0, @@ -570,6 +580,17 @@ typedef enum GTK_STATE_FLAG_FOCUSED = 1 << 5 } GtkStateFlags; +/** + * GtkRegionFlags: + * @GTK_REGION_EVEN: Region has an even number within a set. + * @GTK_REGION_ODD: Region has an odd number within a set. + * @GTK_REGION_FIRST: Region is the first one within a set. + * @GTK_REGION_LAST: Region is the last one within a set. + * @GTK_REGION_DEFAULT: Region is the default option. + * @GTK_REGION_SORTED: Region is part of a sorted area. + * + * Describes a region within a widget. + */ typedef enum { GTK_REGION_EVEN = 1 << 0, GTK_REGION_ODD = 1 << 1, @@ -579,6 +600,16 @@ typedef enum { GTK_REGION_SORTED = 1 << 5 } GtkRegionFlags; +/** + * GtkJunctionSides: + * @GTK_JUNCTION_NONE: No junctions. + * @GTK_JUNCTION_TOP: Element connects on the top side. + * @GTK_JUNCTION_BOTTOM: Element connects on the bottom side. + * @GTK_JUNCTION_LEFT: Element connects on the left side. + * @GTK_JUNCTION_RIGHT: Element connects on the right side. + * + * Describes how a rendered element connects to adjacent elements. + */ typedef enum { GTK_JUNCTION_NONE = 0, GTK_JUNCTION_TOP = 1 << 0, diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index 04a39b53d2..3a0407405c 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -33,6 +33,163 @@ #include "gtkanimationdescription.h" #include "gtktimeline.h" +/** + * SECTION:gtkstylecontext + * @Short_description: rendering UI elements + * @Title: GtkStyleContext + * @See_also: + * + * #GtkStyleContext is an object that stores styling information affecting + * a widget defined by #GtkWidgetPath. + * + * In order to construct the final style information, #GtkStyleContext + * queries information to all attached #GtkStyleProviders, either + * to the context specifically through gtk_style_context_add_provider(), or + * to the screen through gtk_style_context_add_provider_for_screen(). The + * resulting style is a combination of all provider's information in priority + * order. + * + * For GTK+ widgets, any #GtkStyleContext returned by + * gtk_widget_get_style_context() will already have a #GtkWidgetPath, a + * #GdkScreen and RTL/LTR information set, the style context will be also + * updated automatically if any of these settings change on the widget. + * + * If you using are the theming layer standalone, you will need to set a + * widget path and a screen yourself to the created style context through + * gtk_style_context_set_path() and gtk_style_context_set_screen(), as well + * as updating the context yourself using gtk_style_context_invalidate() + * whenever any of the conditions change, such as a change in the + * #GtkSettings:gtk-theme-name property or a hierarchy change in the rendered + * widget. + * + * + * Transition animations + * + * #GtkStyleContext has built-in support for state change transitions. + * + * + * For simple widgets where state changes affect the whole widget area, + * calling gtk_style_context_notify_state_change() with a %NULL identifier + * would be sufficient. + * + * + * 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 around + * gtk_style_context_push_animatable_region() and + * gtk_style_context_pop_animatable_region(). These functions take an + * unique identifier within the style context, for simple widgets with + * little animatable regions, an enum may be used: + * + * + * Using an enum as animatable region identifier + * + * enum { + * REGION_ENTRY, + * REGION_BUTTON_UP, + * REGION_BUTTON_DOWN + * }; + * + * ... + * + * gboolean + * spin_button_draw (GtkWidget *widget, + * cairo_t *cr) + * { + * GtkStyleContext *context; + * + * context = gtk_widget_get_style_context (widget); + * + * gtk_style_context_push_animatable_region (context, + * GUINT_TO_POINTER (REGION_ENTRY)); + * + * gtk_render_background (cr, 0, 0, 100, 30); + * gtk_render_frame (cr, 0, 0, 100, 30); + * + * gtk_style_context_pop_animatable_region (context); + * + * ... + * } + * + * + * + * For complex widgets with an arbitrary number of animatable regions, it + * is up to the implementation to come up with a way to univocally identify + * an animatable region, pointers to internal structs would suffice. + * + * + * Using an arbitrary pointer as animatable region identifier + * + * void + * notebook_draw_tab (GtkWidget *widget, + * NotebookPage *page, + * cairo_t *cr) + * { + * gtk_style_context_push_animatable_region (context, page); + * gtk_render_extension (cr, page->x, page->y, page->width, page->height); + * gtk_style_context_pop_animatable_region (context); + * } + * + * + * + * The widget also needs to notify the style context about a state change + * for a given animatable region so the animation is triggered. + * + * + * Triggering a state change animation on a region + * + * gboolean + * notebook_motion_notify (GtkWidget *widget, + * GdkEventMotion *event) + * { + * GtkStyleContext *context; + * NotebookPage *page; + * + * context = gtk_widget_get_style_context (widget); + * page = find_page_under_pointer (widget, event); + * gtk_style_context_notify_state_change (context, + * gtk_widget_get_window (widget), + * page, + * GTK_STATE_PRELIGHT, + * TRUE); + * ... + * } + * + * + * + * 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. + * + * + * + * + * Custom styling in UI libraries and applications + * + * If you are developing a library with custom #GtkWidgets 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. + * + * + * 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 + * priority, keep in mind that the user settings in $HOME/.gtk-3.0.css will + * still take precedence over your changes, as it uses the + * %GTK_STYLE_PROVIDER_PRIORITY_USER priority. + * + * + * 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. + * + * + */ + typedef struct GtkStyleContextPrivate GtkStyleContextPrivate; typedef struct GtkStyleProviderData GtkStyleProviderData; typedef struct GtkStyleInfo GtkStyleInfo; @@ -571,7 +728,7 @@ gtk_style_context_impl_get_property (GObject *object, } } -GList * +static GList * find_next_candidate (GList *local, GList *global) { @@ -705,7 +862,7 @@ create_query_path (GtkStyleContext *context) return path; } -StyleData * +static StyleData * style_data_lookup (GtkStyleContext *context) { GtkStyleContextPrivate *priv; @@ -825,6 +982,20 @@ style_provider_remove (GList **list, return FALSE; } +/** + * gtk_style_context_add_provider: + * @context: a #GtkStyleContext + * @provider: a #GtkStyleProvider + * @priority: the priority of the style provider. The lower + * it is, the earlier it will be used in the style + * construction. Typically this will be in the range + * between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and + * %GTK_STYLE_PROVIDER_PRIORITY_USER + * + * Adds a style provider to @context, to be used in style construction. + * + * Since: 3.0 + **/ void gtk_style_context_add_provider (GtkStyleContext *context, GtkStyleProvider *provider, @@ -842,6 +1013,15 @@ gtk_style_context_add_provider (GtkStyleContext *context, gtk_style_context_invalidate (context); } +/** + * gtk_style_context_remove_provider: + * @context: a #GtkStyleContext + * @provider: a #GtkStyleProvider + * + * Removes @provider from the style providers list in @context. + * + * Since: 3.0 + **/ void gtk_style_context_remove_provider (GtkStyleContext *context, GtkStyleProvider *provider) @@ -861,6 +1041,19 @@ gtk_style_context_remove_provider (GtkStyleContext *context, } } +/** + * gtk_style_context_reset_widgets: + * @screen: a #GdkScreen + * + * This function recomputes the styles for all widgets under a particular + * #GdkScreen. This is useful when some global parameter has changed that + * affects the appearance of all widgets, because when a widget gets a new + * style, it will both redraw and recompute any cached information about + * its appearance. As an example, it is used when the color scheme changes + * in the related #GtkSettings object. + * + * Since: 3.0 + **/ void gtk_style_context_reset_widgets (GdkScreen *screen) { @@ -880,6 +1073,22 @@ gtk_style_context_reset_widgets (GdkScreen *screen) g_list_free (toplevels); } +/** + * gtk_style_context_add_provider_for_screen: + * @screen: a #GdkScreen + * @provider: a #GtkStyleProvider + * @priority: the priority of the style provider. The lower + * it is, the earlier it will be used in the style + * construction. Typically this will be in the range + * between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and + * %GTK_STYLE_PROVIDER_PRIORITY_USER + * + * Adds a global style provider to @screen, which will be used + * in style construction for all #GtkStyleContexts under + * @screen. + * + * Since: 3.0 + **/ void gtk_style_context_add_provider_for_screen (GdkScreen *screen, GtkStyleProvider *provider, @@ -902,6 +1111,15 @@ gtk_style_context_add_provider_for_screen (GdkScreen *screen, gtk_style_context_reset_widgets (screen); } +/** + * gtk_style_context_remove_provider_for_screen: + * @screen: a #GdkScreen + * @provider: a #GtkStyleProvider + * + * Removes @provider from the global style providers list in @screen. + * + * Since: 3.0 + **/ void gtk_style_context_remove_provider_for_screen (GdkScreen *screen, GtkStyleProvider *provider) @@ -925,6 +1143,18 @@ gtk_style_context_remove_provider_for_screen (GdkScreen *screen, } } +/** + * gtk_style_context_get_property: + * @context: a #GtkStyleContext + * @property: style property name + * @state: state to retrieve the property value for + * @value: (out) (transfer full): return location for the style property value. + * + * Gets a style property from @context for the given state. When done with @value, + * g_value_unset() needs to be called to free any allocated memory. + * + * Since: 3.0 + **/ void gtk_style_context_get_property (GtkStyleContext *context, const gchar *property, @@ -946,6 +1176,16 @@ gtk_style_context_get_property (GtkStyleContext *context, gtk_style_set_get_property (data->store, property, state, value); } +/** + * gtk_style_context_get_valist: + * @context: a #GtkStyleContext + * @state: state to retrieve the property values for + * @args: va_list of property name/return location pairs, followed by %NULL + * + * Retrieves several style property values from @context for a given state. + * + * Since: 3.0 + **/ void gtk_style_context_get_valist (GtkStyleContext *context, GtkStateFlags state, @@ -963,6 +1203,17 @@ gtk_style_context_get_valist (GtkStyleContext *context, gtk_style_set_get_valist (data->store, state, args); } +/** + * gtk_style_context_get: + * @context: a #GtkStyleContext + * @state: state to retrieve the property values for + * @...: property name /return value pairs, followed by %NULL + * + * Retrieves several style property values from @context for a + * given state. + * + * Since: 3.0 + **/ void gtk_style_context_get (GtkStyleContext *context, GtkStateFlags state, @@ -984,6 +1235,16 @@ gtk_style_context_get (GtkStyleContext *context, va_end (args); } +/** + * gtk_style_context_set_state: + * @context: a #GtkStyleContext + * @flags: state to represent + * + * Sets the style to be used when rendering with any + * of the "gtk_render_" prefixed functions. + * + * Since: 3.0 + **/ void gtk_style_context_set_state (GtkStyleContext *context, GtkStateFlags flags) @@ -996,6 +1257,16 @@ gtk_style_context_set_state (GtkStyleContext *context, priv->state_flags = flags; } +/** + * gtk_style_context_get_state: + * @context: a #GtkStyleContext + * + * returns the state used when rendering. + * + * Returns: the state flags + * + * Since: 3.0 + **/ GtkStateFlags gtk_style_context_get_state (GtkStyleContext *context) { @@ -1093,6 +1364,19 @@ gtk_style_context_is_state_set (GtkStyleContext *context, return state_set; } +/** + * gtk_style_context_set_path: + * @context: a #GtkStyleContext + * @path: a #GtkWidgetPath + * + * Sets the #GtkWidgetPath used for style matching. As a + * consequence, the style will be regenerated to match + * the new given path. If you are using a #GtkStyleContext + * returned from gtk_widget_get_style_context(), you do + * not need to call this yourself. + * + * Since: 3.0 + **/ void gtk_style_context_set_path (GtkStyleContext *context, GtkWidgetPath *path) @@ -1116,6 +1400,16 @@ gtk_style_context_set_path (GtkStyleContext *context, gtk_style_context_invalidate (context); } +/** + * gtk_style_context_get_path: + * @context: a #GtkStyleContext + * + * Returns the widget path used for style matching. + * + * Returns: (transfer none): A #GtkWidgetPath + * + * Since: 3.0 + **/ G_CONST_RETURN GtkWidgetPath * gtk_style_context_get_path (GtkStyleContext *context) { @@ -1125,6 +1419,18 @@ gtk_style_context_get_path (GtkStyleContext *context) return priv->widget_path; } +/** + * gtk_style_context_save: + * @context: a #GtkStyleContext + * + * Saves the @context state, so all modifications done through + * gtk_style_context_set_class(), gtk_style_context_unset_class(), + * gtk_style_context_set_region(), gtk_style_context_unset_region() + * or gtk_style_context_set_junction_sides() can be reverted in one + * go through gtk_style_context_restore(). + * + * Since: 3.0 + **/ void gtk_style_context_save (GtkStyleContext *context) { @@ -1141,6 +1447,15 @@ gtk_style_context_save (GtkStyleContext *context) priv->info_stack = g_slist_prepend (priv->info_stack, info); } +/** + * gtk_style_context_restore: + * @context: a #GtkStyleContext + * + * Restores @context state to a previous stage. See + * gtk_style_context_save(). + * + * Since: 3.0 + **/ void gtk_style_context_restore (GtkStyleContext *context) { @@ -1262,6 +1577,30 @@ region_find (GArray *array, return found; } +/** + * gtk_style_context_set_class: + * @context: a #GtkStyleContext + * @class_name: class name to use in styling + * + * Sets a class name to @context, so posterior calls to + * gtk_style_context_get() or any of the gtk_render_* + * functions will make use of this new class for styling. + * + * In the CSS file format, a #GtkEntry defining an "entry" + * class, would be matched by: + * + * + * GtkEntry.entry { ... } + * + * + * While any widget defining an "entry" class would be + * matched by: + * + * .entry { ... } + * + * + * Since: 3.0 + **/ void gtk_style_context_set_class (GtkStyleContext *context, const gchar *class_name) @@ -1289,6 +1628,15 @@ gtk_style_context_set_class (GtkStyleContext *context, } } +/** + * gtk_style_context_unset_class: + * @context: a #GtkStyleContext + * @class_name: class name to remove + * + * Removes @class_name from @context. + * + * Since: 3.0 + **/ void gtk_style_context_unset_class (GtkStyleContext *context, const gchar *class_name) @@ -1320,6 +1668,18 @@ gtk_style_context_unset_class (GtkStyleContext *context, } } +/** + * gtk_style_context_has_class: + * @context: a #GtkStyleContext + * @class_name: a class name + * + * Returns %TRUE if @context currently has defined the + * given class name + * + * Returns: %TRUE if @context has @class_name defined + * + * Since: 3.0 + **/ gboolean gtk_style_context_has_class (GtkStyleContext *context, const gchar *class_name) @@ -1347,6 +1707,19 @@ gtk_style_context_has_class (GtkStyleContext *context, return FALSE; } +/** + * gtk_style_context_list_classes: + * @context: a #GtkStyleContext + * + * Returns the list of classes currently defined in @context. + * + * Returns: (transfer container) (element-type utf8): a #GList of + * strings with the currently defined classes. The contents + * of the list are owned by GTK+, but you must free the list + * itself with g_list_free() when you are done with it. + * + * Since: 3.0 + **/ GList * gtk_style_context_list_classes (GtkStyleContext *context) { @@ -1373,6 +1746,20 @@ gtk_style_context_list_classes (GtkStyleContext *context) return classes; } +/** + * gtk_style_context_list_regions: + * @context: a #GtkStyleContext + * + * + * Returns the list of regions currently defined in @context. + * + * Returns: (transfer container) (element-type utf8): a #GList of + * strings with the currently defined regions. The contents + * of the list are owned by GTK+, but you must free the list + * itself with g_list_free() when you are done with it. + * + * Since: 3.0 + **/ GList * gtk_style_context_list_regions (GtkStyleContext *context) { @@ -1402,30 +1789,58 @@ gtk_style_context_list_regions (GtkStyleContext *context) return classes; } +/** + * gtk_style_context_set_region: + * @context: a #GtkStyleContext + * @region_name: region name to use in styling + * @flags: flags that apply to the region + * + * Sets a region to @context, so posterior calls to + * gtk_style_context_get() or any of the gtk_render_* + * functions will make use of this new region for styling. + * + * In the CSS file format, a #GtkTreeView defining a "row" + * region, would be matched by: + * + * + * GtkTreeView row { ... } + * + * + * pseudo-classes are used for matching @flags, so the two + * following rules: + * + * GtkTreeView row:nth-child (even) { ... } + * GtkTreeView row:nth-child (odd) { ... } + * + * + * would apply to even and odd rows, respectively. + * + * Since: 3.0 + **/ void gtk_style_context_set_region (GtkStyleContext *context, - const gchar *class_name, + const gchar *region_name, GtkRegionFlags flags) { GtkStyleContextPrivate *priv; GtkStyleInfo *info; - GQuark class_quark; + GQuark region_quark; guint position; g_return_if_fail (GTK_IS_STYLE_CONTEXT (context)); - g_return_if_fail (class_name != NULL); + g_return_if_fail (region_name != NULL); priv = context->priv; - class_quark = g_quark_from_string (class_name); + region_quark = g_quark_from_string (region_name); g_assert (priv->info_stack != NULL); info = priv->info_stack->data; - if (!region_find (info->regions, class_quark, &position)) + if (!region_find (info->regions, region_quark, &position)) { GtkRegion region; - region.class_quark = class_quark; + region.class_quark = region_quark; region.flags = flags; g_array_insert_val (info->regions, position, region); @@ -1435,21 +1850,30 @@ gtk_style_context_set_region (GtkStyleContext *context, } } +/** + * gtk_style_context_unset_region: + * @context: a #GtkStyleContext + * @region_name: region name to unset + * + * Removes a region from @context + * + * Since: 3.0 + **/ void -gtk_style_context_unset_region (GtkStyleContext *context, - const gchar *class_name) +gtk_style_context_unset_region (GtkStyleContext *context, + const gchar *region_name) { GtkStyleContextPrivate *priv; GtkStyleInfo *info; - GQuark class_quark; + GQuark region_quark; guint position; g_return_if_fail (GTK_IS_STYLE_CONTEXT (context)); - g_return_if_fail (class_name != NULL); + g_return_if_fail (region_name != NULL); - class_quark = g_quark_try_string (class_name); + region_quark = g_quark_try_string (region_name); - if (!class_quark) + if (!region_quark) return; priv = context->priv; @@ -1457,7 +1881,7 @@ gtk_style_context_unset_region (GtkStyleContext *context, g_assert (priv->info_stack != NULL); info = priv->info_stack->data; - if (region_find (info->regions, class_quark, &position)) + if (region_find (info->regions, region_quark, &position)) { g_array_remove_index (info->regions, position); @@ -1466,25 +1890,38 @@ gtk_style_context_unset_region (GtkStyleContext *context, } } +/** + * gtk_style_context_has_region: + * @context: a #GtkStyleContext + * @region_name: a region name + * @flags_return: (out) (allow-none): return location for region flags + * + * Returns %TRUE if @context has the region defined. If @flags_return is + * not %NULL, it is set to the flags affecting the region. + * + * Returns: %TRUE if region is defined + * + * Since: 3.0 + **/ gboolean gtk_style_context_has_region (GtkStyleContext *context, - const gchar *class_name, + const gchar *region_name, GtkRegionFlags *flags_return) { GtkStyleContextPrivate *priv; GtkStyleInfo *info; - GQuark class_quark; + GQuark region_quark; guint position; g_return_val_if_fail (GTK_IS_STYLE_CONTEXT (context), FALSE); - g_return_val_if_fail (class_name != NULL, FALSE); + g_return_val_if_fail (region_name != NULL, FALSE); if (flags_return) *flags_return = 0; - class_quark = g_quark_try_string (class_name); + region_quark = g_quark_try_string (region_name); - if (!class_quark) + if (!region_quark) return FALSE; priv = context->priv; @@ -1492,7 +1929,7 @@ gtk_style_context_has_region (GtkStyleContext *context, g_assert (priv->info_stack != NULL); info = priv->info_stack->data; - if (region_find (info->regions, class_quark, &position)) + if (region_find (info->regions, region_quark, &position)) { if (flags_return) { @@ -1581,6 +2018,15 @@ _gtk_style_context_peek_style_property (GtkStyleContext *context, return &pcache->value; } +/** + * gtk_style_context_get_style_property: + * @context: a #GtkStyleContext + * @property_name: the name of the widget style property + * @value: (out) (transfer full): Return location for the property value, free with + * g_value_unset() after use. + * + * Gets the value for a widget style property. + **/ void gtk_style_context_get_style_property (GtkStyleContext *context, const gchar *property_name, @@ -1631,6 +2077,16 @@ gtk_style_context_get_style_property (GtkStyleContext *context, G_VALUE_TYPE_NAME (value)); } +/** + * gtk_style_context_get_style_valist: + * @context: a #GtkStyleContext + * @args: va_list of property name/return location pairs, followed by %NULL + * + * Retrieves several widget style properties from @context according to the + * current style. + * + * Since: 3.0 + **/ void gtk_style_context_get_style_valist (GtkStyleContext *context, va_list args) @@ -1688,6 +2144,16 @@ gtk_style_context_get_style_valist (GtkStyleContext *context, } } +/** + * gtk_style_context_get_style: + * @context: a #GtkStyleContext + * @...: property name /return value pairs, followed by %NULL + * + * Retrieves several widget style properties from @context according to the + * current style. + * + * Since: 3.0 + **/ void gtk_style_context_get_style (GtkStyleContext *context, ...) @@ -1702,6 +2168,17 @@ gtk_style_context_get_style (GtkStyleContext *context, } +/** + * gtk_style_context_lookup_icon_set: + * @context: a #GtkStyleContext + * @stock_id: an icon name + * + * Looks up @stock_id in the icon factories associated to @context and + * the default icon factory, returning an icon set if found, otherwise + * %NULL. + * + * Returns: (transfer none): The looked up %GtkIconSet, or %NULL + **/ GtkIconSet * gtk_style_context_lookup_icon_set (GtkStyleContext *context, const gchar *stock_id) @@ -1733,6 +2210,18 @@ gtk_style_context_lookup_icon_set (GtkStyleContext *context, return gtk_icon_factory_lookup_default (stock_id); } +/** + * gtk_style_context_set_screen: + * @context: a #GtkStyleContext + * @screen: a #GdkScreen + * + * Sets the screen to which @context will be attached to, @screen + * is used in order to reconstruct style based on the global providers + * list. If you are using a #GtkStyleContext returned from + * gtk_widget_get_style_context(), you do not need to call this yourself. + * + * Since: 3.0 + **/ void gtk_style_context_set_screen (GtkStyleContext *context, GdkScreen *screen) @@ -1749,6 +2238,14 @@ gtk_style_context_set_screen (GtkStyleContext *context, gtk_style_context_invalidate (context); } +/** + * gtk_style_context_get_screen: + * @context: a #GtkStyleContext + * + * Returns the #GdkScreen to which @context is attached to. + * + * Returns: a #GdkScreen, or %NULL. + **/ GdkScreen * gtk_style_context_get_screen (GtkStyleContext *context) { @@ -1760,6 +2257,17 @@ gtk_style_context_get_screen (GtkStyleContext *context) return priv->screen; } +/** + * gtk_style_context_set_direction: + * @context: a #GtkStyleContext + * @direction: the new direction. + * + * Sets the reading direction for rendering purposes. If you are + * using a #GtkStyleContext returned from gtk_widget_get_style_context(), + * you do not need to call this yourself. + * + * Since: 3.0 + **/ void gtk_style_context_set_direction (GtkStyleContext *context, GtkTextDirection direction) @@ -1774,6 +2282,16 @@ gtk_style_context_set_direction (GtkStyleContext *context, g_object_notify (G_OBJECT (context), "direction"); } +/** + * gtk_style_context_get_direction: + * @context: a #GtkStyleContext + * + * Returns the widget direction used for rendering. + * + * Returns: the widget direction + * + * Since: 3.0 + **/ GtkTextDirection gtk_style_context_get_direction (GtkStyleContext *context) { @@ -1785,6 +2303,17 @@ gtk_style_context_get_direction (GtkStyleContext *context) return priv->direction; } +/** + * gtk_style_context_set_junction_sides: + * @context: a #GtkStyleContext + * @sides: sides where rendered elements are visually connected to other elements. + * + * Sets the sides where rendered elements (mostly through gtk_render_frame()) will + * visually connect with other visual elements. This is merely a guideline that may + * be honored or not in theming engines. + * + * Since: 3.0 + **/ void gtk_style_context_set_junction_sides (GtkStyleContext *context, GtkJunctionSides sides) @@ -1799,6 +2328,16 @@ gtk_style_context_set_junction_sides (GtkStyleContext *context, info->junction_sides = sides; } +/** + * gtk_style_context_get_junction_sides: + * @context: a #GtkStyleContext + * + * Returns the sides where rendered elements connect visually with others. + * + * Returns: the junction sides + * + * Since: 3.0 + **/ GtkJunctionSides gtk_style_context_get_junction_sides (GtkStyleContext *context) { @@ -1812,6 +2351,16 @@ gtk_style_context_get_junction_sides (GtkStyleContext *context) return info->junction_sides; } +/** + * gtk_style_context_lookup_color: + * @context: a #GtkStyleContext + * @color_name: color name to lookup + * @color: (out): Return location for the looked up color + * + * Looks up and resolves a color name in the @context color map. + * + * Returns: %TRUE if @color_name was found and resolved, %FALSE otherwise + **/ gboolean gtk_style_context_lookup_color (GtkStyleContext *context, const gchar *color_name, @@ -1837,6 +2386,53 @@ gtk_style_context_lookup_color (GtkStyleContext *context, return gtk_symbolic_color_resolve (sym_color, data->store, color); } +/** + * gtk_style_context_notify_state_change: + * @context: a #GtkStyleContext + * @window: a #GdkWindow + * @region_id: (allow-none): animatable region to notify on, or %NULL. + * See gtk_style_context_push_animatable_region() + * @state: state to trigger transition for + * @state_value: target value of @state + * + * Notifies a state change on @context, so if the current style makes use + * of transition animations, one will be started so all rendered elements + * under @region_id are animated for state @state being set to value @state_value. + * + * The @window parameter is used in order to invalidate the rendered area + * as the animation runs, so make sure it is the same window that is being + * rendered on by the gtk_render_*() methods. + * + * If @region_id is %NULL, all rendered elements using @context will be + * affected by this state transition. + * + * As a practical example, a #GtkButton notifying a state transition on + * the prelight state: + * + * gtk_style_context_notify_state_change (context, + * gtk_widget_get_window (widget), + * NULL, GTK_STATE_PRELIGHT, + * button->in_button); + * + * + * Could be handled in the CSS file like this: + * + * GtkButton { + * background-color: #f00; + * } + * + * GtkButton:hover { + * background-color: #fff; + * transition: 200ms linear; + * } + * + * + * This combination would animate the button background from red to white + * if a pointer enters the button, and back to red if the pointer leaves + * the button. + * + * Since: 3.0 + **/ void gtk_style_context_notify_state_change (GtkStyleContext *context, GdkWindow *window, @@ -1931,6 +2527,22 @@ gtk_style_context_notify_state_change (GtkStyleContext *context, gtk_animation_description_unref (desc); } +/** + * gtk_style_context_push_animatable_region: + * @context: a #GtkStyleContext + * @region_id: unique identifier for the animatable region + * + * Pushes an animatable region, so all further gtk_render_*() calls between + * this call and the following gtk_style_context_pop_animatable_region() will + * potentially show transition animations for if gtk_style_context_notify_state_change() + * is called for a given state, and the theme/style used contemplates the use of + * transition animations for state changes. + * + * The @region_id used must be unique in @context so the theming engine may + * univocally identify rendered elements subject to a state transition. + * + * Since: 3.0 + **/ void gtk_style_context_push_animatable_region (GtkStyleContext *context, gpointer region_id) @@ -1944,6 +2556,14 @@ gtk_style_context_push_animatable_region (GtkStyleContext *context, priv->animation_regions = g_slist_prepend (priv->animation_regions, region_id); } +/** + * gtk_style_context_pop_animatable_region: + * @context: a #GtkStyleContext + * + * Pops an animatable region from @context. See gtk_style_context_push_animatable_region(). + * + * Since: 3.0 + **/ void gtk_style_context_pop_animatable_region (GtkStyleContext *context) { @@ -2074,6 +2694,16 @@ store_animation_region (GtkStyleContext *context, } } +/** + * gtk_style_context_invalidate: + * @context: a #GtkStyleContext. + * + * Invalidates @context style information, so it will be reconstructed + * again. If you're using a #GtkStyleContext returned from + * gtk_widget_get_style_context(), you do not need to call this yourself. + * + * Since: 3.0 + **/ void gtk_style_context_invalidate (GtkStyleContext *context) { diff --git a/gtk/gtkstylecontext.h b/gtk/gtkstylecontext.h index 9bab375a05..a9843f352e 100644 --- a/gtk/gtkstylecontext.h +++ b/gtk/gtkstylecontext.h @@ -33,16 +33,16 @@ G_BEGIN_DECLS #define GTK_IS_STYLE_CONTEXT_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), GTK_TYPE_STYLE_CONTEXT)) #define GTK_STYLE_CONTEXT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_STYLE_CONTEXT, GtkStyleContextClass)) -typedef struct GtkStyleContext GtkStyleContext; -typedef struct GtkStyleContextClass GtkStyleContextClass; +typedef struct _GtkStyleContext GtkStyleContext; +typedef struct _GtkStyleContextClass GtkStyleContextClass; -struct GtkStyleContext +struct _GtkStyleContext { GObject parent_object; gpointer priv; }; -struct GtkStyleContextClass +struct _GtkStyleContextClass { GObjectClass parent_class; diff --git a/gtk/gtkstyleprovider.c b/gtk/gtkstyleprovider.c index 2c23a80edb..2a9d2fc5e5 100644 --- a/gtk/gtkstyleprovider.c +++ b/gtk/gtkstyleprovider.c @@ -23,6 +23,16 @@ #include "gtkstyleprovider.h" #include "gtkintl.h" +/** + * SECTION:gtkstyleprovider + * @Short_description: Interface to provide style information to #GtkStyleContext + * @Title: GtkStyleProvider + * @See_also: #GtkStyleContext, #GtkCssProvider + * + * #GtkStyleProvider is an interface used to provide style information to a #GtkStyleContext, + * see gtk_style_context_add_provider() and gtk_style_context_add_provider_for_screen(). + */ + static void gtk_style_provider_iface_init (gpointer g_iface); GType @@ -44,6 +54,18 @@ gtk_style_provider_iface_init (gpointer g_iface) { } +/** + * gtk_style_provider_get_style: + * @provider: a #GtkStyleProvider + * @path: #GtkWidgetPath to query + * + * Returns the style settings affecting a widget defined by @path, or %NULL if + * @provider doesn't contemplate styling @path. + * + * Returns: a #GtkStyleSet containing the style settings affecting @path + * + * Since: 3.0 + **/ GtkStyleSet * gtk_style_provider_get_style (GtkStyleProvider *provider, GtkWidgetPath *path) @@ -60,16 +82,28 @@ gtk_style_provider_get_style (GtkStyleProvider *provider, return iface->get_style (provider, path); } +/** + * gtk_style_provider_get_style_property: + * @provider: a #GtkStyleProvider + * @path: #GtkWidgetPath to query + * @property_name: the property name + * @value: (out): return location for the property value + * + * Looks up a widget style property as defined by @provider for + * the widget represented by @widget_path. + * + * Returns: %TRUE if the property was found and has a value, %FALSE otherwise + **/ gboolean gtk_style_provider_get_style_property (GtkStyleProvider *provider, - GtkWidgetPath *widget_path, + GtkWidgetPath *path, const gchar *property_name, GValue *value) { GtkStyleProviderIface *iface; g_return_val_if_fail (GTK_IS_STYLE_PROVIDER (provider), FALSE); - g_return_val_if_fail (widget_path != NULL, FALSE); + g_return_val_if_fail (path != NULL, FALSE); g_return_val_if_fail (property_name != NULL, FALSE); g_return_val_if_fail (value != NULL, FALSE); @@ -78,9 +112,21 @@ gtk_style_provider_get_style_property (GtkStyleProvider *provider, if (!iface->get_style_property) return FALSE; - return iface->get_style_property (provider, widget_path, property_name, value); + return iface->get_style_property (provider, path, property_name, value); } +/** + * gtk_style_provider_get_icon_factory: + * @provider: a #GtkStyleProvider + * @path: #GtkWidgetPath to query + * + * Returns the #GtkIconFactory defined to be in use for @path, or %NULL if none + * is defined. + * + * Returns: The icon factory to use for @path, or %NULL + * + * Since: 3.0 + **/ GtkIconFactory * gtk_style_provider_get_icon_factory (GtkStyleProvider *provider, GtkWidgetPath *path) diff --git a/gtk/gtkstyleprovider.h b/gtk/gtkstyleprovider.h index 556b257405..0f763a2b41 100644 --- a/gtk/gtkstyleprovider.h +++ b/gtk/gtkstyleprovider.h @@ -39,10 +39,16 @@ G_BEGIN_DECLS #define GTK_STYLE_PROVIDER_PRIORITY_APPLICATION 600 #define GTK_STYLE_PROVIDER_PRIORITY_USER 800 -typedef struct GtkStyleProviderIface GtkStyleProviderIface; -typedef struct GtkStyleProvider GtkStyleProvider; /* dummy typedef */ +typedef struct _GtkStyleProviderIface GtkStyleProviderIface; +typedef struct _GtkStyleProvider GtkStyleProvider; /* dummy typedef */ -struct GtkStyleProviderIface +/** + * GtkStyleProviderIface + * @get_style: Gets a set of style information that applies to a widget path. + * @get_style_property: Gets the value of a widget style property that applies to a widget path. + * @get_icon_factory: Gets the icon factory that applies to a widget path. + */ +struct _GtkStyleProviderIface { GTypeInterface g_iface; diff --git a/gtk/gtkstyleset.c b/gtk/gtkstyleset.c index 2f71f718b4..24641621ad 100644 --- a/gtk/gtkstyleset.c +++ b/gtk/gtkstyleset.c @@ -325,6 +325,21 @@ property_node_lookup (GQuark quark) } /* Property registration functions */ + +/** + * gtk_style_set_register_property: + * @property_name: property name to register + * @type: #GType the property will hold + * @default_value: default value for this property + * @parse_func: parsing function to use, or %NULL + * + * Registers a property so it can be used in the CSS file format. + * This function is the low-level equivalent of + * gtk_theming_engine_register_property(), if you are implementing + * a theming engine, you want to use that function instead. + * + * Since: 3.0 + **/ void gtk_style_set_register_property (const gchar *property_name, GType type, @@ -377,6 +392,20 @@ gtk_style_set_register_property (const gchar *property_name, g_array_insert_val (properties, i, new); } +/** + * gtk_style_set_lookup_property: + * @property_name: property name to look up + * @type: (out): return location for the looked up property type + * @parse_func: (out): return value for the parse function + * + * Returns %TRUE if a property has been registered, if @type or + * @parse_func are not %NULL, the property #GType and parsing function + * will be respectively returned. + * + * Returns: %TRUE if the property is registered, %FALSE otherwise + * + * Since: 3.0 + **/ gboolean gtk_style_set_lookup_property (const gchar *property_name, GType *type, @@ -425,12 +454,30 @@ gtk_style_set_lookup_property (const gchar *property_name, /* GtkStyleSet methods */ +/** + * gtk_style_set_new: + * + * Returns a newly created #GtkStyleSet + * + * Returns: a new #GtkStyleSet + **/ GtkStyleSet * gtk_style_set_new (void) { return g_object_new (GTK_TYPE_STYLE_SET, NULL); } +/** + * gtk_style_set_map_color: + * @set: a #GtkStyleSet + * @name: color name + * @color: #GtkSymbolicColor to map @name to + * + * Maps @color so it can be referenced by @name. See + * gtk_style_set_lookup_color() + * + * Since: 3.0 + **/ void gtk_style_set_map_color (GtkStyleSet *set, const gchar *name, @@ -455,6 +502,18 @@ gtk_style_set_map_color (GtkStyleSet *set, gtk_symbolic_color_ref (color)); } +/** + * gtk_style_set_lookup_color: + * @set: a #GtkStyleSet + * @name: color name to lookup + * + * Returns the symbolic color that is mapped + * to @name. + * + * Returns: The mapped color + * + * Since: 3.0 + **/ GtkSymbolicColor * gtk_style_set_lookup_color (GtkStyleSet *set, const gchar *name) @@ -472,6 +531,17 @@ gtk_style_set_lookup_color (GtkStyleSet *set, return g_hash_table_lookup (priv->color_map, name); } +/** + * gtk_style_set_set_property: + * @set: a #GtkStyleSet + * @property: styling property to set + * @state: state to set the value for + * @value: new value for the property + * + * Sets a styling property in @set. + * + * Since: 3.0 + **/ void gtk_style_set_set_property (GtkStyleSet *set, const gchar *property, @@ -538,6 +608,16 @@ gtk_style_set_set_property (GtkStyleSet *set, g_value_copy (value, val); } +/** + * gtk_style_set_set_valist: + * @set: a #GtkStyleSet + * @state: state to set the values for + * @args: va_list of property name/value pairs, followed by %NULL + * + * Sets several style properties on @set. + * + * Since: 3.0 + **/ void gtk_style_set_set_valist (GtkStyleSet *set, GtkStateFlags state, @@ -597,6 +677,16 @@ gtk_style_set_set_valist (GtkStyleSet *set, } } +/** + * gtk_style_set_set: + * @set: a #GtkStyleSet + * @state: state to set the values for + * @...: property name/value pairs, followed by %NULL + * + * Sets several style properties on @set. + * + * Since: 3.0 + **/ void gtk_style_set_set (GtkStyleSet *set, GtkStateFlags state, @@ -646,6 +736,20 @@ resolve_gradient (GtkStyleSet *set, return TRUE; } +/** + * gtk_style_set_get_property: + * @set: a #GtkStyleSet + * @property: style property name + * @state: state to retrieve the property value for + * @value: (out) (transfer full): return location for the style property value. + * + * Gets a style property from @set for the given state. When done with @value, + * g_value_unset() needs to be called to free any allocated memory. + * + * Returns: %TRUE if the property exists in @set, %FALSE otherwise + * + * Since: 3.0 + **/ gboolean gtk_style_set_get_property (GtkStyleSet *set, const gchar *property, @@ -705,6 +809,16 @@ gtk_style_set_get_property (GtkStyleSet *set, return TRUE; } +/** + * gtk_style_set_get_valist: + * @set: a #GtkStyleSet + * @state: state to retrieve the property values for + * @args: va_list of property name/return location pairs, followed by %NULL + * + * Retrieves several style property values from @set for a given state. + * + * Since: 3.0 + **/ void gtk_style_set_get_valist (GtkStyleSet *set, GtkStateFlags state, @@ -770,6 +884,17 @@ gtk_style_set_get_valist (GtkStyleSet *set, } } +/** + * gtk_style_set_get: + * @set: a #GtkStyleSet + * @state: state to retrieve the property values for + * @...: property name /return value pairs, followed by %NULL + * + * Retrieves several style property values from @set for a + * given state. + * + * Since: 3.0 + **/ void gtk_style_set_get (GtkStyleSet *set, GtkStateFlags state, @@ -784,6 +909,16 @@ gtk_style_set_get (GtkStyleSet *set, va_end (args); } +/** + * gtk_style_set_unset_property: + * @set: a #GtkStyleSet + * @property: property to unset + * @state: state to unset + * + * Unsets a style property in @set. + * + * Since: 3.0 + **/ void gtk_style_set_unset_property (GtkStyleSet *set, const gchar *property, @@ -825,6 +960,12 @@ gtk_style_set_unset_property (GtkStyleSet *set, } } +/** + * gtk_style_set_clear: + * @set: a #GtkStyleSet + * + * Clears all style information from @set. + **/ void gtk_style_set_clear (GtkStyleSet *set) { @@ -836,6 +977,19 @@ gtk_style_set_clear (GtkStyleSet *set) g_hash_table_remove_all (priv->properties); } +/** + * gtk_style_set_merge: + * @set: a #GtkStyleSet + * @set_to_merge: a second #GtkStyleSet + * @replace: whether to replace values or not + * + * Merges into @set all the style information contained + * in @set_to_merge. If @replace is %TRUE, the values + * will be overwritten, if it is %FALSE, the older values + * will prevail. + * + * Since: 3.0 + **/ void gtk_style_set_merge (GtkStyleSet *set, const GtkStyleSet *set_to_merge, diff --git a/gtk/gtkstyleset.h b/gtk/gtkstyleset.h index f81881a596..f19ce16041 100644 --- a/gtk/gtkstyleset.h +++ b/gtk/gtkstyleset.h @@ -34,16 +34,16 @@ G_BEGIN_DECLS #define GTK_IS_STYLE_SET_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), GTK_TYPE_STYLE_SET)) #define GTK_STYLE_SET_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_STYLE_SET, GtkStyleSetClass)) -typedef struct GtkStyleSet GtkStyleSet; -typedef struct GtkStyleSetClass GtkStyleSetClass; +typedef struct _GtkStyleSet GtkStyleSet; +typedef struct _GtkStyleSetClass GtkStyleSetClass; -struct GtkStyleSet +struct _GtkStyleSet { GObject parent_object; gpointer priv; }; -struct GtkStyleSetClass +struct _GtkStyleSetClass { GObjectClass parent_class; }; diff --git a/gtk/gtksymboliccolor.c b/gtk/gtksymboliccolor.c index 657ac82e3d..e803c2e1e7 100644 --- a/gtk/gtksymboliccolor.c +++ b/gtk/gtksymboliccolor.c @@ -35,7 +35,7 @@ typedef enum { COLOR_TYPE_MIX } ColorType; -struct GtkSymbolicColor +struct _GtkSymbolicColor { ColorType type; guint ref_count; @@ -68,7 +68,7 @@ struct ColorStop GtkSymbolicColor *color; }; -struct GtkGradient +struct _GtkGradient { gdouble x0; gdouble y0; @@ -82,6 +82,16 @@ struct GtkGradient guint ref_count; }; +/** + * gtk_symbolic_color_new_literal: + * @color: a #GdkColor + * + * Creates a symbolic color pointing to a literal color. + * + * Returns: a newly created #GtkSymbolicColor + * + * Since: 3.0 + **/ GtkSymbolicColor * gtk_symbolic_color_new_literal (GdkColor *color) { @@ -97,6 +107,18 @@ gtk_symbolic_color_new_literal (GdkColor *color) return symbolic_color; } +/** + * gtk_symbolic_color_new_name: + * @name: color name + * + * Creates a symbolic color pointing to an unresolved named + * color. See gtk_style_context_lookup_color() and + * gtk_style_set_lookup_color(). + * + * Returns: a newly created #GtkSymbolicColor + * + * Since: 3.0 + **/ GtkSymbolicColor * gtk_symbolic_color_new_name (const gchar *name) { @@ -112,6 +134,20 @@ gtk_symbolic_color_new_name (const gchar *name) return symbolic_color; } +/** + * gtk_symbolic_color_new_shade: + * @color: another #GtkSymbolicColor + * @factor: shading factor to apply to @color + * + * Creates a symbolic color defined as a shade of + * another color. A factor > 1.0 would resolve to + * a brighter color, while < 1.0 would resolve to + * a darker color. + * + * Returns: A newly created #GtkSymbolicColor + * + * Since: 3.0 + **/ GtkSymbolicColor * gtk_symbolic_color_new_shade (GtkSymbolicColor *color, gdouble factor) @@ -129,6 +165,20 @@ gtk_symbolic_color_new_shade (GtkSymbolicColor *color, return symbolic_color; } +/** + * gtk_symbolic_color_new_mix: + * @color1: color to mix + * @color2: another color to mix + * @factor: mix factor + * + * Creates a symbolic color defined as a mix of another + * two colors. a mix factor of 0 would resolve to @color1, + * while a factor of 1 would resolve to @color2. + * + * Returns: A newly created #GtkSymbolicColor + * + * Since: 3.0 + **/ GtkSymbolicColor * gtk_symbolic_color_new_mix (GtkSymbolicColor *color1, GtkSymbolicColor *color2, @@ -149,6 +199,16 @@ gtk_symbolic_color_new_mix (GtkSymbolicColor *color1, return symbolic_color; } +/** + * gtk_symbolic_color_ref: + * @color: a #GtkSymbolicColor + * + * Increases the reference count of @color + * + * Returns: the same @color + * + * Since: 3.0 + **/ GtkSymbolicColor * gtk_symbolic_color_ref (GtkSymbolicColor *color) { @@ -159,6 +219,15 @@ gtk_symbolic_color_ref (GtkSymbolicColor *color) return color; } +/** + * gtk_symbolic_color_unref: + * @color: a #GtkSymbolicColor + * + * Decreases the reference count of @color, freeing its memory if the + * reference count reaches 0. + * + * Since: 3.0 + **/ void gtk_symbolic_color_unref (GtkSymbolicColor *color) { @@ -188,6 +257,21 @@ gtk_symbolic_color_unref (GtkSymbolicColor *color) } } +/** + * gtk_symbolic_color_resolve: + * @color: a #GtkSymbolicColor + * @style_set: #GtkStyleSet to use when resolving named colors + * @resolved_color: (out): return location for the resolved color + * + * If @color is resolvable, @resolved_color will be filled in + * with the resolved color, and %TRUE will be returned. Generally, + * if @color can't be resolved, it is due to it being defined on + * top of a named color that doesn't exist in @style_set. + * + * Returns: %TRUE if the color has been resolved + * + * Since: 3.0 + **/ gboolean gtk_symbolic_color_resolve (GtkSymbolicColor *color, GtkStyleSet *style_set, @@ -256,6 +340,20 @@ gtk_symbolic_color_resolve (GtkSymbolicColor *color, } /* GtkGradient */ +/** + * gtk_gradient_new_linear: + * @x0: X coordinate of the starting point + * @y0: Y coordinate of the starting point + * @x1: X coordinate of the end point + * @y1: Y coordinate of the end point + * + * Creates a new linear gradient along the line defined by (x0, y0) and (x1, y1). Before using the gradient + * a number of stop colors must be added through gtk_gradient_add_color_stop(). + * + * Returns: A newly created #GtkGradient + * + * Since: 3.0 + **/ GtkGradient * gtk_gradient_new_linear (gdouble x0, gdouble y0, @@ -279,6 +377,23 @@ gtk_gradient_new_linear (gdouble x0, return gradient; } +/** + * gtk_gradient_new_radial: + * @x0: X coordinate of the start circle + * @y0: Y coordinate of the start circle + * @radius0: radius of the start circle + * @x1: X coordinate of the end circle + * @y1: Y coordinate of the end circle + * @radius1: radius of the end circle + * + * Creates a new radial gradient along the two circles defined by (x0, y0, radius0) and + * (x1, y1, radius1). Before using the gradient a number of stop colors must be added + * through gtk_gradient_add_color_stop(). + * + * Returns: A newly created #GtkGradient + * + * Since: 3.0 + **/ GtkGradient * gtk_gradient_new_radial (gdouble x0, gdouble y0, @@ -304,6 +419,16 @@ gtk_gradient_new_radial (gdouble x0, return gradient; } +/** + * gtk_gradient_add_color_stop: + * @gradient: a #GtkGradient + * @offset: offset for the color stop + * @color: color to use + * + * Adds a stop color to @gradient. + * + * Since: 3.0 + **/ void gtk_gradient_add_color_stop (GtkGradient *gradient, gdouble offset, @@ -319,6 +444,16 @@ gtk_gradient_add_color_stop (GtkGradient *gradient, g_array_append_val (gradient->stops, stop); } +/** + * gtk_gradient_ref: + * @gradient: a #GtkGradient + * + * Increases the reference count of @gradient. + * + * Returns: The same @gradient + * + * Since: 3.0 + **/ GtkGradient * gtk_gradient_ref (GtkGradient *gradient) { @@ -329,6 +464,15 @@ gtk_gradient_ref (GtkGradient *gradient) return gradient; } +/** + * gtk_gradient_unref: + * @gradient: a #GtkGradient + * + * Decreases the reference count of @gradient, freeing its memory + * if the reference count reaches 0. + * + * Since: 3.0 + **/ void gtk_gradient_unref (GtkGradient *gradient) { @@ -353,6 +497,22 @@ gtk_gradient_unref (GtkGradient *gradient) } } +/** + * gtk_gradient_resolve: + * @gradient: a #GtkGradient + * @style_set: #GtkStyleSet to use when resolving named colors + * @resolved_gradient: (out): return location for the resolved pattern + * + * If @gradient is resolvable, @resolved_gradient will be filled in + * with the resolved gradient as a cairo_pattern_t, and %TRUE will + * be returned. Generally, if @gradient can't be resolved, it is + * due to it being defined on top of a named color that doesn't + * exist in @style_set. + * + * Returns: %TRUE if the gradient has been resolved + * + * Since: 3.0 + **/ gboolean gtk_gradient_resolve (GtkGradient *gradient, GtkStyleSet *style_set, diff --git a/gtk/gtksymboliccolor.h b/gtk/gtksymboliccolor.h index de403a325f..e326992a33 100644 --- a/gtk/gtksymboliccolor.h +++ b/gtk/gtksymboliccolor.h @@ -25,8 +25,8 @@ G_BEGIN_DECLS /* Dummy typedefs */ -typedef struct GtkSymbolicColor GtkSymbolicColor; -typedef struct GtkGradient GtkGradient; +typedef struct _GtkSymbolicColor GtkSymbolicColor; +typedef struct _GtkGradient GtkGradient; #define GTK_TYPE_SYMBOLIC_COLOR (gtk_symbolic_color_get_type ()) #define GTK_TYPE_GRADIENT (gtk_gradient_get_type ()) diff --git a/gtk/gtkthemingengine.c b/gtk/gtkthemingengine.c index 5096996e57..f72e6a6686 100644 --- a/gtk/gtkthemingengine.c +++ b/gtk/gtkthemingengine.c @@ -29,6 +29,23 @@ #include "gtk9slice.h" #include "gtkpango.h" +/** + * SECTION:gtkthemingengine + * @Short_description: Theming renderers + * @Title: GtkThemingEngine + * @See_also: #GtkStyleContext + * + * #GtkThemingEngine is the object used for rendering themed content + * in GTK+ widgets. Even though GTK+ has a default implementation, + * it can be overridden in CSS files by enforcing a #GtkThemingEngine + * object to be loaded as a module. + * + * In order to implement a theming engine, a #GtkThemingEngine subclass + * must be created, alongside the CSS file that will reference it, the + * theming engine would be created as an .so library, and installed in + * $(gtk-modules-dir)/theming-engines/. + */ + typedef struct GtkThemingEnginePrivate GtkThemingEnginePrivate; enum { @@ -194,6 +211,45 @@ _gtk_theming_engine_set_context (GtkThemingEngine *engine, priv->context = context; } +/** + * gtk_theming_engine_register_property: + * @engine: a #GtkThemingEngine + * @property_name: property name to register + * @type: #GType the property will hold + * @default_value: default value for this property + * @parse_func: parsing function to use, or %NULL + * + * Registers a property so it can be used in the CSS file format, + * on the CSS file the property will look like + * "-${engine-object-name}-${@property_name}". being + * ${engine-object-name} the same than G_OBJECT_TYPE_NAME(engine) + * would return. + * + * For any type a @parse_func may be provided, being this function + * used for turning any property value (between ':' and ';') in + * CSS to the #GValue needed. For basic types there is already + * builtin parsing support, so %NULL may be provided for these + * cases. + * + * + * This function needs to be called only once during theming + * engine object initialization. + * + * + * + * In order to make use of the custom registered properties in + * the CSS file, make sure the engine is loaded first either in + * a previous rule or within the same one. + * + * * { + * engine: someengine; + * SomeEngine-custom-property: 2; + * } + * + * + * + * Since: 3.0 + **/ void gtk_theming_engine_register_property (GtkThemingEngine *engine, const gchar *property_name, @@ -213,6 +269,20 @@ gtk_theming_engine_register_property (GtkThemingEngine *engine, g_free (name); } +/** + * gtk_theming_engine_get_property: + * @engine: a #GtkThemingEngine + * @property: the property name + * @state: state to retrieve the value for + * @value: (out) (transfer full): return location for the property value, + * you must free this memory using g_value_unset() once you are + * done with it. + * + * Gets a property value as retrieved from the style settings that apply + * to the currently rendered element. + * + * Since: 3.0 + **/ void gtk_theming_engine_get_property (GtkThemingEngine *engine, const gchar *property, @@ -229,6 +299,17 @@ gtk_theming_engine_get_property (GtkThemingEngine *engine, gtk_style_context_get_property (priv->context, property, state, value); } +/** + * gtk_theming_engine_get_valist: + * @engine: a #GtkThemingEngine + * @state: state to retrieve values for + * @args: va_list of property name/return location pairs, followed by %NULL + * + * Retrieves several style property values that apply to the currently + * rendered element. + * + * Since: 3.0 + **/ void gtk_theming_engine_get_valist (GtkThemingEngine *engine, GtkStateFlags state, @@ -242,6 +323,17 @@ gtk_theming_engine_get_valist (GtkThemingEngine *engine, gtk_style_context_get_valist (priv->context, state, args); } +/** + * gtk_theming_engine_get: + * @engine: a #GtkThemingEngine + * @state: state to retrieve values for + * @...: property name /return value pairs, followed by %NULL + * + * Retrieves several style property values that apply to the currently + * rendered element. + * + * Since: 3.0 + **/ void gtk_theming_engine_get (GtkThemingEngine *engine, GtkStateFlags state, @@ -259,6 +351,17 @@ gtk_theming_engine_get (GtkThemingEngine *engine, va_end (args); } +/** + * gtk_theming_engine_get_style_property: + * @engine: a #GtkThemingEngine + * @property_name: the name of the widget style property + * @value: (out) (transfer full): Return location for the property value, free with + * g_value_unset() after use. + * + * Gets the value for a widget style property. + * + * Since: 3.0 + **/ void gtk_theming_engine_get_style_property (GtkThemingEngine *engine, const gchar *property_name, @@ -273,6 +376,16 @@ gtk_theming_engine_get_style_property (GtkThemingEngine *engine, gtk_style_context_get_style_property (priv->context, property_name, value); } +/** + * gtk_theming_engine_get_style_valist: + * @engine: a #GtkThemingEngine + * @args: va_list of property name/return location pairs, followed by %NULL + * + * Retrieves several widget style properties from @engine according to the + * currently rendered content's style. + * + * Since: 3.0 + **/ void gtk_theming_engine_get_style_valist (GtkThemingEngine *engine, va_list args) @@ -285,6 +398,16 @@ gtk_theming_engine_get_style_valist (GtkThemingEngine *engine, gtk_style_context_get_style_valist (priv->context, args); } +/** + * gtk_theming_engine_get_style: + * @engine: a #GtkThemingEngine + * @...: property name /return value pairs, followed by %NULL + * + * Retrieves several widget style properties from @engine according + * to the currently rendered content's style. + * + * Since: 3.0 + **/ void gtk_theming_engine_get_style (GtkThemingEngine *engine, ...) @@ -301,6 +424,16 @@ gtk_theming_engine_get_style (GtkThemingEngine *engine, va_end (args); } +/** + * gtk_theming_engine_get_state: + * @engine: a #GtkThemingEngine + * + * returns the state used when rendering. + * + * Returns: the state flags + * + * Since: 3.0 + **/ GtkStateFlags gtk_theming_engine_get_state (GtkThemingEngine *engine) { @@ -325,6 +458,16 @@ gtk_theming_engine_is_state_set (GtkThemingEngine *engine, return gtk_style_context_is_state_set (priv->context, state, progress); } +/** + * gtk_theming_engine_get_path: + * @engine: a #GtkThemingEngine + * + * Returns the widget path used for style matching. + * + * Returns: (transfer none): A #GtkWidgetPath + * + * Since: 3.0 + **/ G_CONST_RETURN GtkWidgetPath * gtk_theming_engine_get_path (GtkThemingEngine *engine) { @@ -336,6 +479,18 @@ gtk_theming_engine_get_path (GtkThemingEngine *engine) return gtk_style_context_get_path (priv->context); } +/** + * gtk_theming_engine_has_class: + * @engine: a #GtkThemingEngine + * @style_class: class name to look up + * + * Returns %TRUE if the currently rendered contents have + * defined the given class name. + * + * Returns: %TRUE if @engine has @class_name defined + * + * Since: 3.0 + **/ gboolean gtk_theming_engine_has_class (GtkThemingEngine *engine, const gchar *style_class) @@ -348,9 +503,23 @@ gtk_theming_engine_has_class (GtkThemingEngine *engine, return gtk_style_context_has_class (priv->context, style_class); } +/** + * gtk_theming_engine_has_region: + * @engine: a #GtkThemingEngine + * @style_region: a region name + * @flags: (out) (allow-none): return location for region flags + * + * Returns %TRUE if the currently rendered contents have the + * region defined. If @flags_return is not %NULL, it is set + * to the flags affecting the region. + * + * Returns: %TRUE if region is defined + * + * Since: 3.0 + **/ gboolean gtk_theming_engine_has_region (GtkThemingEngine *engine, - const gchar *style_class, + const gchar *style_region, GtkRegionFlags *flags) { GtkThemingEnginePrivate *priv; @@ -361,9 +530,19 @@ gtk_theming_engine_has_region (GtkThemingEngine *engine, g_return_val_if_fail (GTK_IS_THEMING_ENGINE (engine), FALSE); priv = engine->priv; - return gtk_style_context_has_region (priv->context, style_class, flags); + return gtk_style_context_has_region (priv->context, style_region, flags); } +/** + * gtk_theming_engine_get_direction: + * @engine: a #GtkThemingEngine + * + * Returns the widget direction used for rendering. + * + * Returns: the widget direction + * + * Since: 3.0 + **/ GtkTextDirection gtk_theming_engine_get_direction (GtkThemingEngine *engine) { @@ -375,6 +554,16 @@ gtk_theming_engine_get_direction (GtkThemingEngine *engine) return gtk_style_context_get_direction (priv->context); } +/** + * gtk_theming_engine_get_junction_sides: + * @engine: a #GtkThemingEngine + * + * Returns the widget direction used for rendering. + * + * Returns: the widget direction + * + * Since: 3.0 + **/ GtkJunctionSides gtk_theming_engine_get_junction_sides (GtkThemingEngine *engine) { @@ -441,6 +630,16 @@ gtk_theming_module_init (GtkThemingModule *module) { } +/** + * gtk_theming_engine_load: + * @name: Theme engine name to load + * + * Loads and initializes a theming engine module from the + * standard directories. + * + * Returns: (transfer none): A theming engine, or %NULL if + * the engine @name doesn't exist. + **/ GtkThemingEngine * gtk_theming_engine_load (const gchar *name) { @@ -484,6 +683,14 @@ gtk_theming_engine_load (const gchar *name) return engine; } +/** + * gtk_theming_engine_get_screen: + * @engine: a #GtkThemingEngine + * + * Returns the #GdkScreen to which @engine currently rendering to. + * + * Returns: a #GdkScreen, or %NULL. + **/ GdkScreen * gtk_theming_engine_get_screen (GtkThemingEngine *engine) { diff --git a/gtk/gtkthemingengine.h b/gtk/gtkthemingengine.h index 47a4234f4b..6ecf9c1009 100644 --- a/gtk/gtkthemingengine.h +++ b/gtk/gtkthemingengine.h @@ -36,16 +36,36 @@ G_BEGIN_DECLS #define GTK_IS_THEMING_ENGINE_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), GTK_TYPE_THEMING_ENGINE)) #define GTK_THEMING_ENGINE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_THEMING_ENGINE, GtkThemingEngineClass)) -typedef struct GtkThemingEngine GtkThemingEngine; -typedef struct GtkThemingEngineClass GtkThemingEngineClass; +typedef struct _GtkThemingEngine GtkThemingEngine; +typedef struct _GtkThemingEngineClass GtkThemingEngineClass; -struct GtkThemingEngine +struct _GtkThemingEngine { GObject parent_object; gpointer priv; }; -struct GtkThemingEngineClass +/** + * GtkThemingEngineClass + * @parent_class: The parent class. + * @render_line: Renders a line between two points. + * @render_background: Renders the background area of a widget region. + * @render_frame: Renders the frame around a widget area. + * @render_frame_gap: Renders the frame around a widget area with a gap in it. + * @render_extension: Renders a extension to a box, usually a notebook tab. + * @render_check: Renders a checkmark, as in #GtkCheckButton. + * @render_option: Renders an option, as in #GtkRadioButton. + * @render_arrow: Renders an arrow pointing to a certain direction. + * @render_expander: Renders an element what will expose/expand part of + * the UI, as in #GtkExpander. + * @render_focus: Renders the focus indicator. + * @render_layout: Renders a #PangoLayout + * @render_slider: Renders a slider control, as in #GtkScale. + * @render_handle: Renders a handle to drag UI elements, as in #GtkPaned. + * + * Base class for theming engines. + */ +struct _GtkThemingEngineClass { GObjectClass parent_class; diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 8ab15be5e2..d1765ec4c7 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -13270,6 +13270,16 @@ _gtk_widget_set_height_request_needed (GtkWidget *widget, widget->priv->height_request_needed = height_request_needed; } +/** + * gtk_widget_get_path: + * @widget: a #GtkWidget + * + * Returns the #GtkWidgetPath representing @widget, if the widget + * is not connected to a toplevel widget, a partial path will be + * created. + * + * Returns: (transfer none): The #GtkWidgetPath representing @widget + **/ GtkWidgetPath * gtk_widget_get_path (GtkWidget *widget) { @@ -13312,6 +13322,15 @@ style_context_changed (GtkStyleContext *context, g_signal_emit (widget, widget_signals[STYLE_UPDATED], 0); } +/** + * gtk_widget_get_style_context: + * @widget: a #GtkWidget + * + * Returns the style context associated to @widget. + * + * Returns: (transfer none): a #GtkStyleContext. This memory is owned by @widget and + * must not be freed. + **/ GtkStyleContext * gtk_widget_get_style_context (GtkWidget *widget) { diff --git a/gtk/gtkwidgetpath.c b/gtk/gtkwidgetpath.c index c6cfbb5c81..578335b8e7 100644 --- a/gtk/gtkwidgetpath.c +++ b/gtk/gtkwidgetpath.c @@ -24,6 +24,62 @@ #include "gtkwidget.h" #include "gtkwidgetpath.h" +/** + * SECTION:gtkwidgetpath + * @Short_description: Widget path abstraction + * @Title: GtkWidgetPath + * @See_also: #GtkStyleContext + * + * #GtkWidgetPath is an struct that represents a widget hierarchy from + * the topmost widget, typically a toplevel, to any child. This widget + * path abstraction is used in #GtkStyleContext on behalf of the real + * widget in order to query style information. + * + * If you are using GTK+ widgets, there are many chances you don't + * need this API directly, as there is gtk_widget_get_path(), and the + * style context returned by gtk_widget_get_style_context() will be + * automatically updated on widget hierarchy changes. + * + * The widget path generation is generally simple: + * + * Defining a button within a window + * + * { + * GtkWidgetPath *path; + * + * path = gtk_widget_path_new (); + * gtk_widget_path_append_type (path, GTK_TYPE_WINDOW); + * gtk_widget_path_append_type (path, GTK_TYPE_BUTTON); + * } + * + * + * + * Although more complex information, such as widget names, or + * different classes (property that may be used by other widget + * types) and intermediate regions may be included: + * + * + * Defining the first tab widget in a notebook + * + * { + * GtkWidgetPath *path; + * guint pos; + * + * path = gtk_widget_path_new (); + * + * pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK); + * gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST); + * + * pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL); + * gtk_widget_path_iter_set_name (path, pos, "first tab label"); + * } + * + * + * + * All this information will be used to match the style information + * that applies to the described widget. + **/ + typedef struct GtkPathElement GtkPathElement; struct GtkPathElement @@ -34,11 +90,20 @@ struct GtkPathElement GArray *classes; }; -struct GtkWidgetPath +struct _GtkWidgetPath { GArray *elems; /* First element contains the described widget */ }; +/** + * gtk_widget_path_new: + * + * Returns an empty widget path. + * + * Returns: (transfer full): A newly created, empty, #GtkWidgetPath + * + * Since: 3.0 + **/ GtkWidgetPath * gtk_widget_path_new (void) { @@ -50,6 +115,16 @@ gtk_widget_path_new (void) return path; } +/** + * gtk_widget_path_copy: + * @path: a #GtkWidgetPath + * + * Returns a copy of @path + * + * Returns: (transfer full): a copy of @path + * + * Since: 3.0 + **/ GtkWidgetPath * gtk_widget_path_copy (const GtkWidgetPath *path) { @@ -87,6 +162,14 @@ gtk_widget_path_copy (const GtkWidgetPath *path) return new_path; } +/** + * gtk_widget_path_free: + * @path: a #GtkWidgetPath + * + * Frees a #GtkWidgetPath. + * + * Since: 3.0 + **/ void gtk_widget_path_free (GtkWidgetPath *path) { @@ -111,6 +194,17 @@ gtk_widget_path_free (GtkWidgetPath *path) g_slice_free (GtkWidgetPath, path); } +/** + * gtk_widget_path_length: + * @path: a #GtkWidgetPath + * + * Returns the number of #GtkWidget #GTypes between the represented + * widget and its topmost container. + * + * Returns: the number of elements in the path + * + * Since: 3.0 + **/ guint gtk_widget_path_length (const GtkWidgetPath *path) { @@ -119,6 +213,17 @@ gtk_widget_path_length (const GtkWidgetPath *path) return path->elems->len; } +/** + * gtk_widget_path_prepend_type: + * @path: a #GtkWidgetPath + * @type: widget type to prepend + * + * Prepends a widget type to the widget hierachy represented by @path. + * + * Returns: the position where the element was inserted + * + * Since: 3.0 + **/ guint gtk_widget_path_prepend_type (GtkWidgetPath *path, GType type) @@ -134,6 +239,17 @@ gtk_widget_path_prepend_type (GtkWidgetPath *path, return 0; } +/** + * gtk_widget_path_append_type: + * @path: a #GtkWidgetPath + * @type: widget type to append + * + * Appends a widget type to the widget hierachy represented by @path. + * + * Returns: the position where the element was inserted + * + * Since: 3.0 + **/ guint gtk_widget_path_append_type (GtkWidgetPath *path, GType type) @@ -149,6 +265,18 @@ gtk_widget_path_append_type (GtkWidgetPath *path, return path->elems->len - 1; } +/** + * gtk_widget_path_iter_get_widget_type: + * @path: a #GtkWidgetPath + * @pos: position to get the widget type for + * + * Returns the widget #GType that is at position @pos in the widget + * hierarchy defined in @path. + * + * Returns: a widget type + * + * Since: 3.0 + **/ GType gtk_widget_path_iter_get_widget_type (const GtkWidgetPath *path, guint pos) @@ -162,6 +290,17 @@ gtk_widget_path_iter_get_widget_type (const GtkWidgetPath *path, return elem->type; } +/** + * gtk_widget_path_iter_set_widget_type: + * @path: a #GtkWidgetPath + * @pos: position to modify + * @type: widget type to set + * + * Sets the widget type for a given position in the widget hierarchy + * defined by @path. @type must be a #GtkWidget derived #GType. + * + * Since: 3.0 + **/ void gtk_widget_path_iter_set_widget_type (GtkWidgetPath *path, guint pos, @@ -177,6 +316,17 @@ gtk_widget_path_iter_set_widget_type (GtkWidgetPath *path, elem->type = type; } +/** + * gtk_widget_path_iter_get_name: + * @path: a #GtkWidgetPath + * @pos: position to get the widget name for + * + * Returns the name corresponding to the widget found at + * the position @pos in the widget hierarchy defined by + * @path + * + * Returns: The widget name, or %NULL if none was set. + **/ G_CONST_RETURN gchar * gtk_widget_path_iter_get_name (const GtkWidgetPath *path, guint pos) @@ -190,6 +340,17 @@ gtk_widget_path_iter_get_name (const GtkWidgetPath *path, return g_quark_to_string (elem->name); } +/** + * gtk_widget_path_iter_set_name: + * @path: a #GtkWidgetPath + * @pos: position to modify + * @name: widget name + * + * Sets the widget name for the widget found at position @pos + * in the widget hierarchy defined by @path. + * + * Since: 3.0 + **/ void gtk_widget_path_iter_set_name (GtkWidgetPath *path, guint pos, @@ -206,6 +367,19 @@ gtk_widget_path_iter_set_name (GtkWidgetPath *path, elem->name = g_quark_from_string (name); } +/** + * gtk_widget_path_iter_has_qname: + * @path: a #GtkWidgetPath + * @pos: position to query + * @qname: widget name as a #GQuark + * + * See gtk_widget_path_iter_has_name(). This is a version + * that operates on #GQuarks. + * + * Returns: %TRUE if the widget at @pos has this name + * + * Since: 3.0 + **/ gboolean gtk_widget_path_iter_has_qname (const GtkWidgetPath *path, guint pos, @@ -222,6 +396,19 @@ gtk_widget_path_iter_has_qname (const GtkWidgetPath *path, return (elem->name == qname); } +/** + * gtk_widget_path_iter_has_name: + * @path: a #GtkWidgetPath + * @pos: position to query + * @name: a widget name + * + * Returns %TRUE if the widget at position @pos has the name @name, + * %FALSE otherwise. + * + * Returns: %TRUE if the widget at @pos has this name + * + * Since: 3.0 + **/ gboolean gtk_widget_path_iter_has_name (const GtkWidgetPath *path, guint pos, @@ -241,6 +428,18 @@ gtk_widget_path_iter_has_name (const GtkWidgetPath *path, return gtk_widget_path_iter_has_qname (path, pos, qname); } +/** + * gtk_widget_path_iter_add_class: + * @path: a #GtkWidget + * @pos: position to modify + * @name: a class name + * + * Adds the class @name to the widget at position @pos in + * the hierarchy defined in @path. See + * gtk_style_context_set_class(). + * + * Since: 3.0 + **/ void gtk_widget_path_iter_add_class (GtkWidgetPath *path, guint pos, @@ -285,6 +484,17 @@ gtk_widget_path_iter_add_class (GtkWidgetPath *path, g_array_append_val (elem->classes, qname); } +/** + * gtk_widget_path_iter_remove_class: + * @path: a #GtkWidgetPath + * @pos: position to modify + * @name: class name + * + * Removes the class @name from the widget at position @pos in + * the hierarchy defined in @path. + * + * Since: 3.0 + **/ void gtk_widget_path_iter_remove_class (GtkWidgetPath *path, guint pos, @@ -324,6 +534,16 @@ gtk_widget_path_iter_remove_class (GtkWidgetPath *path, } } +/** + * gtk_widget_path_iter_clear_classes: + * @path: a #GtkWidget + * @pos: position to modify + * + * Removes all classes from the widget at position @pos in the + * hierarchy defined in @path. + * + * Since: 3.0 + **/ void gtk_widget_path_iter_clear_classes (GtkWidgetPath *path, guint pos) @@ -342,6 +562,21 @@ gtk_widget_path_iter_clear_classes (GtkWidgetPath *path, g_array_remove_range (elem->classes, 0, elem->classes->len); } +/** + * gtk_widget_path_iter_list_classes: + * @path: a #GtkWidgetPath + * @pos: position to query + * + * Returns a list with all the class names defined for the widget + * at position @pos in the hierarchy defined in @path. + * + * Returns: (transfer container) (type utf8): The list of classes, + * This is a list of strings, the #GSList contents are + * owned by GTK+, but you should use g_slist_free() to + * free the list itself. + * + * Since: 3.0 + **/ GSList * gtk_widget_path_iter_list_classes (const GtkWidgetPath *path, guint pos) @@ -369,6 +604,19 @@ gtk_widget_path_iter_list_classes (const GtkWidgetPath *path, return g_slist_reverse (list); } +/** + * gtk_widget_path_iter_has_qclass: + * @path: a #GtkWidgetPath + * @pos: position to query + * @qname: class name as a #GQuark + * + * See gtk_widget_path_iter_has_class(). This is a version that operates + * with GQuarks. + * + * Returns: %TRUE if the widget at @pos has the class defined. + * + * Since: 3.0 + **/ gboolean gtk_widget_path_iter_has_qclass (const GtkWidgetPath *path, guint pos, @@ -401,6 +649,19 @@ gtk_widget_path_iter_has_qclass (const GtkWidgetPath *path, return FALSE; } +/** + * gtk_widget_path_iter_has_class: + * @path: a #GtkWidgetPath + * @pos: position to query + * @name: class name + * + * Returns %TRUE if the widget at position @pos has the class @name + * defined, %FALSE otherwise. + * + * Returns: %TRUE if the class @name is defined for the widget at @pos + * + * Since: 3.0 + **/ gboolean gtk_widget_path_iter_has_class (const GtkWidgetPath *path, guint pos, @@ -420,6 +681,19 @@ gtk_widget_path_iter_has_class (const GtkWidgetPath *path, return gtk_widget_path_iter_has_qclass (path, pos, qname); } +/** + * gtk_widget_path_iter_add_region: + * @path: a #GtkWidgetPath + * @pos: position to modify + * @name: region name + * @flags: flags affecting the region + * + * Adds the region @name to the widget at position @pos in + * the hierarchy defined in @path. See + * gtk_style_context_set_region(). + * + * Since: 3.0 + **/ void gtk_widget_path_iter_add_region (GtkWidgetPath *path, guint pos, @@ -444,6 +718,17 @@ gtk_widget_path_iter_add_region (GtkWidgetPath *path, GUINT_TO_POINTER (flags)); } +/** + * gtk_widget_path_iter_remove_region: + * @path: a #GtkWidgetPath + * @pos: position to modify + * @name: region name + * + * Removes the region @name from the widget at position @pos in + * the hierarchy defined in @path. + * + * Since: 3.0 + **/ void gtk_widget_path_iter_remove_region (GtkWidgetPath *path, guint pos, @@ -467,6 +752,16 @@ gtk_widget_path_iter_remove_region (GtkWidgetPath *path, g_hash_table_remove (elem->regions, GUINT_TO_POINTER (qname)); } +/** + * gtk_widget_path_iter_clear_regions: + * @path: a #GtkWidgetPath + * @pos: position to modify + * + * Removes all regions from the widget at position @pos in the + * hierarchy defined in @path. + * + * Since: 3.0 + **/ void gtk_widget_path_iter_clear_regions (GtkWidgetPath *path, guint pos) @@ -482,6 +777,21 @@ gtk_widget_path_iter_clear_regions (GtkWidgetPath *path, g_hash_table_remove_all (elem->regions); } +/** + * gtk_widget_path_iter_list_regions: + * @path: a #GtkWidgetPath + * @pos: position to query + * + * Returns a list with all the region names defined for the widget + * at position @pos in the hierarchy defined in @path. + * + * Returns: (transfer container) (type utf8): The list of regions, + * This is a list of strings, the #GSList contents are + * owned by GTK+, but you should use g_slist_free() to + * free the list itself. + * + * Since: 3.0 + **/ GSList * gtk_widget_path_iter_list_regions (const GtkWidgetPath *path, guint pos) @@ -512,6 +822,20 @@ gtk_widget_path_iter_list_regions (const GtkWidgetPath *path, return list; } +/** + * gtk_widget_path_iter_has_qregion: + * @path: a #GtkWidgetPath + * @pos: position to query + * @qname: region name as a #GQuark + * @flags: (out): return location for the region flags + * + * See gtk_widget_path_iter_has_region(). This is a version that operates + * with GQuarks. + * + * Returns: %TRUE if the widget at @pos has the region defined. + * + * Since: 3.0 + **/ gboolean gtk_widget_path_iter_has_qregion (const GtkWidgetPath *path, guint pos, @@ -541,6 +865,20 @@ gtk_widget_path_iter_has_qregion (const GtkWidgetPath *path, return TRUE; } +/** + * gtk_widget_path_iter_has_region: + * @path: a #GtkWidgetPath + * @pos: position to query + * @name: region name + * @flags: (out): return location for the region flags + * + * Returns %TRUE if the widget at position @pos has the class @name + * defined, %FALSE otherwise. + * + * Returns: %TRUE if the class @name is defined for the widget at @pos + * + * Since: 3.0 + **/ gboolean gtk_widget_path_iter_has_region (const GtkWidgetPath *path, guint pos, @@ -561,6 +899,17 @@ gtk_widget_path_iter_has_region (const GtkWidgetPath *path, return gtk_widget_path_iter_has_qregion (path, pos, qname, flags); } +/** + * gtk_widget_path_get_widget_type: + * @path: a #GtkWidget + * + * Returns the topmost widget type, that is, the widget type this path + * is representing. + * + * Returns: The widget type + * + * Since: 3.0 + **/ GType gtk_widget_path_get_widget_type (const GtkWidgetPath *path) { @@ -568,10 +917,23 @@ gtk_widget_path_get_widget_type (const GtkWidgetPath *path) g_return_val_if_fail (path != NULL, G_TYPE_INVALID); - elem = &g_array_index (path->elems, GtkPathElement, 0); + elem = &g_array_index (path->elems, GtkPathElement, + path->elems->len - 1); return elem->type; } +/** + * gtk_widget_path_is_type: + * @path: a #GtkWidgetPath + * @type: widget type to match + * + * Returns %TRUE if the widget type represented by this path + * is @type, or a subtype of it. + * + * Returns: %TRUE if the widget represented by @path is of type @type + * + * Since: 3.0 + **/ gboolean gtk_widget_path_is_type (const GtkWidgetPath *path, GType type) @@ -581,7 +943,8 @@ gtk_widget_path_is_type (const GtkWidgetPath *path, g_return_val_if_fail (path != NULL, FALSE); g_return_val_if_fail (g_type_is_a (type, GTK_TYPE_WIDGET), FALSE); - elem = &g_array_index (path->elems, GtkPathElement, 0); + elem = &g_array_index (path->elems, GtkPathElement, + path->elems->len - 1); if (elem->type == type || g_type_is_a (elem->type, type)) @@ -590,6 +953,18 @@ gtk_widget_path_is_type (const GtkWidgetPath *path, return FALSE; } +/** + * gtk_widget_path_has_parent: + * @path: a #GtkWidgetPath + * @type: widget type to check in parents + * + * Returns %TRUE if any of the parents of the widget represented + * in @path is of type @type, or any subtype of it. + * + * Returns: %TRUE if any parent is of type @type + * + * Since: 3.0 + **/ gboolean gtk_widget_path_has_parent (const GtkWidgetPath *path, GType type) @@ -599,7 +974,7 @@ gtk_widget_path_has_parent (const GtkWidgetPath *path, g_return_val_if_fail (path != NULL, FALSE); g_return_val_if_fail (g_type_is_a (type, GTK_TYPE_WIDGET), FALSE); - for (i = 1; i < path->elems->len; i++) + for (i = 0; i < path->elems->len - 1; i++) { GtkPathElement *elem; diff --git a/gtk/gtkwidgetpath.h b/gtk/gtkwidgetpath.h index 4e5c4769cb..f36ebcb830 100644 --- a/gtk/gtkwidgetpath.h +++ b/gtk/gtkwidgetpath.h @@ -25,7 +25,7 @@ G_BEGIN_DECLS -typedef struct GtkWidgetPath GtkWidgetPath; +typedef struct _GtkWidgetPath GtkWidgetPath; GtkWidgetPath * gtk_widget_path_new (void);