forked from AuroraMiddleware/gtk
824e8e2d9d
2002-01-06 Havoc Pennington <hp@pobox.com> * gtk/gtk-docs.sgml: remove gtk- prefix from TreeView and a few other entities, more consistent anyway (I thought this would make links to "GtkTreeView" etc. go to the ref page, not the struct, but it wasn't the problem, the issue is the way gtkdoc-mkdb decides what's an object, see CheckIsObject() routine) * gtk/changes-1.2.sgml: sgml fixes to get rid of warnings * gtk/changes-2.0.sgml: ditto * gtk/question_index.sgml: add some questions
383 lines
11 KiB
Plaintext
383 lines
11 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 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>
|
|
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>
|
|
|
|
</qandadiv>
|
|
|
|
|
|
|
|
</qandaset>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|