forked from AuroraMiddleware/gtk
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:
parent
19f4715cee
commit
08cc834061
@ -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:
|
||||
|
@ -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>
|
||||
|
@ -90,6 +90,7 @@ IGNORE_HFILES= \
|
||||
gtkxembed.h \
|
||||
gtkwin32embed.h \
|
||||
gtkwin32embedwidget.h \
|
||||
gtkwindow-decorate.h \
|
||||
xdgmime \
|
||||
xembed.h
|
||||
|
||||
|
@ -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>
|
||||
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
||||
|
@ -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,
|
||||
|
@ -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>
|
||||
|
@ -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 — 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 — 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, "<big>big text</big>");
|
||||
</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>
|
||||
|
@ -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>
|
||||
|
||||
|
@ -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
|
||||
|
@ -243,7 +243,7 @@ Deprecated.
|
||||
|
||||
<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
|
||||
<para>
|
||||
<!-- documented inline -->
|
||||
|
||||
</para>
|
||||
|
||||
@object:
|
||||
|
@ -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:
|
||||
|
||||
|
||||
|
@ -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 ##### -->
|
||||
|
@ -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>
|
||||
|
@ -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.
|
||||
|
@ -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>
|
||||
|
||||
|
@ -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 */
|
||||
|
@ -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,
|
||||
|
@ -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().
|
||||
|
@ -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)
|
||||
|
@ -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;
|
||||
|
Loading…
Reference in New Issue
Block a user