Update docs Deprecate gtk_widget_{ref,unref}

2007-06-09  Matthias Clasen  <mclasen@redhat.com>

        * gtk/gtkwidget.c:
        * gtk/gtkscrolledwindow.c: Update docs
        * gtk/gtkwidget.h: Deprecate gtk_widget_{ref,unref}

        * gtk/tmpl/gtkbindings.sgml:
        * gtk/tmpl/gtkrc.sgml:
        * gtk/tmpl/gtkwidget.sgml:
        * gtk/tmpl/gtkrecentmanager.sgml:
        * gtk/*.sgml:
        * gtk/tmpl/gtkstock.sgml:
        * gtk/gtk-sections.txt: Updates



svn path=/trunk/; revision=18090
This commit is contained in:
Matthias Clasen 2007-06-10 06:52:51 +00:00 committed by Matthias Clasen
parent 19f4715cee
commit 08cc834061
25 changed files with 300 additions and 298 deletions

View File

@ -1,5 +1,9 @@
2007-06-09 Matthias Clasen <mclasen@redhat.com>
* gtk/gtkwidget.c:
* gtk/gtkscrolledwindow.c: Update docs
* gtk/gtkwidget.h: Deprecate gtk_widget_{ref,unref}
* gtk/gtkbox.c: Move docs inline.
* gtk/gtkrange.c:

View File

@ -1,5 +1,15 @@
2007-06-09 Matthias Clasen <mclasen@redhat.com>
* gtk/tmpl/gtkbindings.sgml:
* gtk/tmpl/gtkrc.sgml:
* gtk/tmpl/gtkwidget.sgml:
* gtk/tmpl/gtkrecentmanager.sgml:
* gtk/*.sgml:
* gtk/tmpl/gtkstock.sgml:
* gtk/gtk-sections.txt: Updates
* gtk/Makefile.am: Exclude another private header
* gtk/tmpl/gtkbox.sgml: Move docs inline
2007-06-08 Matthias Clasen <mclasen@redhat.com>

View File

@ -90,6 +90,7 @@ IGNORE_HFILES= \
gtkxembed.h \
gtkwin32embed.h \
gtkwin32embedwidget.h \
gtkwindow-decorate.h \
xdgmime \
xembed.h

View File

@ -45,11 +45,12 @@ How to compile GTK+ itself
of the tools are already included in the source packages. But
it's useful to know a bit about how packages that use these
tools work. A source package is distributed as a
<literal>tar.gz</literal> file which you unpack into a
directory full of the source files as follows:
<literal>tar.gz</literal> or <literal>tar.bz2</literal> file
which you unpack into a directory full of the source files as follows:
</para>
<programlisting>
tar xvfz gtk+-2.0.0.tar.gz
tar xvfj gtk+-2.0.0.tar.bz2
</programlisting>
<para>
In the toplevel of the directory that is created, there will be
@ -142,7 +143,7 @@ How to compile GTK+ itself
needed for that library along with version number information.)
The version of <command>pkg-config</command> needed to build
GTK+ is mirrored in the <filename>dependencies</filename> directory
on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.6/">GTK+ FTP
on the <ulink url="ftp://ftp.gtk.org/pub/gtk/">GTK+ FTP
site.</ulink>
</para>
</listitem>
@ -331,6 +332,10 @@ How to compile GTK+ itself
<arg>--disable-xkb</arg>
<arg>--enable-xkb</arg>
</group>
<group>
<arg>--disable-xinerama</arg>
<arg>--enable-xinerama</arg>
</group>
<group>
<arg>--disable-gtk-doc</arg>
<arg>--enable-gtk-doc</arg>
@ -339,7 +344,7 @@ How to compile GTK+ itself
<arg>--with-xinput=[no|yes]</arg>
</group>
<group>
<arg>--with-gdktarget=[x11|linux-fb|win32]</arg>
<arg>--with-gdktarget=[x11|linux-fb|win32|quartz|directfb]</arg>
</group>
<group>
<arg>--disable-shadowfb</arg>
@ -480,6 +485,18 @@ How to compile GTK+ itself
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-xinerama</systemitem> and
<systemitem>--enable-xinerama</systemitem></title>
<para>
By default the <command>configure</command> script will try
to link against the Xinerama libraries if they are found.
These options can be used to explicitly control whether
Xinerama should be used.
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-gtk-doc</systemitem> and
<systemitem>--enable-gtk-doc</systemitem></title>
@ -519,7 +536,9 @@ How to compile GTK+ itself
<para>
Toggles between the supported backends for GDK.
The default is x11, unless the platform is Windows, in which
case the default is win32.
case the default is win32. Other supported backends are
the quartz backend for OS X, and the DirectFB backend
for the Linux framebuffer.
</para>
</formalpara>

View File

@ -31,75 +31,10 @@ system.
<refsect2><title>Build requirements</title>
<para>
Beyond the usual GTK+ build requirements, the DirectFB backend (obviously) needs
the DirectFB libraries (at least 0.9.21) and Cairo compiled with DirectFB support.
Beyond the usual GTK+ build requirements, the DirectFB backend (obviously)
needs the DirectFB libraries (at least 0.9.21) and cairo compiled with
DirectFB support.
</para>
</refsect2>
<!--
FIXME: it seems most of the options listed in _gdk_windowing_args
are ignored, and they need to be described by somebody who knows
what they are supposed to do...
<refsect2><title>DirectFB-specific commandline options</title>
<para>
The DirectFB GDB backend can be influenced with some additional
command line arguments.
</para>
<formalpara>
<title><systemitem>dfb-help</systemitem></title>
<para>
Display help for DirectFB-specific commandline options.
</para>
</formalpara>
<formalpara>
<title><systemitem>dfb=<replaceable>value</replaceable></systemitem></title>
<para>
Possible values: sdl, system.
</para>
</formalpara>
<formalpara>
<title><systemitem>disable-aa-fonts=<replaceable>number</replaceable></systemitem></title>
<para>
If <replaceable>number</replaceable> is 1, disable antialising for fonts.
</para>
</formalpara>
<formalpara>
<title><systemitem>argb-font=<replaceable>number</replaceable></systemitem></title>
<para>
If <replaceable>number</replaceable> is 1, enable ARGB fonts.
</para>
</formalpara>
<formalpara>
<title><systemitem>transparent-unfocused=<replaceable>number</replaceable></systemitem></title>
<para>
If <replaceable>number</replaceable> is 1, make unfocused windows transparent.
</para>
</formalpara>
<formalpara>
<title><systemitem>glyph-surface-cache=<replaceable>number</replaceable></systemitem></title>
<para>
Set the size of the glyph surface cache. The default value is 8.
</para>
</formalpara>
<formalpara>
<title><systemitem>enable-color-keyring=<replaceable>number</replaceable></systemitem></title>
<para>
If <replaceable>number</replaceable> is 1, turn on the color keyring.
</para>
</formalpara>
-->
</refsect1>
</refentry>

View File

@ -263,38 +263,31 @@ string utilities, file utilities, a main loop abstraction, and so on.
<varlistentry>
<term>Pango</term>
<listitem><para>
Pango is a library for internationalized text handling. It centers
around the <link linkend="PangoLayout">PangoLayout</link> object, representing
a paragraph of text.
Pango provides the engine for <link linkend="GtkTextView">GtkTextView</link>,
<link linkend="GtkLabel">GtkLabel</link>,
<link linkend="GtkEntry">GtkEntry</link>, and
around the #PangoLayout object, representing a paragraph of text.
Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
other widgets that display text.
</para></listitem>
</varlistentry>
<varlistentry>
<term>ATK</term>
<listitem><para>
ATK is the Accessibility Toolkit. It provides a set of generic
interfaces allowing accessibility technologies to interact with a
graphical user interface. For example, a screen reader uses ATK to
discover the text in an interface and read it to blind users. GTK+
widgets have built-in support for accessibility using the ATK
framework.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GdkPixbuf</term>
<listitem><para>
This is a small library which allows you to create <link linkend="GdkPixbuf">GdkPixbuf</link>
This is a small library which allows you to create #GdkPixbuf
("pixel buffer") objects from image data or image files.
Use a <link linkend="GdkPixbuf">GdkPixbuf</link> in combination with <link linkend="GtkImage">GtkImage</link> to display images.
Use a #GdkPixbuf in combination with #GtkImage to display images.
</para></listitem>
</varlistentry>
@ -310,11 +303,8 @@ on X11, Windows, and the Linux framebuffer device.
<varlistentry>
<term>GTK+</term>
<listitem><para>
The GTK+ library itself contains <firstterm>widgets</firstterm>,
that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
<link linkend="GtkTextView">GtkTextView</link>.
that is, GUI components such as #GtkButton or #GtkTextView.
</para></listitem>
</varlistentry>
</variablelist>

View File

@ -4395,6 +4395,7 @@ gtk_tree_store_set_column_types
gtk_tree_store_set_value
gtk_tree_store_set
gtk_tree_store_set_valist
gtk_tree_store_set_valuesv
gtk_tree_store_remove
gtk_tree_store_insert
gtk_tree_store_insert_before
@ -4478,6 +4479,7 @@ gtk_tree_view_column_cell_get_position
gtk_tree_view_column_cell_is_visible
gtk_tree_view_column_focus_cell
gtk_tree_view_column_queue_resize
gtk_tree_view_column_get_tree_view
<SUBSECTION Standard>
GTK_TREE_VIEW_COLUMN
GTK_IS_TREE_VIEW_COLUMN
@ -4828,6 +4830,7 @@ gtk_list_store_set_column_types
gtk_list_store_set
gtk_list_store_set_valist
gtk_list_store_set_value
gtk_list_store_set_valuesv
gtk_list_store_remove
gtk_list_store_insert
gtk_list_store_insert_before
@ -5134,6 +5137,7 @@ gtk_widget_modify_bg
gtk_widget_modify_text
gtk_widget_modify_base
gtk_widget_modify_font
gtk_widget_modify_cursor
gtk_widget_create_pango_context
gtk_widget_get_pango_context
gtk_widget_create_pango_layout
@ -5973,6 +5977,7 @@ GTK_STOCK_DIALOG_INFO
GTK_STOCK_DIALOG_QUESTION
GTK_STOCK_DIALOG_WARNING
GTK_STOCK_DIRECTORY
GTK_STOCK_DISCARD
GTK_STOCK_DISCONNECT
GTK_STOCK_DND
GTK_STOCK_DND_MULTIPLE

View File

@ -56,8 +56,8 @@
g_object_unref (pixbuf);
</programlisting></informalexample>
If the g_object_new() construction scares you, you can also use
gtk_about_dialog_new() to construct the dialog and then use the setters for
the individual properties.
gtk_about_dialog_new() to construct the dialog and then use the
setters for the individual properties.
</para>
<para>

View File

@ -58,8 +58,8 @@ gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
</programlisting></informalexample>
In order to react to the user's selection, connect to the "changed"
signal on the combo box and use gtk_combo_box_get_active()
In order to react to the user's selection, connect to the
#GtkComboBox::changed signal and use gtk_combo_box_get_active()
to retrieve the index of the selected item.
</para>

View File

@ -11,15 +11,15 @@
<para>
Porting an application from <structname>GnomeHRef</structname> to
#GtkLinkButton is very simple. #GtkLinkButton does not have a
default action for "clicked" signal. So instead of simply creating
the widget
default action for #GtkButton::clicked signal. So instead of simply
creating the widget
<informalexample><programlisting>
GtkWidget *button;
button = gnome_href_new (url, "");
</programlisting></informalexample>
you will have to handle the activation of the #GtkLinkButton, using
the "clicked" signal for instance
the ::clicked signal for instance
<informalexample><programlisting>
static void
link_button_clicked_cb (GtkWidget *widget,

View File

@ -22,7 +22,7 @@
</formalpara>
<para>
The #GtkWidget::popup_menu signal instructs the widget for which
The #GtkWidget::popup-menu signal instructs the widget for which
it is emitted to create a context-sensitive popup menu. By default,
the <link linkend="gtk-bindings">key binding mechanism</link> is set to
emit this signal when the
@ -75,7 +75,7 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
<listitem>
<para>
In your ::button-press handler, call this function
In your #GtkWidget::button-press-event handler, call this function
when you need to pop up a menu:
</para>
@ -97,7 +97,7 @@ my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event)
<listitem>
<para>
Implement a handler for the ::popup-menu signal:
Implement a handler for the #GtkWidget::popup-menu signal:
</para>
<programlisting>
@ -124,10 +124,10 @@ my_widget_popup_menu_handler (GtkWidget *widget)
provide your own <link
linkend="GtkMenuPositionFunc">menu-positioning function</link>
in the case where the <parameter>event</parameter> is
<constant>NULL</constant>. This function should compute the
desired position for a menu when it is invoked through the
keyboard. For example, #GtkEntry aligns the
top edge of its popup menu with the bottom edge of the entry.
%NULL. This function should compute the desired position for
a menu when it is invoked through the keyboard. For example,
#GtkEntry aligns the top edge of its popup menu with the bottom
edge of the entry.
</para>
</note>
@ -137,8 +137,7 @@ my_widget_popup_menu_handler (GtkWidget *widget)
able to take the keyboard focus. In general, widgets should
be fully usable through the keyboard and not just the mouse.
The very first step of this is to ensure that your widget
turns on the %GTK_CAN_FOCUS <link
linkend="gtkwidgetflags">flag</link>.
turns on the %GTK_CAN_FOCUS <link linkend="gtkwidgetflags">flag</link>.
</para>
</note>
</section>
@ -180,7 +179,7 @@ my_widget_popup_menu_handler (GtkWidget *widget)
<para>
Regions have an internal representation that is accessible as a
list of rectangles. To turn the
list of rectangles. To turn the
<structfield>GdkEventExpose.region</structfield> field into such
a list, use gdk_region_get_rectangles():
</para>
@ -215,12 +214,10 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
<formalpara>
<title>Why</title>
<para>
With
gtk_accelerator_get_default_mod_mask()
you can test for modifier keys reliably; this way your key
event handlers will work correctly even if
<keycap>NumLock</keycap> or <keycap>CapsLock</keycap> are
activated.
With gtk_accelerator_get_default_mod_mask() you can test for
modifier keys reliably; this way your key event handlers will
work correctly even if <keycap>NumLock</keycap> or
<keycap>CapsLock</keycap> are activated.
</para>
</formalpara>
@ -230,7 +227,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
indicates the modifier state at the time the key was pressed.
Modifiers are keys like <keycap>Control</keycap> and
<keycap>NumLock</keycap>. When implementing a
#GtkWidget::key_press_event handler, you should use
#GtkWidget::key-press-event handler, you should use
gtk_accelerator_get_default_mod_mask() to
test against modifier keys. This function returns a bit mask
which encompasses all the modifiers which the user may be
@ -298,7 +295,7 @@ my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event)
gtk_window_set_icon_name()) and images (see gtk_image_set_icon_name()).
In GTK+ 2.8, you can also use named icons for drag-and-drop (see
gtk_drag_source_set_icon_name()) and in treeview cells (see the
#GtkCellRendererPixbuf:icon_name property).
#GtkCellRendererPixbuf:icon-name property).
</para>
</section>
</chapter>

View File

@ -59,7 +59,7 @@ See the <link linkend="gtk-resources">documentation on this topic</link>.
<qandaentry>
<question><para>How do I port from one GTK+
<question><para>How do I port from one GTK+
version to another?</para></question>
<answer>
@ -96,17 +96,17 @@ from functions?
<answer>
<para>
See the documentation for #GObject and #GtkObject. For #GObject note specifically
g_object_ref() and g_object_unref(). #GtkObject is a subclass of #GObject so the
same points apply, except that it has a "floating" state (explained in its
documentation).
See the documentation for #GObject and #GtkObject. For #GObject note
specifically g_object_ref() and g_object_unref(). #GtkObject is a subclass
of #GObject so the same points apply, except that it has a "floating" state
(explained in its documentation).
</para>
<para>
For strings returned from functions, they will be declared "const" (using
#G_CONST_RETURN) if they should not be freed. Non-const strings should be freed
with g_free(). Arrays follow the same rule. (If you find an exception to the rules,
please report a bug to <ulink
#G_CONST_RETURN) if they should not be freed. Non-const strings should be
freed with g_free(). Arrays follow the same rule. (If you find an exception
to the rules, please report a bug to <ulink
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
</para>
@ -135,8 +135,9 @@ reference counting, not floating reference counting.
</para>
<para>
To to get this, you must acquire a reference to the widget and drop the floating
reference (<quote>ref and sink</quote> in GTK+ parlance) after creating it:
To to get this, you must acquire a reference to the widget and drop the
floating reference (<quote>ref and sink</quote> in GTK+ parlance) after
creating it:
<informalexample><programlisting>
foo = gtk_foo_new (<!-- -->);
g_object_ref (foo);
@ -165,10 +166,9 @@ How do I use GTK+ with threads?
<answer>
<para>
This is covered in the
<link linkend="gdk-Threads">GDK threads documentation</link>.
See also the <link linkend="glib-Threads">GThread</link> documentation for portable
threading primitives.
This is covered in the <link linkend="gdk-Threads">GDK threads
documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
documentation for portable threading primitives.
</para>
</answer>
@ -184,8 +184,8 @@ How do I internationalize a GTK+ program?
<para>
Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
gettext</ulink>, already required in order to install GLib. On a UNIX
or Linux system with gettext installed, type <literal>info
gettext</literal> to read the documentation.
or Linux system with gettext installed, type <literal>info gettext</literal>
to read the documentation.
</para>
<para>
The short checklist on how to use gettext is: call bindtextdomain() so gettext
@ -199,15 +199,17 @@ follows for convenience:
#define N_(x) x
</programlisting>
</informalexample>
You use N_() (N stands for no-op) to mark a string for translation in a context
where a function call to gettext() is not allowed, such as in an array initializer.
You use N_() (N stands for no-op) to mark a string for translation in a
context where a function call to gettext() is not allowed, such as in an
array initializer.
You eventually have to call gettext() on the string to actually fetch the
translation. _() both marks the string for translation and actually translates it.
translation. _() both marks the string for translation and actually
translates it.
</para>
<para>
Nowadays, GLib provides the common shorthand macros in the header file
<filename>gi18n.h</filename>, so you don't have to define them yourself, just
include that header.
<filename>gi18n.h</filename>, so you don't have to define them yourself,
just include that header.
</para>
<para>
Code using these macros ends up looking like this:
@ -230,10 +232,11 @@ Code using these macros ends up looking like this:
</informalexample>
</para>
<para>
Libraries using gettext should use dgettext() instead of gettext(), which allows
them to specify the translation domain each time they ask for a translation. Libraries
should also avoid calling textdomain(), since they'll be specifying the domain instead
of using the default.For dgettext() the _() macro can be defined as:
Libraries using gettext should use dgettext() instead of gettext(), which
allows them to specify the translation domain each time they ask for a
translation. Libraries should also avoid calling textdomain(), since they
will be specifying the domain instead of using the default. For dgettext()
the _() macro can be defined as:
<informalexample>
<programlisting>
#define _(x) dgettext ("MyDomain", x)
@ -241,9 +244,9 @@ of using the default.For dgettext() the _() macro can be defined as:
</informalexample>
</para>
<para>
Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the trouble
of defining the macros by hand. The macros in that header expect the translation
domain to be specified by the %GETTEXT_PACKAGE macro.
Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the
trouble of defining the macros by hand. The macros in that header expect the
translation domain to be specified by the %GETTEXT_PACKAGE macro.
</para>
</answer>
</qandaentry>
@ -258,10 +261,9 @@ How do I use non-ASCII characters in GTK+ programs ?
<answer>
<para>
GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a
sequence of one to six bytes and has a number of nice
properties which make it a good choice for working with Unicode
text in C programs:
UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of
one to six bytes and has a number of nice properties which make it a good
choice for working with Unicode text in C programs:
<itemizedlist>
<listitem><para>
ASCII characters are encoded by their familiar ASCII codepoints.
@ -270,21 +272,22 @@ ASCII characters are encoded by their familiar ASCII codepoints.
ASCII characters never appear as part of any other character.
</para></listitem>
<listitem><para>
The zero byte doesn't occur as part of a character, so that UTF-8 strings can
be manipulated with the usual C library functions for
handling zero-terminated strings.
The zero byte doesn't occur as part of a character, so that UTF-8 strings
can be manipulated with the usual C library functions for handling
zero-terminated strings.
</para></listitem>
</itemizedlist>
More information about Unicode and UTF-8 can be found in the
<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.
<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode i
FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other
encodings, see g_locale_to_utf8() and g_convert().
encodings, see g_locale_to_utf8() and g_convert().
</para>
<para>
Text coming from external sources (e.g. files or user input), has to be
converted to UTF-8 before being handed over to GTK+. The
following example writes the content of a IS0-8859-1 encoded text
file to <literal>stdout</literal>:
converted to UTF-8 before being handed over to GTK+. The following example
writes the content of a IS0-8859-1 encoded text file to
<literal>stdout</literal>:
<informalexample><programlisting>
gchar *text, *utf8_text;
gsize length;
@ -308,7 +311,7 @@ else
</para>
<para>
For string literals in the source code, there are several alternatives for
handling non-ASCII content:
handling non-ASCII content:
<variablelist>
<varlistentry><term>direct UTF-8</term>
<listitem><para>
@ -334,8 +337,9 @@ very convenient. Be careful when mixing hexadecimal escapes with ordinary text;
<listitem><para>
If the string literals can be represented in an encoding which your toolchain
can handle (e.g. IS0-8859-1), you can write your source files in that encoding
and use g_convert() to convert the strings to UTF-8 at runtime. Note that this has
some runtime overhead, so you may want to move the conversion out of inner loops.
and use g_convert() to convert the strings to UTF-8 at runtime. Note that this
has some runtime overhead, so you may want to move the conversion out of inner
loops.
</para></listitem>
</varlistentry>
</variablelist>
@ -364,7 +368,7 @@ There are two ways to approach this. The GTK+ header files use the subset
of C that's also valid C++, so you can simply use the normal GTK+ API
in a C++ program. Alternatively, you can use a "C++ binding"
such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>
which provides a C++-native API.
which provides a native C++ API.
</para>
<para>
When using GTK+ directly, keep in mind that only functions can be
@ -404,7 +408,7 @@ How do I use GTK+ with other non-C languages?
<para>
See the <ulink url="http://www.gtk.org/bindings.html">list of language
bindings</ulink> on <ulink
url="http://www.gtk.org">http://www.gtk.org</ulink>.
url="http://www.gtk.org">http://www.gtk.org</ulink>.
</para>
</answer>
@ -419,15 +423,16 @@ How do I load an image or animation from a file?
<answer>
<para>
To load an image file straight into a display widget, use gtk_image_new_from_file()
<footnote><para> If the file load fails, gtk_image_new_from_file() will display no
image graphic &mdash; to detect a failed load yourself, use gdk_pixbuf_new_from_file()
directly, then gtk_image_new_from_pixbuf().</para></footnote>.
To load an image for another purpose, use gdk_pixbuf_new_from_file(). To load an
animation, use gdk_pixbuf_animation_new_from_file().
gdk_pixbuf_animation_new_from_file() can also load non-animated images, so use it
in combination with gdk_pixbuf_animation_is_static_image() to load a file of unknown
type.
To load an image file straight into a display widget, use
gtk_image_new_from_file() <footnote><para> If the file load fails,
gtk_image_new_from_file() will display no image graphic &mdash; to detect
a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
gtk_image_new_from_pixbuf().</para></footnote>.
To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i
load an animation, use gdk_pixbuf_animation_new_from_file().
gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
use it in combination with gdk_pixbuf_animation_is_static_image() to load a
file of unknown type.
</para>
<para>
To load an image or animation file asynchronously (without blocking), use
@ -503,21 +508,22 @@ to the GNOME 2.0 platform</ulink>.
<qandaentry>
<question>
<para>
Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal> macro ?
Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
macro ?
</para>
</question>
<answer>
<para>
The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
<literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> functions
are declared as <literal>G_GNUC_CONST</literal> which allows the compiler to optimize
<literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> i
functions are declared as %G_GNUC_CONST which allows the compiler to optimize
the call away if it appears that the value is not being used.
</para>
<para>
A common workaround for this problem is to store the result in a volatile variable,
which keeps the compiler from optimizing the call away.
A common workaround for this problem is to store the result in a volatile
variable, which keeps the compiler from optimizing the call away.
<informalexample><programlisting>
volatile GType dummy = GTK_TYPE_BLAH;
</programlisting></informalexample>
@ -595,9 +601,9 @@ should use the #GtkTextView widget. Do not use the deprecated widget #GtkText
in newly-written code, it has a number of problems that are best avoided.
</para>
<para>
If you only have a small amount of text, #GtkLabel may also be appropriate of course.
It can be made selectable with gtk_label_set_selectable(). For a single-line text
entry, see #GtkEntry.
If you only have a small amount of text, #GtkLabel may also be appropriate
of course. It can be made selectable with gtk_label_set_selectable(). For a
single-line text entry, see #GtkEntry.
</para>
</answer>
</qandaentry>
@ -610,9 +616,9 @@ entry, see #GtkEntry.
<answer>
<para>
#GtkImage can display images in just about any format GTK+ understands. You can also
use #GtkDrawingArea if you need to do something more complex, such as draw text or
graphics over the top of the image.
#GtkImage can display images in just about any format GTK+ understands.
You can also use #GtkDrawingArea if you need to do something more complex,
such as draw text or graphics over the top of the image.
</para>
</answer>
</qandaentry>
@ -644,14 +650,15 @@ How do I change the color of a widget?
<answer><para>
See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(),
and gtk_widget_modify_text(). See <link linkend="gtk-Resource-Files">GTK+
resource files</link> for more discussion. You can also change widget color by
installing a resource file and parsing it with gtk_rc_add_default_file().
resource files</link> for more discussion. You can also change widget color
by installing a resource file and parsing it with gtk_rc_add_default_file().
The advantage of a resource file is that users can then override the
color you've chosen.
</para>
<para>To change the background color for widgets such as #GtkLabel that have no
background, place them in a #GtkEventBox and set the background of the event box.
<para>To change the background color for widgets such as #GtkLabel that have
no background, place them in a #GtkEventBox and set the background of the
event box.
</para></answer>
</qandaentry>
@ -661,9 +668,9 @@ How do I change the font of a widget?
</para></question>
<answer><para>
This has several possible answers, depending on what exactly you want to achieve.
One option is gtk_widget_modify_font(). Note that this function can be used to
change only the font size, as in the following example:
This has several possible answers, depending on what exactly you want to
achieve. One option is gtk_widget_modify_font(). Note that this function
can be used to change only the font size, as in the following example:
<programlisting>
PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
pango_font_description_set_size (font_desc, 40);
@ -672,23 +679,24 @@ change only the font size, as in the following example:
</programlisting>
</para>
<para>
If you want to make the text of a label larger, you can use gtk_label_set_markup():
If you want to make the text of a label larger, you can use
gtk_label_set_markup():
<programlisting>
gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;");
</programlisting>
This is preferred for many apps because it's a relative size to the
user's chosen font size. See g_markup_escape_text() if you are constructing such
strings on the fly.
user's chosen font size. See g_markup_escape_text() if you are
constructing such strings on the fly.
</para>
<para>
You can also change the font of a widget by putting
<programlisting>
gtk-font-name = "Sans 30"
</programlisting>
in a resource file and parsing it with gtk_rc_add_default_file(). The advantage of
a resource file is that users can then override the font you've chosen. See
<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
discussion.
in a resource file and parsing it with gtk_rc_add_default_file().
The advantage of a resource file is that users can then override the font you
have chosen. See <link linkend="gtk-Resource-Files">GTK+ resource files</link>
for more discussion.
</para>
</answer>
</qandaentry>
@ -738,9 +746,10 @@ How do I make a text widget display its complete contents in a specific font?
</para></question>
<answer><para>
If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select the
font, the inserted text will have the desired appearance, but text typed in by the
user before or after the tagged block will appear in the default style.
If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select
the font, the inserted text will have the desired appearance, but text typed
in by the user before or after the tagged block will appear in the default
style.
</para>
<para>
To ensure that all text has the desired appearance, use gtk_widget_modify_font()
@ -789,8 +798,8 @@ How do I associate some data with a row in the tree?
<answer>
<para>
Remember that the #GtkTreeModel columns don't necessarily have to be displayed.
So you can put non-user-visible data in your model just like any other data, and
retrieve it with gtk_tree_model_get(). See the
So you can put non-user-visible data in your model just like any other data,
and retrieve it with gtk_tree_model_get(). See the
<link linkend="TreeWidget">tree widget overview</link>.
</para>
</answer>
@ -818,9 +827,10 @@ How do I put an image and some text in the same column?
<answer>
<para>
You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn using
gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both
a #GtkCellRendererPixbuf and a #GtkCellRendererText into the column.
You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
column.
</para>
</answer>
</qandaentry>
@ -834,8 +844,9 @@ gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
<answer>
<para>
Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
interface. Consequentially, the can use any function this interface implements.
The easiest way to read a set of data back is to use gtk_tree_model_get().
interface. Consequentially, the can use any function this interface
implements. The easiest way to read a set of data back is to use
gtk_tree_model_get().
</para>
</answer>
</qandaentry>
@ -846,8 +857,8 @@ How do I change the way that numbers are formatted by #GtkTreeView?
</para></question>
<answer><para>
Use gtk_tree_view_insert_column_with_data_func()
or gtk_tree_view_column_set_cell_data_func() and do the conversion from number to
string yourself (with, say, g_strdup_printf()).
or gtk_tree_view_column_set_cell_data_func() and do the conversion from i
number to string yourself (with, say, g_strdup_printf()).
</para>
<para>

View File

@ -20,9 +20,9 @@ How to run and debug your GTK+ application
<para>
All GTK+ applications support a number of standard commandline
options. These are removed from <literal>argv</literal> by <link
linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
further options. The <link linkend="x11-cmdline">X11</link> and
options. These are removed from <literal>argv</literal> by gtk_init().
Modules may parse and remove further options. The
<link linkend="x11-cmdline">X11</link> and
<link linkend="win32-cmdline">Windows</link> GDK backends parse
some additional commandline options.
</para>
@ -80,7 +80,7 @@ list them here for completeness nevertheless.
<title><systemitem>--class <replaceable>class</replaceable></systemitem></title>
<para>
Sets the program class; see <link linkend="gdk-set-program-class"><function>gdk_set_program_class</function>()</link>.
Sets the program class; see gdk_set_program_class().
</para>
</formalpara>
@ -97,10 +97,9 @@ Sets the program name.
<para>
A list of <link linkend="GDK-Debug-Options">debug options</link>
to turn on in addition to those
specified in the <envar>GDK_DEBUG</envar> environment variable.
This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
to turn on in addition to those specified in the <envar>GDK_DEBUG</envar>
environment variable. This option is only available if GTK+ has been
configured with <option>--enable-debug=yes</option>.
</para>
</formalpara>
@ -109,8 +108,7 @@ This option is only available if GTK+ has been configured with
<para>
A list of <link linkend="GDK-Debug-Options">debug options</link>
to turn off.
This option is only available if GTK+ has been configured with
to turn off. This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
</para>
</formalpara>
@ -184,7 +182,8 @@ additional environment variables.
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn on all debug options.
The special value <literal>all</literal> can be used to turn on all
debug options.
</para>
</formalpara>
@ -202,12 +201,13 @@ additional environment variables.
<para>
Specifies a list of directories to search when GTK+ is looking for
dynamically loaded objects such as the modules specified by
<envar>GTK_MODULES</envar>, theme engines, and input method
modules. 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, followed
by the directory <filename>.gtk-2.0</filename> in the user's home
directory, followed by the system default directory,
<envar>GTK_MODULES</envar>, theme engines, input method
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,
followed by the directory <filename>.gtk-2.0</filename> in the user's
home directory, followed by the system default directory,
which is <filename><replaceable>libdir</replaceable>/gtk-2.0/modules</filename>.
(If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
<filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
@ -225,9 +225,10 @@ additional environment variables.
--variable=gtk_host gtk+-2.0</literal> to determine this from a
script), and <replaceable>type</replaceable> is a directory
specific to the type of modules; currently it can be
<literal>modules</literal>, <literal>engines</literal> or
<literal>immodules</literal> corresponding to the three types of
modules above. Either <replaceable>version</replaceable>,
<literal>modules</literal>, <literal>engines</literal>,
<literal>immodules</literal>, <literal>filesystems</literal> or
<literal>printbackends</literal>, corresponding to the types of
modules mentioned above. Either <replaceable>version</replaceable>,
<replaceable>host</replaceable>, or both may be omitted. GTK+ looks
first in the most specific directory, then in directories with
fewer components.
@ -328,7 +329,8 @@ nevertheless.
<listitem><para>Information about XIM support</para></listitem>
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn on all debug options.
The special value <literal>all</literal> can be used to turn on all
debug options.
</para>
</formalpara>

View File

@ -37,8 +37,8 @@ be called "bold" and make the text inside the tag bold. However, the tag
concept is more general than that; tags don't have to affect appearance. They
can instead affect the behavior of mouse and key presses, "lock" a range of
text so the user can't edit it, or countless other things. A tag is
represented by a #GtkTextTag object. One #GtkTextTag can be applied to any number
of text ranges in any number of buffers.
represented by a #GtkTextTag object. One #GtkTextTag can be applied to any
number of text ranges in any number of buffers.
</para>
<para>
@ -57,35 +57,36 @@ is convenient if you're creating tags on-the-fly).
<para>
Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
represented by a #GtkTextIter. An iterator represents a position between two
characters in the text buffer. #GtkTextIter is a struct designed to be allocated
on the stack; it's guaranteed to be copiable by value and never contain any
heap-allocated data. Iterators are not valid indefinitely; whenever the buffer
is modified in a way that affects the number of characters in the buffer, all
outstanding iterators become invalid. (Note that deleting 5 characters and then
reinserting 5 still invalidates iterators, though you end up with the same
number of characters you pass through a state with a different number).
characters in the text buffer. #GtkTextIter is a struct designed to be
allocated on the stack; it's guaranteed to be copiable by value and never
contain any heap-allocated data. Iterators are not valid indefinitely;
whenever the buffer is modified in a way that affects the number of characters
in the buffer, all outstanding iterators become invalid. (Note that deleting
5 characters and then reinserting 5 still invalidates iterators, though you
end up with the same number of characters you pass through a state with a
different number).
</para>
<para>
Because of this, iterators can't be used to preserve positions across buffer
modifications. To preserve a position, the #GtkTextMark object is ideal. You can
think of a mark as an invisible cursor or insertion point; it floats in the buffer,
saving a position. If the text surrounding the mark is deleted, the mark remains
in the position the text once occupied; if text is inserted at the mark, the
mark ends up either to the left or to the right of the new text, depending on
its <firstterm>gravity</firstterm>. The standard text cursor in left-to-right
languages is a mark with right gravity, because it stays to the right of
inserted text.
modifications. To preserve a position, the #GtkTextMark object is ideal. You
can think of a mark as an invisible cursor or insertion point; it floats in
the buffer, saving a position. If the text surrounding the mark is deleted,
the mark remains in the position the text once occupied; if text is inserted
at the mark, the mark ends up either to the left or to the right of the new
text, depending on its <firstterm>gravity</firstterm>. The standard text
cursor in left-to-right languages is a mark with right gravity, because it
stays to the right of inserted text.
</para>
<para>
Like tags, marks can be either named or anonymous. There are two marks built-in
to #GtkTextBuffer; these are named <literal>"insert"</literal> and
<literal>"selection_bound"</literal> and refer to the insertion point and the
boundary of the selection which is not the insertion point, respectively. If no
text is selected, these two marks will be in the same position. You can manipulate
what is selected and where the cursor appears by moving these marks around.
boundary of the selection which is not the insertion point, respectively. If
no text is selected, these two marks will be in the same position. You can
manipulate what is selected and where the cursor appears by moving these
marks around.
<footnote>
<para>
If you want to place the cursor in response to a user action, be sure to use

View File

@ -243,7 +243,7 @@ Deprecated.
<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
<para>
<!-- documented inline -->
</para>
@object:

View File

@ -181,17 +181,16 @@ application.)
reference to the start (top/left) or end (bottom/right) of the GtkBox.
@is_secondary:
<!-- ##### FUNCTION gtk_box_pack_start ##### -->
<para>
</para>
@box:
@child:
@expand:
@box
@fill:
@child:
@expand:
@box
@fill:
@padding:
@ -222,7 +221,7 @@ application.)
</para>
@box:
@widget:
@widget:
<!-- ##### FUNCTION gtk_box_get_homogeneous ##### -->
@ -267,8 +266,8 @@ application.)
</para>
@box:
@child:
@position:
@child:
@position:
<!-- ##### FUNCTION gtk_box_query_child_packing ##### -->
@ -276,11 +275,11 @@ application.)
</para>
@box:
@child:
@expand:
@box:
@child:
@expand:
@fill:
@padding:
@padding:
@pack_type:
@ -291,7 +290,9 @@ application.)
@box:
@child:
@expand:
@expand:
@fill:
@padding:
@pack_type:
@padding:
@pack_type:

View File

@ -952,13 +952,23 @@ Parses resource information directly from a string.
<!-- ##### FUNCTION gtk_rc_parse_color ##### -->
<para>
Parses a color in the <link linkend="color-format">format</link> expected in a RC file.
</para>
@scanner: a #GtkScanner
@color: a pointer to a #GtkColor structure in which to store the result
@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
that was expected but not found.
@scanner:
@color:
@Returns:
<!-- ##### FUNCTION gtk_rc_parse_color_full ##### -->
<para>
</para>
@scanner:
@style:
@color:
@Returns:
<!-- ##### FUNCTION gtk_rc_parse_state ##### -->

View File

@ -110,23 +110,17 @@ recently used files list.
<!-- ##### STRUCT GtkRecentData ##### -->
<para>
Meta-data passed to gtk_recent_manager_add_full(). You should
use #GtkRecentData if you want to control the meta-data associated
to an entry of the recently used files list when you are adding
a new file to it.
</para>
@display_name: the string to be used when displaying the file
inside a #GtkRecentChooser
@description: a user readable description of the file
@mime_type: the mime type of the file
@app_name: the name of the application that is registering
the file
@app_exec: the command line that should be used when launching
the file
@groups: the list of group names to which the file belongs to
@is_private: whether the file should be displayed only by
the applications that have registered it
@display_name:
@description:
@mime_type:
@app_name:
@app_exec:
@groups:
@is_private:
<!-- ##### MACRO GTK_RECENT_MANAGER_ERROR ##### -->
<para>

View File

@ -275,6 +275,14 @@ The "Directory" icon.
@Since: 2.6
<!-- ##### MACRO GTK_STOCK_DISCARD ##### -->
<para>
The "Discard" item.
</para>
@Since: 2.12
<!-- ##### MACRO GTK_STOCK_DISCONNECT ##### -->
<para>
The "Disconnect" icon.

View File

@ -323,15 +323,11 @@ gtk_widget_style_get_valist() to obtain the value of a style property.
<!-- ##### SIGNAL GtkWidget::hierarchy-changed ##### -->
<para>
Emitted when there is a change in the hierarchy to
which a widget belongs. More precisely, a widget is
<firstterm>anchored</firstterm> when its toplevel
ancestor is a #GtkWindow. This signal is emitted when
a widget changes from un-anchored to anchored or vice-versa.
</para>
@widget: the object which received the signal.
@widget2: the toplevel ancestor, or %NULL
@widget:
@widget2:
<!-- ##### SIGNAL GtkWidget::key-press-event ##### -->
<para>
@ -1979,6 +1975,16 @@ This function is not useful for applications.
@font_desc:
<!-- ##### FUNCTION gtk_widget_modify_cursor ##### -->
<para>
</para>
@widget:
@primary:
@secondary:
<!-- ##### FUNCTION gtk_widget_create_pango_context ##### -->
<para>

View File

@ -195,7 +195,8 @@ gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
<para>
Most applications will need to not only deal with displaying data, but
also receiving input events from users. To do this, simply get a
reference to a selection object and connect to the "changed" signal.
reference to a selection object and connect to the
#GtkTreeSelection::changed signal.
</para>
<informalexample><programlisting><![CDATA[
/* Prototype for selection handler callback */

View File

@ -633,8 +633,8 @@ gtk_box_reorder_child (GtkBox *box,
* @fill: pointer to return location for #GtkBox:fill child property
* @padding: pointer to return location for #GtkBox:padding child property
* @pack_type: pointer to return location for #GtkBox:pack-type child property
*
* Returns information about how @child is packed into @box.
*
* Obtains information about how @child is packed into @box.
*/
void
gtk_box_query_child_packing (GtkBox *box,

View File

@ -664,9 +664,14 @@ gtk_scrolled_window_set_placement_set (GtkScrolledWindow *scrolled_window,
/**
* gtk_scrolled_window_set_placement:
* @scrolled_window: a #GtkScrolledWindow
* @window_placement: position of the child window
*
* Sets the placement of the contents with respect to the scrollbars
* for the scrolled window.
* The default is %GTK_CORNER_TOP_LEFT, meaning the child is
* in the top left, with the scrollbars underneath and to the right.
* Other values in #GtkCornerType are %GTK_CORNER_TOP_RIGHT,
* %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT.
*
* See also gtk_scrolled_window_get_placement() and
* gtk_scrolled_window_unset_placement().

View File

@ -714,8 +714,10 @@ gtk_widget_class_init (GtkWidgetClass *klass)
* if the widget was previously unanchored
*
* The ::hierarchy-changed signal is emitted when the
* anchored state of a widget changes. A widget is anchored,
* if it has an ancestor that is a toplevel window.
* anchored state of a widget changes. A widget is
* <firstterm>anchored</firstterm> when its toplevel
* ancestor is a #GtkWindow. This signal is emitted when
* a widget changes from un-anchored to anchored or vice-versa.
*/
widget_signals[HIERARCHY_CHANGED] =
g_signal_new (I_("hierarchy_changed"),
@ -7837,7 +7839,7 @@ gtk_widget_reset_shapes (GtkWidget *widget)
*
* Return value: the widget that was referenced
*
* Deprecated: Use g_object_ref() instead.
* Deprecated:2.12: Use g_object_ref() instead.
**/
GtkWidget*
gtk_widget_ref (GtkWidget *widget)
@ -7853,7 +7855,7 @@ gtk_widget_ref (GtkWidget *widget)
*
* Inverse of gtk_widget_ref(). Equivalent to g_object_unref().
*
* Deprecated: Use g_object_unref() instead.
* Deprecated:2.12: Use g_object_unref() instead.
**/
void
gtk_widget_unref (GtkWidget *widget)

View File

@ -444,12 +444,12 @@ GType gtk_widget_get_type (void) G_GNUC_CONST;
GtkWidget* gtk_widget_new (GType type,
const gchar *first_property_name,
...);
GtkWidget* gtk_widget_ref (GtkWidget *widget);
void gtk_widget_unref (GtkWidget *widget);
void gtk_widget_destroy (GtkWidget *widget);
void gtk_widget_destroyed (GtkWidget *widget,
GtkWidget **widget_pointer);
#ifndef GTK_DISABLE_DEPRECATED
GtkWidget* gtk_widget_ref (GtkWidget *widget);
void gtk_widget_unref (GtkWidget *widget);
void gtk_widget_set (GtkWidget *widget,
const gchar *first_property_name,
...) G_GNUC_NULL_TERMINATED;