From a5e10e9b260fbae666ae3f3ef3dd37be18b4001a Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 23 Nov 2010 01:05:11 -0500 Subject: [PATCH] Improve some gtk_render_ docs With pictures !! --- docs/reference/gtk/Makefile.am | 4 +- docs/reference/gtk/images/checks.png | Bin 0 -> 529 bytes docs/reference/gtk/images/options.png | Bin 0 -> 1048 bytes gtk/gtkcssprovider.c | 70 ++++++++---- gtk/gtkstylecontext.c | 158 +++++++++++++++----------- 5 files changed, 144 insertions(+), 88 deletions(-) create mode 100644 docs/reference/gtk/images/checks.png create mode 100644 docs/reference/gtk/images/options.png diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 0ce22bcf38..5adc949562 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -341,7 +341,9 @@ HTML_IMAGES = \ $(srcdir)/images/border1.png \ $(srcdir)/images/border2.png \ $(srcdir)/images/border3.png \ - $(srcdir)/images/slices.png + $(srcdir)/images/slices.png \ + $(srcdir)/images/checks.png \ + $(srcdir)/images/options.png # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=../gdk/html \ diff --git a/docs/reference/gtk/images/checks.png b/docs/reference/gtk/images/checks.png new file mode 100644 index 0000000000000000000000000000000000000000..143043a274b065cb0d40640b3f4fc9e46d634cf5 GIT binary patch literal 529 zcmeAS@N?(olHy`uVBq!ia0vp^IY6w+!2~2Vf@j+SDdu7)&kzm{j@u9Y9{{ln@} zck|LW-%K(3Xmfts+rtkHBzUr(WXvkF6Pu*scqO9UO?BP%?AYt#-L4|8r=M>6CG&&% z`JRexW$~I?8e8IU4EIjJ$h}};)^TF z`ds40CmKYw9bT9yv9mpCv|89ZJ6T-G@yGywp^%;5|2JHG`K zb8&r4&vsfpF-1DBX!TN#6W5BPw{DFJ>ziPoRln@4S#+^&$mTcwQQMa(h2)>zy7A^F zAiC;8+j$=az{*LalunDFL<;?0N7n+~^wCFbi!uAedM+wHgKK6ZAtwr+^fNxJfC z*Dm8zmuwjt=7im9nYYjG_m3abJxq4RYNX8ITD(zD-GACnX_=bP{B5COnKtwIy}iBV z?W?|;vTa`a@abts4#ld)vo9o@%t}?Y-X(XhaKH4cm+$WE&3;}vSyi3?#0QzDx3|Af z%YOXfL-f)h&&&3~&n)uN(v~fA`@iD1W8}@aDX~CHKYzVeU7mOHsj4P_i-E+P>^(O= zO?m71C1sX%`{zpU(^IGR28p;{-r}?{BX{qsnr}>n-9hsl6cP+1e$?#qTmJd?-y8FI zzg^BRpJP*4lUg9+%E*wiY0~B8eqV0OcFglBUVc^nTh-p8oi=+#c-XYH`S;fUw$j(v ze=Viie=tEpR`#g{AH#x+8E$TFP74Fp&AWFmuJ3W!R3Ej;Zo#cDE@trd@3I2Ay(&{t zW?O`Q@2>Vho0;djDs0q*I;W)%&wBf^|6{>$F{sHsyCiY$J2=;4Q|)9D{pglP32pS(voL`#%` z;qc{q_vY34yDkna;qO1*t^O$Jq*SqZ_wk=La*Nc1%Xk)-?Tj&-o%{5=lhE|jOT)qy zOSp|zBu{%m5k{1Y9d_R+}yg?*k&y|np9X<_wUY~I|mLlT+G-K zdA2IH^w+=iuO3S;H8nK_Xgn#fFne?}!QMvh{jIOk3=NNx{%u=(Tj}D73m0b3-u^x= zBkRKJEuffk4-{!B$f~;avgTuDjgm}Xhs$mLH|bf~{+iz2g5o#M$o+08&dEtCEDTf- zkg+*2$2xlUWOeVdlc|&b)Ew5oApJMo_U8Zdk4nGUSDYvo!IA;6 * - * A linear gradient along the line from (@start-x, @start-y) to - * (@end-x, @end-y) is specified using the syntax + * A linear gradient along the line from (@start_x, @start_y) to + * (@end_x, @end_y) is specified using the syntax * -gtk-gradient (linear, - * @start-x @start-y, @end-x @end-y, + * @start_x @start_y, @end_x @end_y, * color-stop (@position, @color), * ...) - * where @start-x and @end-x can be either a floating point number between - * 0 and 1 or one of the special values 'left', 'right' or 'center', @start-y - * and @end-y can be either a floating point number between 0 and 1 or one + * where @start_x and @end_x can be either a floating point number between + * 0 and 1 or one of the special values 'left', 'right' or 'center', @start_y + * and @end_y can be either a floating point number between 0 and 1 or one * of the special values 'top', 'bottom' or 'center', @position is a floating * point number between 0 and 1 and @color is a color expression (see above). * The color-stop can be repeated multiple times to add more than one color @@ -422,15 +422,15 @@ * color-stop(1, #0f0)) * * - * A radial gradient along the two circles defined by (@start-x, @start-y, - * @start-radius) and (@end-x, @end-y, @end-radius) is specified using the + * A radial gradient along the two circles defined by (@start_x, @start_y, + * @start_radius) and (@end_x, @end_y, @end_radius) is specified using the * syntax * -gtk-gradient (radial, - * @start-x @start-y, @start-radius, - * @end-x @end-y, @end-radius, + * @start_x @start_y, @start_radius, + * @end_x @end_y, @end_radius, * color-stop (@position, @color), * ...) - * where @start-radius and @end-radius are floating point numbers and + * where @start_radius and @end_radius are floating point numbers and * the other parameters are as before. * * @@ -475,21 +475,24 @@ * * * A border image - * This border image was specified with * - * url("gradient1.png") 10 10 10 10 + * This border image was specified with + * url("gradient1.png") 10 10 10 10 + * * * * A repeating border image - * This border image was specified with * - * url("gradient1.png") 10 10 10 10 repeat + * This border image was specified with + * url("gradient1.png") 10 10 10 10 repeat + * * * * A stretched border image - * This border image was specified with * - * url("gradient1.png") 10 10 10 10 stretch + * This border image was specified with + * url("gradient1.png") 10 10 10 10 stretch + * * * * @@ -559,9 +562,9 @@ * color (see above) * #GdkRGBA * background-color: #fff; - * color: @color-name; - * background-color: shade (@color-name, 0.5); - * color: mix (@color-name, #f0f, 0.8); + * color: &color1; + * background-color: shade (&color1, 0.5); + * color: mix (&color1, #f0f, 0.8); * * * @@ -579,9 +582,9 @@ * * margin * @width - * @vertical-width @horizontal-width - * @top-width @horizontal-width @bottom-width - * @top-width @right-width @bottom-width @left-width + * @vertical_width @horizontal_width + * @top_width @horizontal_width @bottom_width + * @top_width @right_width @bottom_width @left_width * * #GtkBorder * margin: 5; @@ -648,6 +651,27 @@ * * * + * + * GtkThemingEngines can register their own, engine-specific style properties + * with the function gtk_theming_engine_register_property(). These properties + * can be set in CSS like other properties, using a name of the form + * -namespace-name, where namespace is typically + * the name of the theming engine, and name is the + * name of the property. Style properties that have been registered by widgets + * using gtk_widget_class_install_style_property() can also be set in this + * way, using the widget class name for namespace. + * + * + * Using engine-specific style properties + * + * * { + * engine: clearlooks; + * border-radius: 4; + * -GtkPaned-handle-size: 6; + * -clearlooks-colorize-scrollbar: false; + * } + * + * * */ diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index 48429c7065..eda87bf8ec 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -313,23 +313,23 @@ gtk_style_context_class_init (GtkStyleContextClass *klass) signals[CHANGED] = g_signal_new (I_("changed"), - G_TYPE_FROM_CLASS (object_class), - G_SIGNAL_RUN_FIRST, - G_STRUCT_OFFSET (GtkStyleContextClass, changed), - NULL, NULL, + G_TYPE_FROM_CLASS (object_class), + G_SIGNAL_RUN_FIRST, + G_STRUCT_OFFSET (GtkStyleContextClass, changed), + NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); g_object_class_install_property (object_class, - PROP_SCREEN, - g_param_spec_object ("screen", + PROP_SCREEN, + g_param_spec_object ("screen", P_("Screen"), P_("The associated GdkScreen"), GDK_TYPE_SCREEN, GTK_PARAM_READWRITE)); g_object_class_install_property (object_class, - PROP_DIRECTION, - g_param_spec_enum ("direction", + PROP_DIRECTION, + g_param_spec_enum ("direction", P_("Direction"), P_("Text direction"), GTK_TYPE_TEXT_DIRECTION, @@ -829,7 +829,7 @@ build_icon_factories (GtkStyleContext *context, factory = gtk_style_provider_get_icon_factory (data->provider, path); if (factory) - style_data->icon_factories = g_slist_prepend (style_data->icon_factories, factory); + style_data->icon_factories = g_slist_prepend (style_data->icon_factories, factory); } } @@ -1183,10 +1183,12 @@ gtk_style_context_remove_provider_for_screen (GdkScreen *screen, * @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. + * @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. + * Gets a style property from @context for the given state. + * + * When @value is no longer needed, g_value_unset() must be called + * to free any allocated memory. * * Since: 3.0 **/ @@ -1275,8 +1277,8 @@ gtk_style_context_get (GtkStyleContext *context, * @context: a #GtkStyleContext * @flags: state to represent * - * Sets the style to be used when rendering with any - * of the "gtk_render_" prefixed functions. + * Sets the state to be used when rendering with any + * of the gtk_render_*() functions. * * Since: 3.0 **/ @@ -1298,7 +1300,7 @@ gtk_style_context_set_state (GtkStyleContext *context, * gtk_style_context_get_state: * @context: a #GtkStyleContext * - * returns the state used when rendering. + * Returns the state used when rendering. * * Returns: the state flags * @@ -1352,10 +1354,10 @@ context_has_animatable_region (GtkStyleContext *context, * current region (see gtk_style_context_push_animatable_region()). * * If @progress is not %NULL, the animation progress will be returned - * there, 0.0 means the state is closest to being %FALSE, while 1.0 means - * it's closest to being %TRUE. This means transition animations will - * run from 0 to 1 when @state is being set to %TRUE and from 1 to 0 when - * it's being set to %FALSE. + * there, 0.0 means the state is closest to being unset, while 1.0 means + * it's closest to being set. This means transition animation will + * run from 0 to 1 when @state is being set and from 1 to 0 when + * it's being unset. * * Returns: %TRUE if there is a running transition animation for @state. * @@ -1398,9 +1400,11 @@ gtk_style_context_state_is_running (GtkStyleContext *context, * * 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. + * 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 **/ @@ -1478,8 +1482,8 @@ gtk_style_context_save (GtkStyleContext *context) * gtk_style_context_restore: * @context: a #GtkStyleContext * - * Restores @context state to a previous stage. See - * gtk_style_context_save(). + * Restores @context state to a previous stage. + * See gtk_style_context_save(). * * Since: 3.0 **/ @@ -1609,8 +1613,8 @@ region_find (GArray *array, * @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_* + * Adds a style class 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" @@ -1777,7 +1781,6 @@ gtk_style_context_list_classes (GtkStyleContext *context) * 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 @@ -1822,8 +1825,8 @@ gtk_style_context_list_regions (GtkStyleContext *context) * @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_* + * Adds 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" @@ -1833,7 +1836,7 @@ gtk_style_context_list_regions (GtkStyleContext *context) * GtkTreeView row { ... } * * - * pseudo-classes are used for matching @flags, so the two + * Pseudo-classes are used for matching @flags, so the two * following rules: * * GtkTreeView row:nth-child (even) { ... } @@ -1882,7 +1885,7 @@ gtk_style_context_add_region (GtkStyleContext *context, * @context: a #GtkStyleContext * @region_name: region name to unset * - * Removes a region from @context + * Removes a region from @context. * * Since: 3.0 **/ @@ -1923,8 +1926,9 @@ gtk_style_context_remove_region (GtkStyleContext *context, * @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 @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 * @@ -1973,7 +1977,7 @@ gtk_style_context_has_region (GtkStyleContext *context, static gint style_property_values_cmp (gconstpointer bsearch_node1, - gconstpointer bsearch_node2) + gconstpointer bsearch_node2) { const PropertyValue *val1 = bsearch_node1; const PropertyValue *val2 = bsearch_node2; @@ -2015,7 +2019,7 @@ _gtk_style_context_peek_style_property (GtkStyleContext *context, i = 0; while (i < data->property_cache->len && - style_property_values_cmp (&key, &g_array_index (data->property_cache, PropertyValue, i)) >= 0) + style_property_values_cmp (&key, &g_array_index (data->property_cache, PropertyValue, i)) >= 0) i++; g_array_insert_val (data->property_cache, i, key); @@ -2101,10 +2105,12 @@ _gtk_style_context_peek_style_property (GtkStyleContext *context, * 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. + * @value: (out) (transfer full): Return location for the property value * * Gets the value for a widget style property. + * + * When @value is no longer needed, g_value_unset() must be called + * to free any allocated memory. **/ void gtk_style_context_get_style_property (GtkStyleContext *context, @@ -2260,7 +2266,7 @@ gtk_style_context_get_style (GtkStyleContext *context, **/ GtkIconSet * gtk_style_context_lookup_icon_set (GtkStyleContext *context, - const gchar *stock_id) + const gchar *stock_id) { GtkStyleContextPrivate *priv; StyleData *data; @@ -2283,7 +2289,7 @@ gtk_style_context_lookup_icon_set (GtkStyleContext *context, icon_set = gtk_icon_factory_lookup (factory, stock_id); if (icon_set) - return icon_set; + return icon_set; } return gtk_icon_factory_lookup_default (stock_id); @@ -2294,10 +2300,14 @@ gtk_style_context_lookup_icon_set (GtkStyleContext *context, * @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. + * Attaches @context to the given screen. + * + * The screen is used to add style information from 'global' style + * providers, such as the screens #GtkSettings instance. + * + * If you are using a #GtkStyleContext returned from + * gtk_widget_get_style_context(), you do not need to + * call this yourself. * * Since: 3.0 **/ @@ -2321,7 +2331,7 @@ gtk_style_context_set_screen (GtkStyleContext *context, * gtk_style_context_get_screen: * @context: a #GtkStyleContext * - * Returns the #GdkScreen to which @context is attached to. + * Returns the #GdkScreen to which @context is attached. * * Returns: a #GdkScreen, or %NULL. **/ @@ -2341,9 +2351,11 @@ gtk_style_context_get_screen (GtkStyleContext *context) * @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. + * 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 **/ @@ -2385,17 +2397,20 @@ gtk_style_context_get_direction (GtkStyleContext *context) /** * gtk_style_context_set_junction_sides: * @context: a #GtkStyleContext - * @sides: sides where rendered elements are visually connected to other elements. + * @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. + * Sets the sides where rendered elements (mostly through + * gtk_render_frame()) will visually connect with other visual elements. + * + * This is merely a hint that may or may not be honored + * by theming engines. * * Since: 3.0 **/ void gtk_style_context_set_junction_sides (GtkStyleContext *context, - GtkJunctionSides sides) + GtkJunctionSides sides) { GtkStyleContextPrivate *priv; GtkStyleInfo *info; @@ -2470,10 +2485,10 @@ gtk_style_context_lookup_color (GtkStyleContext *context, * @context: a #GtkStyleContext * @window: a #GdkWindow * @region_id: (allow-none): animatable region to notify on, or %NULL. - * See gtk_style_context_push_animatable_region() + * See gtk_style_context_push_animatable_region() * @state: state to trigger transition for - * @state_value: %TRUE if @state is the state we are changing to, %FALSE if - * we are changing away from it + * @state_value: %TRUE if @state is the state we are changing to, + * %FALSE if we are changing away from it * * Notifies a state change on @context, so if the current style makes use * of transition animations, one will be started so all rendered elements @@ -2482,7 +2497,7 @@ gtk_style_context_lookup_color (GtkStyleContext *context, * * 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. + * rendered on by the gtk_render_*() functions. * * If @region_id is %NULL, all rendered elements using @context will be * affected by this state transition. @@ -2627,10 +2642,10 @@ gtk_style_context_notify_state_change (GtkStyleContext *context, * * 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 + * will potentially show transition animations for this region 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. + * and the current theme/style defines transition animations for state + * changes. * * The @region_id used must be unique in @context so the theming engine * can uniquely identify rendered elements subject to a state transition. @@ -2794,8 +2809,11 @@ store_animation_region (GtkStyleContext *context, * @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. + * 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 **/ @@ -2875,9 +2893,16 @@ gtk_style_context_set_background (GtkStyleContext *context, * @width: rectangle width * @height: rectangle height * - * Renders a checkmark (as in a #GtkCheckButton), the %GTK_STATE_FLAG_ACTIVE - * state will determine whether the check is on or off, and - * %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined. + * Renders a checkmark (as in a #GtkCheckButton). + * + * The %GTK_STATE_FLAG_ACTIVE state determines whether the check is + * on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it + * should be marked as undefined. + * + * + * Typical checkmark rendering + * + * * * Since: 3.0 **/ @@ -2918,6 +2943,11 @@ gtk_render_check (GtkStyleContext *context, * state will determine whether the option is on or off, and * %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined. * + * + * Typical option mark rendering + * + * + * * Since: 3.0 **/ void