Migrating theme engines: GTK+ 3 Reference Manual

Migrating theme engines

Migrating a GtkStyle based engine to a GtkThemingEngine based one should be straightforward for most of the vfuncs. Besides a cleanup in the available paint methods and a simplification in the passed arguments (in favor of GtkStyleContext containing all the information), the available render methods resemble those of GtkStyle quite evidently. Notable differences include:

All variations of gtk_paint_box(), gtk_paint_flat_box(), gtk_paint_shadow(), gtk_paint_box_gap() and gtk_paint_shadow_gap() are replaced by gtk_render_background(), gtk_render_frame() and gtk_render_frame_gap(). The first function renders frameless backgrounds and the last two render frames in various forms.
gtk_paint_resize_grip() has been subsumed by gtk_render_handle() with a GTK_STYLE_CLASS_GRIP class set in the style context.
gtk_paint_spinner() disappears in favor of gtk_render_activity() with a GTK_STYLE_CLASS_SPINNER class set in the style context.

The list of available render methods is:

gtk_render_background(): Renders a widget/area background.

gtk_render_frame(): Renders a frame border around the given rectangle. Usually the detail of the border depends on the theme information, plus the current widget state.

gtk_render_frame_gap(): Renders a frame border with a gap on one side.

gtk_render_layout(): Renders a PangoLayout.

gtk_render_handle(): Renders all kind of handles and resize grips, depending on the style class.

gtk_render_check(): Render checkboxes.

gtk_render_option(): Render radiobuttons.

gtk_render_arrow(): Renders an arrow pointing to a direction.

gtk_render_expander(): Renders an expander indicator, such as in GtkExpander.

gtk_render_focus(): Renders the indication that a widget has the keyboard focus.

gtk_render_line(): Renders a line from one coordinate to another.

gtk_render_slider(): Renders a slider, such as in GtkScale.

gtk_render_extension(): Renders an extension that protrudes from a UI element, such as a notebook tab.

gtk_render_activity(): Renders an area displaying activity, be it a progressbar or a spinner.

gtk_render_icon_pixbuf(): Renders an icon into a GdkPixbuf.

One of the main differences to GtkStyle-based engines is that the rendered widget is totally isolated from the theme engine, all style information is meant to be retrieved from the GtkThemingEngine API, or from the GtkWidgetPath obtained from gtk_theming_engine_get_path(), which fully represents the rendered widget's hierarchy from a styling point of view.

The detail string available in GtkStyle-based engines has been replaced by widget regions and style classes. Regions are a way for complex widgets to associate different styles with different areas, such as even and odd rows in a treeview. Style classes allow sharing of style information between widgets, regardless of their type. Regions and style classes can be used in style sheets to associate styles, and them engines can also access them. There are several predefined classes and regions such as GTK_STYLE_CLASS_BUTTON or GTK_STYLE_REGION_TAB in gtkstylecontext.h, although custom widgets may define their own, which themes may attempt to handle.