diff options
| author | Tristan Van Berkom <tristan.van.berkom@gmail.com> | 2010-12-05 00:36:37 +0900 |
|---|---|---|
| committer | Tristan Van Berkom <tristan.van.berkom@gmail.com> | 2010-12-05 00:36:37 +0900 |
| commit | 0d786985a368d88e8ab4e45fc3607efc5e773732 (patch) | |
| tree | 5dfc8ec0e27ac3c23b9dc2eb097018971c28fd6b /docs/reference | |
| parent | 1d3961b34258a7a8c97ca12993220554369fccb1 (diff) | |
| parent | cd76b057e9693b6919f4ccbe40ce205efc8d3caf (diff) | |
| download | gtk+-0d786985a368d88e8ab4e45fc3607efc5e773732.tar.gz | |
Merge branch 'master' into treeview-refactor
Conflicts:
gtk/gtkmarshalers.list
tests/Makefile.am
Diffstat (limited to 'docs/reference')
37 files changed, 1054 insertions, 97 deletions
diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml index a4f4d39123..c77b8be902 100644 --- a/docs/reference/gdk/gdk-docs.sgml +++ b/docs/reference/gdk/gdk-docs.sgml @@ -22,7 +22,6 @@ <xi:include href="xml/gdkdisplaymanager.xml" /> <xi:include href="xml/gdkscreen.xml" /> <xi:include href="xml/regions.xml" /> - <xi:include href="xml/drawing.xml" /> <xi:include href="xml/colors.xml" /> <xi:include href="xml/rgba_colors.xml" /> <xi:include href="xml/visuals.xml" /> diff --git a/docs/reference/gdk/gdk3-overrides.txt b/docs/reference/gdk/gdk3-overrides.txt index bcc85bba84..3ba60be322 100644 --- a/docs/reference/gdk/gdk3-overrides.txt +++ b/docs/reference/gdk/gdk3-overrides.txt @@ -1,27 +1,4 @@ -# GdkPixmap, GdkBitmap and GdkDrawable are the same as GdkWindow. -<STRUCT> -<NAME>GdkWindow</NAME> -struct GdkPixmap -{ - gpointer user_data; -}; -</STRUCT> -<STRUCT> -<NAME>GdkPixmap</NAME> -struct GdkPixmap -{ - gpointer user_data; -}; -</STRUCT> -<STRUCT> -<NAME>GdkDrawable</NAME> -struct GdkDrawable -{ - gpointer user_data; -}; -</STRUCT> - # GdkAtom is an opaque typedef <STRUCT> <NAME>GdkAtom</NAME> diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt index 40bcaaf67d..f4b7e32999 100644 --- a/docs/reference/gdk/gdk3-sections.txt +++ b/docs/reference/gdk/gdk3-sections.txt @@ -257,6 +257,8 @@ gdk_color_to_string <SUBSECTION Standard> GDK_TYPE_COLOR +<SUBSECTION Private> +gdk_color_get_type </SECTION> <SECTION> @@ -272,25 +274,9 @@ gdk_rgba_to_string <SUBSECTION Standard> GDK_TYPE_RGBA -</SECTION> - -<SECTION> -<TITLE>Drawing Primitives</TITLE> -<FILE>drawing</FILE> -GdkDrawable -gdk_drawable_get_clip_region -gdk_drawable_get_visible_region - -<SUBSECTION Standard> -GDK_DRAWABLE -GDK_DRAWABLE_GET_CLASS -GDK_TYPE_DRAWABLE -GDK_IS_DRAWABLE -GDK_DRAWABLE_CLASS -GDK_IS_DRAWABLE_CLASS <SUBSECTION Private> -GdkDrawableClass +gdk_rgba_get_type </SECTION> <SECTION> @@ -331,6 +317,7 @@ GDK_VISUAL_GET_CLASS <SUBSECTION Private> GdkVisualClass +GdkVisualPrivate gdk_visual_get_type </SECTION> @@ -339,7 +326,7 @@ gdk_visual_get_type <FILE>windows</FILE> GdkWindow GdkWindowType -GdkWindowClass +GdkWindowWindowClass GdkWindowHints GdkGeometry GdkGravity @@ -397,9 +384,11 @@ gdk_window_constrain_size gdk_window_beep <SUBSECTION> +gdk_window_get_clip_region gdk_window_begin_paint_rect gdk_window_begin_paint_region gdk_window_end_paint +gdk_window_get_visible_region <SUBSECTION> gdk_window_invalidate_rect @@ -524,12 +513,12 @@ GDK_TYPE_WM_DECORATION GDK_TYPE_WM_FUNCTION <SUBSECTION Private> -gdk_window_object_get_type -gdk_drawable_get_type +gdk_window_get_type +gdk_window_window_class_get_type GdkWindowObject -GdkWindowObjectClass +GdkWindowClass GdkWindowImpl -GdkWindowImplIface +GdkWindowImplClass GdkWindowRedirect gdk_window_impl_get_type gdk_window_freeze_toplevel_updates_libgtk_only @@ -616,7 +605,6 @@ gdk_cairo_set_source_pixbuf gdk_cairo_set_source_window gdk_cairo_rectangle gdk_cairo_region -gdk_cairo_reset_clip gdk_cairo_region_create_from_surface </SECTION> @@ -733,6 +721,7 @@ gdk_device_get_device_type gdk_device_get_display gdk_device_get_has_cursor gdk_device_get_n_axes +gdk_device_get_n_keys <SUBSECTION> gdk_device_grab @@ -862,7 +851,6 @@ GdkNativeWindow GdkEventDND GdkEventProximity GdkEventClient -GdkEventNoExpose GdkEventWindowState GdkEventSetting GdkEventOwnerChange @@ -966,17 +954,13 @@ gdk_drag_context_get_type <TITLE>X Window System Interaction</TITLE> <FILE>x_interaction</FILE> GDK_ROOT_WINDOW -GDK_WINDOW_XDISPLAY GDK_WINDOW_XID GDK_DISPLAY_XDISPLAY -GDK_DRAWABLE_XDISPLAY -GDK_DRAWABLE_XID GDK_SCREEN_XDISPLAY GDK_SCREEN_XNUMBER GDK_SCREEN_XSCREEN GDK_CURSOR_XCURSOR GDK_CURSOR_XDISPLAY -GDK_WINDOW_XWINDOW gdkx_visual_get gdk_window_foreign_new gdk_window_foreign_new_for_display @@ -998,6 +982,7 @@ gdk_x11_cursor_get_xcursor gdk_x11_cursor_get_xdisplay gdk_x11_display_broadcast_startup_message gdk_x11_display_get_startup_notification_id +gdk_x11_display_set_startup_notification_id gdk_x11_display_get_xdisplay gdk_x11_display_grab gdk_x11_display_ungrab @@ -1006,8 +991,7 @@ gdk_x11_display_error_trap_pop gdk_x11_display_error_trap_pop_ignored gdk_x11_display_set_cursor_theme gdk_x11_register_standard_event_type -gdk_x11_drawable_get_xdisplay -gdk_x11_drawable_get_xid +gdk_x11_window_get_xid gdk_x11_get_default_root_xwindow gdk_x11_get_default_screen gdk_x11_get_default_xdisplay @@ -1028,7 +1012,6 @@ gdk_x11_get_xatom_name_for_display <SUBSECTION Private> GDK_HAVE_WCHAR_H GDK_HAVE_WCTYPE_H -gdk_x11_window_get_drawable_impl </SECTION> <SECTION> diff --git a/docs/reference/gdk/gdk3.types b/docs/reference/gdk/gdk3.types index f5889831f9..bb8607d4f8 100644 --- a/docs/reference/gdk/gdk3.types +++ b/docs/reference/gdk/gdk3.types @@ -3,8 +3,7 @@ gdk_display_get_type gdk_display_manager_get_type gdk_screen_get_type -gdk_drawable_get_type -gdk_window_object_get_type +gdk_window_get_type gdk_keymap_get_type gdk_device_get_type gdk_device_manager_get_type diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 1de3259a6d..42d23fc1c1 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 \ @@ -122,6 +125,7 @@ content_files = \ migrating-2to3.xml \ migrating-checklist.sgml \ migrating-GtkApplication.xml \ + migrating-GtkStyleContext.xml \ objects_grouped.sgml \ osx.sgml \ question_index.sgml \ @@ -144,6 +148,7 @@ expand_content_files = \ migrating-2to3.xml \ migrating-checklist.sgml \ migrating-GtkApplication.xml \ + migrating-GtkStyleContext.xml \ question_index.sgml \ text_widget.sgml \ tree_widget.sgml @@ -324,6 +329,30 @@ HTML_IMAGES = \ $(srcdir)/images/window-default.png \ $(srcdir)/images/hello-world.png \ $(srcdir)/images/switch.png + $(srcdir)/images/linear.png \ + $(srcdir)/images/ease.png \ + $(srcdir)/images/ease-in-out.png \ + $(srcdir)/images/ease-in.png \ + $(srcdir)/images/ease-out.png \ + $(srcdir)/images/gradient1.png \ + $(srcdir)/images/gradient2.png \ + $(srcdir)/images/gradient3.png \ + $(srcdir)/images/gradient4.png \ + $(srcdir)/images/border1.png \ + $(srcdir)/images/border2.png \ + $(srcdir)/images/border3.png \ + $(srcdir)/images/slices.png \ + $(srcdir)/images/checks.png \ + $(srcdir)/images/options.png \ + $(srcdir)/images/arrows.png \ + $(srcdir)/images/expanders.png \ + $(srcdir)/images/background.png \ + $(srcdir)/images/frames.png \ + $(srcdir)/images/frame-gap.png \ + $(srcdir)/images/sliders.png \ + $(srcdir)/images/focus.png \ + $(srcdir)/images/handles.png \ + $(srcdir)/images/extensions.png # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=../gdk/html \ diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index db3435cb71..39b9624c0a 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -3,6 +3,8 @@ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> <!ENTITY version SYSTEM "version.xml"> +<!ENTITY pi "π"> +<!ENTITY solidus "⁄"> ]> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> <bookinfo> @@ -38,19 +40,31 @@ <xi:include href="xml/gtkaccelmap.xml" /> <xi:include href="xml/gtkclipboard.xml" /> <xi:include href="xml/gtkdnd.xml" /> - <xi:include href="xml/gtkicontheme.xml" /> <xi:include href="xml/gtkstock.xml" /> - <xi:include href="xml/gtkiconfactory.xml" /> - <xi:include href="xml/gtkrc.xml" /> <xi:include href="xml/gtksettings.xml" /> <xi:include href="xml/gtkbindings.xml" /> <xi:include href="xml/gtkenums.xml" /> - <xi:include href="xml/gtkstyle.xml" /> <xi:include href="xml/gtkselection.xml" /> <xi:include href="xml/gtktesting.xml" /> <xi:include href="xml/filesystem.xml" /> </part> + <part id="theming"> + <title>Theming in GTK+</title> + <xi:include href="xml/gtkstylecontext.xml" /> + <xi:include href="xml/gtkcssprovider.xml" /> + <xi:include href="xml/gtkstyleprovider.xml" /> + <xi:include href="xml/gtkstyleproperties.xml" /> + <xi:include href="xml/gtkthemingengine.xml" /> + <xi:include href="xml/gtkwidgetpath.xml" /> + <xi:include href="xml/gtksymboliccolor.xml" /> + <xi:include href="xml/gtkgradient.xml" /> + <xi:include href="xml/gtkicontheme.xml" /> + <xi:include href="xml/gtkiconfactory.xml" /> + <xi:include href="xml/gtkrc.xml" /> + <xi:include href="xml/gtkstyle.xml" /> + </part> + <part id="gtkobjects"> <title>GTK+ Widgets and Objects</title> @@ -336,6 +350,7 @@ <xi:include href="xml/migrating-checklist.sgml" /> <xi:include href="xml/migrating-2to3.xml" /> <xi:include href="xml/migrating-GtkApplication.xml" /> + <xi:include href="xml/migrating-GtkStyleContext.xml" /> </part> <part> diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 8104875f3d..08f6a2f475 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 @@ -4956,6 +4957,11 @@ gtk_widget_input_shape_combine_region gtk_widget_path gtk_widget_class_path gtk_widget_get_composite_name +gtk_widget_override_background_color +gtk_widget_override_color +gtk_widget_override_font +gtk_widget_override_symbolic_color +gtk_widget_override_cursor gtk_widget_modify_style gtk_widget_get_modifier_style gtk_widget_modify_fg @@ -4964,11 +4970,11 @@ gtk_widget_modify_text gtk_widget_modify_base gtk_widget_modify_font gtk_widget_modify_cursor -gtk_widget_modify_symbolic_color gtk_widget_create_pango_context gtk_widget_get_pango_context gtk_widget_create_pango_layout gtk_widget_render_icon +gtk_widget_render_icon_pixbuf gtk_widget_pop_composite_child gtk_widget_push_composite_child gtk_widget_queue_draw_area @@ -5043,6 +5049,9 @@ gtk_widget_is_sensitive gtk_widget_get_state gtk_widget_get_visible gtk_widget_set_visible +gtk_widget_set_state_flags +gtk_widget_unset_state_flags +gtk_widget_get_state_flags gtk_widget_has_default gtk_widget_has_focus gtk_widget_has_grab @@ -5062,6 +5071,11 @@ gtk_widget_get_requisition gtk_widget_device_is_shadowed <SUBSECTION> +gtk_widget_get_path +gtk_widget_get_style_context +gtk_widget_reset_style + +<SUBSECTION> gtk_requisition_new gtk_requisition_copy gtk_requisition_free @@ -5358,6 +5372,319 @@ GTK_CHECK_VERSION </SECTION> <SECTION> +<FILE>gtkwidgetpath</FILE> +<TITLE>GtkWidgetPath</TITLE> +GtkWidgetPath +gtk_widget_path_append_type +gtk_widget_path_copy +gtk_widget_path_free +gtk_widget_path_get_widget_type +gtk_widget_path_has_parent +gtk_widget_path_is_type +gtk_widget_path_iter_add_class +gtk_widget_path_iter_add_region +gtk_widget_path_iter_clear_classes +gtk_widget_path_iter_clear_regions +gtk_widget_path_iter_get_name +gtk_widget_path_iter_get_widget_type +gtk_widget_path_iter_has_class +gtk_widget_path_iter_has_name +gtk_widget_path_iter_has_qclass +gtk_widget_path_iter_has_qname +gtk_widget_path_iter_has_qregion +gtk_widget_path_iter_has_region +gtk_widget_path_iter_list_classes +gtk_widget_path_iter_list_regions +gtk_widget_path_iter_remove_class +gtk_widget_path_iter_remove_region +gtk_widget_path_iter_set_name +gtk_widget_path_iter_set_widget_type +gtk_widget_path_length +gtk_widget_path_new +gtk_widget_path_prepend_type +</SECTION> + +<SECTION> +<FILE>gtkstyleprovider</FILE> +<TITLE>GtkStyleProvider</TITLE> +GtkStyleProviderIface +GtkStyleProvider +GTK_STYLE_PROVIDER_PRIORITY_FALLBACK +GTK_STYLE_PROVIDER_PRIORITY_THEME +GTK_STYLE_PROVIDER_PRIORITY_SETTINGS +GTK_STYLE_PROVIDER_PRIORITY_APPLICATION +GTK_STYLE_PROVIDER_PRIORITY_USER +gtk_style_provider_get_icon_factory +gtk_style_provider_get_style +gtk_style_provider_get_style_property +<SUBSECTION Standard> +GTK_TYPE_STYLE_PROVIDER +GTK_STYLE_PROVIDER +GTK_IS_STYLE_PROVIDER +GTK_STYLE_PROVIDER_GET_IFACE +<SUBSECTION Private> +gtk_style_provider_get_type +</SECTION> + +<SECTION> +<FILE>gtkstyleproperties</FILE> +<TITLE>GtkStyleProperties</TITLE> +GtkStyleProperties +gtk_style_properties_clear +gtk_style_properties_get +gtk_style_properties_get_property +gtk_style_properties_get_valist +gtk_style_properties_lookup_color +gtk_style_properties_lookup_property +gtk_style_properties_map_color +gtk_style_properties_merge +gtk_style_properties_new +GtkStylePropertyParser +gtk_style_properties_register_property +gtk_style_properties_set +gtk_style_properties_set_property +gtk_style_properties_set_valist +gtk_style_properties_unset_property +<SUBSECTION Standard> +GTK_TYPE_STYLE_PROPERTIES +GTK_IS_STYLE_PROPERTIES +GTK_IS_STYLE_PROPERTIES_CLASS +GTK_STYLE_PROPERTIES +GTK_STYLE_PROPERTIES_CLASS +GTK_STYLE_PROPERTIES_GET_CLASS +<SUBSECTION Private> +gtk_style_properties_get_type +</SECTION> + +<SECTION> +<FILE>gtkstylecontext</FILE> +<TITLE>GtkStyleContext</TITLE> +<SUBSECTION> +GTK_STYLE_PROPERTY_BACKGROUND_COLOR +GTK_STYLE_PROPERTY_COLOR +GTK_STYLE_PROPERTY_FONT +GTK_STYLE_PROPERTY_MARGIN +GTK_STYLE_PROPERTY_PADDING +GTK_STYLE_PROPERTY_BORDER_WIDTH +GTK_STYLE_PROPERTY_BORDER_RADIUS +GTK_STYLE_PROPERTY_BORDER_STYLE +GTK_STYLE_PROPERTY_BORDER_COLOR +GTK_STYLE_PROPERTY_BACKGROUND_IMAGE +<SUBSECTION> +GTK_STYLE_CLASS_BACKGROUND +GTK_STYLE_CLASS_BUTTON +GTK_STYLE_CLASS_CALENDAR +GTK_STYLE_CLASS_CELL +GTK_STYLE_CLASS_CHECK +GTK_STYLE_CLASS_DEFAULT +GTK_STYLE_CLASS_ENTRY +GTK_STYLE_CLASS_HEADER +GTK_STYLE_CLASS_MENU +GTK_STYLE_CLASS_RADIO +GTK_STYLE_CLASS_RUBBERBAND +GTK_STYLE_CLASS_SCROLLBAR +GTK_STYLE_CLASS_SLIDER +GTK_STYLE_CLASS_TOOLTIP +GTK_STYLE_CLASS_TROUGH +GTK_STYLE_CLASS_ACCELERATOR +GTK_STYLE_CLASS_DOCK +GTK_STYLE_CLASS_GRIP +GTK_STYLE_CLASS_MENUBAR +GTK_STYLE_CLASS_MENUITEM +GTK_STYLE_CLASS_PROGRESSBAR +GTK_STYLE_CLASS_SPINNER +GTK_STYLE_CLASS_TOOLBAR +GTK_STYLE_REGION_COLUMN +GTK_STYLE_REGION_COLUMN_HEADER +GTK_STYLE_REGION_ROW +GTK_STYLE_REGION_TAB +<SUBSECTION> +GtkStyleContext +gtk_style_context_new +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_get_color +gtk_style_context_get_background_color +gtk_style_context_get_border_color +gtk_style_context_get_border +gtk_style_context_get_padding +gtk_style_context_get_margin +gtk_style_context_invalidate +gtk_style_context_state_is_running +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_set_background +gtk_style_context_restore +gtk_style_context_save +gtk_style_context_set_direction +gtk_style_context_set_junction_sides +gtk_style_context_set_path +gtk_style_context_add_class +gtk_style_context_remove_class +gtk_style_context_has_class +gtk_style_context_list_classes +gtk_style_context_add_region +gtk_style_context_remove_region +gtk_style_context_has_region +gtk_style_context_list_regions +gtk_style_context_set_screen +gtk_style_context_set_state + +<SUBSECTION> +GtkBorder +gtk_border_new +gtk_border_copy +gtk_border_free + +<SUBSECTION> +gtk_render_arrow +gtk_render_background +gtk_render_check +gtk_render_expander +gtk_render_extension +gtk_render_focus +gtk_render_frame +gtk_render_frame_gap +gtk_render_handle +gtk_render_layout +gtk_render_line +gtk_render_option +gtk_render_slider +gtk_render_activity +gtk_render_icon_pixbuf + +<SUBSECTION Standard> +GTK_TYPE_STYLE_CONTEXT +GTK_STYLE_CONTEXT +GTK_STYLE_CONTEXT_CLASS +GTK_STYLE_CONTEXT_GET_CLASS +GTK_IS_STYLE_CONTEXT +GTK_IS_STYLE_CONTEXT_CLASS +GTK_TYPE_BORDER + +<SUBSECTION Private> +gtk_style_context_get_type +gtk_border_get_type +</SECTION> + +<SECTION> +<FILE>gtkcssprovider</FILE> +<TITLE>GtkCssProvider</TITLE> +GtkCssProvider +gtk_css_provider_get_default +gtk_css_provider_get_named +gtk_css_provider_load_from_data +gtk_css_provider_load_from_file +gtk_css_provider_load_from_path +gtk_css_provider_new +GTK_CSS_PROVIDER_ERROR +GtkCssProviderError +<SUBSECTION Standard> +GTK_TYPE_CSS_PROVIDER +GTK_CSS_PROVIDER +GTK_CSS_PROVIDER_CLASS +GTK_CSS_PROVIDER_GET_CLASS +GTK_IS_CSS_PROVIDER +GTK_IS_CSS_PROVIDER_CLASS +<SUBSECTION Private> +gtk_css_provider_get_type +gtk_css_provider_error_quark +</SECTION> + +<SECTION> +<FILE>gtkthemingengine</FILE> +<TITLE>GtkThemingEngine</TITLE> +GtkThemingEngineClass +GtkThemingEngine +gtk_theming_engine_get +gtk_theming_engine_get_direction +gtk_theming_engine_get_junction_sides +gtk_theming_engine_get_path +gtk_theming_engine_get_property +gtk_theming_engine_get_screen +gtk_theming_engine_get_state +gtk_theming_engine_get_style +gtk_theming_engine_get_style_property +gtk_theming_engine_get_style_valist +gtk_theming_engine_get_valist +gtk_theming_engine_get_color +gtk_theming_engine_get_background_color +gtk_theming_engine_get_border_color +gtk_theming_engine_get_border +gtk_theming_engine_get_padding +gtk_theming_engine_get_margin +gtk_theming_engine_has_class +gtk_theming_engine_has_region +gtk_theming_engine_lookup_color +gtk_theming_engine_state_is_running +gtk_theming_engine_load +gtk_theming_engine_register_property +<SUBSECTION Standard> +GTK_THEMING_ENGINE +GTK_THEMING_ENGINE_CLASS +GTK_THEMING_ENGINE_GET_CLASS +GTK_IS_THEMING_ENGINE +GTK_IS_THEMING_ENGINE_CLASS +<SUBSECTION Private> +GTK_TYPE_THEMING_ENGINE +gtk_theming_engine_get_type +</SECTION> + +<SECTION> +<FILE>gtksymboliccolor</FILE> +<TITLE>GtkSymbolicColor</TITLE> +GtkSymbolicColor +gtk_symbolic_color_new_literal +gtk_symbolic_color_new_name +gtk_symbolic_color_new_shade +gtk_symbolic_color_new_alpha +gtk_symbolic_color_new_mix +gtk_symbolic_color_ref +gtk_symbolic_color_unref +gtk_symbolic_color_resolve + +<SUBSECTION Standard> +GTK_TYPE_SYMBOLIC_COLOR + +<SUBSECTION Private> +gtk_symbolic_color_get_type +</SECTION> + +<SECTION> +<FILE>gtkgradient</FILE> +<TITLE>GtkGradient</TITLE> +GtkGradient +gtk_gradient_new_linear +gtk_gradient_new_radial +gtk_gradient_add_color_stop +gtk_gradient_ref +gtk_gradient_unref +gtk_gradient_resolve + +<SUBSECTION Standard> +GTK_TYPE_GRADIENT + +gtk_gradient_get_type +</SECTION> + +<SECTION> <FILE>gtkstyle</FILE> <TITLE>GtkStyle</TITLE> GTK_STYLE_ATTACHED @@ -5397,12 +5724,6 @@ gtk_paint_resize_grip gtk_draw_insertion_cursor <SUBSECTION> -GtkBorder -gtk_border_new -gtk_border_copy -gtk_border_free - -<SUBSECTION> GtkRcProperty GtkRcPropertyParser @@ -5414,10 +5735,8 @@ GTK_TYPE_STYLE GTK_STYLE_CLASS GTK_IS_STYLE_CLASS GTK_STYLE_GET_CLASS -GTK_TYPE_BORDER -<SUBSECTION Private> + gtk_style_get_type -gtk_border_get_type GtkThemeEngine </SECTION> @@ -5667,12 +5986,16 @@ GtkScrollType GtkSelectionMode GtkShadowType GtkStateType +GtkStateFlags GtkToolbarStyle GtkUpdateType GtkWindowPosition GtkWindowType GtkSortType GtkDragResult +GtkJunctionSides +GtkBorderStyle +GtkRegionFlags <SUBSECTION Private> GTK_PATH_PRIO_MASK @@ -5834,6 +6157,7 @@ gtk_icon_info_get_builtin_pixbuf gtk_icon_info_load_icon gtk_icon_info_load_symbolic gtk_icon_info_load_symbolic_for_style +gtk_icon_info_load_symbolic_for_context gtk_icon_info_set_raw_coordinates gtk_icon_info_get_embedded_rect gtk_icon_info_get_attach_points @@ -5875,6 +6199,7 @@ gtk_icon_set_new gtk_icon_set_new_from_pixbuf gtk_icon_set_ref gtk_icon_set_render_icon +gtk_icon_set_render_icon_pixbuf gtk_icon_set_unref gtk_icon_size_lookup gtk_icon_size_lookup_for_settings diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types index bdf3063bd2..fe0ff45f6b 100644 --- a/docs/reference/gtk/gtk3.types +++ b/docs/reference/gtk/gtk3.types @@ -50,6 +50,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 @@ -144,6 +145,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 @@ -153,6 +156,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/docs/reference/gtk/images/arrows.png b/docs/reference/gtk/images/arrows.png Binary files differnew file mode 100644 index 0000000000..d189a510a5 --- /dev/null +++ b/docs/reference/gtk/images/arrows.png diff --git a/docs/reference/gtk/images/background.png b/docs/reference/gtk/images/background.png Binary files differnew file mode 100644 index 0000000000..ad6ea36a99 --- /dev/null +++ b/docs/reference/gtk/images/background.png diff --git a/docs/reference/gtk/images/border1.png b/docs/reference/gtk/images/border1.png Binary files differnew file mode 100644 index 0000000000..92e2cc5bf2 --- /dev/null +++ b/docs/reference/gtk/images/border1.png diff --git a/docs/reference/gtk/images/border2.png b/docs/reference/gtk/images/border2.png Binary files differnew file mode 100644 index 0000000000..808c3a56d0 --- /dev/null +++ b/docs/reference/gtk/images/border2.png diff --git a/docs/reference/gtk/images/border3.png b/docs/reference/gtk/images/border3.png Binary files differnew file mode 100644 index 0000000000..980f4bdbc4 --- /dev/null +++ b/docs/reference/gtk/images/border3.png diff --git a/docs/reference/gtk/images/checks.png b/docs/reference/gtk/images/checks.png Binary files differnew file mode 100644 index 0000000000..143043a274 --- /dev/null +++ b/docs/reference/gtk/images/checks.png diff --git a/docs/reference/gtk/images/ease-in-out.png b/docs/reference/gtk/images/ease-in-out.png Binary files differnew file mode 100644 index 0000000000..1591b6fee1 --- /dev/null +++ b/docs/reference/gtk/images/ease-in-out.png diff --git a/docs/reference/gtk/images/ease-in.png b/docs/reference/gtk/images/ease-in.png Binary files differnew file mode 100644 index 0000000000..cece95df7f --- /dev/null +++ b/docs/reference/gtk/images/ease-in.png diff --git a/docs/reference/gtk/images/ease-out.png b/docs/reference/gtk/images/ease-out.png Binary files differnew file mode 100644 index 0000000000..9a5162f082 --- /dev/null +++ b/docs/reference/gtk/images/ease-out.png diff --git a/docs/reference/gtk/images/ease.png b/docs/reference/gtk/images/ease.png Binary files differnew file mode 100644 index 0000000000..6a70bcdc2d --- /dev/null +++ b/docs/reference/gtk/images/ease.png diff --git a/docs/reference/gtk/images/expanders.png b/docs/reference/gtk/images/expanders.png Binary files differnew file mode 100644 index 0000000000..629922e4d1 --- /dev/null +++ b/docs/reference/gtk/images/expanders.png diff --git a/docs/reference/gtk/images/extensions.png b/docs/reference/gtk/images/extensions.png Binary files differnew file mode 100644 index 0000000000..f41d710ac8 --- /dev/null +++ b/docs/reference/gtk/images/extensions.png diff --git a/docs/reference/gtk/images/focus.png b/docs/reference/gtk/images/focus.png Binary files differnew file mode 100644 index 0000000000..583d292c9c --- /dev/null +++ b/docs/reference/gtk/images/focus.png diff --git a/docs/reference/gtk/images/frame-gap.png b/docs/reference/gtk/images/frame-gap.png Binary files differnew file mode 100644 index 0000000000..3c0caf24d4 --- /dev/null +++ b/docs/reference/gtk/images/frame-gap.png diff --git a/docs/reference/gtk/images/frames.png b/docs/reference/gtk/images/frames.png Binary files differnew file mode 100644 index 0000000000..12d6c7efc7 --- /dev/null +++ b/docs/reference/gtk/images/frames.png diff --git a/docs/reference/gtk/images/gradient1.png b/docs/reference/gtk/images/gradient1.png Binary files differnew file mode 100644 index 0000000000..248c998daf --- /dev/null +++ b/docs/reference/gtk/images/gradient1.png diff --git a/docs/reference/gtk/images/gradient2.png b/docs/reference/gtk/images/gradient2.png Binary files differnew file mode 100644 index 0000000000..cc5fc054d3 --- /dev/null +++ b/docs/reference/gtk/images/gradient2.png diff --git a/docs/reference/gtk/images/gradient3.png b/docs/reference/gtk/images/gradient3.png Binary files differnew file mode 100644 index 0000000000..4ff8f90bd8 --- /dev/null +++ b/docs/reference/gtk/images/gradient3.png diff --git a/docs/reference/gtk/images/gradient4.png b/docs/reference/gtk/images/gradient4.png Binary files differnew file mode 100644 index 0000000000..b619cae336 --- /dev/null +++ b/docs/reference/gtk/images/gradient4.png diff --git a/docs/reference/gtk/images/handles.png b/docs/reference/gtk/images/handles.png Binary files differnew file mode 100644 index 0000000000..24151b559b --- /dev/null +++ b/docs/reference/gtk/images/handles.png diff --git a/docs/reference/gtk/images/linear.png b/docs/reference/gtk/images/linear.png Binary files differnew file mode 100644 index 0000000000..2339839e21 --- /dev/null +++ b/docs/reference/gtk/images/linear.png diff --git a/docs/reference/gtk/images/options.png b/docs/reference/gtk/images/options.png Binary files differnew file mode 100644 index 0000000000..3c274810fa --- /dev/null +++ b/docs/reference/gtk/images/options.png diff --git a/docs/reference/gtk/images/slices.png b/docs/reference/gtk/images/slices.png Binary files differnew file mode 100644 index 0000000000..c0a064efbf --- /dev/null +++ b/docs/reference/gtk/images/slices.png diff --git a/docs/reference/gtk/images/sliders.png b/docs/reference/gtk/images/sliders.png Binary files differnew file mode 100644 index 0000000000..e832aa708d --- /dev/null +++ b/docs/reference/gtk/images/sliders.png diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml index d150987e11..fc39ff1e24 100644 --- a/docs/reference/gtk/migrating-2to3.xml +++ b/docs/reference/gtk/migrating-2to3.xml @@ -134,7 +134,7 @@ them, are gone. This includes the <literal>gdk_draw</literal> family of functions like gdk_draw_rectangle() and gdk_draw_drawable(). As #GdkGC is roughly equivalent to #cairo_t and #GdkImage was used for - drawing images to GdkDrawables, which cairo supports automatically, + drawing images to GdkWindows, which cairo supports automatically, a transition is usually straightforward. </para> <para> @@ -143,7 +143,7 @@ was replaced. </para> <example> - <title>Drawing a GdkPixbuf onto a GdkDrawable</title> + <title>Drawing a GdkPixbuf onto a GdkWindow</title> <para> Drawing a pixbuf onto a drawable used to be done like this: <programlisting><![CDATA[ @@ -170,7 +170,7 @@ cairo_destroy (cr); </para> </example> <example> - <title>Drawing a tiled GdkPixmap to a GdkDrawable</title> + <title>Drawing a tiled GdkPixmap to a GdkWindow</title> <para> Tiled pixmaps are often used for drawing backgrounds. Old code looked something like this: diff --git a/docs/reference/gtk/migrating-ClientSideWindows.sgml b/docs/reference/gtk/migrating-ClientSideWindows.sgml index 845e9561b2..017249c3e9 100644 --- a/docs/reference/gtk/migrating-ClientSideWindows.sgml +++ b/docs/reference/gtk/migrating-ClientSideWindows.sgml @@ -13,7 +13,7 @@ longer correct to assume that each window has an associated XID. Code that makes this assumption can sometimes be fixed by calling gdk_window_ensure_native() on the windows in question. - Calling gdk_x11_drawable_get_xid() (or GDK_WINDOW_XID()) from the + Calling gdk_x11_window_get_xid() (or GDK_WINDOW_XID()) from the X11-specific API on a non-native window will explicitly call gdk_window_ensure_native(), so old code using this will continue to work. A small gotcha is that the GDK_WINDOW_XID() call is no longer a @@ -46,15 +46,9 @@ <para> Problems can also occur when using cairo for drawing. One thing that can - go wrong is clip handling. If you ever need to reset the clip region on - a cairo_t (i.e. use cairo_reset_clip()), you have to to use - gdk_cairo_reset_clip() instead. The reason for this is that the cairo_reset_clip() call will remove the initial clip region that limits your drawing to - the client-side window at hand, so you will end up drawing over stuff - outside the window. You also need to use gdk_cairo_reset_clip() if you - use a cairo_t that was not allocated in a double-buffered expose handler - and keep it in use after window hierarchy changes (resizing, moving, - stacking order changes). The easiest fix for this kind of problem is to - simply create a new cairo context for each expose event. + go wrong is clip handling. You may not use cairo_reset_clip() on a + cairo_t on a cairo context created via gdk_cairo_create() or passed to + the GtkWidget::draw signal. </para> <para> diff --git a/docs/reference/gtk/migrating-GtkStyleContext.xml b/docs/reference/gtk/migrating-GtkStyleContext.xml new file mode 100644 index 0000000000..775fee0545 --- /dev/null +++ b/docs/reference/gtk/migrating-GtkStyleContext.xml @@ -0,0 +1,631 @@ +<?xml version="1.0"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ +]> +<chapter id="gtk-migrating-GtkStyleContext"> + <title>Migrating from GtkStyle to GtkStyleContext</title> + + <para> + In GTK+ 3.0, #GtkStyleContext was added to replace #GtkStyle and + the theming infrastructure available in 2.x. GtkStyleContext is an + object similar in spirit to GtkStyle, as it contains theming information, + although in a more complete and tokenized fashion. There are two aspects + to switching to GtkStyleContext: porting themes and theme engines, and + porting applications, libraries and widgets. + </para> + + <refsect2 id="gtk-migrating-GtkStyleContext-themes"> + <title>Migrating themes</title> + + <para> + From GTK+ 3.0 on, theme engines must implement #GtkThemingEngine and be + installed in <filename>$libdir/gtk+-3.0/$GTK_VERSION/theming-engines</filename>, + and the files containing style information must be written in the CSS-like + format that is understood by #GtkCssProvider. For a theme named + "Clearlooks", the CSS file parsed by default is + <filename>$datadir/themes/Clearlooks/gtk-3.0/gtk.css</filename>, + with possible variants such as the dark theme being named + <filename>gtk-dark.css</filename> in the same directory. + </para> + </refsect2> + + <refsect2 id="gtk-migrating-theme-GtkStyleContext-engines"> + <title>Migrating theme engines</title> + + <para> + 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: + </para> + + <orderedlist> + <listitem> + 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. + </listitem> + <listitem> + gtk_paint_resize_grip() has been subsumed by gtk_render_handle() + with a #GTK_STYLE_CLASS_GRIP class set in the style context. + </listitem> + <listitem> + gtk_paint_spinner() disappears in favor of gtk_render_activity() + with a #GTK_STYLE_CLASS_SPINNER class set in the style context. + </listitem> + </orderedlist> + + <para> + The list of available render methods is: + </para> + + <simplelist> + <member> + gtk_render_background(): Renders a widget/area background. + </member> + <member> + 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. + </member> + <member> + gtk_render_frame_gap(): Renders a frame border with a gap on one side. + </member> + <member> + gtk_render_layout(): Renders a #PangoLayout. + </member> + <member> + gtk_render_handle(): Renders all kind of handles and resize grips, + depending on the style class. + </member> + <member> + gtk_render_check(): Render checkboxes. + </member> + <member> + gtk_render_option(): Render radiobuttons. + </member> + <member> + gtk_render_arrow(): Renders an arrow pointing to a direction. + </member> + <member> + gtk_render_expander(): Renders an expander indicator, such as in + #GtkExpander. + </member> + <member> + gtk_render_focus(): Renders the indication that a widget has the + keyboard focus. + </member> + <member> + gtk_render_line(): Renders a line from one coordinate to another. + </member> + <member> + gtk_render_slider(): Renders a slider, such as in #GtkScale. + </member> + <member> + gtk_render_extension(): Renders an extension that protrudes from + a UI element, such as a notebook tab. + </member> + <member> + gtk_render_activity(): Renders an area displaying activity, be it + a progressbar or a spinner. + </member> + <member> + gtk_render_icon_pixbuf(): Renders an icon into a #GdkPixbuf. + </member> + </simplelist> + + <para> + 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. + </para> + + <para> + 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 <filename>gtkstylecontext.h</filename>, + although custom widgets may define their own, which themes may + attempt to handle. + </para> + + </refsect2> + + <refsect2 id="gtk-migrating-GtkStyleContext-parser-extensions"> + <title>Extending the CSS parser</title> + + <para> + In #GtkStyle-based engines, #GtkRCStyle provided ways to extend the + gtkrc parser with engine-specific extensions. This has been replaced + by gtk_theming_engine_register_property(), which lets a theme engine + register new properties with an arbitrary type. While there is built-in + support for most basic types, it is possible to use a custom parser + for the property. + </para> + + <para> + The installed properties depend on the #GtkThemeEngine::name property, + so they should be added in the <literal>constructed()</literal> vfunc. + For example, if an engine with the name "Clearlooks" installs a + "focus-color" property with the type #GdkRGBA, the property + <literal>-Clearlooks-focus-color</literal> will be registered and + accepted in CSS like this: + <informalexample><programlisting> + GtkEntry { + -Clearlooks-focus-color: rgba(255, 0, 0, 1.0); + } + </programlisting></informalexample> + </para> + + <para> + Widget style properties also follow a similar syntax, with the widget + type name used as a prefix. For example, the #GtkWidget:focus-line-width + style property can be modified in CSS as + <literal>-GtkWidget-focus-line-width</literal>. + </para> + </refsect2> + + <refsect2 id="gtk-migrating-GtkStyleContext-css"> + <title>Using the CSS file format</title> + + <para> + The syntax of RC and CSS files formats is obviously different. + The CSS-like syntax will hopefully be much more familiar to many + people, lowering the barrier for custom theming. + </para> + <para> + Instead of going through the syntax differences one-by-one, we + will present a more or less comprehensive example and discuss + how it can be translated into CSS: + </para> + + <example> + <title>Sample RC code</title> + <programlisting> + style "default" { + xthickness = 1 + ythickness = 1 + + GtkButton::child-displacement-x = 1 + GtkButton::child-displacement-y = 1 + GtkCheckButton::indicator-size = 14 + + bg[NORMAL] = @bg_color + bg[PRELIGHT] = shade (1.02, @bg_color) + bg[SELECTED] = @selected_bg_color + bg[INSENSITIVE] = @bg_color + bg[ACTIVE] = shade (0.9, @bg_color) + + fg[NORMAL] = @fg_color + fg[PRELIGHT] = @fg_color + fg[SELECTED] = @selected_fg_color + fg[INSENSITIVE] = darker (@bg_color) + fg[ACTIVE] = @fg_color + + text[NORMAL] = @text_color + text[PRELIGHT] = @text_color + text[SELECTED] = @selected_fg_color + text[INSENSITIVE] = darker (@bg_color) + text[ACTIVE] = @selected_fg_color + + base[NORMAL] = @base_color + base[PRELIGHT] = shade (0.95, @bg_color) + base[SELECTED] = @selected_bg_color + base[INSENSITIVE] = @bg_color + base[ACTIVE] = shade (0.9, @selected_bg_color) + + engine "clearlooks" { + colorize_scrollbar = TRUE + style = CLASSIC + } + } + + style "tooltips" { + xthickness = 4 + ythickness = 4 + + bg[NORMAL] = @tooltip_bg_color + fg[NORMAL] = @tooltip_fg_color + } + + style "button" { + xthickness = 3 + ythickness = 3 + + bg[NORMAL] = shade (1.04, @bg_color) + bg[PRELIGHT] = shade (1.06, @bg_color) + bg[ACTIVE] = shade (0.85, @bg_color) + } + + style "entry" { + xthickness = 3 + ythickness = 3 + + bg[SELECTED] = mix (0.4, @selected_bg_color, @base_color) + fg[SELECTED] = @text_color + + engine "clearlooks" { + focus_color = shade (0.65, @selected_bg_color) + } + } + + style "other" { + bg[NORMAL] = #fff; + } + + class "GtkWidget" style "default" + class "GtkEntry" style "entry" + widget_class "*<GtkButton>" style "button" + widget "gtk-tooltip*" style "tooltips" + widget_class "window-name.*.GtkButton" style "other" + </programlisting> + </example> + + <para> + would roughly translate to this CSS: + </para> + + <example> + <title>CSS translation</title> + <programlisting> + * { + padding: 1; + -GtkButton-child-displacement-x: 1; + -GtkButton-child-displacement-y: 1; + -GtkCheckButton-indicator-size: 14; + + background-color: @bg_color; + color: @fg_color; + + -Clearlooks-colorize-scrollbar: true; + -Clearlooks-style: classic; + } + + *:hover { + background-color: shade (@bg_color, 1.02); + } + + *:selected { + background-color: @selected_bg_color; + color: @selected_fg_color; + } + + *:insensitive { + color: shade (@bg_color, 0.7); + } + + *:active { + background-color: shade (@bg_color, 0.9); + } + + .tooltip { + padding: 4; + + background-color: @tooltip_bg_color; + color: @tooltip_fg_color; + } + + .button { + padding: 3; + background-color: shade (@bg_color, 1.04); + } + + .button:hover { + background-color: shade (@bg_color, 1.06); + } + + .button:active { + background-color: shade (@bg_color, 0.85); + } + + .entry { + padding: 3; + + background-color: @base_color; + color: @text_color; + } + + .entry:selected { + background-color: mix (@selected_bg_color, @base_color, 0.4); + -Clearlooks-focus-color: shade (0.65, @selected_bg_color) + } + + /* The latter selector is an specification of the first, + since any widget may use the same classes or names */ + #window-name .button, + GtkWindow#window-name GtkButton.button { + background-color: #fff; + } + </programlisting> + </example> + + <para> + One notable difference is the reduction from fg/bg/text/base colors + to only foreground/background, in exchange the widget is able to render + its various elements with different CSS classes, which can be themed + independently. + </para> + + <para> + Access to colors has also changed a bit. With #GtkStyle, the common + way to access colors is: + <informalexample><programlisting> + GdkColor *color1; + GdkColor color2; + + color1 = &style->bg[GTK_STATE_PRELIGHT]; + gtk_style_lookup_color (style, "focus_color", &color2); + </programlisting></informalexample> + With #GtkStyleContext, you generally use #GdkRGBA instead of #GdkColor + and the code looks like this: + <informalexample><programlisting> + GdkRGBA *color1; + GdkRGBA color2; + + gtk_style_context_get (context, GTK_STATE_FLAG_PRELIGHT, + "background-color", &color1, + NULL); + gtk_style_context_lookup_color (context, "focus_color", &color2); + + ... + + gdk_rgba_free (color1); + </programlisting></informalexample> + Note that the memory handling here is different: gtk_style_context_get() + expects the address of a GdkRGBA* and returns a newly allocated struct, + gtk_style_context_lookup_color() expects the address of an existing + struct, and fills it. + </para> + + <para> + It is worth mentioning that the new file format does not support + custom keybindings nor stock icon mappings as the RC format did. + </para> + </refsect2> + + <refsect2 id="gtk-migrating-GtkStyleContext-checklist"> + <title>A checklist for widgets</title> + + <para> + When porting your widgets to use #GtkStyleContext, this checklist + might be useful. + </para> + + <orderedlist> + <listitem> + Replace <literal>style_set()</literal> calls with + <literal>style_updated()</literal>. + </listitem> + + <listitem> + <para> + Try to identify the role of what you're rendering with any number + of classes. This will replace the detail string. There is a predefined + set of CSS classes which you can reuse where appropriate. Doing so + will give you theming 'for free', whereas custom classes will require + extra work in the theme. Note that complex widgets are likely to + need different styles when rendering different parts, and style + classes are one way to achieve this. This could result in code like + the following (simplified) examples: + </para> + + <example> + <title>Setting a permanent CSS class</title> + <programlisting> + static void + gtk_button_init (GtkButton *button) + { + GtkStyleContext *context; + + ... + + context = gtk_widget_get_style_context (GTK_WIDGET (button)); + + /* Set the "button" class */ + gtk_style_context_add_class (context, GTK_STYLE_CLASS_BUTTON); + } + </programlisting> + </example> + + <para> + Or + </para> + + <example> + <title>Using dynamic CSS classes for different elements</title> + <programlisting> + static gboolean + gtk_spin_button_draw (GtkSpinButton *spin, + cairo_t *cr) + { + GtkStyleContext *context; + + ... + + context = gtk_widget_get_style_context (GTK_WIDGET (spin)); + + gtk_style_context_save (context); + gtk_style_context_add_class (context, GTK_STYLE_CLASS_ENTRY); + + /* Call to entry draw impl with "entry" class */ + parent_class->draw (spin, cr); + + gtk_style_context_restore (context); + gtk_style_context_save (context); + + /* Render up/down buttons with the "button" class */ + gtk_style_context_add_class (context, GTK_STYLE_CLASS_BUTTON); + draw_up_button (spin, cr); + draw_down_button (spin, cr); + + gtk_style_context_restore (context); + + ... + } + </programlisting> + </example> + + <para> + Note that #GtkStyleContext only provides fg/bg colors, so text/base + is done through distinctive theming of the different classes. For + example, an entry would usually be black on white while a button + would usually be black on light grey. + </para> + </listitem> + + <listitem> + Replace all <literal>gtk_paint_*()</literal> calls with corresponding + <literal>gtk_render_*()</literal> calls. The most distinctive changes + are the use of #GtkStateFlags to represent the widget state and the + lack of #GtkShadowType. For gtk_render_check() and gtk_render_option(), + the @shadow_type parameter is replaced by the #GTK_STATE_FLAG_ACTIVE + and #GTK_STATE_FLAG_INCONSISTENT state flags. For things such as + pressed/unpressed button states, #GTK_STATE_FLAG_ACTIVE is used, and + the CSS may style normal/active states differently to render + outset/inset borders, respectively. + </listitem> + + <listitem> + The various <literal>gtk_widget_modify_*()</literal> functions to + override colors or fonts for individual widgets have been replaced + by similar <literal>gtk_widget_override_*()</literal> functions. + </listitem> + + <listitem> + It is no longer necessary to call gtk_widget_style_attach(), + gtk_style_attach(), gtk_style_detach() or gtk_widget_ensure_style(). + </listitem> + + <listitem> + Replace all uses of xthickness/ythickness. #GtkStyleContext uses the + CSS box model, and there are border-width/padding/margin properties to + replace the different applications of X and Y thickness. Note that all + of this is merely a guideline. Widgets may choose to follow it or not. + </listitem> + </orderedlist> + </refsect2> + + <refsect2 id="gtk-migrating-GtkStyleContext-parsing"> + <title>Parsing of custom resources</title> + <para> + As a consequence of the RC format going away, calling gtk_rc_parse() or + gtk_rc_parse_string() won't have any effect on a widgets appearance. + The way to replace these calls is using a custom #GtkStyleProvider, + either for an individual widget through gtk_style_context_add_provider() + or for all widgets on a screen through gtk_style_context_add_provider_for_screen(). + Typically, the provider will be a #GtkCssProvider, which parse CSS + information from a file or from a string. + </para> + + <para> + Notice that you can also get style information from custom resources + by implementing the #GtkStyleProvider interface yourself. This is + an advanced feature that should be rarely used. + </para> + </refsect2> + + <refsect2 id="gtk-migrating-GtkStyleContext-bonus-points"> + <title>Bonus points</title> + + <para> + There are some features in #GtkStyleContext that were not available in + #GtkStyle, or were made available over time for certain widgets through + extending the detail string in obscure ways. There is a lot more + information available when rendering UI elements, and it is accessible + in more uniform, less hacky ways. By going through this list you'll + ensure your widget is a good citizen in a fully themable user interface. + </para> + + <orderedlist> + <listitem> + If your widget renders a series of similar elements, such as tabs + in a #GtkNotebook or rows/column in a #GtkTreeView, consider adding + regions through gtk_style_context_add_region(). These regions can be + referenced in CSS and the :nth-child pseudo-class may be used to match + the elements depending on the flags passed. + + <example> + <title>Theming widget regions</title> + <programlisting> + GtkNotebook tab { + background-color: #f3329d; + } + + GtkTreeView row::nth-child (even) { + background-color: #dddddd; + } + </programlisting> + </example> + </listitem> + + <listitem> + <para> + If your container renders child widgets within different regions, + make it implement GtkContainer::get_path_for_child(). This function + lets containers assign a special #GtkWidgetPath to child widgets + depending on their role/region. This is necessary to extend the + concept above throughout the widget hierarchy. + </para> + + <para> + For example, a #GtkNotebook modifies the tab labels' #GtkWidgetPath + so the "tab" region is added. This makes it possible to theme tab + labels through: + </para> + + <example> + <title>Theming a widget within a parent container region</title> + <programlisting> + GtkNotebook tab GtkLabel { + font: Sans 8; + } + </programlisting> + </example> + + </listitem> + + <listitem> + If you intend several visual elements to look interconnected, + make sure you specify rendered elements' connection areas with + gtk_style_context_set_junction_sides(). It is of course up to the + theme to make use of this information or not. + </listitem> + + <listitem> + <para> + #GtkStyleContext supports implicit animations on state changes for + the most simple case out-of-the-box: widgets with a single animatable + area, whose state is changed with gtk_widget_set_state_flags() or + gtk_widget_unset_state_flags(). These functions trigger animated + transitions for the affected state flags. Examples of widgets for + which this kind of animation may be sufficient are #GtkButton or + #GtkEntry. + </para> + <para> + If your widget consists of more than a simple area, and these areas + may be rendered with different states, make sure to mark the rendered + areas with gtk_style_context_push_animatable_region() and + gtk_style_context_pop_animatable_region(). + </para> + + <para> + gtk_style_context_notify_state_change() may be used to trigger a + transition for a given state. The region ID will determine the + animatable region that is affected by this transition. + </para> + </listitem> + </orderedlist> + </refsect2> +</chapter> diff --git a/docs/reference/gtk/tmpl/gtkenums.sgml b/docs/reference/gtk/tmpl/gtkenums.sgml index 90c5817326..24b4d335af 100644 --- a/docs/reference/gtk/tmpl/gtkenums.sgml +++ b/docs/reference/gtk/tmpl/gtkenums.sgml @@ -315,19 +315,16 @@ Used to change the appearance of an outline typically provided by a #GtkFrame. <!-- ##### ENUM GtkStateType ##### --> <para> -This type indicates the current state of a widget; the state determines how -the widget is drawn. The #GtkStateType enumeration is also used to -identify different colors in a #GtkStyle for drawing, so states can be -used for subparts of a widget as well as entire widgets. -</para> - -@GTK_STATE_NORMAL: State during normal operation. -@GTK_STATE_ACTIVE: State of a currently active widget, such as a depressed button. -@GTK_STATE_PRELIGHT: State indicating that the mouse pointer is over -the widget and the widget will respond to mouse clicks. -@GTK_STATE_SELECTED: State of a selected item, such the selected row in a list. -@GTK_STATE_INSENSITIVE: State indicating that the widget is -unresponsive to user actions. + +</para> + +@GTK_STATE_NORMAL: +@GTK_STATE_ACTIVE: +@GTK_STATE_PRELIGHT: +@GTK_STATE_SELECTED: +@GTK_STATE_INSENSITIVE: +@GTK_STATE_INCONSISTENT: +@GTK_STATE_FOCUSED: <!-- ##### ENUM GtkToolbarStyle ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml index e146d3157f..b89710a3f6 100644 --- a/docs/reference/gtk/tmpl/gtkrc.sgml +++ b/docs/reference/gtk/tmpl/gtkrc.sgml @@ -10,6 +10,10 @@ GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ program at runtime. </para> +<para> +In GTK+ 3.0, resource files have been deprecated and replaced +by CSS-like style sheets, which are understood by #GtkCssProvider. +</para> <refsect2><title>Default files</title> <para> |
