forked from AuroraMiddleware/gtk
938cc404c1
Tue Mar 12 00:29:31 2002 Jonathan Blandford <jrb@redhat.com> * gtk/question_index.sgml: new FAQ. * gtk/tmpl/gtktreemodel.sgml: clean up example
555 lines
16 KiB
Plaintext
555 lines
16 KiB
Plaintext
<refentry id="gtk-question-index" revision="1 Jan 2002">
|
|
<refmeta>
|
|
<refentrytitle>Common Questions</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>Common Questions</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>Common Questions</refname>
|
|
<refpurpose>
|
|
Find answers to common questions in the GTK+ manual
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Questions and Answers</title>
|
|
|
|
<para>
|
|
This is an "index" of the reference manual organized by common "How do
|
|
I..." questions. If you aren't sure which documentation to read for
|
|
the question you have, this list is a good place to start.
|
|
</para>
|
|
|
|
<qandaset>
|
|
|
|
<qandadiv><title>General</title>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
Where can I get help with GTK+, submit a bug report, or make a feature
|
|
request?
|
|
</para></question>
|
|
|
|
<answer>
|
|
|
|
<para>
|
|
See the <link linkend="gtk-resources">documentation on this topic</link>.
|
|
</para>
|
|
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
|
|
<qandaentry>
|
|
<question><para>How do I port from one GTK+
|
|
version to another?</para></question>
|
|
|
|
<answer>
|
|
|
|
<para>
|
|
See the <link linkend="gtk-changes-2-0">list of incompatible changes
|
|
from 1.2 to 2.0</link>. Also, the <ulink
|
|
url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
|
|
guide</ulink> on <ulink
|
|
url="http://developer.gnome.org">http://developer.gnome.org</ulink>
|
|
has some more detailed discussion of porting from 1.2 to 2.0.
|
|
You may also find useful information in the documentation for
|
|
specific widgets and functions.
|
|
</para>
|
|
|
|
<para>
|
|
If you have a question not covered in the manual, feel free to
|
|
ask on the mailing lists and please <ulink
|
|
url="http://bugzilla.gnome.org">file a bug report</ulink> against the
|
|
documentation.
|
|
</para>
|
|
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How does memory management work in GTK+? Should I free data returned
|
|
from functions?
|
|
</para></question>
|
|
|
|
<answer>
|
|
|
|
<para>
|
|
See the documentation for <link linkend="GObject">GObject</link> and
|
|
<link linkend="GtkObject">GtkObject</link>. For <link
|
|
linkend="GObject">GObject</link> note specifically <link
|
|
linkend="g-object-ref">g_object_ref()</link> and <link
|
|
linkend="g-object-unref">g_object_unref()</link>. <link
|
|
linkend="GtkObject">GtkObject</link> is a subclass of <link
|
|
linkend="GObject">GObject</link> 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 <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
|
|
should not be freed. Non-const strings should be freed with <link
|
|
linkend="g-free">g_free()</link>. 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>
|
|
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I use GTK+ with threads?
|
|
</para></question>
|
|
|
|
<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.
|
|
</para>
|
|
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I internationalize a GTK+ program?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<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.
|
|
</para>
|
|
<para>
|
|
The short checklist on how to use gettext is: call
|
|
<function>bindtextdomain()</function> so gettext can find the files
|
|
containing your translations, call <function>textdomain()</function>
|
|
to set the default translation domain, then call
|
|
<function>gettext()</function> to look up each string to be translated
|
|
in the default domain. Conventionally, people define macros as
|
|
follows for convenience:
|
|
<informalexample>
|
|
<programlisting>
|
|
#define _(x) gettext (x)
|
|
#define N_(x) x
|
|
</programlisting>
|
|
</informalexample>
|
|
You use <function>N_()</function> (N stands for no-op) to mark
|
|
a string for translation in a context where a function call
|
|
to <function>gettext()</function> is not allowed, such as in
|
|
an array initializer. You eventually have to call
|
|
<function>gettext()</function> on the string to actually fetch the
|
|
translation. <function>_()</function> both marks the string for
|
|
translation and actually translates it.
|
|
</para>
|
|
<para>
|
|
Code using these macros ends up looking like this:
|
|
<informalexample>
|
|
<programlisting>
|
|
#include <libintl.h>
|
|
|
|
#define _(x) gettext (x)
|
|
#define N_(x) x
|
|
|
|
static const char *global_variable = N_("Translate this string");
|
|
|
|
static void
|
|
make_widgets (void)
|
|
{
|
|
GtkWidget *label1;
|
|
GtkWidget *label2;
|
|
|
|
label1 = gtk_label_new (_("Another string to translate"));
|
|
label2 = gtk_label_new (_(global_variable));
|
|
...
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Libraries using gettext should use <function>dgettext()</function>
|
|
instead of <function>gettext()</function>, which allows
|
|
them to specify the translation domain each time they
|
|
ask for a translation. Libraries should also avoid calling
|
|
<function>textdomain()</function>, since they'll be specifying
|
|
the domain instead of using the default.
|
|
For <function>dgettext()</function> the <function>_()</function> macro
|
|
can be defined as:
|
|
<informalexample>
|
|
<programlisting>
|
|
#define _(x) dgettext ("MyDomain", x)
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I use GTK+ with C++?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
When using GTK+ directly, keep in mind that only functions can be
|
|
connected to signals, not methods. So you will need to use global
|
|
functions or "static" class functions for signal connections.
|
|
</para>
|
|
<para>
|
|
Another common issue when using GTK+ directly is that
|
|
C++ will not implicitly convert an integer to an enumeration.
|
|
This comes up when using bitfields; in C you can write the following
|
|
code:
|
|
<informalexample>
|
|
<programlisting>
|
|
gdk_window_set_events (gdk_window,
|
|
GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
|
|
</programlisting>
|
|
</informalexample>
|
|
while in C++ you must write:
|
|
<informalexample>
|
|
<programlisting>
|
|
gdk_window_set_events (gdk_window,
|
|
(GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
|
|
</programlisting>
|
|
</informalexample>
|
|
There are very few functions that require this cast, however.
|
|
</para>
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I use GTK+ with other non-C languages?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<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>.
|
|
</para>
|
|
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I load an image or animation from a file?
|
|
</para></question>
|
|
|
|
<answer>
|
|
|
|
<para>
|
|
To load an image file straight into a display widget, use <link
|
|
linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
|
|
<footnote><para> If the file load fails, <link
|
|
linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
|
|
will display a "broken image" graphic &mdash to detect a failed load
|
|
yourself, use <link
|
|
linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
|
|
directly then <link
|
|
linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
|
|
</para></footnote>. To load an image for another purpose, use <link
|
|
linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
|
|
To load an animation, use <link
|
|
linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
|
|
<link
|
|
linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>
|
|
can also load non-animated images, so use it in combination with
|
|
<link
|
|
linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type.
|
|
</para>
|
|
<para>
|
|
To load an image or animation file asynchronously (without blocking), use
|
|
<link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.
|
|
</para>
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
|
|
</qandadiv>
|
|
|
|
<qandadiv><title>Which widget should I use...</title>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
...for lists and trees?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
See <link linkend="TreeWidget">tree widget overview</link> &mdash you
|
|
should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
|
|
(A list is just a tree with no branches, so the tree widget is used
|
|
for lists as well.) Do not use the deprecated widgets <link
|
|
linkend="GtkTree">GtkTree</link> or <link
|
|
linkend="GtkCList">GtkCList</link>/<link
|
|
linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
|
|
less flexible and result in an inferior user interface.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
...for multi-line text display or editing?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
See <link linkend="TextWidget">text widget overview</link> &mdash you
|
|
should use the <link linkend="GtkTextView">GtkTextView</link> widget.
|
|
Do not use the deprecated widget <link
|
|
linkend="GtkText">GtkText</link> 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, <link
|
|
linkend="GtkLabel">GtkLabel</link> may also be appropriate of course.
|
|
It can be made selectable with <link
|
|
linkend="gtk-label-set-selectable">
|
|
gtk_label_set_selectable()</link>. For a single-line text entry,
|
|
see <link linkend="GtkEntry">GtkEntry</link>.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
...to display an image or animation?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
<link linkend="GtkImage">GtkImage</link> can display images
|
|
in just about any format GTK+ understands. You can also
|
|
use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need
|
|
to do something more complex, such as draw text or graphics over the
|
|
top of the image.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
...for presenting a set of mutually-exclusive choices, where Windows
|
|
would use a combo box?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
|
|
recommended instead of a combo box, if the user is selecting from a
|
|
fixed set of options. That is, non-editable combo boxes are not
|
|
encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
|
|
much easier to use than <link linkend="GtkCombo">GtkCombo</link>
|
|
as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you
|
|
need the editable text entry.
|
|
</para>
|
|
<para>
|
|
(As a future enhancement to GTK+, a new widget to replace <link
|
|
linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
|
|
linkend="GtkCombo">GtkCombo</link> is planned. This widget will be
|
|
themeable to look like either a combo box or the current option menu,
|
|
and will address some shortcomings in the <link
|
|
linkend="GtkCombo">GtkCombo</link> API. <ulink
|
|
url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
|
|
50554</ulink> tracks this issue, if you want to check status or post
|
|
comments.)
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
</qandadiv>
|
|
|
|
<qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I change the color of a widget?
|
|
</para></question>
|
|
|
|
<answer><para>
|
|
See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,
|
|
<link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
|
|
<link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
|
|
and <link
|
|
linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>. 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 <link
|
|
linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
|
|
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 <link
|
|
linkend="GtkLabel">GtkLabel</link> that have no background, place them
|
|
in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
|
|
background of the event box.
|
|
</para></answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I disable/ghost/desensitize a widget?
|
|
</para></question>
|
|
|
|
<answer><para> In GTK+ a disabled widget is termed "insensitive." See
|
|
<link
|
|
linkend="gtk-widget-set-sensitive">gtk_widget_set_sensitive()</link>.
|
|
</para></answer>
|
|
</qandaentry>
|
|
|
|
</qandadiv>
|
|
|
|
|
|
<qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I get the contents of the entire text widget as a string?
|
|
</para></question>
|
|
|
|
<answer><para>
|
|
|
|
See <link
|
|
linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
|
|
and <link
|
|
linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
|
|
or <link
|
|
linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
|
|
</para>
|
|
<para>
|
|
<informalexample><programlisting>
|
|
GtkTextIter start, end;
|
|
GtkTextBuffer *buffer;
|
|
char *text;
|
|
|
|
buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
|
|
gtk_text_buffer_get_bounds (buffer, &start, &end);
|
|
text = gtk_text_iter_get_text (&start, &end);
|
|
/* use text */
|
|
g_free (text);
|
|
</programlisting></informalexample>
|
|
</para></answer>
|
|
</qandaentry>
|
|
|
|
</qandadiv>
|
|
|
|
|
|
|
|
<qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I associate some data with a row in the tree?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
|
|
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 <link
|
|
linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
|
|
See the <link linkend="TreeWidget">tree widget overview</link>.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
As there is no separate data column in the #GtkTreeModel, there's no
|
|
built in function to find the iter from data. You can write a custom
|
|
searching function to walk the tree and find the data, or use
|
|
gtk_tree_model_foreach().
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
How do I put an image and some text in the same column?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
You can pack more than one <link
|
|
linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
|
|
<link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
|
|
<link
|
|
linkend="gtk-tree-view-column-pack-start">gtk_tree_view_column_pack_start()</link> or <link linkend="gtk-tree-view-column-pack-end">gtk_tree_view_column_pack_end()</link>. So pack both a <link
|
|
linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
|
|
and a <link
|
|
linkend="GtkCellRendererText">GtkCellRendererText</link> into the
|
|
column.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question><para>
|
|
I can set data easily on my <link
|
|
linkend="GtkTreeStore">GtkTreeStore</link>/<link
|
|
linkend="GtkListStore">GtkListStore</link> models using <link
|
|
linkend="gtk-tree-model-get">gtk_list_store_set()</link> and <link
|
|
linkend="gtk-tree-model-get">gtk_tree_store_set()</link>, but can't read
|
|
it back?
|
|
</para></question>
|
|
|
|
<answer>
|
|
<para>
|
|
Both the <link
|
|
linkend="GtkTreeStore">GtkTreeStore</link> and the <link
|
|
linkend="GtkListStore">GtkListStore</link> implement the
|
|
<link linkend="GtkTreeModel">GtkTreeModel</link>
|
|
interface. Consequentially, the can use any function
|
|
this interface implements. The easiest way to read a
|
|
set of data back is to use
|
|
<link
|
|
linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
</qandadiv>
|
|
|
|
|
|
|
|
</qandaset>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|