Pileus Git - ~andy/gtk/blob - docs/reference/gtk/question_index.sgml

   1 <refentry id="gtk-question-index" revision="1 Jan 2002">
   2 <refmeta>
   3 <refentrytitle>Common Questions</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Common Questions</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Common Questions</refname>
  10 <refpurpose>
  11 Find answers to common questions in the GTK+ manual
  12 </refpurpose>
  13 </refnamediv>
  14
  15 <refsect1>
  16 <title>Questions and Answers</title>
  17
  18 <para>
  19 This is an "index" of the reference manual organized by common "How do
  20 I..." questions. If you aren't sure which documentation to read for
  21 the question you have, this list is a good place to start.
  22 </para>
  23
  24 <qandaset>
  25
  26 <qandadiv><title>General</title>
  27
  28 <qandaentry>
  29 <question><para>
  30 Where can I get help with GTK+, submit a bug report, or make a feature
  31 request?
  32 </para></question>
  33
  34 <answer>
  35
  36 <para>
  37 See the <link linkend="gtk-resources">documentation on this topic</link>.
  38 </para>
  39
  40 </answer>
  41
  42 </qandaentry>
  43
  44
  45 <qandaentry>
  46 <question><para>How do I port from one GTK+
  47 version to another?</para></question>
  48
  49 <answer>
  50
  51 <para>
  52 See the <link linkend="gtk-changes-2-0">list of incompatible changes
  53 from 1.2 to 2.0</link>. Also, the <ulink
  54 url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
  55 guide</ulink> on <ulink
  56 url="http://developer.gnome.org">http://developer.gnome.org</ulink>
  57 has some more detailed discussion of porting from 1.2 to 2.0.
  58 You may also find useful information in the documentation for
  59 specific widgets and functions.
  60 </para>
  61
  62 <para>
  63 If you have a question not covered in the manual, feel free to
  64 ask on the mailing lists and please <ulink
  65 url="http://bugzilla.gnome.org">file a bug report</ulink> against the
  66 documentation.
  67 </para>
  68
  69 </answer>
  70
  71 </qandaentry>
  72
  73
  74 <qandaentry>
  75 <question><para>
  76 How does memory management work in GTK+? Should I free data returned
  77 from functions?
  78 </para></question>
  79
  80 <answer>
  81
  82 <para>
  83 See the documentation for <link linkend="GObject">GObject</link> and
  84 <link linkend="GtkObject">GtkObject</link>. For <link
  85 linkend="GObject">GObject</link> note specifically <link
  86 linkend="g-object-ref">g_object_ref()</link> and <link
  87 linkend="g-object-unref">g_object_unref()</link>. <link
  88 linkend="GtkObject">GtkObject</link> is a subclass of <link
  89 linkend="GObject">GObject</link> so the same points apply, except that
  90 it has a "floating" state (explained in its documentation).
  91 </para>
  92
  93 <para>
  94 For strings returned from functions, they will be declared "const"
  95 (using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
  96 should not be freed. Non-const strings should be freed with <link
  97 linkend="g-free">g_free()</link>. Arrays follow the same rule.  (If
  98 you find an exception to the rules, please report a bug to <ulink
  99 url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
 100 </para>
 101
 102 </answer>
 103
 104 </qandaentry>
 105
 106
 107 <qandaentry>
 108 <question><para>
 109 How do I use GTK+ with threads?
 110 </para></question>
 111
 112 <answer>
 113
 114 <para>
 115 This is covered in the
 116 <link linkend="gdk-Threads">GDK threads documentation</link>.
 117 See also the <link linkend="glib-Threads">GThread</link> documentation for portable
 118 threading primitives.
 119 </para>
 120
 121 </answer>
 122
 123 </qandaentry>
 124
 125
 126 <qandaentry>
 127 <question><para>
 128 How do I load an image or animation from a file?
 129 </para></question>
 130
 131 <answer>
 132
 133 <para>
 134 To load an image file straight into a display widget, use <link
 135 linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
 136 <footnote><para> If the file load fails, <link
 137 linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
 138 will display a "broken image" graphic &mdash to detect a failed load
 139 yourself, use <link
 140 linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
 141 directly then <link
 142 linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
 143 </para></footnote>. To load an image for another purpose, use <link
 144 linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
 145 To load an animation, use <link
 146 linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
 147 <link
 148 linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>
 149 can also load non-animated images, so use it in combination with
 150 <link
 151       linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type.
 152 </para>
 153 <para>
 154 To load an image or animation file asynchronously (without blocking), use
 155 <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.
 156 </para>
 157 </answer>
 158
 159 </qandaentry>
 160
 161
 162 </qandadiv>
 163
 164 <qandadiv><title>Which widget should I use...</title>
 165
 166 <qandaentry>
 167 <question><para>
 168 ...for lists and trees?
 169 </para></question>
 170
 171 <answer>
 172 <para>
 173 See <link linkend="TreeWidget">tree widget overview</link> &mdash you
 174 should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
 175 (A list is just a tree with no branches, so the tree widget is used
 176 for lists as well.) Do not use the deprecated widgets <link
 177 linkend="GtkTree">GtkTree</link> or <link
 178 linkend="GtkCList">GtkCList</link>/<link
 179 linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
 180 less flexible and result in an inferior user interface.
 181 </para>
 182 </answer>
 183 </qandaentry>
 184
 185 <qandaentry>
 186 <question><para>
 187 ...for multi-line text display or editing?
 188 </para></question>
 189
 190 <answer>
 191 <para>
 192 See <link linkend="TextWidget">text widget overview</link> &mdash you
 193 should use the <link linkend="GtkTextView">GtkTextView</link> widget.
 194 Do not use the deprecated widget <link
 195 linkend="GtkText">GtkText</link> in newly-written code, it has a
 196 number of problems that are best avoided.
 197 </para>
 198 <para>
 199 If you only have a small amount of text, <link
 200 linkend="GtkLabel">GtkLabel</link> may also be appropriate of course.
 201 It can be made selectable with <link
 202                                      linkend="gtk-label-set-selectable">
 203 gtk_label_set_selectable()</link>. For a single-line text entry,
 204 see <link linkend="GtkEntry">GtkEntry</link>.
 205 </para>
 206 </answer>
 207 </qandaentry>
 208
 209
 210 <qandaentry>
 211 <question><para>
 212 ...to display an image or animation?
 213 </para></question>
 214
 215 <answer>
 216 <para>
 217 <link linkend="GtkImage">GtkImage</link> can display images
 218 in just about any format GTK+ understands. You can also
 219 use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need
 220 to do something more complex, such as draw text or graphics over the
 221 top of the image.
 222 </para>
 223 </answer>
 224 </qandaentry>
 225
 226 <qandaentry>
 227 <question><para>
 228 ...for presenting a set of mutually-exclusive choices, where Windows
 229 would use a combo box?
 230 </para></question>
 231
 232 <answer>
 233 <para>
 234 With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
 235 recommended instead of a combo box, if the user is selecting from a
 236 fixed set of options. That is, non-editable combo boxes are not
 237 encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
 238 much easier to use than <link linkend="GtkCombo">GtkCombo</link>
 239 as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you
 240 need the editable text entry.
 241 </para>
 242 <para>
 243 (As a future enhancement to GTK+, a new widget to replace <link
 244 linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
 245 linkend="GtkCombo">GtkCombo</link> is planned.  This widget will be
 246 themeable to look like either a combo box or the current option menu,
 247 and will address some shortcomings in the <link
 248 linkend="GtkCombo">GtkCombo</link> API.  <ulink
 249 url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
 250 50554</ulink> tracks this issue, if you want to check status or post
 251 comments.)
 252 </para>
 253 </answer>
 254 </qandaentry>
 255
 256 </qandadiv>
 257
 258 <qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
 259
 260 <qandaentry>
 261 <question><para>
 262 How do I change the color of a widget?
 263 </para></question>
 264
 265 <answer><para>
 266 See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,
 267 <link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
 268 <link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
 269 and <link
 270 linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>.  See
 271 <link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
 272 discussion. You can also change widget color by installing a resource
 273 file and parsing it with <link
 274 linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
 275 The advantage of a resource file is that users can then override the
 276 color you've chosen.
 277 </para>
 278
 279 <para>To change the background color for widgets such as <link
 280 linkend="GtkLabel">GtkLabel</link> that have no background, place them
 281 in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
 282 background of the event box.
 283 </para></answer>
 284 </qandaentry>
 285
 286 <qandaentry>
 287 <question><para>
 288 How do I disable/ghost/desensitize a widget?
 289 </para></question>
 290
 291 <answer><para> In GTK+ a disabled widget is termed "insensitive." See
 292 <link
 293 linkend="gtk-widget-set-sensitive">gtk_widget_set_sensitive()</link>.
 294 </para></answer>
 295 </qandaentry>
 296
 297 </qandadiv>
 298
 299
 300 <qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>
 301
 302 <qandaentry>
 303 <question><para>
 304 How do I get the contents of the entire text widget as a string?
 305 </para></question>
 306
 307 <answer><para>
 308
 309 See <link
 310           linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
 311           and <link
 312           linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
 313 or <link
 314           linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
 315 </para>
 316 <para>
 317 <informalexample><programlisting>
 318   GtkTextIter start, end;
 319   GtkTextBuffer *buffer;
 320   char *text;
 321
 322   buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
 323   gtk_text_buffer_get_bounds (buffer, &amp;start, &amp;end);
 324   text = gtk_text_iter_get_text (&amp;start, &amp;end);
 325   /* use text */
 326   g_free (text);
 327 </programlisting></informalexample>
 328 </para></answer>
 329 </qandaentry>
 330
 331 </qandadiv>
 332
 333
 334
 335 <qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
 336
 337 <qandaentry>
 338 <question><para>
 339 How do I associate some data with a row in the tree?
 340 </para></question>
 341
 342 <answer>
 343 <para>
 344 Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
 345 columns don't necessarily have to be displayed. So you can put
 346 non-user-visible data in your model just like any other data, and
 347 retrieve it with <link
 348 linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
 349 See the <link linkend="TreeWidget">tree widget overview</link>.
 350 </para>
 351 </answer>
 352 </qandaentry>
 353
 354 <qandaentry>
 355 <question><para>
 356 How do I put an image and some text in the same column?
 357 </para></question>
 358
 359 <answer>
 360 <para>
 361 You can pack more than one <link
 362 linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
 363 <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
 364 <link
 365       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
 366 linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
 367 and a <link
 368 linkend="GtkCellRendererText">GtkCellRendererText</link> into the
 369 column.
 370 </para>
 371 </answer>
 372 </qandaentry>
 373
 374 </qandadiv>
 375
 376
 377
 378 </qandaset>
 379
 380 </refsect1>
 381
 382 </refentry>