Class: Gtk::StyleContext

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Instance Method Summary collapse

Instance Method Details

#add_class(class_name) ⇒ nil

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 Gtk::Entry defining a “search” class, would be matched by:

|[ <!– language=“CSS” –> entry.search { … } ]|

While any widget defining a “search” class would be matched by: |[ <!– language=“CSS” –> .search { … } ]|

Parameters:

  • class_name (String)

    class name to use in styling

Returns:

  • (nil)

#add_provider(provider, priority) ⇒ nil

Adds a style provider to context, to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which context belongs. If you want to affect the style of all widgets, use gtk_style_context_add_provider_for_screen().

Note: If both priorities are the same, a Gtk::StyleProvider added through this function takes precedence over another added through gtk_style_context_add_provider_for_screen().

Parameters:

  • provider (Gtk::StyleProvider)

    a Gtk::StyleProvider

  • priority (Integer)

    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

Returns:

  • (nil)

#add_region(region_name, flags) ⇒ nil

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 Gtk::TreeView defining a “row” region, would be matched by:

|[ <!– language=“CSS” –> treeview row { … } ]|

Pseudo-classes are used for matching flags, so the two following rules: |[ <!– language=“CSS” –> treeview row:nth-child(even) { … } treeview row:nth-child(odd) { … } ]|

would apply to even and odd rows, respectively.

Region names must only contain lowercase letters and “-”, starting always with a lowercase letter.

Parameters:

  • region_name (String)

    region name to use in styling

  • flags (Gtk::RegionFlags)

    flags that apply to the region

Returns:

  • (nil)

#background=(window) ⇒ nil

Sets the background of window to the background pattern or color specified in context for its current state.

Parameters:

Returns:

  • (nil)

#cancel_animations(region_id) ⇒ nil

Stops all running animations for region_id and all animatable regions underneath.

A nil region_id will stop all ongoing animations in context, when dealing with a Gtk::StyleContext obtained through gtk_widget_get_style_context(), this is normally done for you in all circumstances you would expect all widget to be stopped, so this should be only used in complex widgets with different animatable regions.

Parameters:

  • region_id (GObject)

    animatable region to stop, or nil. See gtk_style_context_push_animatable_region()

Returns:

  • (nil)

#directionGtk::TextDirection

Returns direction.

Returns:

#direction=(direction) ⇒ Gtk::TextDirection

Parameters:

Returns:

#frame_clockGdk::FrameClock

Returns the Gdk::FrameClock to which context is attached.

Returns:

  • (Gdk::FrameClock)

    a Gdk::FrameClock, or nil if context does not have an attached frame clock.

#frame_clock=(frame_clock) ⇒ nil

Attaches context to the given frame clock.

The frame clock is used for the timing of animations.

If you are using a Gtk::StyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself.

Parameters:

Returns:

  • (nil)

#get(state, array) ⇒ nil

Retrieves several style property values from context for a given state.

See gtk_style_context_get_property() for details.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the property values for

  • array (Array)

    property name /return value pairs, followed by nil

Returns:

  • (nil)

#get_background_color(state, color) ⇒ nil

Gets the background color for a given state.

This function is far less useful than it seems, and it should not be used in newly written code. CSS has no concept of “background color”, as a background can be an image, or a gradient, or any other pattern including solid colors.

The only reason why you would call gtk_style_context_get_background_color() is to use the returned value to draw the background with it; the correct way to achieve this result is to use gtk_render_background() instead, along with CSS style classes to modify the color to be rendered.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the color for

  • color (Gdk::RGBA)

    return value for the background color

Returns:

  • (nil)

#get_border(state, border) ⇒ nil

Gets the border for a given state as a Gtk::Border.

See gtk_style_context_get_property() and #GTK_STYLE_PROPERTY_BORDER_WIDTH for details.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the border for

  • border (Gtk::Border)

    return value for the border settings

Returns:

  • (nil)

#get_border_color(state, color) ⇒ nil

Gets the border color for a given state.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the color for

  • color (Gdk::RGBA)

    return value for the border color

Returns:

  • (nil)

#get_color(state, color) ⇒ nil

Gets the foreground color for a given state.

See gtk_style_context_get_property() and #GTK_STYLE_PROPERTY_COLOR for details.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the color for

  • color (Gdk::RGBA)

    return value for the foreground color

Returns:

  • (nil)

#get_font(state) ⇒ Pango::FontDescription

Returns the font description for a given state. The returned object is const and will remain valid until the Gtk::StyleContext::changed signal happens.

Parameters:

Returns:

  • (Pango::FontDescription)

    the Pango::FontDescription for the given state. This object is owned by GTK+ and should not be freed.

#get_margin(state, margin) ⇒ nil

Gets the margin for a given state as a Gtk::Border. See gtk_style_property_get() and #GTK_STYLE_PROPERTY_MARGIN for details.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the border for

  • margin (Gtk::Border)

    return value for the margin settings

Returns:

  • (nil)

#get_padding(state, padding) ⇒ nil

Gets the padding for a given state as a Gtk::Border. See gtk_style_context_get() and #GTK_STYLE_PROPERTY_PADDING for details.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the padding for

  • padding (Gtk::Border)

    return value for the padding settings

Returns:

  • (nil)

#get_property(property, state, value) ⇒ nil

Gets a style property from context for the given state.

Note that not all CSS properties that are supported by GTK+ can be retrieved in this way, since they may not be representable as #GValue. GTK+ defines macros for a number of properties that can be used with this function.

Note that passing a state other than the current state of context is not recommended unless the style context has been saved with gtk_style_context_save().

When value is no longer needed, g_value_unset() must be called to free any allocated memory.

Parameters:

  • property (String)

    style property name

  • state (Gtk::StateFlags)

    state to retrieve the property value for

  • value (GObject::Value)

    return location for the style property value

Returns:

  • (nil)

#get_section(property) ⇒ Gtk::CssSection

Queries the location in the CSS where property was defined for the current context. Note that the state to be queried is taken from gtk_style_context_get_state().

If the location is not available, nil will be returned. The location might not be available for various reasons, such as the property being overridden, property not naming a supported CSS property or tracking of definitions being disabled for performance reasons.

Shorthand CSS properties cannot be queried for a location and will always return nil. for property was defined

Parameters:

  • property (String)

    style property name

Returns:

  • (Gtk::CssSection)

    nil or the section where a value

#get_style(array) ⇒ nil

Retrieves several widget style properties from context according to the current style.

Parameters:

  • array (Array)

    property name /return value pairs, followed by nil

Returns:

  • (nil)

#get_style_property(property_name, value) ⇒ nil

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.

Parameters:

  • property_name (String)

    the name of the widget style property

  • value (GObject::Value)

    Return location for the property value

Returns:

  • (nil)

#get_style_valist(args) ⇒ nil

Retrieves several widget style properties from context according to the current style.

Parameters:

  • args (Gtk::va_list)

    va_list of property name/return location pairs, followed by nil

Returns:

  • (nil)

#get_valist(state, args) ⇒ nil

Retrieves several style property values from context for a given state.

See gtk_style_context_get_property() for details.

Parameters:

  • state (Gtk::StateFlags)

    state to retrieve the property values for

  • args (Gtk::va_list)

    va_list of property name/return location pairs, followed by nil

Returns:

  • (nil)

#has_class(class_name) ⇒ TrueClass

Returns true if context currently has defined the given class name.

Parameters:

  • class_name (String)

    a class name

Returns:

  • (TrueClass)

    true if context has class_name defined

#has_region(region_name, flags_return) ⇒ TrueClass

Returns true if context has the region defined. If flags_return is not nil, it is set to the flags affecting the region.

Parameters:

  • region_name (String)

    a region name

  • flags_return (Gtk::RegionFlags)

    return location for region flags

Returns:

  • (TrueClass)

    true if region is defined

#invalidatenil

Invalidates context style information, so it will be reconstructed again. It is useful if you modify the context and need the new information immediately.

Returns:

  • (nil)

#junction_sidesGtk::JunctionSides

Returns the sides where rendered elements connect visually with others.

Returns:

#junction_sides=(sides) ⇒ nil

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 themes.

Container widgets are expected to set junction hints as appropriate for their children, so it should not normally be necessary to call this function manually.

Parameters:

  • sides (Gtk::JunctionSides)

    sides where rendered elements are visually connected to other elements

Returns:

  • (nil)

#list_classesGLib::List

Returns the list of classes currently defined in context.

Returns:

  • (GLib::List)

    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.

#list_regionsGLib::List

Returns the list of regions currently defined in context.

Returns:

  • (GLib::List)

    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.

#lookup_color(color_name, color) ⇒ TrueClass

Looks up and resolves a color name in the context color map.

Parameters:

  • color_name (String)

    color name to lookup

  • color (Gdk::RGBA)

    Return location for the looked up color

Returns:

  • (TrueClass)

    true if color_name was found and resolved, false otherwise

#lookup_icon_set(stock_id) ⇒ Gtk::IconSet

Looks up stock_id in the icon factories associated to context and the default icon factory, returning an icon set if found, otherwise nil.

Parameters:

  • stock_id (String)

    an icon name

Returns:

  • (Gtk::IconSet)

    The looked up %GtkIconSet, or nil

#newGtk::StyleContext

Creates a standalone Gtk::StyleContext, this style context won’t be attached to any widget, so you may want to call gtk_style_context_set_path() yourself.

This function is only useful when using the theming layer separated from GTK+, if you are using Gtk::StyleContext to theme Gtk::Widgets, use gtk_widget_get_style_context() in order to get a style context ready to theme the widget.

Returns:

#notify_state_change(window, region_id, state, state_value) ⇒ nil

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_*() functions.

If region_id is nil, all rendered elements using context will be affected by this state transition.

As a practical example, a Gtk::Button notifying a state transition on the prelight state: |[ <!– language=“C” –> gtk_style_context_notify_state_change (context,

gtk_widget_get_window (widget),
NULL,
GTK_STATE_PRELIGHT,
button->in_button);

]|

Can be handled in the CSS file like this: |[ <!– language=“CSS” –> button

background-color: #f00

button:hover

background-color: #fff;
transition: 200ms linear

]|

This combination will animate the button background from red to white if a pointer enters the button, and back to red if the pointer leaves the button.

Note that state is used when finding the transition parameters, which is why the style places the transition under the :hover pseudo-class.

Parameters:

  • window (Gdk::Window)

    a Gdk::Window

  • region_id (GObject)

    animatable region to notify on, or nil. See gtk_style_context_push_animatable_region()

  • state (Gtk::StateType)

    state to trigger transition for

  • state_value (TrueClass)

    true if state is the state we are changing to, false if we are changing away from it

Returns:

  • (nil)

#paint_clockGdk::FrameClock

Returns paint-clock.

Returns:

#paint_clock=(paint_clock) ⇒ Gdk::FrameClock

Parameters:

Returns:

#parentGtk::StyleContext

Sets or gets the style context’s parent. See gtk_style_context_set_parent() for details.

Returns:

#parent=(parent) ⇒ Gtk::StyleContext

Sets or gets the style context’s parent. See gtk_style_context_set_parent() for details.

Parameters:

Returns:

#pathGtk::WidgetPath

Returns the widget path used for style matching.

Returns:

  • (Gtk::WidgetPath)

    A Gtk::WidgetPath

#path=(path) ⇒ nil

Sets the Gtk::WidgetPath used for style matching. As a consequence, the style will be regenerated to match the new given path.

If you are using a Gtk::StyleContext returned from gtk_widget_get_style_context(), you do not need to call this yourself.

Parameters:

  • path (Gtk::WidgetPath)

    a Gtk::WidgetPath

Returns:

  • (nil)

#pop_animatable_regionnil

Pops an animatable region from context. See gtk_style_context_push_animatable_region().

Returns:

  • (nil)

#push_animatable_region(region_id) ⇒ nil

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 this region if gtk_style_context_notify_state_change() is called for a given state, and the current theme/style defines transition animations for state changes.

The region_id used must be unique in context so the themes can uniquely identify rendered elements subject to a state transition.

Parameters:

  • region_id (GObject)

    unique identifier for the animatable region

Returns:

  • (nil)

#remove_class(class_name) ⇒ nil

Removes class_name from context.

Parameters:

  • class_name (String)

    class name to remove

Returns:

  • (nil)

#remove_provider(provider) ⇒ nil

Removes provider from the style providers list in context.

Parameters:

Returns:

  • (nil)

#remove_region(region_name) ⇒ nil

Removes a region from context.

Parameters:

  • region_name (String)

    region name to unset

Returns:

  • (nil)

#restorenil

Restores context state to a previous stage. See gtk_style_context_save().

Returns:

  • (nil)

#savenil

Saves the context state, so temporary modifications done through gtk_style_context_add_class(), gtk_style_context_remove_class(), gtk_style_context_set_state(), etc. can quickly be reverted in one go through gtk_style_context_restore().

The matching call to gtk_style_context_restore() must be done before GTK returns to the main loop.

Returns:

  • (nil)

#scaleInteger

Returns the scale used for assets.

Returns:

  • (Integer)

    the scale

#scale=(scale) ⇒ nil

Sets the scale to use when getting image assets for the style.

Parameters:

  • scale (Integer)

    scale

Returns:

  • (nil)

#screenGdk::Screen

Returns screen.

Returns:

#screen=(screen) ⇒ Gdk::Screen

Parameters:

Returns:

#scroll_animations(window, dx, dy) ⇒ nil

This function is analogous to gdk_window_scroll(), and should be called together with it so the invalidation areas for any ongoing animation are scrolled together with it.

Parameters:

  • window (Gdk::Window)

    a Gdk::Window used previously in gtk_style_context_notify_state_change()

  • dx (Integer)

    Amount to scroll in the X axis

  • dy (Integer)

    Amount to scroll in the Y axis

Returns:

  • (nil)

#stateGtk::StateFlags

Returns the state used for style matching.

This method should only be used to retrieve the Gtk::StateFlags to pass to Gtk::StyleContext methods, like gtk_style_context_get_padding(). If you need to retrieve the current state of a Gtk::Widget, use gtk_widget_get_state_flags().

Returns:

#state=(flags) ⇒ nil

Sets the state to be used for style matching.

Parameters:

Returns:

  • (nil)

#state_is_running(state, progress) ⇒ TrueClass

Returns true if there is a transition animation running for the current region (see gtk_style_context_push_animatable_region()).

If progress is not nil, the animation progress will be returned 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.

Parameters:

  • state (Gtk::StateType)

    a widget state

  • progress (Float)

    return location for the transition progress

Returns:

  • (TrueClass)

    true if there is a running transition animation for state.

#to_string(flags) ⇒ String

Converts the style context into a string representation.

The string representation always includes information about the name, state, id, visibility and style classes of the CSS node that is backing context. Depending on the flags, more information may be included.

This function is intended for testing and debugging of the CSS implementation in GTK+. There are no guarantees about the format of the returned string, it may change.

Parameters:

Returns:

  • (String)

    a newly allocated string representing context