diff options
Diffstat (limited to 'docs/reference/gtk')
27 files changed, 335 insertions, 3379 deletions
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 091f06d7b7..6a37a3cf02 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -106,7 +106,7 @@ CPPFLAGS += \ -UGTK_DISABLE_SINGLE_INCLUDES GTKDOC_LIBS = \ - $(top_builddir)/gtk/libgtk-3.0.la \ + $(top_builddir)/gtk/libgtk-3.la \ $(GTK_DEP_LIBS) diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml index 70802e53c9..9e60e927be 100644 --- a/docs/reference/gtk/building.sgml +++ b/docs/reference/gtk/building.sgml @@ -172,7 +172,7 @@ How to compile GTK+ itself such as high level data types, Unicode manipulation, and an object and type system to C programs. It is available from the <ulink url="ftp://ftp.gtk.org/pub/glib/">GTK+ - FTP site.</ulink> + FTP site</ulink>. </para> </listitem> <listitem> @@ -180,7 +180,7 @@ How to compile GTK+ itself <ulink url="http://www.pango.org">Pango</ulink> is a library for internationalized text handling. It is available from the <ulink url="ftp://ftp.gtk.org/pub/pango/">GTK+ FTP - site.</ulink>. + site</ulink>. </para> </listitem> <listitem> @@ -189,7 +189,7 @@ How to compile GTK+ itself interfaces allowing accessibility technologies such as screen readers to interact with a graphical user interface. It is available from the <ulink - url="ftp://ftp.gtk.org/pub/atk/">GTK+ FTP site.</ulink> + url="ftp://ftp.gtk.org/pub/atk/">GTK+ FTP site</ulink>. </para> </listitem> <listitem> @@ -309,49 +309,60 @@ How to compile GTK+ itself <cmdsynopsis> <command>configure</command> - + <sbr/> <group> <arg>--disable-modules</arg> <arg>--enable-modules</arg> </group> + <sbr/> <group> <arg>--with-included-immodules=MODULE1,MODULE2,...</arg> </group> + <sbr/> <group> <arg>--enable-debug=[no/minimum/yes]</arg> </group> + <sbr/> <group> <arg>--disable-Bsymbolic</arg> <arg>--enable-Bsymbolic</arg> </group> + <sbr/> <group> <arg>--disable-xkb</arg> <arg>--enable-xkb</arg> </group> + <sbr/> <group> <arg>--disable-xinerama</arg> <arg>--enable-xinerama</arg> </group> + <sbr/> <group> <arg>--disable-gtk-doc</arg> <arg>--enable-gtk-doc</arg> </group> + <sbr/> <group> <arg>--disable-cups</arg> <arg>--enable-cups</arg> </group> + <sbr/> <group> <arg>--disable-papi</arg> <arg>--enable-papi</arg> </group> + <sbr/> <group> <arg>--enable-xinput</arg> <arg>--disable-xinput</arg> </group> + <sbr/> <group> <arg>--enable-packagekit</arg> <arg>--disable-packagekit</arg> </group> + <sbr/> <group> <arg>--enable-x11-backend</arg> <arg>--disable-x11-backend</arg> @@ -360,9 +371,11 @@ How to compile GTK+ itself <arg>--enable-quartz-backend</arg> <arg>--disable-quartz-backend</arg> </group> + <sbr/> <group> <arg>--enable-introspection=[no/auto/yes]</arg> </group> + <sbr/> <group> <arg>--enable-gtk2-dependency</arg> <arg>--disable-gtk2-dependency</arg> diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml index 7382f5c4cd..58d97edbce 100644 --- a/docs/reference/gtk/compiling.sgml +++ b/docs/reference/gtk/compiling.sgml @@ -32,7 +32,7 @@ your system may be different): $ pkg-config --cflags gtk+-3.0 -pthread -I/usr/include/gtk-3.0 -I/usr/lib64/gtk-3.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12 $ pkg-config --libs gtk+-3.0 - -pthread -lgtk-3.0 -lgdk-3.0 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-3.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0 + -pthread -lgtk-3 -lgdk-3 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0 </programlisting> </para> <para> diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml index d47a09f1fd..0d870fee1d 100644 --- a/docs/reference/gtk/getting_started.xml +++ b/docs/reference/gtk/getting_started.xml @@ -12,7 +12,7 @@ <link linkend="gtk-compiling">Compiling the GTK+ libraries</link> section in this reference.</para> - <section> + <simplesect> <title>Basics</title> <para>To begin our introduction to GTK, we'll start with the simplest @@ -114,9 +114,9 @@ </xi:include> </programlisting> </example> - </section> + </simplesect> - <section> + <simplesect> <title>Packing</title> <para>When creating an application, you'll want to put more than one widget @@ -145,9 +145,9 @@ </xi:include> </programlisting> </example> - </section> + </simplesect> - <section> + <simplesect> <title>Drawing</title> <para>Many widgets, like buttons, do all their drawing themselves. You @@ -183,5 +183,55 @@ </xi:include> </programlisting> </example> - </section> + </simplesect> + + <simplesect> + <title>Building interfaces</title> + + <para>When construcing a more complicated user interface, with dozens + or hundreds of widgets, doing all the setup work in C code is + cumbersome, and making changes becomes next to impossible.</para> + + <para>Thankfully, GTK+ supports the separation of user interface + layout from your business logic, by using UI descriptions in an + XML format that can be parsed by the #GtkBuilder class.</para> + + <example> + <title>Packing buttons with GtkBuilder</title> + <programlisting> + <xi:include href="../../../../examples/builder.c" parse="text"> + <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> + </xi:include> + </programlisting> + The builder.ui file looks like this: + <programlisting> + <xi:include href="../../../../examples/builder.ui" parse="text"> + <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> + </xi:include> + </programlisting> + </example> + + <para>Note that GtkBuilder can also be used to construct objects + that are not widgets, such as tree models, adjustments, etc. + That is the reason the method we use here is called + gtk_builder_get_object() and returns a GObject* instead of a + GtkWidget*.</para> + + <para>Normally, you would pass a full path to + gtk_builder_add_from_file() to make the execution of your program + independent of the current directory. A common location to install + UI descriptions and similar data is + <filename>/usr/share/<replaceable>appname</replaceable></filename>. + </para> + + <para>It is also possible to embed the UI description in the source + code as a string and use gtk_builder_add_from_string() to load it. + But keeping the UI description in a separate file has several + advantages: It is then possible to make minor adjustments to the UI + without recompiling your program, and, more importantly, graphical + UI editors such as <ulink url="http://glade.gnome.org">glade</ulink> + can load the file and allow you to create and modify your UI by + point-and-click.</para> + + </simplesect> </chapter> diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 9f57e97057..fdb301682a 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -8,11 +8,15 @@ ]> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> <bookinfo> - <title>GTK+ Reference Manual</title> + <title>GTK+ 3 Reference Manual</title> <releaseinfo> - for GTK+ &version; - The latest version of this documentation can be found on-line at - <ulink role="online-location" url="http://library.gnome.org/devel/gtk/unstable/">http://library.gnome.org/devel/gtk/unstable/</ulink>. + This document is for the GTK+ 3 library, version &version;. + The latest version can be found online at + <ulink role="online-location" url="http://library.gnome.org/devel/gtk3/unstable/">http://library.gnome.org/devel/gtk3/unstable/</ulink>. + If you are looking for the older GTK+ 2 series of libraries, + they can be found under their version numbers; for example, + 2.24 is available at + <ulink role="online-location" url="http://library.gnome.org/devel/gtk/2.24/">http://library.gnome.org/devel/gtk/2.24/</ulink>. </releaseinfo> </bookinfo> diff --git a/docs/reference/gtk/gtk-query-immodules-3.0.xml b/docs/reference/gtk/gtk-query-immodules-3.0.xml index c9e541b6d2..97af84df11 100644 --- a/docs/reference/gtk/gtk-query-immodules-3.0.xml +++ b/docs/reference/gtk/gtk-query-immodules-3.0.xml @@ -5,13 +5,14 @@ <refentry id="gtk-query-immodules-3.0"> <refmeta> -<refentrytitle>gtk-query-immodules-3.0</refentrytitle> -<manvolnum>1</manvolnum> + <refentrytitle>gtk-query-immodules-3.0</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">User Commands</refmiscinfo> </refmeta> <refnamediv> -<refname>gtk-query-immodules-3.0</refname> -<refpurpose>Input method module registration utility</refpurpose> + <refname>gtk-query-immodules-3.0</refname> + <refpurpose>Input method module registration utility</refpurpose> </refnamediv> <refsynopsisdiv> @@ -38,8 +39,8 @@ may be absolute or relative paths. </para> <para> Normally, the output of <command>gtk-query-immodules-3.0</command> is written -to <filename><replaceable>libdir</replaceable>gtk-3.0/3.0.0/immodules.cache</filename>, where GTK+ looks for it by default. If it is written to some other -location, the environment variable <link linkend="GTK_IM_MODULE_FILE"><envar>GTK_IM_MODULE_FILE</envar></link> +to <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/immodules.cache</filename>, where GTK+ looks for it by default. If it is written to some other +location, the environment variable <link linkend="gtk-im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link> can be set to point GTK+ at the file. </para> </refsect1> @@ -56,7 +57,7 @@ can be set to point GTK+ at the file. <refsect1><title>Environment</title> <para> -The environment variable <link linkend="GTK_PATH"><envar>GTK_PATH</envar></link> +The environment variable <link linkend="gtk-path"><envar>GTK_PATH</envar></link> can be used to prepend directories to the input method module path. </para> </refsect1> diff --git a/docs/reference/gtk/gtk-update-icon-cache.xml b/docs/reference/gtk/gtk-update-icon-cache.xml index 2a5bc27fbf..d6f3ac850f 100644 --- a/docs/reference/gtk/gtk-update-icon-cache.xml +++ b/docs/reference/gtk/gtk-update-icon-cache.xml @@ -5,13 +5,14 @@ <refentry id="gtk-update-icon-cache"> <refmeta> -<refentrytitle>gtk-update-icon-cache</refentrytitle> -<manvolnum>1</manvolnum> + <refentrytitle>gtk-update-icon-cache</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">User Commands</refmiscinfo> </refmeta> <refnamediv> -<refname>gtk-update-icon-cache</refname> -<refpurpose>Icon theme caching utility</refpurpose> + <refname>gtk-update-icon-cache</refname> + <refpurpose>Icon theme caching utility</refpurpose> </refnamediv> <refsynopsisdiv> @@ -20,28 +21,29 @@ <arg choice="opt">--force</arg> <arg choice="opt">--ignore-theme-index</arg> <arg choice="opt">--index-only</arg> -<arg choice="opt">--source<arg>name</arg></arg> +<arg choice="opt">--source <arg choice="plain"><replaceable>NAME</replaceable></arg></arg> <arg choice="opt">--quiet</arg> <arg choice="opt">--validate</arg> -<arg choice="req">iconpath</arg> +<arg choice="plain"><replaceable>PATH</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> <refsect1><title>Description</title> <para> - <command>gtk-update-icon-cache</command> creates mmap()able cache + <command>gtk-update-icon-cache</command> creates mmapable cache files for icon themes. </para> <para> - It expects to be given the path to a icon theme directory containing an - <filename>index.theme</filename>, e.g. <filename>/usr/share/icons/hicolor</filename>, - and writes a <filename>icon-theme.cache</filename> containing cached - information about the icons in the directory tree below the given directory. + It expects to be given the <replaceable>PATH</replaceable> to a icon theme + directory containing an <filename>index.theme</filename>, e.g. + <filename>/usr/share/icons/hicolor</filename>, and writes a + <filename>icon-theme.cache</filename> containing cached information about + the icons in the directory tree below the given directory. </para> <para> GTK+ can use the cache files created by <command>gtk-update-icon-cache</command> to avoid a lot of system call and disk seek overhead when the application - starts. Since the format of the cache files allows them to be mmap()ed + starts. Since the format of the cache files allows them to be mmaped shared between multiple applications, the overall memory consumption is reduced as well. </para> @@ -59,8 +61,8 @@ <varlistentry> <term>--ignore-theme-index</term> <term>-t</term> - <listitem><para>Don't check for the existence of 'index.theme' in the icon - theme directory. Without this option, <command>gtk-update-icon-cache</command> + <listitem><para>Don't check for the existence of <filename>index.theme</filename> + in the icon theme directory. Without this option, <command>gtk-update-icon-cache</command> refuses to create an icon cache in a directory which does not appear to be the toplevel directory of an icon theme. </para></listitem> @@ -77,7 +79,7 @@ <term>--source</term> <term>-c</term> <listitem><para>Output a C header file declaring a constant - <replaceable>name</replaceable> with the contents of the icon + <replaceable>NAME</replaceable> with the contents of the icon cache.</para></listitem> </varlistentry> diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 8134a01b86..0b08465feb 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -2058,6 +2058,8 @@ gtk_menu_item_deselect gtk_menu_item_activate gtk_menu_item_toggle_size_request gtk_menu_item_toggle_size_allocate +gtk_menu_item_get_reserve_indicator +gtk_menu_item_set_reserve_indicator <SUBSECTION Standard> GTK_MENU_ITEM GTK_IS_MENU_ITEM @@ -3448,6 +3450,7 @@ gtk_text_view_move_mark_onscreen gtk_text_view_place_cursor_onscreen gtk_text_view_get_visible_rect gtk_text_view_get_iter_location +gtk_text_view_get_cursor_locations gtk_text_view_get_line_at_y gtk_text_view_get_line_yrange gtk_text_view_get_iter_at_location @@ -4201,6 +4204,7 @@ gtk_tree_view_column_set_clickable gtk_tree_view_column_get_clickable gtk_tree_view_column_set_widget gtk_tree_view_column_get_widget +gtk_tree_view_column_get_button gtk_tree_view_column_set_alignment gtk_tree_view_column_get_alignment gtk_tree_view_column_set_reorderable @@ -4285,6 +4289,7 @@ gtk_tree_view_row_expanded gtk_tree_view_set_reorderable gtk_tree_view_get_reorderable gtk_tree_view_get_path_at_pos +gtk_tree_view_is_blank_at_pos gtk_tree_view_get_cell_area gtk_tree_view_get_background_area gtk_tree_view_get_visible_rect @@ -4425,8 +4430,6 @@ gtk_cell_area_foreach gtk_cell_area_foreach_alloc gtk_cell_area_event gtk_cell_area_render -gtk_cell_area_set_style_detail -gtk_cell_area_get_style_detail gtk_cell_area_get_cell_allocation gtk_cell_area_get_cell_at_position gtk_cell_area_create_context @@ -4556,6 +4559,7 @@ gtk_cell_renderer_get_alignment gtk_cell_renderer_set_alignment gtk_cell_renderer_get_padding gtk_cell_renderer_set_padding +gtk_cell_renderer_get_state gtk_cell_renderer_is_activatable <SUBSECTION Width-for-height> @@ -5749,6 +5753,7 @@ gtk_style_new gtk_style_copy gtk_style_attach gtk_style_detach +gtk_style_get_context gtk_style_set_background gtk_style_apply_default_background gtk_style_lookup_color @@ -6009,6 +6014,7 @@ gtk_bindings_activate gtk_bindings_activate_event gtk_binding_set_activate gtk_binding_entry_add_signal +gtk_binding_entry_add_signal_from_string gtk_binding_entry_skip gtk_binding_entry_remove gtk_binding_set_add_path @@ -6959,6 +6965,8 @@ gtk_app_chooser_button_append_separator gtk_app_chooser_button_set_active_custom_item gtk_app_chooser_button_get_show_dialog_item gtk_app_chooser_button_set_show_dialog_item +gtk_app_chooser_button_get_heading +gtk_app_chooser_button_set_heading <SUBSECTION Standard> GtkAppChooserButtonClass @@ -6981,6 +6989,8 @@ GtkAppChooserDialog gtk_app_chooser_dialog_new gtk_app_chooser_dialog_new_for_content_type gtk_app_chooser_dialog_get_widget +gtk_app_chooser_dialog_set_heading +gtk_app_chooser_dialog_get_heading <SUBSECTION Standard> GtkAppChooserDialogClass diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types index 47295b1679..bf2ca649eb 100644 --- a/docs/reference/gtk/gtk3.types +++ b/docs/reference/gtk/gtk3.types @@ -1,4 +1,4 @@ -#include <gtk/gtk.h> +#include <gtk/gtkx.h> #include <gtk/gtkunixprint.h> gtk_about_dialog_get_type diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml index 6022ce7a1b..98a700abab 100644 --- a/docs/reference/gtk/migrating-2to3.xml +++ b/docs/reference/gtk/migrating-2to3.xml @@ -144,8 +144,8 @@ GAppLaunchContext *context; GError *error = NULL; - info = g_desktop_app_info_new ("epiphany.desktop"); - context = gdk_display_get_app_launch_context (display); + info = (GAppInfo*) g_desktop_app_info_new ("epiphany.desktop"); + context = (GAppLaunchContext*) gdk_display_get_app_launch_context (display); g_app_info_launch (info, NULL, context, &error); if (error) @@ -157,6 +157,10 @@ g_object_unref (info); g_object_unref (context); </programlisting></informalexample> + Remember that you have to include + <filename>gio/gdesktopappinfo.h</filename> + and use the <filename>gio-unix-2.0</filename> pkg-config file + when using g_desktop_app_info_new(). </listitem> <listitem>If you are launching a custom commandline, you can still use g_app_info_launch() with a GAppInfo that is constructed @@ -606,6 +610,7 @@ gtk_fixed_get_preferred_height (GtkWidget *widget, find-and-replace task. Please refer to the following table: <table> <tgroup cols="2"> + <title>GdkRegion to cairo_region_t</title> <thead> <row><entry>GDK</entry><entry>cairo</entry></row> </thead> @@ -697,7 +702,7 @@ g_object_unref (pixbuf); </section> <section> - <title>Replace colormaps by visuals</title> + <title>Replace GdkColormap by GdkVisual</title> <para> For drawing with cairo, it is not necessary to allocate colors, and a #GdkVisual provides enough information for cairo to handle colors @@ -747,6 +752,105 @@ on_alpha_screen_changed (GtkWindow *window, </section> <section> + <title>GdkDrawable is gone</title> + + <para> + #GdkDrawable has been removed in GTK+ 3, together with #GdkPixmap + and #GdkImage. The only remaining drawable class is #GdkWindow. + For dealing with image data, you should use cairo surfaces or + #GdkPixbufs. + </para> + + <para> + GdkDrawable functions that are useful with windows have been replaced + by corresponding GdkWindow functions: + <table> + <title>GdkDrawable to GdkWindow</title> + <tgroup cols="2"> + <thead> + <row><entry>GDK 2.x</entry><entry>GDK 3</entry></row> + </thead> + <tbody> + <row><entry>gdk_drawable_get_visual()</entry><entry>gdk_window_get_visual()</entry></row> + <row><entry>gdk_drawable_get_size()</entry><entry>gdk_window_get_width() + gdk_window_get_height()</entry></row> + <row><entry>gdk_pixbuf_get_from_drawable()</entry><entry>gdk_pixbuf_get_from_window()</entry></row> + <row><entry>gdk_drawable_get_clip_region()</entry><entry>gdk_window_get_clip_region()</entry></row> + <row><entry>gdk_drawable_get_visible_region()</entry><entry>gdk_window_get_visible_region()</entry></row> + </tbody> + </tgroup> + </table> + </para> + </section> + + <section> + <title>Event filtering</title> + + <para> + If your application uses the low-level event filtering facilities in GDK, + there are some changes you need to be aware of. + </para> + + <para> + The special-purpose GdkEventClient events and the gdk_add_client_message_filter() and gdk_display_add_client_message_filter() functions have been + removed. Receiving X11 ClientMessage events is still possible, using + the general gdk_window_add_filter() API. A client message filter like +<informalexample><programlisting> +static GdkFilterReturn +message_filter (GdkXEvent *xevent, GdkEvent *event, gpointer data) +{ + XClientMessageEvent *evt = (XClientMessageEvent *)xevent; + + /* do something with evt ... */ +} + + ... + +message_type = gdk_atom_intern ("MANAGER", FALSE); +gdk_display_add_client_message_filter (display, message_type, message_filter, NULL); +</programlisting></informalexample> + then looks like this: + <informalexample><programlisting> +static GdkFilterReturn +event_filter (GdkXEvent *xevent, GdkEvent *event, gpointer data) +{ + XClientMessageEvent *evt; + GdkAtom message_type; + + if (((XEvent *)xevent)->type != ClientMessage) + return GDK_FILTER_CONTINUE; + + evt = (XClientMessageEvent *)xevent; + message_type = XInternAtom (evt->display, "MANAGER", FALSE); + + if (evt->message_type != message_type) + return GDK_FILTER_CONTINUE; + + /* do something with evt ... */ +} + + ... + +gdk_window_add_filter (NULL, message_filter, NULL); +</programlisting></informalexample> + One advantage of using an event filter is that you can actually + remove the filter when you don't need it anymore, using + gdk_window_remove_filter(). + </para> + + <para> + The other difference to be aware of when working with event filters + in GTK+ 3 is that GDK now uses XI2 by default when available. That + means that your application does not receive core X11 key or button + events. Instead, all input events are delivered as XIDeviceEvents. + As a short-term workaround for this, you can force your application + to not use XI2, with gdk_disable_multidevice(). In the long term, + you probably want to rewrite your event filter to deal with + XIDeviceEvents. + </para> + </section> + + <section> <title>Backend-specific code</title> <para> In GTK+ 2.x, GDK could only be compiled for one backend at a time, @@ -790,6 +894,17 @@ on_alpha_screen_changed (GtkWindow *window, </section> <section> + <title>GtkPlug and GtkSocket</title> + + <para> + The #GtkPlug and #GtkSocket widgets are now X11-specific, and you + have to include the <filename><gtk/gtkx.h></filename> header + to use them. The previous section about proper handling of + backend-specific code applies, if you care about other backends. + </para> + </section> + + <section> <title>The GtkWidget::draw signal</title> <para> The GtkWidget #GtkWidget::expose-event signal has been replaced by @@ -917,7 +1032,7 @@ gtk_arrow_draw (GtkWidget *widget, </section> <section> - <title>Check your expand flags</title> + <title>Check your expand and fill flags</title> <para> The behaviour of expanding widgets has changed slightly in GTK+ 3, @@ -928,6 +1043,11 @@ gtk_arrow_draw (GtkWidget *widget, expand flag of the child from being inherited. See gtk_widget_set_hexpand() and gtk_widget_set_vexpand(). </para> + <para> + If you experience sizing problems with widgets in ported code, + carefully check the #GtkBox::expand and #GtkBox::fill flags of your + boxes. + </para> </section> <section> @@ -978,6 +1098,18 @@ gtk_arrow_draw (GtkWidget *widget, </section> <section> + <title>GtkEntryCompletion signal parameters</title> + + <para> + The #GtkEntryCompletion::match-selected and + #GtkEntryCompletion::cursor-on-match signals were erroneously + given the internal filter model instead of the users model. + This oversight has been fixed in GTK+ 3; if you have handlers + for these signals, they will likely need slight adjustments. + </para> + </section> + + <section> <title>Resize grips</title> <para> diff --git a/docs/reference/gtk/migrating-GtkApplication.xml b/docs/reference/gtk/migrating-GtkApplication.xml index 712d521a45..a53f165d55 100644 --- a/docs/reference/gtk/migrating-GtkApplication.xml +++ b/docs/reference/gtk/migrating-GtkApplication.xml @@ -59,11 +59,21 @@ The same application using GtkApplication: static void activate (GtkApplication *app) { + GList *list; GtkWidget *window; - window = create_my_window (); - gtk_window_set_application (GTK_WINDOW (window), app); - gtk_widget_show (window); + list = gtk_application_get_windows (app); + + if (list) + { + gtk_window_present (GTK_WINDOW (list->data)); + } + else + { + window = create_my_window (); + gtk_window_set_application (GTK_WINDOW (window), app); + gtk_widget_show (window); + } } int diff --git a/docs/reference/gtk/migrating-GtkStyleContext.xml b/docs/reference/gtk/migrating-GtkStyleContext.xml index 42ede40768..b2e73edc41 100644 --- a/docs/reference/gtk/migrating-GtkStyleContext.xml +++ b/docs/reference/gtk/migrating-GtkStyleContext.xml @@ -27,6 +27,21 @@ with possible variants such as the dark theme being named <filename>gtk-dark.css</filename> in the same directory. </para> + + <para> + If your theme RC file was providing values for #GtkSettings, you + can install a <filename>settings.ini</filename> keyfile along with + the <filename>gtk.css</filename> to provide theme-specific defaults + for settings. + </para> + + <para> + Key themes have been converted to CSS syntax too. See the + <link linkend="css-binding-set">GtkCssProvider</link> documentation + information about the syntax. GTK+ looks for key themes in the file + <filename>$datadir/themes/<replaceable>theme</replaceable>/gtk-3.0/gtk-keys.css</filename>, where <replaceable>theme</replaceable> is the current + key theme name. + </para> </section> <section id="gtk-migrating-theme-GtkStyleContext-engines"> @@ -414,8 +429,8 @@ <orderedlist> <listitem> - Replace <literal>style_set()</literal> calls with - <literal>style_updated()</literal>. + Replace #GtkWidget::style-set handlers with + #GtkWidget::style-updated handlers. </listitem> <listitem> diff --git a/docs/reference/gtk/objects_grouped.sgml b/docs/reference/gtk/objects_grouped.sgml index 9b0c95bad8..78dc95bf9f 100644 --- a/docs/reference/gtk/objects_grouped.sgml +++ b/docs/reference/gtk/objects_grouped.sgml @@ -127,7 +127,6 @@ <emphasis>Misc. Objects</emphasis> <link linkend="GtkAdjustment">GtkAdjustment</link> - <link linkend="GtkItemFactory">GtkItemFactory</link> <link linkend="GtkInvisible">GtkInvisible</link> </literallayout></entry> diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index b633a48f4d..24f6b99413 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -35,11 +35,11 @@ How do I get started with GTK+? </para></question> <answer><para> -The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a -<ulink url="http://www.gtk.org/tutorial">tutorial</ulink> and a -<ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging -from whitepapers to online books can be found at the -<ulink url="http://library.gnome.org/devel/">GNOME developer's site</ulink>. +The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers some +<ulink url="http://www.gtk.org/documentation">tutorials</ulink> and other +documentation (most of it about GTK+ 2.x, but mostly still applicable). +More documentation ranging from whitepapers to online books can be found at +the <ulink url="http://library.gnome.org/devel/">GNOME developer's site</ulink>. After studying these materials you should be well prepared to come back to this reference manual for details. </para></answer> diff --git a/docs/reference/gtk/running.sgml b/docs/reference/gtk/running.sgml index 9a9376ba64..40a70d7ac0 100644 --- a/docs/reference/gtk/running.sgml +++ b/docs/reference/gtk/running.sgml @@ -199,9 +199,13 @@ additional environment variables. <para> A list of modules to load. Note that GTK+ also allows to specify modules to load via a commandline option (<option>--gtk-module</option>) and with the <literal>gtk-modules</literal> setting. </para> + <warning> + Note that this environment variable is read by GTK+ 2.x too, + which may not have the same set of modules available for loading. + </warning> </formalpara> -<formalpara> +<formalpara id="gtk-path"> <title><envar>GTK_PATH</envar></title> <para> @@ -211,7 +215,7 @@ additional environment variables. modules, file system backends and print backends. If the path to the dynamically loaded object is given as an absolute path name, then GTK+ loads it directly. - Otherwise, GTK+ goes in turn through the directories in GTK_PATH, + Otherwise, GTK+ goes in turn through the directories in <envar>GTK_PATH</envar>, followed by the directory <filename>.gtk-3.0</filename> in the user's home directory, followed by the system default directory, which is <filename><replaceable>libdir</replaceable>/gtk-3.0/modules</filename>. @@ -241,6 +245,12 @@ additional environment variables. The components of GTK_PATH are separated by the ':' character on Linux and Unix, and the ';' character on Windows. </para> + <warning> + Note that this environment variable is read by GTK+ 2.x too, which + makes it unsuitable for setting it system-wide (or session-wide), + since doing so will cause either GTK+ 2.x applications or GTK+ 3 + applications to see incompatible modules. + </warning> </formalpara> <formalpara> @@ -248,23 +258,32 @@ additional environment variables. <para> Specifies an IM module to use in preference to the one determined - from the locale. If this isn't set and you are running on the system + from the locale. If this isn't set and you are running on the system that enables <literal>XSETTINGS</literal> and has a value in <literal>Gtk/IMModule</literal>, that will be used for the default IM module. </para> </formalpara> -<formalpara id="im-module-file"> +<formalpara id="gtk-im-module-file"> <title><envar>GTK_IM_MODULE_FILE</envar></title> <para> Specifies the file listing the IM modules to load. This environment - variable overrides the <literal>im_module_file</literal> specified in - the RC files, which in turn overrides the default value + variable the default value <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/immodules.cache</filename> (<replaceable>libdir</replaceable> has the same meaning here as explained for <envar>GTK_PATH</envar>). </para> + <para> + The <filename>immodules.cache</filename> file is generated by the + <command>gtk-query-immodules-3.0</command> utility. + </para> + <warning> + Note that this environment variable is read by GTK+ 2.x too, which + makes it unsuitable for setting it system-wide (or session-wide), + since doing so will cause either GTK+ 2.x applications or GTK+ 3 + applications to see the wrong list of IM modules. + </warning> </formalpara> <formalpara> @@ -297,9 +316,13 @@ nevertheless. <para> Specifies the file listing the GdkPixbuf loader modules to load. This environment variable overrides the default value - <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/loaders.cache</filename> + <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/loaders.cache</filename> (<replaceable>libdir</replaceable> is the sysconfdir specified when - GTK+ was configured, usually <filename>/usr/local/lib</filename>.) + GTK+ was configured, usually <filename>/usr/local/lib</filename>.) + </para> + <para> + The <filename>loaders.cache</filename> file is generated by the + <command>gdk-pixbuf-query-loaders</command> utility. </para> </formalpara> diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index e7c14a5afa..6798cae786 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -3,6 +3,7 @@ gtkactiongroup.sgml gtkaboutdialog.sgml gtkadjustment.sgml gtkbbox.sgml +gtkbindings.sgml gtkbox.sgml gtkbuilder.sgml gtkbutton.sgml @@ -49,6 +50,7 @@ gtkpaned.sgml gtkpapersize.sgml gtkprinter.sgml gtkprintjob.sgml +gtkprintoperation.sgml gtkprogressbar.sgml gtkradioaction.sgml gtkradiobutton.sgml diff --git a/docs/reference/gtk/tmpl/gtkbindings.sgml b/docs/reference/gtk/tmpl/gtkbindings.sgml deleted file mode 100644 index 61961adab0..0000000000 --- a/docs/reference/gtk/tmpl/gtkbindings.sgml +++ /dev/null @@ -1,296 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Bindings - -<!-- ##### SECTION Short_Description ##### --> -Key bindings for individual widgets - -<!-- ##### SECTION Long_Description ##### --> -<para> -GtkBinding provides a mechanism for configuring GTK+ key bindings through -RC files. This eases key binding adjustments for application developers as -well as users and provides GTK+ users or administrators with high key -binding configurability which requires no application or toolkit side changes. -</para> - -<refsect2> -<anchor id="gtk-bindings-install"/> -<title>Installing a key binding</title> - -<para> -A resource file binding consists of a 'binding' definition and a match -statement to apply the binding to specific widget types. Details on the -matching mechanism are described under -<link linkend="gtkrc-pathnames-and-patterns">Pathnames and patterns</link>. -Inside the binding definition, key combinations are bound to specific signal -emissions on the target widget. Key combinations are strings consisting of -an optional #GdkModifierType name and -<link linkend="gdk-Keyboard-Handling">key names</link> such as those defined -in <filename><gdk/gdkkeysyms.h></filename> or returned from -gdk_keyval_name(), they have to be parsable by gtk_accelerator_parse(). -Specifications of signal emissions consist of a string identifying the signal -name, and a list of signal specific arguments in parenthesis. -</para> -<para> -For example for binding Control and the left or right cursor keys of a -#GtkEntry widget to the #GtkEntry::move-cursor signal, so movement occurs -in 3 letter steps, the following binding can be used: - -<informalexample><programlisting> -binding "MoveCursor3" { - bind "<Control>Right" { - "move-cursor" (visual-positions, 3, 0) - } - bind "<Control>Left" { - "move-cursor" (visual-positions, -3, 0) - } -} -class "GtkEntry" binding "MoveCursor3" -</programlisting></informalexample> -</para> - - -<anchor id="gtk-bindings-unbind"/> -<title>Unbinding existing key bindings</title> -<para> -GTK+ already defines a number of useful bindings for the widgets it provides. -Because custom bindings set up in RC files take precedence over the default -bindings shipped with GTK+, overriding existing bindings as demonstrated in -<link linkend="gtk-bindings-install">Installing a key binding</link> -works as expected. The same mechanism can not be used to "unbind" existing -bindings, however. - -<informalexample><programlisting> -binding "MoveCursor3" { - bind "<Control>Right" { } - bind "<Control>Left" { } -} -class "GtkEntry" binding "MoveCursor3" -</programlisting></informalexample> - -The above example will not have the desired effect of causing -"<Control>Right" and "<Control>Left" key presses to be ignored -by GTK+. Instead, it just causes any existing bindings from the bindings -set "MoveCursor3" to be deleted, so when "<Control>Right" or -"<Control>Left" are pressed, no binding for these keys is found in -binding set "MoveCursor3". GTK+ will thus continue to search for matching -key bindings, and will eventually lookup and find the default GTK+ bindings -for entries which implement word movement. To keep GTK+ from activating its -default bindings, the "unbind" keyword can be used like this: - -<informalexample><programlisting> -binding "MoveCursor3" { - unbind "<Control>Right" - unbind "<Control>Left" -} -class "GtkEntry" binding "MoveCursor3" -</programlisting></informalexample> - -Now, GTK+ will find a match when looking up "<Control>Right" and -"<Control>Left" key presses before it resorts to its default -bindings, and the match instructs it to abort ("unbind") the search, so -the key presses are not consumed by this widget. As usual, further processing -of the key presses, e.g. by an entry's parent widget, is now possible. -</para> - -<para> -The "unbind" functionality has been introduced in GTK+ 2.12. -</para> - -</refsect2> - -<!-- ##### SECTION See_Also ##### --> -<para> -<variablelist> - -<varlistentry> -<term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link> -</term> -<listitem><para>installing and using keyboard short-cuts.</para></listitem> -</varlistentry> - -<varlistentry> -<term><link linkend="Resource-Files">Resource Files</link> -</term> -<listitem><para>GTK+ Resource Files - behavior and style definitions.</para></listitem> -</varlistentry> - -</variablelist> -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkBindingSet ##### --> -<para> -A binding set maintains a list of activatable key bindings. -A single binding set can match multiple types of widgets. -Similar to styles, widgets can be mapped by widget name paths, widget -class paths or widget class types. When a binding within a set is -matched upon activation, an action signal is emitted on the target -widget to carry out the actual activation. -</para> - -@set_name: unique binding set name -@priority: unused -@widget_path_pspecs: widgets matched by path that this binding set applies to -@widget_class_pspecs: widgets matched by class path that this binding set applies to -@class_branch_pspecs: widgets matched by class that this binding set applies to -@entries: the key binding entries in this binding set -@current: implementation detail -@parsed: whether this binding set stems from an RC file and is reset upon theme changes - -<!-- ##### STRUCT GtkBindingEntry ##### --> -<para> -Each key binding element of a binding sets binding list is represented by -a #GtkBindingEntry. -</para> - -@keyval: key value to match -@modifiers: key modifier to match -@binding_set: binding set this entry belongs to -@destroyed: implementation detail -@in_emission: implementation detail -@marks_unbound: implementation detail -@set_next: linked list of entries maintained by binding set -@hash_next: implementation detail -@signals: action signals of this entry - -<!-- ##### STRUCT GtkBindingSignal ##### --> -<anchor id="keybinding-signals"/> -<para> -A #GtkBindingSignal stores the necessary information to activate a widget -in response to a key press via a signal emission. -</para> - -@next: implementation detail -@signal_name: the action signal to be emitted -@n_args: number of arguments specified for the signal -@args: the arguments specified for the signal - -<!-- ##### STRUCT GtkBindingArg ##### --> -<para> -A #GtkBindingArg holds the data associated with an argument for a -key binding signal emission as stored in #GtkBindingSignal. -</para> - -@arg_type: implementation detail - -<!-- ##### FUNCTION gtk_binding_entry_add_signall ##### --> -<para> - -</para> - -@binding_set: -@keyval: -@modifiers: -@signal_name: -@binding_args: - - -<!-- ##### FUNCTION gtk_binding_set_new ##### --> -<para> - -</para> - -@set_name: -@Returns: - - -<!-- ##### FUNCTION gtk_binding_set_by_class ##### --> -<para> - -</para> - -@object_class: -@Returns: - - -<!-- ##### FUNCTION gtk_binding_set_find ##### --> -<para> - -</para> - -@set_name: -@Returns: - - -<!-- ##### FUNCTION gtk_bindings_activate ##### --> -<para> - -</para> - -@object: -@keyval: -@modifiers: -@Returns: - - -<!-- ##### FUNCTION gtk_bindings_activate_event ##### --> -<para> - -</para> - -@object: -@event: -@Returns: - - -<!-- ##### FUNCTION gtk_binding_set_activate ##### --> -<para> - -</para> - -@binding_set: -@keyval: -@modifiers: -@object: -@Returns: - - -<!-- ##### FUNCTION gtk_binding_entry_add_signal ##### --> -<para> - -</para> - -@binding_set: -@keyval: -@modifiers: -@signal_name: -@n_args: -@Varargs: - - -<!-- ##### FUNCTION gtk_binding_entry_skip ##### --> -<para> - -</para> - -@binding_set: -@keyval: -@modifiers: - - -<!-- ##### FUNCTION gtk_binding_entry_remove ##### --> -<para> - -</para> - -@binding_set: -@keyval: -@modifiers: - - -<!-- ##### FUNCTION gtk_binding_set_add_path ##### --> -<para> - -</para> - -@binding_set: -@path_type: -@path_pattern: -@priority: - - diff --git a/docs/reference/gtk/tmpl/gtkclist.sgml b/docs/reference/gtk/tmpl/gtkclist.sgml deleted file mode 100644 index 25a18252d5..0000000000 --- a/docs/reference/gtk/tmpl/gtkclist.sgml +++ /dev/null @@ -1,1312 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkCList - -<!-- ##### SECTION Short_Description ##### --> -A multi-columned scrolling list widget - -<!-- ##### SECTION Long_Description ##### --> -<para> -The #GtkCList widget is a very useful multi-columned scrolling list. -It can display data in nicely aligned vertical columns, with titles -at the top of the list. -</para> -<para> -GtkCList has been deprecated since GTK+ 2.0 and should not be used -in newly written code. Use #GtkTreeView instead. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### STRUCT GtkCList ##### --> -<para> -This is the embodiment of the #GtkCList widget. This structure contains -only private data, and should be accessed only via the CList API. -</para> - - -<!-- ##### SIGNAL GtkCList::abort-column-resize ##### --> -<para> -This signal is emitted when a column resize is aborted. -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::click-column ##### --> -<para> -This signal is emitted when a column title is clicked. -</para> - -@clist: The object which received the signal. -@column: The number of the column. - -<!-- ##### SIGNAL GtkCList::end-selection ##### --> -<para> -This signal is emitted when a selection ends in a -multiple selection CList. -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::extend-selection ##### --> -<para> -This signal is emitted when the selection is extended. -</para> - -@clist: the object which received the signal. -@scroll_type: A #GtkScrollType value of any scrolling operation the -occured during the selection. -@position: A value between 0.0 and 1.0. -@auto_start_selection: %TRUE or %FALSE. - -<!-- ##### SIGNAL GtkCList::resize-column ##### --> -<para> -This signal is emitted when a column is resized. -</para> - -@clist: The object which received the signal. -@column: The number of the column -@width: The new width of the column. - -<!-- ##### SIGNAL GtkCList::row-move ##### --> -<para> -This signal is emitted when a row is moved. -</para> - -@clist: The object which received the signal. -@arg1: The source position of the row. -@arg2: The destination position of the row. - -<!-- ##### SIGNAL GtkCList::scroll-horizontal ##### --> -<para> -This signal is emitted when the CList is scrolled horizontally. -</para> - -@clist: the object which received the signal. -@scroll_type: A #GtkScrollType value of how the scroll operation occured. -@position: a value between 0.0 and 1.0. - -<!-- ##### SIGNAL GtkCList::scroll-vertical ##### --> -<para> -This signal is emitted when the CList is scrolled vertically. -</para> - -@clist: the object which received the signal. -@scroll_type: A #GtkScrollType value of how the scroll operation occured. -@position: A value between 0.0 and 1.0. - -<!-- ##### SIGNAL GtkCList::select-all ##### --> -<para> -This signal is emitted when all the rows are selected in a CList. -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::select-row ##### --> -<para> -This signal is emitted when the user selects a row in the list. -It is emitted for every row that is selected in a multi-selection or -by calling gtk_clist_select_all(). -</para> - -@clist: The object which received the signal. -@row: The row selected. -@column: The column where the selection occured. -@event: A #GdkEvent structure for the selection. - -<!-- ##### SIGNAL GtkCList::set-scroll-adjustments ##### --> -<para> - -</para> - -@clist: the object which received the signal. -@arg1: -@arg2: - -<!-- ##### SIGNAL GtkCList::start-selection ##### --> -<para> -This signal is emitted when a drag-selection is started in -a multiple-selection CList. -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::toggle-add-mode ##### --> -<para> -This signal is emitted when "add mode" is toggled. -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::toggle-focus-row ##### --> -<para> - -</para> - -@clist: The object which received the signal. - -<!-- ##### SIGNAL GtkCList::undo-selection ##### --> -<para> -This signal is emitted when an undo selection occurs in the CList, -probably via calling gtk_clist_undo_selection(). -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::unselect-all ##### --> -<para> -This signal is emitted when all rows are unselected in a CList. -</para> - -@clist: the object which received the signal. - -<!-- ##### SIGNAL GtkCList::unselect-row ##### --> -<para> -This signal is emitted when the user unselects a row in the list. -It is emitted for every row that is unselected in a multi-selection or -by calling gtk_clist_unselect_all(). It is also emitted for the -previously selected row in a "single" or "browse" mode CList. -</para> - -@clist: The object which received the signal. -@row: The selected row -@column: The column where the selection occured. -@event: - -<!-- ##### ARG GtkCList:n-columns ##### --> -<para> -An integer value for a column. -</para> - -<!-- ##### ARG GtkCList:reorderable ##### --> -<para> -A boolean value for determining if the user can re-order the CList's -columns. -</para> - -<!-- ##### ARG GtkCList:row-height ##### --> -<para> -An integer value representing the height of a row in pixels. -</para> - -<!-- ##### ARG GtkCList:selection-mode ##### --> -<para> -Sets the type of selection mode for the CList. -</para> - -<!-- ##### ARG GtkCList:shadow-type ##### --> -<para> -Sets the shadowing for the CList. -</para> - -<!-- ##### ARG GtkCList:sort-type ##### --> -<para> - -</para> - -<!-- ##### ARG GtkCList:titles-active ##### --> -<para> -A boolean value for setting whether the column titles can be -clicked. -</para> - -<!-- ##### ARG GtkCList:use-drag-icons ##### --> -<para> -A boolean value for setting whether to use icons during drag -operations. -</para> - -<!-- ##### ENUM GtkCellType ##### --> -<para> -Identifies the type of element in the current cell of the CList. Cells can -contain text, pixmaps, or both. Unfortunately support for %GTK_CELL_WIDGET -was never completed. -</para> - -@GTK_CELL_EMPTY: -@GTK_CELL_TEXT: -@GTK_CELL_PIXMAP: -@GTK_CELL_PIXTEXT: -@GTK_CELL_WIDGET: - -<!-- ##### ENUM GtkButtonAction ##### --> -<para> -Values for specifying what mouse button events a CList will -react to. -</para> - -@GTK_BUTTON_IGNORED: -@GTK_BUTTON_SELECTS: -@GTK_BUTTON_DRAGS: -@GTK_BUTTON_EXPANDS: - -<!-- ##### MACRO GTK_CLIST_FLAGS ##### --> -<para> -Reads the current flags of the specified CList. -</para> - -@clist: The #GtkCList widget from which to get the flags - - -<!-- ##### MACRO GTK_CLIST_SET_FLAG ##### --> -<para> -A macro to set a particular flag for the specified CList. -</para> - -@clist: The #GtkCList widget to affect. -@flag: A single #GtkCList flag to set. NOTE: Do not add the GTK_ prefix. - - -<!-- ##### MACRO GTK_CLIST_UNSET_FLAG ##### --> -<para> -A macro to clear a particular flag for the specified CList. -</para> - -@clist: The #GtkCList widget to affect. -@flag: A single #GtkCList flag to clear. NOTE: Do not add the GTK_ prefix. - - -<!-- ##### MACRO GTK_CLIST_IN_DRAG ##### --> -<para> -A macro to check whether the #GtkCList is in "drag mode." -</para> - -@clist: The #GtkCList to check. - - -<!-- ##### MACRO GTK_CLIST_ROW_HEIGHT_SET ##### --> -<para> -A macro to check whether the #GtkCList's row height is set. -</para> - -@clist: The #GtkCList to check. - - -<!-- ##### MACRO GTK_CLIST_SHOW_TITLES ##### --> -<para> -A macro to check whether the flag for showing the -widget's column titles is set. -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_ADD_MODE ##### --> -<para> -A macro to test whether the CList is in "add mode." -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_AUTO_SORT ##### --> -<para> -A macro to test whether the CList has automatic sorting -switched on. -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_AUTO_RESIZE_BLOCKED ##### --> -<para> -A macro to check if automatic resizing of columns is blocked. -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_REORDERABLE ##### --> -<para> -A macro to test if the CList's columns are re-orderable -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_USE_DRAG_ICONS ##### --> -<para> -A macro to check if the USE_DRAG_ICONS property is enabled. -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_DRAW_DRAG_LINE ##### --> -<para> -A macro to check if the DRAW_DRAG_LINE property is enabled. -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_DRAW_DRAG_RECT ##### --> -<para> -A macro to check if the DRAW_DRAG_RECT property is enabled. -</para> - -@clist: The #GtkCList widget to check. - - -<!-- ##### MACRO GTK_CLIST_ROW ##### --> -<para> -A macro to cast a GList element to a CListRow pointer. -</para> - -@_glist_: The GList element to convert. - - -<!-- ##### MACRO GTK_CELL_TEXT ##### --> -<para> -A macro to cast a generic #GtkCList cell item to a GtkCellText pointer. -</para> - -@cell: The #GtkCList cell item to convert. - - -<!-- ##### MACRO GTK_CELL_PIXMAP ##### --> -<para> -A macro to cast a generic #GtkCList cell item to a GtkCellPixmap pointer. -</para> - -@cell: The #GtkCList cell item to convert. - - -<!-- ##### MACRO GTK_CELL_PIXTEXT ##### --> -<para> -A macro to cast a generic #GtkCList cell item to a GtkCellPixText pointer. -</para> - -@cell: The #GtkCList cell item to convert. - - -<!-- ##### MACRO GTK_CELL_WIDGET ##### --> -<para> -A macro to cast a generic #GtkCList cell item to a GtkCellWidget pointer. -</para> - -@cell: The #GtkCList cell item to convert. - - -<!-- ##### USER_FUNCTION GtkCListCompareFunc ##### --> -<para> -Function prototype for the compare function callback. -</para> - -@clist: The #GtkCList that is affected. -@ptr1: A #gconstpointer to the first node to compare. -@ptr2: A #gconstpointer to the second node to compare. -@Returns: 0 if the nodes are equal, less than 0 if the first node should -come before the second, and greater than 1 if the second come before the -first. - - -<!-- ##### STRUCT GtkCListColumn ##### --> -<para> -A structure that the #GtkCList widget uses to keep track of information -about its columns. -</para> - -@title: -@area: -@button: -@window: -@width: -@min_width: -@max_width: -@justification: -@visible: -@width_set: -@resizeable: -@auto_resize: -@button_passive: - -<!-- ##### STRUCT GtkCListRow ##### --> -<para> -A structure that the #GtkCList widget uses to keep track of information -about its rows. -</para> - -@cell: -@state: -@foreground: -@background: -@style: -@data: -@destroy: -@fg_set: -@bg_set: -@selectable: - -<!-- ##### STRUCT GtkCellText ##### --> -<para> -A structure that the #GtkCList widget uses to keep track of #GtkCList cells -that contain text. -</para> - -@type: -@vertical: -@horizontal: -@style: -@text: - -<!-- ##### STRUCT GtkCellPixmap ##### --> -<para> -A structure that the #GtkCList widget uses to keep track of #GtkCList cells -that contain a GdkPixmap. -</para> - -@type: -@vertical: -@horizontal: -@style: -@pixmap: -@mask: - -<!-- ##### STRUCT GtkCellPixText ##### --> -<para> -A structure that the #GtkCList widget uses to keep track of #GtkCList cells -that contain a combination of text and a GdkPixmap. -</para> - -@type: -@vertical: -@horizontal: -@style: -@text: -@spacing: -@pixmap: -@mask: - -<!-- ##### STRUCT GtkCellWidget ##### --> -<para> -A structure that the #GtkCList widget uses to keep track of #GtkCList cells -that contain another widget. -</para> - -@type: -@vertical: -@horizontal: -@style: -@widget: - -<!-- ##### STRUCT GtkCell ##### --> -<para> -A generic structure that the #GtkCList widget uses to keep track of the -contents of each of its cells. -</para> - -@type: -@vertical: -@horizontal: -@style: -@widget: - -<!-- ##### STRUCT GtkCListCellInfo ##### --> -<para> -A simple structure that the #GtkCList widget uses to keep track -of the location of a cell. -</para> - -@row: -@column: - -<!-- ##### STRUCT GtkCListDestInfo ##### --> -<para> -A simple structure that the #GtkCList widget uses to track -a cell for a drag operation. -</para> - -@cell: -@insert_pos: - -<!-- ##### ENUM GtkCListDragPos ##### --> -<para> -An enumeration for drag operations. -</para> - -@GTK_CLIST_DRAG_NONE: -@GTK_CLIST_DRAG_BEFORE: -@GTK_CLIST_DRAG_INTO: -@GTK_CLIST_DRAG_AFTER: - -<!-- ##### FUNCTION gtk_clist_new ##### --> -<para> -Creates a new #GtkCList widget for use. -</para> - -@columns: The number of columns the #GtkCList should have. -@Returns: A pointer to a new GtkCList object. - - -<!-- ##### FUNCTION gtk_clist_new_with_titles ##### --> -<para> -Creates a new #GtkCList widget with column titles for use. -</para> - -@columns: The number of columns the #GtkCList should have. -@titles: A string array of titles for the widget. There should be -enough strings in the array for the specified number of columns. -@Returns: A pointer to a new GtkCList object. - - -<!-- ##### FUNCTION gtk_clist_set_shadow_type ##### --> -<para> -Sets the shadow type for the specified CList. Changing this value -will cause the #GtkCList to update its visuals. -</para> - -@clist: The #GtkCList to affect. -@type: The GtkShadowType desired. - - -<!-- ##### FUNCTION gtk_clist_set_selection_mode ##### --> -<para> -Sets the selection mode for the specified CList. This allows you to -set whether only one or more than one item can be selected at a time -in the widget. Note that setting the widget's selection mode to one -of GTK_SELECTION_BROWSE or GTK_SELECTION_SINGLE will cause all the -items in the #GtkCList to become deselected. -</para> - -@clist: The #GtkCList to affect. -@mode: The GtkSelectionMode type to set for this CList. - - -<!-- ##### FUNCTION gtk_clist_freeze ##### --> -<para> -Causes the #GtkCList to stop updating its visuals until a matching call to -gtk_clist_thaw() is made. This function is useful if a lot of changes -will be made to the widget that may cause a lot of visual updating to -occur. Note that calls to gtk_clist_freeze() can be nested. -</para> - -@clist: The #GtkCList to freeze. - - -<!-- ##### FUNCTION gtk_clist_thaw ##### --> -<para> -Causes the specified #GtkCList to allow visual updates. -</para> - -@clist: The #GtkCList to thaw. - - -<!-- ##### FUNCTION gtk_clist_column_titles_show ##### --> -<para> -This function causes the #GtkCList to show its column titles, if -they are not already showing. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_column_titles_hide ##### --> -<para> -Causes the #GtkCList to hide its column titles, if they are currently -showing. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_column_title_active ##### --> -<para> -Sets the specified column in the #GtkCList to become selectable. You can -then respond to events from the user clicking on a title button, and take -appropriate action. -</para> - -@clist: The #GtkCList to affect. -@column: The column to make active, counting from 0. - - -<!-- ##### FUNCTION gtk_clist_column_title_passive ##### --> -<para> -Causes the specified column title button to become passive, i.e., does -not respond to events, such as the user clicking on it. -</para> - -@clist: The #GtkCList to affect. -@column: The column to make passive, counting from 0. - - -<!-- ##### FUNCTION gtk_clist_column_titles_active ##### --> -<para> -Causes all column title buttons to become active. This is the same -as calling gtk_clist_column_title_active() for each column. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_column_titles_passive ##### --> -<para> -Causes all column title buttons to become passive. This is the same -as calling gtk_clist_column_title_passive() for each column. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_set_column_title ##### --> -<para> -Sets the title for the specified column. -</para> - -@clist: The #GtkCList to affect. -@column: The column whose title should be changed. -@title: A string to be the column's title. - - -<!-- ##### FUNCTION gtk_clist_set_column_widget ##### --> -<para> -Sets a widget to be used as the specified column's title. This -can be used to place a pixmap or something else as the column -title, instead of the standard text. -</para> - -@clist: The #GtkCList to affect. -@column: The column whose title should be a widget. -@widget: A pointer to a previously create widget. - - -<!-- ##### FUNCTION gtk_clist_set_column_justification ##### --> -<para> -Sets the justification to be used for all text in the specified -column. -</para> - -@clist: The #GtkCList to affect. -@column: The column which should be affected. -@justification: A GtkJustification value for the column. - - -<!-- ##### FUNCTION gtk_clist_set_column_visibility ##### --> -<para> -Allows you to set whether a specified column in the #GtkCList should -be hidden or shown. Note that at least one column must always be -showing, so attempting to hide the last visible column will be -ignored. -</para> - -@clist: The #GtkCList to affect. -@column: The column to set visibility. -@visible: %TRUE or %FALSE. - - -<!-- ##### FUNCTION gtk_clist_set_column_resizeable ##### --> -<para> -Lets you specify whether a specified column should be resizeable -by the user. Note that turning on resizeability for the column will -automatically shut off auto-resizing, but turning off resizeability -will NOT turn on auto-resizing. This must be done manually via a -call to gtk_clist_set_column_auto_resize(). -</para> - -@clist: The #GtkCList to affect. -@column: The column on which to set resizeability. -@resizeable: %TRUE or %FALSE. - - -<!-- ##### FUNCTION gtk_clist_set_column_auto_resize ##### --> -<para> -Lets you specify whether a column should be automatically resized -by the widget when data is added or removed. Enabling auto-resize -on a column explicity disallows user-resizing of the column. -</para> - -@clist: The #GtkCList to affect. -@column: The column on which to set auto-resizing. -@auto_resize: %TRUE or %FALSE. - - -<!-- ##### FUNCTION gtk_clist_optimal_column_width ##### --> -<para> -Gets the required width in pixels that is needed to show -everything in the specified column. -</para> - -@clist: The #GtkCList to check. -@column: The column to check. -@Returns: The required width in pixels for the column. - - -<!-- ##### FUNCTION gtk_clist_set_column_width ##### --> -<para> -Causes the column specified for the #GtkCList to be set to -a specified width. -</para> - -@clist: The #GtkCList to affect. -@column: The column to set the width. -@width: The width, in pixels. - - -<!-- ##### FUNCTION gtk_clist_set_column_min_width ##### --> -<para> -Causes the column specified to have a minimum width, preventing -the user from resizing it smaller than that specified. -</para> - -@clist: The #GtkCList to affect. -@column: The column to set the minimum width. -@min_width: The width, in pixels. - - -<!-- ##### FUNCTION gtk_clist_set_column_max_width ##### --> -<para> -Causes the column specified to have a maximum width, preventing -the user from resizing it larger than that specified. -</para> - -@clist: The #GtkCList to affect. -@column: The column to set the maximum width. -@max_width: The width, in pixels. - - -<!-- ##### FUNCTION gtk_clist_set_row_height ##### --> -<para> -Causes the #GtkCList to have a specified height for its -rows. Setting the row height to 0 allows the #GtkCList to adjust -automatically to data in the row. -</para> - -@clist: The #GtkCList to affect. -@height: The height, in pixels. - - -<!-- ##### FUNCTION gtk_clist_moveto ##### --> -<para> -Tells the CList widget to visually move to the specified -row and column. -</para> - -@clist: The #GtkCList to affect. -@row: The row to which to move. -@column: The column to which to move. -@row_align: A value between 0 and 1 that describes the positioning of -the row in relation to the viewable area of the CList's contents. -@col_align: A value between 0 and 1 that describes the positioning of -the column in relation to the viewable area of the CList's contents. - - -<!-- ##### FUNCTION gtk_clist_row_is_visible ##### --> -<para> -Checks how the specified row is visible. -</para> - -@clist: The #GtkCList to affect. -@row: The row to query. -@Returns: A #GtkVisibility value that tells you how the row is visible. - - -<!-- ##### FUNCTION gtk_clist_get_cell_type ##### --> -<para> -Checks the type of cell at the location specified. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@Returns: A #GtkCellType value describing the cell. - - -<!-- ##### FUNCTION gtk_clist_set_text ##### --> -<para> -Sets the displayed text in the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@text: The text to set in the cell. - - -<!-- ##### FUNCTION gtk_clist_get_text ##### --> -<para> -Gets the text for the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row to query. -@column: The column to query. -@text: A pointer to a pointer to store the text. -@Returns: 1 if the cell's text could be retrieved, 0 otherwise. - - -<!-- ##### FUNCTION gtk_clist_set_pixmap ##### --> -<para> -Sets a pixmap for the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@pixmap: A pointer to a #GdkPixmap to place in the cell. -@mask: A pointer to a #GdkBitmap mask for the cell. - - -<!-- ##### FUNCTION gtk_clist_get_pixmap ##### --> -<para> -Gets the pixmap and bitmap mask of the specified cell. The returned mask value can be NULL. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@pixmap: A pointer to a pointer to store the cell's #GdkPixmap. -@mask: A pointer to a pointer to store the cell's #GdkBitmap mask. -@Returns: 1 if the cell's pixmap could be retrieved, 0 otherwise. - - -<!-- ##### FUNCTION gtk_clist_set_pixtext ##### --> -<para> -Sets text and a pixmap/bitmap on the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@text: The text to set in the cell. -@spacing: The spacing between the cell's text and pixmap. -@pixmap: A pointer to a #GdkPixmap for the cell. -@mask: A pointer to a #GdkBitmap mask for the cell. - - -<!-- ##### FUNCTION gtk_clist_get_pixtext ##### --> -<para> -Gets the text, pixmap and bitmap mask for the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row to query. -@column: The column to query. -@text: A pointer to a pointer to store the text. -@spacing: A pointer to a #guint8 to store the spacing. -@pixmap: A pointer to a #GdkPixmap pointer to store the cell's pixmap. -@mask: A pointer to a #GdkBitmap pointer to store the cell's bitmap mask. -@Returns: 1 if the retrieval was successful, 0 otherwise. - - -<!-- ##### FUNCTION gtk_clist_set_foreground ##### --> -<para> -Sets the foreground color for the specified row. -</para> - -@clist: The #GtkCList to affect. -@row: The row to affect. -@color: A pointer to a #GdkColor structure. - - -<!-- ##### FUNCTION gtk_clist_set_background ##### --> -<para> -Sets the background color for the specified row. -</para> - -@clist: The #GtkCList to affect. -@row: The row to affect. -@color: A pointer to a #GdkColor structure. - - -<!-- ##### FUNCTION gtk_clist_set_cell_style ##### --> -<para> -Sets the style for the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@style: A pointer to a #GtkStyle structure. - - -<!-- ##### FUNCTION gtk_clist_get_cell_style ##### --> -<para> -Gets the current style of the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@Returns: A #GtkStyle object. - - -<!-- ##### FUNCTION gtk_clist_set_row_style ##### --> -<para> -Sets the style for all cells in the specified row. -</para> - -@clist: The #GtkCList to affect. -@row: The row to affect. -@style: A pointer to a #GtkStyle to set. - - -<!-- ##### FUNCTION gtk_clist_get_row_style ##### --> -<para> -Gets the style set for the specified row. -</para> - -@clist: The #GtkCList to affect. -@row: The row to query. -@Returns: The #GtkStyle of the row. - - -<!-- ##### FUNCTION gtk_clist_set_shift ##### --> -<para> -Sets the vertical and horizontal shift of the specified cell. -</para> - -@clist: The #GtkCList to affect. -@row: The row of the cell. -@column: The column of the cell. -@vertical: The value to set for the vertical shift. -@horizontal: The value to set for the vertical shift. - - -<!-- ##### FUNCTION gtk_clist_set_selectable ##### --> -<para> -Sets whether the specified row is selectable or not. -</para> - -@clist: The #GtkCList to affect. -@row: The row to affect. -@selectable: %TRUE or %FALSE. - - -<!-- ##### FUNCTION gtk_clist_get_selectable ##### --> -<para> -Gets whether the specified row is selectable or not. -</para> - -@clist: The #GtkCList to affect. -@row: The row to query. -@Returns: A #gboolean value. - - -<!-- ##### FUNCTION gtk_clist_prepend ##### --> -<para> -Adds a row to the CList at the top. -</para> - -@clist: The #GtkCList to affect. -@text: An array of strings to add. -@Returns: The number of the row added. - - -<!-- ##### FUNCTION gtk_clist_append ##### --> -<para> -Adds a row to the CList at the bottom. -</para> - -@clist: The #GtkCList to affect. -@text: An array of strings to add. -@Returns: The number of the row added. - - -<!-- ##### FUNCTION gtk_clist_insert ##### --> -<para> -Adds a row of text to the CList at the specified position. -</para> - -@clist: The #GtkCList to affect. -@row: The row where the text should be inserted. -@text: An array of string to add. -@Returns: The number of the row added. - - -<!-- ##### FUNCTION gtk_clist_remove ##### --> -<para> -Removes the specified row from the CList. -</para> - -@clist: The #GtkCList to affect. -@row: The row to remove. - - -<!-- ##### FUNCTION gtk_clist_set_row_data ##### --> -<para> -Sets data for the specified row. This is the same as calling gtk_clist_set_row_data_full(clist, row, data, NULL). -</para> - -@clist: The #GtkCList to affect. -@row: The row to affect. -@data: The data to set for the row. - - -<!-- ##### FUNCTION gtk_clist_set_row_data_full ##### --> -<para> -Sets the data for specified row, with a callback when the row is destroyed. -</para> - -@clist: The #GtkCList to affect. -@row: The row to affect. -@data: The data to set for the row. -@destroy: A #GtkDestroyNotify function to be called when the row is destroyed. - - -<!-- ##### FUNCTION gtk_clist_get_row_data ##### --> -<para> -Gets the currently set data for the specified row. -</para> - -@clist: The #GtkCList to affect. -@row: The row to query. -@Returns: The data set for the row. - - -<!-- ##### FUNCTION gtk_clist_find_row_from_data ##### --> -<para> -Searches the CList for the row with the specified data. -</para> - -@clist: The #GtkCList to search. -@data: The data to search for a match. -@Returns: The number of the matching row, or -1 if no match could be found. - - -<!-- ##### FUNCTION gtk_clist_select_row ##### --> -<para> -Selects the specified row. Causes the "select-row" signal to be emitted for the specified row and column. -</para> - -@clist: The #GtkCList to affect. -@row: The row to select. -@column: The column to select. - - -<!-- ##### FUNCTION gtk_clist_unselect_row ##### --> -<para> -Unselects the specified row. Causes the "unselect-row" signal to be emitted for the specified row and column. -</para> - -@clist: The #GtkCList to affect. -@row: The row to select. -@column: The column to select. - - -<!-- ##### FUNCTION gtk_clist_undo_selection ##### --> -<para> -Undoes the last selection for an "extended selection mode" CList. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_clear ##### --> -<para> -Removes all the CList's rows. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_get_selection_info ##### --> -<para> -Gets the row and column at the specified pixel position in the CList. -</para> - -@clist: The #GtkCList to affect. -@x: The horizontal pixel position to check. -@y: The vertical pixel position to check.. -@row: Pointer to a #gint to store the row value. -@column: Pointer to a #gint to store the column value. -@Returns: 1 if row/column is returned and in range, 0 otherwise. - - -<!-- ##### FUNCTION gtk_clist_select_all ##### --> -<para> -Selects all rows in the CList. This function has no affect for a -CList in "single" or "browse" selection mode. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_unselect_all ##### --> -<para> -Unselects all rows in the CList. -</para> - -@clist: The #GtkCList to affect. - - -<!-- ##### FUNCTION gtk_clist_swap_rows ##### --> -<para> -Swaps the two specified rows with each other. -</para> - -@clist: The #GtkCList to affect. -@row1: Number of the first row. -@row2: Number of the second row. - - -<!-- ##### FUNCTION gtk_clist_set_compare_func ##### --> -<para> -Sets the compare function of the #GtkClist to @cmp_func. If @cmp_func is NULL, -then the default compare function is used. The default compare function sorts -ascending or with the type set by gtk_clist_set_sort_type() by the column set -by gtk_clist_set_sort_column(). -</para> - -@clist: The #GtkCList to affect. -@cmp_func: The #GtkCompareFunction to use. - - -<!-- ##### FUNCTION gtk_clist_set_sort_column ##### --> -<para> -Sets the sort column of the clist. The sort column is used by the -default compare function to determine which column to sort by. -</para> - -@clist: The #GtkCList to affect. -@column: The column to sort by - - -<!-- ##### FUNCTION gtk_clist_set_sort_type ##### --> -<para> -Sets the sort type of the #GtkClist. This is either GTK_SORT_ASCENDING for -ascening sort or GTK_SORT_DESCENDING for descending sort. -</para> - -@clist: The #GtkCList to affect. -@sort_type: the #GtkSortType to use - - -<!-- ##### FUNCTION gtk_clist_sort ##### --> -<para> -Sorts the #GtkClist according to the current compare function, which -can be set with the gtk_clist_set_compare_func() function. -</para> - -@clist: The #GtkCList to sort. - - -<!-- ##### FUNCTION gtk_clist_set_auto_sort ##### --> -<para> -Turns on or off auto sort of the #GtkCList. If auto sort is on, then the CList will be resorted when a row is inserted into the CList. -</para> - -@clist: The #GtkCList to affect. -@auto_sort: whether auto sort should be on or off - - -<!-- ##### FUNCTION gtk_clist_columns_autosize ##### --> -<para> -Auto-sizes all columns in the CList and returns the total width of the CList. -</para> - -@clist: The #GtkCList to affect. -@Returns: The total width of the CList. - - -<!-- ##### FUNCTION gtk_clist_get_column_title ##### --> -<para> -Gets the current title of the specified column -</para> - -@clist: The #GtkCList to affect. -@column: The column to query. -@Returns: The title of the column. - - -<!-- ##### FUNCTION gtk_clist_get_column_widget ##### --> -<para> -Gets the widget in the column header for the specified column. -</para> - -@clist: The #GtkCList to affect. -@column: The column to query. -@Returns: Pointer to a #GtkWidget for the column header. - - -<!-- ##### FUNCTION gtk_clist_get_hadjustment ##### --> -<para> -Gets the #GtkAdjustment currently being used for the horizontal -aspect. -</para> - -@clist: The #GtkCList to check. -@Returns: A #GtkAdjustment object, or NULL if none is currently -being used. - - -<!-- ##### FUNCTION gtk_clist_get_vadjustment ##### --> -<para> -Gets the #GtkAdjustment currently being used for the vertical -aspect. -</para> - -@clist: The #GtkCList to check. -@Returns: A #GtkAdjustment object, or NULL if none is currently -being used. - - -<!-- ##### FUNCTION gtk_clist_row_move ##### --> -<para> -Allows you to move a row from one position to another in the -list. -</para> - -@clist: The #GtkCList to affect. -@source_row: The original position of the row to move. -@dest_row: The position to which the row should be moved. - - -<!-- ##### FUNCTION gtk_clist_set_button_actions ##### --> -<para> -Sets the action(s) that the specified mouse button will have -on the CList. -</para> - -@clist: The #GtkCList to affect. -@button: The mouse button to set. The values here, unlike in the - rest of GTK+ start from 0. For instance, the right mouse - button, which is 3 elsewhere, should be given as 2 here. -@button_actions: A logically OR'd value of #GtkButtonAction values -for the button. - - -<!-- ##### FUNCTION gtk_clist_set_hadjustment ##### --> -<para> -Allows you to set the #GtkAdjustment to be used for the horizontal -aspect of the #GtkCList widget. -</para> - -@clist: The #GtkCList to affect. -@adjustment: A pointer to a #GtkAdjustment widget, or NULL. - - -<!-- ##### FUNCTION gtk_clist_set_reorderable ##### --> -<para> -Sets whether the CList's rows are re-orderable using drag-and-drop. -</para> - -@clist: The #GtkCList to affect. -@reorderable: %TRUE or %FALSE. - - -<!-- ##### FUNCTION gtk_clist_set_use_drag_icons ##### --> -<para> -Determines whether the #GtkClist should use icons when -doing drag-and-drop operations. -</para> - -@clist: The #GtkCList to affect. -@use_icons: %TRUE or %FALSE. - - -<!-- ##### FUNCTION gtk_clist_set_vadjustment ##### --> -<para> -Allows you to set the #GtkAdjustment to be used for the vertical -aspect of the #GtkCList widget. -</para> - -@clist: The #GtkCList to affect. -@adjustment: A pointer to a #GtkAdjustment widget, or NULL. - - diff --git a/docs/reference/gtk/tmpl/gtkpreview.sgml b/docs/reference/gtk/tmpl/gtkpreview.sgml deleted file mode 100644 index 0c744b4ca1..0000000000 --- a/docs/reference/gtk/tmpl/gtkpreview.sgml +++ /dev/null @@ -1,265 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkPreview - -<!-- ##### SECTION Short_Description ##### --> -A widget to display RGB or grayscale data - -<!-- ##### SECTION Long_Description ##### --> -<para> -The #GtkPreview widget provides a simple interface -used to display images as RGB or grayscale data. -It's deprecated; just use a #GdkPixbuf displayed by a #GtkImage, or -perhaps a #GtkDrawingArea. #GtkPreview has no advantage over those -approaches. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -<variablelist> - -<varlistentry> -<term>#GdkRGB</term> -<listitem><para>the backend used by #GtkPreview.</para></listitem> -</varlistentry> - -</variablelist> -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### STRUCT GtkPreview ##### --> -<para> -The #GtkPreview-struct struct contains private data only, and -should be accessed using the functions below. -</para> - - -<!-- ##### ARG GtkPreview:expand ##### --> -<para> - -</para> - -<!-- ##### STRUCT GtkPreviewInfo ##### --> -<para> -Contains information about global properties -of preview widgets. - -The #GtkPreviewInfo struct contains the following fields. -(These fields should be considered read-only. They should never be set by -an application.) - -<informaltable pgwide="1" frame="none" role="struct"> -<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/> -<tbody> - -<row> -<entry>#GdkVisual *visual;</entry> -<entry>the visual used by all previews.</entry> -</row> - -<row> -<entry>#GdkColormap *cmap;</entry> -<entry>the colormap used by all previews.</entry> -</row> - -<row> -<entry>gdouble gamma;</entry> -<entry>the gamma correction value used by all previews (See gtk_preview_set_gamma()).</entry> -</row> - -</tbody> -</tgroup> -</informaltable> - -</para> - -@lookup: -@gamma: - -<!-- ##### UNION GtkDitherInfo ##### --> -<para> -This union not used in GTK+. -</para> - - -<!-- ##### FUNCTION gtk_preview_uninit ##### --> -<para> -This function is deprecated and does nothing. -</para> - - - -<!-- ##### FUNCTION gtk_preview_new ##### --> -<para> -Create a new preview widget. -</para> - -@type: the type data contained by the widget. -(Grayscale or RGB) -@Returns: a new #GtkPreview - - -<!-- ##### FUNCTION gtk_preview_size ##### --> -<para> -Set the size that the preview widget will request -in response to a "size_request" signal. The -drawing area may actually be allocated a size -larger than this depending on how it is packed -within the enclosing containers. The effect -of this is determined by whether the preview -is set to expand or not (see gtk_preview_expand()) -</para> - -@preview: a #GtkPreview. -@width: the new width. -@height: the new height. - - -<!-- ##### FUNCTION gtk_preview_put ##### --> -<para> -Takes a portion of the contents of a preview widget -and draws it onto the given drawable, @window. -</para> - -@preview: a #GtkPreview. -@window: a window or pixmap. -@gc: The graphics context for the operation. Only the - clip mask for this GC matters. -@srcx: the x coordinate of the upper left corner in the source image. -@srcy: the y coordinate of the upper left corner in the source image. -@destx: the x coordinate of the upper left corner in the destination image. -@desty: the y coordinate of the upper left corner in the destination image. -@width: the width of the rectangular portion to draw. -@height: the height of the rectangular portion to draw. - - -<!-- ##### FUNCTION gtk_preview_draw_row ##### --> -<para> -Sets the data for a portion of a row. -</para> - -@preview: a #GtkPreview. -@data: the new data for the portion. It should contain - @w bytes of data if the preview is of type - GTK_TYPE_GRAYSCALE, and 3*@w bytes of data - if the preview is of type GTK_TYPE_COLOR. -@x: the starting value on the row to set. -@y: the row to change. -@w: the number of pixels in the row to change. - - -<!-- ##### FUNCTION gtk_preview_set_expand ##### --> -<para> -Determines the way that the the preview widget behaves -when the size it is allocated is larger than the requested -size. If @expand is %FALSE, then the preview's window -and buffer will be no larger than the size set with -gtk_preview_size(), and the data set will be centered -in the allocation if it is larger. If @expand is %TRUE -then the window and buffer will expand with the allocation; -the application is responsible for catching -the "size_allocate" signal and providing the data -appropriate for this size. -</para> - -@preview: a #GtkPreview. -@expand: whether the preview's window should expand or not. - - -<!-- ##### FUNCTION gtk_preview_set_gamma ##### --> -<para> -Set the gamma-correction value for all preview widgets. -(This function will eventually be replaced with a -function that sets a per-preview-widget gamma value). -The resulting intensity is given by: -<literal>destination_value * pow (source_value/255, 1/gamma)</literal>. -The gamma value is applied when the data is -set with gtk_preview_draw_row() so changing this -value will not affect existing data in preview -widgets. -</para> - -@gamma_: the new gamma value. - - -<!-- ##### FUNCTION gtk_preview_set_color_cube ##### --> -<para> -This function is deprecated and does nothing. GdkRGB -automatically picks an optimium color cube for the -display. -</para> - -@nred_shades: ignored -@ngreen_shades: ignored -@nblue_shades: ignored -@ngray_shades: ignored - - -<!-- ##### FUNCTION gtk_preview_set_install_cmap ##### --> -<para> -This function is deprecated -and does nothing. GdkRGB will automatically pick -a private colormap if it cannot allocate sufficient -colors. -</para> - -@install_cmap: ignored. - - -<!-- ##### FUNCTION gtk_preview_set_reserved ##### --> -<para> -This function is deprecated and does nothing. -</para> - -@nreserved: ignored. - - -<!-- ##### FUNCTION gtk_preview_set_dither ##### --> -<para> -Set the dithering mode for the display. -</para> - -@preview: a #GtkPreview. -@dither: the dithering mode. - - -<!-- ##### FUNCTION gtk_preview_get_visual ##### --> -<para> -Returns the visual used by preview widgets. This -function is deprecated, and you should use -gdk_rgb_get_visual() instead. -</para> - -@Returns: the visual for previews. - - -<!-- ##### FUNCTION gtk_preview_get_cmap ##### --> -<para> -Returns the colormap used by preview widgets. This -function is deprecated, and you should use -gdk_rgb_get_cmap() instead. -</para> - -@Returns: the colormap for previews. - - -<!-- ##### FUNCTION gtk_preview_get_info ##### --> -<para> -Return a #GtkPreviewInfo structure containing -global information about preview widgets. -</para> - -@Returns: a #GtkPreviewInfo structure. The return - value belongs to GTK+ and must not be modified - or freed. - - -<!-- ##### FUNCTION gtk_preview_reset ##### --> -<para> -This function is deprecated and does nothing. It was -once used for changing the colormap and visual on the fly. -</para> - - - diff --git a/docs/reference/gtk/tmpl/gtkprintoperation.sgml b/docs/reference/gtk/tmpl/gtkprintoperation.sgml deleted file mode 100644 index 0b0446026e..0000000000 --- a/docs/reference/gtk/tmpl/gtkprintoperation.sgml +++ /dev/null @@ -1,701 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkPrintOperation - -<!-- ##### SECTION Short_Description ##### --> -High-level Printing API - -<!-- ##### SECTION Long_Description ##### --> -<para> -GtkPrintOperation is the high-level, portable printing API. It looks -a bit different than other GTK+ dialogs such as the #GtkFileChooser, -since some platforms don't expose enough infrastructure to implement -a good print dialog. On such platforms, GtkPrintOperation uses the -native print dialog. On platforms which do not provide a native -print dialog, GTK+ uses its own, see #GtkPrintUnixDialog. -</para> - -<para> -The typical way to use the high-level printing API is to create a -#GtkPrintOperation object with gtk_print_operation_new() when the user -selects to print. Then you set some properties on it, e.g. the page size, -any #GtkPrintSettings from previous print operations, the number of pages, -the current page, etc. -</para> -<para> -Then you start the print operation by calling gtk_print_operation_run(). -It will then show a dialog, let the user select a printer and options. -When the user finished the dialog various signals will be emitted on the -#GtkPrintOperation, the main one being ::draw-page, which you are supposed -to catch and render the page on the provided #GtkPrintContext using Cairo. -</para> - -<example> -<title>The high-level printing API</title> -<programlisting> -static GtkPrintSettings *settings = NULL; - -static void -do_print (void) -{ - GtkPrintOperation *print; - GtkPrintOperationResult res; - - print = gtk_print_operation_new (<!-- -->); - - if (settings != NULL) - gtk_print_operation_set_print_settings (print, settings); - - g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL); - g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL); - - res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, - GTK_WINDOW (main_window), NULL); - - if (res == GTK_PRINT_OPERATION_RESULT_APPLY) - { - if (settings != NULL) - g_object_unref (settings); - settings = g_object_ref (gtk_print_operation_get_print_settings (print)); - } - - g_object_unref (print); -} - -</programlisting> -</example> - -<para> -By default GtkPrintOperation uses an external application to do -print preview. To implement a custom print preview, an application -must connect to the preview signal. The functions -gtk_print_operation_print_preview_render_page(), -gtk_print_operation_preview_end_preview() and -gtk_print_operation_preview_is_selected() are useful -when implementing a print preview. -</para> - -<para> -Printing support was added in GTK+ 2.10. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -#GtkPrintContext, #GtkPrintUnixDialog -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkPrintOperation ##### --> -<para> - -</para> - - -<!-- ##### SIGNAL GtkPrintOperation::begin-print ##### --> -<para> - -</para> - -@printoperation: -@context: - -<!-- ##### SIGNAL GtkPrintOperation::create-custom-widget ##### --> -<para> - -</para> - -@printoperation: -@Returns: - -<!-- ##### SIGNAL GtkPrintOperation::custom-widget-apply ##### --> -<para> - -</para> - -@printoperation: -@widget: - -<!-- ##### SIGNAL GtkPrintOperation::done ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@arg1: - -<!-- ##### SIGNAL GtkPrintOperation::draw-page ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@arg1: -@arg2: - -<!-- ##### SIGNAL GtkPrintOperation::end-print ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@arg1: - -<!-- ##### SIGNAL GtkPrintOperation::paginate ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@arg1: -@Returns: - -<!-- ##### SIGNAL GtkPrintOperation::preview ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@arg1: -@arg2: -@arg3: -@Returns: - -<!-- ##### SIGNAL GtkPrintOperation::request-page-setup ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@arg1: -@arg2: -@arg3: - -<!-- ##### SIGNAL GtkPrintOperation::status-changed ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. - -<!-- ##### SIGNAL GtkPrintOperation::update-custom-widget ##### --> -<para> - -</para> - -@printoperation: the object which received the signal. -@widget: -@arg1: -@arg2: - -<!-- ##### ARG GtkPrintOperation:allow-async ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:current-page ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:custom-tab-label ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:default-page-setup ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:embed-page-setup ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:export-filename ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:has-selection ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:job-name ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:n-pages ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:n-pages-to-print ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:print-settings ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:show-progress ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:status ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:status-string ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:support-selection ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:track-print-status ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:unit ##### --> -<para> - -</para> - -<!-- ##### ARG GtkPrintOperation:use-full-page ##### --> -<para> - -</para> - -<!-- ##### ENUM GtkPrintStatus ##### --> -<para> -The status gives a rough indication of the completion -of a running print operation. -</para> - -@GTK_PRINT_STATUS_INITIAL: The printing has not started yet; this - status is set initially, and while the print dialog is shown. -@GTK_PRINT_STATUS_PREPARING: This status is set while the begin-print - signal is emitted and during pagination. -@GTK_PRINT_STATUS_GENERATING_DATA: This status is set while the - pages are being rendered. -@GTK_PRINT_STATUS_SENDING_DATA: The print job is being sent off to the - printer. -@GTK_PRINT_STATUS_PENDING: The print job has been sent to the printer, - but is not printed for some reason, e.g. the printer may be stopped. -@GTK_PRINT_STATUS_PENDING_ISSUE: Some problem has occurred during - printing, e.g. a paper jam. -@GTK_PRINT_STATUS_PRINTING: The printer is processing the print job. -@GTK_PRINT_STATUS_FINISHED: The printing has been completed successfully. -@GTK_PRINT_STATUS_FINISHED_ABORTED: The printing has been aborted. - -<!-- ##### ENUM GtkPrintOperationAction ##### --> -<para> -The @action parameter to gtk_print_operation_run() -determines what action the print operation should perform. -</para> - -@GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG: Show the print dialog. -@GTK_PRINT_OPERATION_ACTION_PRINT: Start to print without showing - the print dialog, based on the current print settings. -@GTK_PRINT_OPERATION_ACTION_PREVIEW: Show the print preview. -@GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires - the export-filename property to be set. - -<!-- ##### ENUM GtkPrintOperationResult ##### --> -<para> -A value of this type is returned by gtk_print_operation_run(). -</para> - -@GTK_PRINT_OPERATION_RESULT_ERROR: An error has occured. -@GTK_PRINT_OPERATION_RESULT_APPLY: The print settings should be stored. -@GTK_PRINT_OPERATION_RESULT_CANCEL: The print operation has been canceled, - the print settings should not be stored. -@GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is not complete - yet. This value will only be returned when running asynchronously. - -<!-- ##### ENUM GtkPrintError ##### --> -<para> -Error codes that identify various errors that can occur while -using the GTK+ printing support. -</para> - -@GTK_PRINT_ERROR_GENERAL: An unspecified error occurred. -@GTK_PRINT_ERROR_INTERNAL_ERROR: An internal error occurred. -@GTK_PRINT_ERROR_NOMEM: A memory allocation failed. -@GTK_PRINT_ERROR_INVALID_FILE: An error occurred while loading a page setup - or paper size from a key file. - -<!-- ##### MACRO GTK_PRINT_ERROR ##### --> -<para> -The #GQuark used for #GtkPrintError errors. -</para> - - - -<!-- ##### FUNCTION gtk_print_operation_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_allow_async ##### --> -<para> - -</para> - -@op: -@allow_async: - - -<!-- ##### FUNCTION gtk_print_operation_get_error ##### --> -<para> - -</para> - -@op: -@error: - - -<!-- ##### FUNCTION gtk_print_operation_set_default_page_setup ##### --> -<para> - -</para> - -@op: -@default_page_setup: - - -<!-- ##### FUNCTION gtk_print_operation_get_default_page_setup ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_print_settings ##### --> -<para> - -</para> - -@op: -@print_settings: - - -<!-- ##### FUNCTION gtk_print_operation_get_print_settings ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_job_name ##### --> -<para> - -</para> - -@op: -@job_name: - - -<!-- ##### FUNCTION gtk_print_operation_set_n_pages ##### --> -<para> - -</para> - -@op: -@n_pages: - - -<!-- ##### FUNCTION gtk_print_operation_get_n_pages_to_print ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_current_page ##### --> -<para> - -</para> - -@op: -@current_page: - - -<!-- ##### FUNCTION gtk_print_operation_set_use_full_page ##### --> -<para> - -</para> - -@op: -@full_page: - - -<!-- ##### FUNCTION gtk_print_operation_set_unit ##### --> -<para> - -</para> - -@op: -@unit: - - -<!-- ##### FUNCTION gtk_print_operation_set_export_filename ##### --> -<para> - -</para> - -@op: -@filename: - - -<!-- ##### FUNCTION gtk_print_operation_set_show_progress ##### --> -<para> - -</para> - -@op: -@show_progress: - - -<!-- ##### FUNCTION gtk_print_operation_set_track_print_status ##### --> -<para> - -</para> - -@op: -@track_status: - - -<!-- ##### FUNCTION gtk_print_operation_set_custom_tab_label ##### --> -<para> - -</para> - -@op: -@label: - - -<!-- ##### FUNCTION gtk_print_operation_run ##### --> -<para> - -</para> - -@op: -@action: -@parent: -@error: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_cancel ##### --> -<para> - -</para> - -@op: - - -<!-- ##### FUNCTION gtk_print_operation_draw_page_finish ##### --> -<para> - -</para> - -@op: - - -<!-- ##### FUNCTION gtk_print_operation_set_defer_drawing ##### --> -<para> - -</para> - -@op: - - -<!-- ##### FUNCTION gtk_print_operation_get_status ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_get_status_string ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_is_finished ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_support_selection ##### --> -<para> - -</para> - -@op: -@support_selection: - - -<!-- ##### FUNCTION gtk_print_operation_get_support_selection ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_has_selection ##### --> -<para> - -</para> - -@op: -@has_selection: - - -<!-- ##### FUNCTION gtk_print_operation_get_has_selection ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_set_embed_page_setup ##### --> -<para> - -</para> - -@op: -@embed: - - -<!-- ##### FUNCTION gtk_print_operation_get_embed_page_setup ##### --> -<para> - -</para> - -@op: -@Returns: - - -<!-- ##### FUNCTION gtk_print_run_page_setup_dialog ##### --> -<para> - -</para> - -@parent: -@page_setup: -@settings: -@Returns: - - -<!-- ##### USER_FUNCTION GtkPageSetupDoneFunc ##### --> -<para> - -</para> - -@page_setup: -@data: - - -<!-- ##### FUNCTION gtk_print_run_page_setup_dialog_async ##### --> -<para> - -</para> - -@parent: -@page_setup: -@settings: -@done_cb: -@data: - - -<!-- ##### STRUCT GtkPrintOperationPreview ##### --> -<para> - -</para> - - -<!-- ##### SIGNAL GtkPrintOperationPreview::got-page-size ##### --> -<para> - -</para> - -@printoperationpreview: the object which received the signal. -@arg1: -@arg2: - -<!-- ##### SIGNAL GtkPrintOperationPreview::ready ##### --> -<para> - -</para> - -@printoperationpreview: the object which received the signal. -@arg1: - -<!-- ##### FUNCTION gtk_print_operation_preview_end_preview ##### --> -<para> - -</para> - -@preview: - - -<!-- ##### FUNCTION gtk_print_operation_preview_is_selected ##### --> -<para> - -</para> - -@preview: -@page_nr: -@Returns: - - -<!-- ##### FUNCTION gtk_print_operation_preview_render_page ##### --> -<para> - -</para> - -@preview: -@page_nr: - - diff --git a/docs/reference/gtk/tmpl/gtkprogress.sgml b/docs/reference/gtk/tmpl/gtkprogress.sgml deleted file mode 100644 index 3b63a76c83..0000000000 --- a/docs/reference/gtk/tmpl/gtkprogress.sgml +++ /dev/null @@ -1,215 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkProgress - -<!-- ##### SECTION Short_Description ##### --> -Base class for GtkProgressBar - -<!-- ##### SECTION Long_Description ##### --> -<para> -A #GtkProgress is the abstract base class used to derive -a #GtkProgressBar which provides a visual representation of -the progress of a long running operation. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkProgress ##### --> -<para> -The #GtkProgress-struct struct contains private data only. -and should be accessed using the functions below. -</para> - - -<!-- ##### ARG GtkProgress:activity-mode ##### --> -<para> - -</para> - -<!-- ##### ARG GtkProgress:show-text ##### --> -<para> - -</para> - -<!-- ##### ARG GtkProgress:text-xalign ##### --> -<para> - -</para> - -<!-- ##### ARG GtkProgress:text-yalign ##### --> -<para> - -</para> - -<!-- ##### FUNCTION gtk_progress_set_show_text ##### --> -<para> -Controls whether progress text is shown. -</para> - -@progress: a #GtkProgress. -@show_text: a boolean indicating whether the progress text -is shown. - - -<!-- ##### FUNCTION gtk_progress_set_text_alignment ##### --> -<para> -Controls the alignment of the text within the progress bar area. -</para> - -@progress: a #GtkProgress. -@x_align: a number between 0.0 and 1.0 indicating the horizontal -alignment of the progress text within the #GtkProgress. -@y_align: a number between 0.0 and 1.0 indicating the vertical -alignment of the progress text within the #GtkProgress. - - -<!-- ##### FUNCTION gtk_progress_set_format_string ##### --> -<para> -Sets a format string used to display text indicating the -current progress. The string can contain the following substitution characters: - -<itemizedlist> -<listitem> -<para> -%v - the current progress value. -</para> -</listitem> -<listitem> -<para> -%l - the lower bound for the progress value. -</para> -</listitem> -<listitem> -<para> -%u - the upper bound for the progress value. -</para> -</listitem> -<listitem> -<para> -%p - the current progress percentage. -</para> -</listitem> -</itemizedlist> -</para> - -@progress: a #GtkProgress. -@format: a string used to display progress text, or %NULL - to restore to the default format. - - -<!-- ##### FUNCTION gtk_progress_set_adjustment ##### --> -<para> -Associates a #GtkAdjustment with the #GtkProgress. A #GtkAdjustment -is used to represent the upper and lower bounds and the step interval -of the underlying value for which progress is shown. -</para> - -@progress: a #GtkProgress. -@adjustment: the #GtkAdjustment to be associated with the #GtkProgress. - - -<!-- ##### FUNCTION gtk_progress_set_percentage ##### --> -<para> -Sets the current percentage completion for the #GtkProgress. -</para> - -@progress: a #GtkProgress. -@percentage: the percentage complete which must be between 0.0 -and 1.0. - - -<!-- ##### FUNCTION gtk_progress_set_value ##### --> -<para> -Sets the value within the #GtkProgress to an absolute value. -The value must be within the valid range of values for the -underlying #GtkAdjustment. -</para> - -@progress: a #GtkProgress. -@value: the value indicating the current completed amount. - - -<!-- ##### FUNCTION gtk_progress_get_value ##### --> -<para> -Returns the current progress complete value. -</para> - -@progress: a #GtkProgress. -@Returns: the current progress complete value. - - -<!-- ##### FUNCTION gtk_progress_set_activity_mode ##### --> -<para> -A #GtkProgress can be in one of two different modes: percentage -mode (the default) and activity mode. In activity mode, the -progress is simply indicated as activity rather than as a percentage -complete. -</para> - -@progress: a #GtkProgress. -@activity_mode: a boolean, %TRUE for activity mode. - - -<!-- ##### FUNCTION gtk_progress_get_current_text ##### --> -<para> -Returns the current text associated with the #GtkProgress. This -text is the based on the underlying format string after any substitutions -are made. -</para> - -@progress: a #GtkProgress. -@Returns: the text indicating the current progress. - - -<!-- ##### FUNCTION gtk_progress_get_text_from_value ##### --> -<para> -Returns the text indicating the progress based on the supplied value. -The current value for the #GtkProgress remains unchanged. -</para> - -@progress: a #GtkProgress. -@value: an absolute progress value to use when formatting the progress text. -@Returns: a string indicating the progress. - - -<!-- ##### FUNCTION gtk_progress_get_current_percentage ##### --> -<para> -Returns the current progress as a percentage. -</para> - -@progress: a #GtkProgress. -@Returns: a number between 0.0 and 1.0 indicating the percentage complete. - - -<!-- ##### FUNCTION gtk_progress_get_percentage_from_value ##### --> -<para> -Returns the progress as a percentage calculated from the supplied -absolute progress value. -</para> - -@progress: a #GtkProgress. -@value: an absolute progress value. -@Returns: a number between 0.0 and 1.0 indicating the percentage complete -represented by @value. - - -<!-- ##### FUNCTION gtk_progress_configure ##### --> -<para> -Allows the configuration of the minimum, maximum, and current values for -the #GtkProgress. -</para> - -@progress: a #GtkProgress. -@value: the current progress value. -@min: the minimum progress value. -@max: the maximum progress value. - - diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml index b89710a3f6..7901b3b73b 100644 --- a/docs/reference/gtk/tmpl/gtkrc.sgml +++ b/docs/reference/gtk/tmpl/gtkrc.sgml @@ -2,7 +2,7 @@ Resource Files <!-- ##### SECTION Short_Description ##### --> -Routines for handling resource files +Deprecated routines for handling resource files <!-- ##### SECTION Long_Description ##### --> <para> @@ -10,10 +10,10 @@ GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ program at runtime. </para> -<para> +<warning> In GTK+ 3.0, resource files have been deprecated and replaced by CSS-like style sheets, which are understood by #GtkCssProvider. -</para> +</warning> <refsect2><title>Default files</title> <para> diff --git a/docs/reference/gtk/tmpl/gtkrecentfilter.sgml b/docs/reference/gtk/tmpl/gtkrecentfilter.sgml deleted file mode 100644 index d2b1b78970..0000000000 --- a/docs/reference/gtk/tmpl/gtkrecentfilter.sgml +++ /dev/null @@ -1,207 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkRecentFilter - -<!-- ##### SECTION Short_Description ##### --> -A filter for selecting a subset of recently used files - -<!-- ##### SECTION Long_Description ##### --> -<para> -A #GtkRecentFilter can be used to restrict the files being shown -in a #GtkRecentChooser. Files can be filtered based on their name -(with gtk_recent_filter_add_pattern()), on their mime type (with -gtk_file_filter_add_mime_type()), on the application that has -registered them (with gtk_recent_filter_add_application()), or by -a custom filter function (with gtk_recent_filter_add_custom()). -</para> - -<para> -Filtering by mime type handles aliasing and subclassing of mime -types; e.g. a filter for text/plain also matches a file with mime -type application/rtf, since application/rtf is a subclass of text/plain. -Note that #GtkRecentFilter allows wildcards for the subtype of a -mime type, so you can e.g. filter for image/*. -</para> - -<para> -Normally, filters are used by adding them to a #GtkRecentChooser, -see gtk_recent_chooser_add_filter(), but it is also possible to -manually use a filter on a file with gtk_recent_filter_filter(). -</para> - -<para> -Recently used files are supported since GTK+ 2.10. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -#GtkRecentChooser -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkRecentFilter ##### --> -<para> -The <structname>GtkRecentFilter</structname> struct contains -only private fields and should not be directly accessed. -</para> - - -<!-- ##### STRUCT GtkRecentFilterInfo ##### --> -<para> -A <structname>GtkRecentFilterInfo</structname> struct is used -to pass information about the tested file to gtk_recent_filter_filter(). -</para> - -@contains: Flags indicating which of the following fields need - are filled -@uri: the URI of the file being tested -@display_name: the string that will be used to display the file - in the recent chooser -@mime_type: the mime type of the file -@applications: the list of applications that have registered the file -@groups: the groups to which the file belongs to -@age: the number of days elapsed since the file has been registered - -<!-- ##### ENUM GtkRecentFilterFlags ##### --> -<para> -These flags indicate what parts of a #GtkRecentFilterInfo struct -are filled or need to be filled. -</para> - -@GTK_RECENT_FILTER_URI: the URI of the file being tested -@GTK_RECENT_FILTER_DISPLAY_NAME: the string that will be used to - display the file in the recent chooser -@GTK_RECENT_FILTER_MIME_TYPE: the mime type of the file -@GTK_RECENT_FILTER_APPLICATION: the list of applications that have - registered the file -@GTK_RECENT_FILTER_GROUP: the groups to which the file belongs to -@GTK_RECENT_FILTER_AGE: the number of days elapsed since the file - has been registered - -<!-- ##### USER_FUNCTION GtkRecentFilterFunc ##### --> -<para> -The type of function that is used with custom filters, -see gtk_recent_filter_add_custom(). -</para> - -@filter_info: a #GtkRecentFilterInfo that is filled according - to the @needed flags passed to gtk_recent_filter_add_custom() -@user_data: user data passed to gtk_recent_filter_add_custom() -@Returns: %TRUE if the file should be displayed - - -<!-- ##### FUNCTION gtk_recent_filter_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION gtk_recent_filter_get_name ##### --> -<para> - -</para> - -@filter: -@Returns: - - -<!-- ##### FUNCTION gtk_recent_filter_set_name ##### --> -<para> - -</para> - -@filter: -@name: - - -<!-- ##### FUNCTION gtk_recent_filter_add_mime_type ##### --> -<para> - -</para> - -@filter: -@mime_type: - - -<!-- ##### FUNCTION gtk_recent_filter_add_pattern ##### --> -<para> - -</para> - -@filter: -@pattern: - - -<!-- ##### FUNCTION gtk_recent_filter_add_pixbuf_formats ##### --> -<para> - -</para> - -@filter: - - -<!-- ##### FUNCTION gtk_recent_filter_add_application ##### --> -<para> - -</para> - -@filter: -@application: - - -<!-- ##### FUNCTION gtk_recent_filter_add_group ##### --> -<para> - -</para> - -@filter: -@group: - - -<!-- ##### FUNCTION gtk_recent_filter_add_age ##### --> -<para> - -</para> - -@filter: -@days: - - -<!-- ##### FUNCTION gtk_recent_filter_add_custom ##### --> -<para> - -</para> - -@filter: -@needed: -@func: -@data: -@data_destroy: - - -<!-- ##### FUNCTION gtk_recent_filter_get_needed ##### --> -<para> - -</para> - -@filter: -@Returns: - - -<!-- ##### FUNCTION gtk_recent_filter_filter ##### --> -<para> - -</para> - -@filter: -@filter_info: -@Returns: - - diff --git a/docs/reference/gtk/tmpl/gtkruler.sgml b/docs/reference/gtk/tmpl/gtkruler.sgml deleted file mode 100644 index 747fc7b7d9..0000000000 --- a/docs/reference/gtk/tmpl/gtkruler.sgml +++ /dev/null @@ -1,134 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkRuler - -<!-- ##### SECTION Short_Description ##### --> -Base class for horizontal or vertical rulers - -<!-- ##### SECTION Long_Description ##### --> -<note> -<para> - This widget is considered too specialized/little-used for - GTK+, and will in the future be moved to some other package. If - your application needs this widget, feel free to use it, as the - widget does work and is useful in some applications; it's just not - of general interest. However, we are not accepting new features for - the widget, and it will eventually move out of the GTK+ - distribution. -</para> -</note> -<para> -The GTKRuler widget is a base class for horizontal and vertical rulers. Rulers -are used to show the mouse pointer's location in a window. The ruler can either -be horizontal or vertical on the window. Within the ruler a small triangle -indicates the location of the mouse relative to the horizontal or vertical -ruler. See #GtkHRuler to learn how to create a new horizontal ruler. See -#GtkVRuler to learn how to create a new vertical ruler. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -#GtkHRuler, #GtkVRuler -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkRuler ##### --> -<para> -All distances are in 1/72nd's of an inch. (According to Adobe thats a point, but -points are really 1/72.27 in.) -</para> - - -<!-- ##### ARG GtkRuler:lower ##### --> -<para> - -</para> - -<!-- ##### ARG GtkRuler:max-size ##### --> -<para> - -</para> - -<!-- ##### ARG GtkRuler:metric ##### --> -<para> - -</para> - -<!-- ##### ARG GtkRuler:position ##### --> -<para> - -</para> - -<!-- ##### ARG GtkRuler:upper ##### --> -<para> - -</para> - -<!-- ##### STRUCT GtkRulerMetric ##### --> -<para> -This should be points_per_unit. This is the size of the unit in 1/72nd's of an inch and has nothing to do with screen pixels. -</para> - -@metric_name: -@abbrev: -@pixels_per_unit: -@ruler_scale: -@subdivide: - -<!-- ##### FUNCTION gtk_ruler_new ##### --> -<para> - -</para> - -@orientation: -@Returns: - - -<!-- ##### FUNCTION gtk_ruler_set_metric ##### --> -<para> -This calls the #GTKMetricType to set the ruler to units defined. Available units -are GTK_PIXELS, GTK_INCHES, or GTK_CENTIMETERS. The default unit of measurement -is GTK_PIXELS. -</para> - -@ruler: the gtkruler -@metric: the unit of measurement - - -<!-- ##### FUNCTION gtk_ruler_set_range ##### --> -<para> - -</para> - -@ruler: -@lower: -@upper: -@position: -@max_size: - - -<!-- ##### FUNCTION gtk_ruler_get_metric ##### --> -<para> - -</para> - -@ruler: -@Returns: - - -<!-- ##### FUNCTION gtk_ruler_get_range ##### --> -<para> - -</para> - -@ruler: -@lower: -@upper: -@position: -@max_size: - - diff --git a/docs/reference/gtk/tmpl/gtkthemes.sgml b/docs/reference/gtk/tmpl/gtkthemes.sgml deleted file mode 100644 index bfe5d5c34e..0000000000 --- a/docs/reference/gtk/tmpl/gtkthemes.sgml +++ /dev/null @@ -1,19 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Themes - -<!-- ##### SECTION Short_Description ##### --> - - -<!-- ##### SECTION Long_Description ##### --> -<para> - -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - diff --git a/docs/reference/gtk/tmpl/gtktipsquery.sgml b/docs/reference/gtk/tmpl/gtktipsquery.sgml deleted file mode 100644 index 999f482bba..0000000000 --- a/docs/reference/gtk/tmpl/gtktipsquery.sgml +++ /dev/null @@ -1,163 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkTipsQuery - -<!-- ##### SECTION Short_Description ##### --> -Displays help about widgets in the user interface - -<!-- ##### SECTION Long_Description ##### --> -<para> -The #GtkTipsQuery widget is a subclass of #GtkLabel which is used to display -help about widgets in a user interface. -</para> -<para> -A query is started with a call to gtk_tips_query_start_query(), usually -when some kind of 'Help' button is pressed. The #GtkTipsQuery then grabs all -events, stopping the user interface from functioning normally. -Then as the user moves the mouse over the widgets, the #GtkTipsQuery displays -each widget's tooltip text. -</para> -<para> -By connecting to the "widget-entered" or "widget-selected" signals, it is -possible to customize the #GtkTipsQuery to perform other actions when widgets -are entered or selected. For example, a help browser could be opened with -documentation on the widget selected. -</para> -<para> -At some point a call to gtk_tips_query_stop_query() must be made in order to -stop the query and return the interface to its normal state. -The gtk_tips_query_set_caller() function can be used to specify a widget -which the user can select to stop the query (often the same button used to -start the query). -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -<variablelist> -<varlistentry> -<term>#GtkTooltips</term> -<listitem><para>the object which handles tooltips.</para></listitem> -</varlistentry> -</variablelist> -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### STRUCT GtkTipsQuery ##### --> -<para> -The #GtkTipsQuery-struct struct contains private data only, and -should be accessed using the functions below. -</para> - - -<!-- ##### SIGNAL GtkTipsQuery::start-query ##### --> -<para> -Emitted when the query is started. -</para> - -@tipsquery: the object which received the signal. - -<!-- ##### SIGNAL GtkTipsQuery::stop-query ##### --> -<para> -Emitted when the query is stopped. -</para> - -@tipsquery: the object which received the signal. - -<!-- ##### SIGNAL GtkTipsQuery::widget-entered ##### --> -<para> -Emitted when a widget is entered by the pointer while the query is in effect. -</para> - -@tipsquery: the object which received the signal. -@widget: the widget that was entered by the pointer. -@tip_text: the widget's tooltip. -@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()). - -<!-- ##### SIGNAL GtkTipsQuery::widget-selected ##### --> -<para> -Emitted when a widget is selected during a query. -</para> - -@tipsquery: the object which received the signal. -@widget: the widget that was selected. -@tip_text: the widget's tooltip. -@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()). -@event: the button press or button release event. -@Returns: %TRUE if the query should be stopped. - -<!-- ##### ARG GtkTipsQuery:caller ##### --> -<para> -The widget that starts the tips query, usually a button. -If it is selected while the query is in effect the query is automatically -stopped. -</para> - -<!-- ##### ARG GtkTipsQuery:emit-always ##### --> -<para> -%TRUE if the widget-entered and widget-selected signals are emitted even when -the widget has no tooltip set. -</para> - -<!-- ##### ARG GtkTipsQuery:label-inactive ##### --> -<para> -The text to display in the #GtkTipsQuery widget when the query is not in -effect. -</para> - -<!-- ##### ARG GtkTipsQuery:label-no-tip ##### --> -<para> -The text to display in the #GtkTipsQuery widget when the query is running -and the widget that the pointer is over has no tooltip. -</para> - -<!-- ##### FUNCTION gtk_tips_query_new ##### --> -<para> -Creates a new #GtkTipsQuery. -</para> - -@Returns: a new #GtkTipsQuery. - - -<!-- ##### FUNCTION gtk_tips_query_start_query ##### --> -<para> -Starts a query. -The #GtkTipsQuery widget will take control of the mouse and as the mouse -moves it will display the tooltip of the widget beneath the mouse. -</para> - -@tips_query: a #GtkTipsQuery. - - -<!-- ##### FUNCTION gtk_tips_query_stop_query ##### --> -<para> -Stops a query. -</para> - -@tips_query: a #GtkTipsQuery. - - -<!-- ##### FUNCTION gtk_tips_query_set_caller ##### --> -<para> -Sets the widget which initiates the query, usually a button. -If the @caller is selected while the query is running, the query is -automatically stopped. -</para> - -@tips_query: a #GtkTipsQuery. -@caller: the widget which initiates the query. - - -<!-- ##### FUNCTION gtk_tips_query_set_labels ##### --> -<para> -Sets the text to display when the query is not in effect, -and the text to display when the query is in effect but the widget beneath -the pointer has no tooltip. -</para> - -@tips_query: a #GtkTipsQuery. -@label_inactive: the text to display when the query is not running. -@label_no_tip: the text to display when the query is running but the widget -beneath the pointer has no tooltip. - - diff --git a/docs/reference/gtk/x11.sgml b/docs/reference/gtk/x11.sgml index 0fede1b7fe..0a8ad33f90 100644 --- a/docs/reference/gtk/x11.sgml +++ b/docs/reference/gtk/x11.sgml @@ -31,6 +31,13 @@ see <link linkend="gdk-X-Window-System-Interaction">GDK X Window System interaction</link> in the GDK manual. </para> +<para> +GTK+ includes an cross-process embedding facility in the form of +the #GtkSocket and #GtkPlug widgets. These are X11-specific, and +you have to include the <filename>gtk/gtkx.h</filename> header +to use them. +</para> + <refsect2 id="x11-cmdline"> <title>X11-specific commandline options</title> |