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 How do I get started with GTK+?
  31 </para></question>
  32
  33 <answer><para>
  34 The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a
  35 <ulink url="http://www.gtk.org/tutorial">tutorial</ulink> and a
  36 <ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging
  37 from whitepapers to online books can be found at the
  38 <ulink url="http://developer.gnome.org/doc">GNOME developer's site</ulink>.
  39 After studying these materials you should be well prepared to come back to
  40 this reference manual for details.
  41 </para></answer>
  42 </qandaentry>
  43
  44 <qandaentry>
  45 <question><para>
  46 Where can I get help with GTK+, submit a bug report, or make a feature
  47 request?
  48 </para></question>
  49
  50 <answer>
  51
  52 <para>
  53 See the <link linkend="gtk-resources">documentation on this topic</link>.
  54 </para>
  55
  56 </answer>
  57
  58 </qandaentry>
  59
  60
  61 <qandaentry>
  62 <question><para>How do I port from one GTK+
  63 version to another?</para></question>
  64
  65 <answer>
  66
  67 <para>
  68 See the <link linkend="gtk-changes-2-0">list of incompatible changes
  69 from 1.2 to 2.0</link>. Also, the <ulink
  70 url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
  71 guide</ulink> on <ulink
  72 url="http://developer.gnome.org">http://developer.gnome.org</ulink>
  73 has some more detailed discussion of porting from 1.2 to 2.0.
  74 You may also find useful information in the documentation for
  75 specific widgets and functions.
  76 </para>
  77
  78 <para>
  79 If you have a question not covered in the manual, feel free to
  80 ask on the mailing lists and please <ulink
  81 url="http://bugzilla.gnome.org">file a bug report</ulink> against the
  82 documentation.
  83 </para>
  84
  85 </answer>
  86
  87 </qandaentry>
  88
  89
  90 <qandaentry>
  91 <question><para>
  92 How does memory management work in GTK+? Should I free data returned
  93 from functions?
  94 </para></question>
  95
  96 <answer>
  97
  98 <para>
  99 See the documentation for <link linkend="GObject">GObject</link> and
 100 <link linkend="GtkObject">GtkObject</link>. For <link
 101 linkend="GObject">GObject</link> note specifically <link
 102 linkend="g-object-ref">g_object_ref()</link> and <link
 103 linkend="g-object-unref">g_object_unref()</link>. <link
 104 linkend="GtkObject">GtkObject</link> is a subclass of <link
 105 linkend="GObject">GObject</link> so the same points apply, except that
 106 it has a "floating" state (explained in its documentation).
 107 </para>
 108
 109 <para>
 110 For strings returned from functions, they will be declared "const"
 111 (using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
 112 should not be freed. Non-const strings should be freed with <link
 113 linkend="g-free">g_free()</link>. Arrays follow the same rule.  (If
 114 you find an exception to the rules, please report a bug to <ulink
 115 url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
 116 </para>
 117
 118 </answer>
 119
 120 </qandaentry>
 121
 122
 123 <qandaentry>
 124 <question><para>
 125 How do I use GTK+ with threads?
 126 </para></question>
 127
 128 <answer>
 129
 130 <para>
 131 This is covered in the
 132 <link linkend="gdk-Threads">GDK threads documentation</link>.
 133 See also the <link linkend="glib-Threads">GThread</link> documentation for portable
 134 threading primitives.
 135 </para>
 136
 137 </answer>
 138
 139 </qandaentry>
 140
 141 <qandaentry>
 142 <question><para>
 143 How do I internationalize a GTK+ program?
 144 </para></question>
 145
 146 <answer>
 147 <para>
 148 Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
 149 gettext</ulink>, already required in order to install GLib. On a UNIX
 150 or Linux system with gettext installed, type <literal>info
 151 gettext</literal> to read the documentation.
 152 </para>
 153 <para>
 154 The short checklist on how to use gettext is: call
 155 <function>bindtextdomain()</function> so gettext can find the files
 156 containing your translations, call <function>textdomain()</function>
 157 to set the default translation domain, then call
 158 <function>gettext()</function> to look up each string to be translated
 159 in the default domain. Conventionally, people define macros as
 160 follows for convenience:
 161 <informalexample>
 162 <programlisting>
 163   #define  _(x)  gettext (x)
 164   #define N_(x)  x
 165 </programlisting>
 166 </informalexample>
 167 You use <function>N_()</function> (N stands for no-op) to mark
 168 a string for translation in a context where a function call
 169 to <function>gettext()</function> is not allowed, such as in
 170 an array initializer. You eventually have to call
 171 <function>gettext()</function> on the string to actually fetch the
 172 translation.  <function>_()</function> both marks the string for
 173 translation and actually translates it.
 174 </para>
 175 <para>
 176 Code using these macros ends up looking like this:
 177 <informalexample>
 178 <programlisting>
 179  #include &lt;libintl.h&gt;
 180
 181  #define  _(x)  gettext (x)
 182  #define N_(x)  x
 183
 184  static const char *global_variable = N_("Translate this string");
 185
 186  static void
 187  make_widgets (void)
 188  {
 189     GtkWidget *label1;
 190     GtkWidget *label2;
 191
 192     label1 = gtk_label_new (_("Another string to translate"));
 193     label2 = gtk_label_new (_(global_variable));
 194 ...
 195 </programlisting>
 196 </informalexample>
 197 </para>
 198 <para>
 199 Libraries using gettext should use <function>dgettext()</function>
 200 instead of <function>gettext()</function>, which allows
 201 them to specify the translation domain each time they
 202 ask for a translation. Libraries should also avoid calling
 203 <function>textdomain()</function>, since they'll be specifying
 204 the domain instead of using the default.
 205 For <function>dgettext()</function> the <function>_()</function> macro
 206 can be defined as:
 207 <informalexample>
 208 <programlisting>
 209   #define _(x) dgettext ("MyDomain", x)
 210 </programlisting>
 211 </informalexample>
 212 </para>
 213 </answer>
 214 </qandaentry>
 215
 216 <qandaentry>
 217 <question>
 218 <para>
 219 How do I use non-ASCII characters in GTK+ programs ?
 220 </para>
 221 </question>
 222
 223 <answer>
 224 <para>
 225 GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
 226 UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a
 227               sequence of one to six bytes and has a number of nice
 228               properties which make it a good choice for working with Unicode
 229               text in C programs:
 230 <itemizedlist>
 231 <listitem><para>
 232 ASCII characters are encoded by their familiar ASCII codepoints.
 233 </para></listitem>
 234 <listitem><para>
 235 ASCII characters never appear as part of any other character.
 236 </para></listitem>
 237 <listitem><para>
 238 The zero byte doesn't occur as part of a character, so that UTF-8 strings can
 239                     be manipulated with the usual C library functions for
 240                     handling zero-terminated strings.
 241 </para></listitem>
 242 </itemizedlist>
 243 More information about Unicode and UTF-8 can be found in the
 244 <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.
 245 GLib provides functions for converting strings between UTF-8 and other
 246               encodings, see
 247 <link linkend="g-locale-to-utf8">g_locale_to_utf8()</link> and <link
 248                 linkend="g-convert">g_convert()</link>.
 249 </para>
 250 <para>
 251 Text coming from external sources (e.g. files or user input), has to be
 252               converted to UTF-8 before being handed over to GTK+. The
 253               following example writes the content of a IS0-8859-1 encoded text
 254               file to <literal>stdout</literal>:
 255 <informalexample><programlisting>
 256 gchar *text, *utf8_text;
 257 gsize length;
 258 GError *error = NULL;
 259
 260 if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
 261   {
 262      utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
 263                             NULL, NULL, &amp;error);
 264      if (error != NULL)
 265        {
 266          fprintf ("Couldn't convert file &percnt;s to UTF-8\n", filename);
 267          g_error_free (error);
 268        }
 269      else
 270        g_print (utf8_text);
 271   }
 272 else
 273   fprintf (stderr, "Unable to read file &percnt;s\n", filename);
 274 </programlisting></informalexample>
 275 </para>
 276 <para>
 277 For string literals in the source code, there are several alternatives for
 278               handling non-ASCII content:
 279 <variablelist>
 280 <varlistentry><term>direct UTF-8</term>
 281 <listitem><para>
 282 If your editor and compiler are capable of handling UTF-8 encoded sources,
 283 it is very convenient to simply use UTF-8 for string literals, since it allows
 284 you to edit the strings in "wysiwyg". Note that choosing this option may
 285 reduce the portability of your code.
 286 </para></listitem>
 287 </varlistentry>
 288
 289 <varlistentry><term>escaped UTF-8</term>
 290 <listitem><para>
 291 Even if your toolchain can't handle UTF-8 directly, you can still encode string
 292 literals in UTF-8 by using octal or hexadecimal escapes like
 293 <literal>\212</literal> or <literal>\xa8</literal> to
 294 encode each byte. This is portable, but modifying the escaped strings is not
 295 very convenient. Be careful when mixing hexadecimal escapes with ordinary text;
 296 <literal>"\xa8abcd"</literal> is a string of length 1 !
 297 </para></listitem>
 298 </varlistentry>
 299
 300 <varlistentry><term>runtime conversion</term>
 301 <listitem><para>
 302 If the string literals can be represented in an encoding which your toolchain
 303 can handle (e.g. IS0-8859-1), you can write your source files in that encoding
 304 and use <link linkend="g-convert">g_convert()</link> to convert the strings to
 305 UTF-8 at runtime. Note that this has some runtime overhead, so you may want to
 306 move the conversion out of inner loops.
 307 </para></listitem>
 308 </varlistentry>
 309 </variablelist>
 310 Here is an example showing the three approaches using the copyright sign
 311 &copy; which has Unicode and ISO-8859-1 codepoint 169 and is represented in
 312 UTF-8 by the two bytes 194, 169:
 313 <informalexample><programlisting>
 314 g_print ("direct UTF-8: &copy;");
 315 g_print ("escaped UTF-8: \302\251");
 316 text = g_convert ("runtime conversion: &copy;", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
 317 g_print(text);
 318 g_free (text);
 319 </programlisting></informalexample>
 320 </para>
 321 </answer>
 322 </qandaentry>
 323
 324 <qandaentry>
 325 <question><para>
 326 How do I use GTK+ with C++?
 327 </para></question>
 328
 329 <answer>
 330 <para>
 331 There are two ways to approach this. The GTK+ header files use the subset
 332 of C that's also valid C++, so you can simply use the normal GTK+ API
 333 in a C++ program. Alternatively, you can use a "C++ binding"
 334 such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>
 335 which provides a C++-native API.
 336 </para>
 337 <para>
 338 When using GTK+ directly, keep in mind that only functions can be
 339 connected to signals, not methods. So you will need to use global
 340 functions or "static" class functions for signal connections.
 341 </para>
 342 <para>
 343 Another common issue when using GTK+ directly is that
 344 C++ will not implicitly convert an integer to an enumeration.
 345 This comes up when using bitfields; in C you can write the following
 346 code:
 347 <informalexample>
 348 <programlisting>
 349   gdk_window_set_events (gdk_window,
 350                          GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
 351 </programlisting>
 352 </informalexample>
 353 while in C++ you must write:
 354 <informalexample>
 355 <programlisting>
 356   gdk_window_set_events (gdk_window,
 357                          (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
 358 </programlisting>
 359 </informalexample>
 360 There are very few functions that require this cast, however.
 361 </para>
 362 </answer>
 363
 364 </qandaentry>
 365
 366 <qandaentry>
 367 <question><para>
 368 How do I use GTK+ with other non-C languages?
 369 </para></question>
 370
 371 <answer>
 372 <para>
 373 See the <ulink url="http://www.gtk.org/bindings.html">list of language
 374 bindings</ulink> on <ulink
 375                            url="http://www.gtk.org">http://www.gtk.org</ulink>.
 376 </para>
 377
 378 </answer>
 379
 380 </qandaentry>
 381
 382 <qandaentry>
 383 <question><para>
 384 How do I load an image or animation from a file?
 385 </para></question>
 386
 387 <answer>
 388
 389 <para>
 390 To load an image file straight into a display widget, use <link
 391 linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
 392 <footnote><para> If the file load fails, <link
 393 linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
 394 will display a "broken image" graphic &mdash; to detect a failed load
 395 yourself, use <link
 396 linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
 397 directly then <link
 398 linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
 399 </para></footnote>. To load an image for another purpose, use <link
 400 linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
 401 To load an animation, use <link
 402 linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
 403 <link
 404 linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>
 405 can also load non-animated images, so use it in combination with
 406 <link
 407       linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type.
 408 </para>
 409 <para>
 410 To load an image or animation file asynchronously (without blocking), use
 411 <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.
 412 </para>
 413 </answer>
 414
 415 </qandaentry>
 416
 417 <qandaentry>
 418 <question><para>
 419 How do I draw text ?
 420 </para></question>
 421
 422 <answer>
 423 <para>
 424 To draw a piece of text, use a Pango layout and
 425 <link linkend="gdk-draw-layout">gdk_draw_layout()</link>,
 426 using code like the following:
 427 <informalexample>
 428 <programlisting>
 429  layout = gtk_widget_create_pango_layout (widget, text);
 430  fontdesc = pango_font_description_from_string ("Luxi Mono 12");
 431  pango_layout_set_font_description (layout, fontdesc);
 432  gdk_draw_layout (..., layout);
 433  pango_font_description_free (fontdesc);
 434  g_object_unref (layout);
 435 </programlisting>
 436 </informalexample>
 437 Do not use the deprecated <link linkend="GdkFont">GdkFont</link> and <link linkend="gdk-draw-text">gdk_draw_text()</link>.
 438 </para>
 439
 440 <para>
 441 See also the "Text Handling in GTK 2" section of
 442 <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications
 443 to the GNOME 2.0 platform</ulink>.
 444 </para>
 445 </answer>
 446
 447 </qandaentry>
 448
 449 <qandaentry>
 450 <question>
 451 <para>
 452 How do I measure the size of a piece of text ?
 453 </para>
 454 </question>
 455
 456 <answer>
 457 <para>
 458 To obtain the size of a piece of text, use a Pango layout and
 459 <link
 460                 linkend="pango-layout-get-pixel-size">pango_layout_get_pixel_size()</link>,
 461 using code like the following:
 462 <informalexample>
 463 <programlisting>
 464  layout = gtk_widget_create_pango_layout (widget, text);
 465  fontdesc = pango_font_description_from_string ("Luxi Mono 12");
 466  pango_layout_set_font_description (layout, fontdesc);
 467  pango_layout_get_pixel_size (layout, &amp;width, &amp;height);
 468  pango_font_description_free (fontdesc);
 469  g_object_unref (layout);
 470 </programlisting>
 471 </informalexample>
 472 Do not use the deprecated function <link linkend="gdk-text-width">gdk_text_width()</link>.
 473 </para>
 474
 475 <para>
 476 See also the "Text Handling in GTK 2" section of
 477 <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications
 478 to the GNOME 2.0 platform</ulink>.
 479 </para>
 480 </answer>
 481 </qandaentry>
 482
 483 <qandaentry>
 484 <question>
 485 <para>
 486 Why are types not registered if I use their <literal>GTK_TYPE_BLAH;</literal> macro ?
 487 </para>
 488 </question>
 489
 490 <answer>
 491 <para>
 492 The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
 493 <literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> functions
 494 are declared as <literal>G_GNUC_CONST</literal> which allows the compiler to optimize
 495 the call away if it appears that the value is not being used.
 496 </para>
 497
 498 <para>
 499 A common workaround for this problem is to store the result in a volatile variable,
 500 which keeps the compiler from optimizing the call away.
 501 <informalexample><programlisting>
 502 volatile GType dummy = GTK_TYPE_BLAH;
 503 </programlisting></informalexample>
 504 </para>
 505 </qandadiv>
 506
 507 <qandadiv><title>Which widget should I use...</title>
 508
 509 <qandaentry>
 510 <question><para>
 511 ...for lists and trees?
 512 </para></question>
 513
 514 <answer>
 515 <para>
 516 See <link linkend="TreeWidget">tree widget overview</link> &mdash; you
 517 should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
 518 (A list is just a tree with no branches, so the tree widget is used
 519 for lists as well.) Do not use the deprecated widgets <link
 520 linkend="GtkTree">GtkTree</link> or <link
 521 linkend="GtkCList">GtkCList</link>/<link
 522 linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
 523 less flexible and result in an inferior user interface.
 524 </para>
 525 </answer>
 526 </qandaentry>
 527
 528 <qandaentry>
 529 <question><para>
 530 ...for multi-line text display or editing?
 531 </para></question>
 532
 533 <answer>
 534 <para>
 535 See <link linkend="TextWidget">text widget overview</link> &mdash; you
 536 should use the <link linkend="GtkTextView">GtkTextView</link> widget.
 537 Do not use the deprecated widget <link
 538 linkend="GtkText">GtkText</link> in newly-written code, it has a
 539 number of problems that are best avoided.
 540 </para>
 541 <para>
 542 If you only have a small amount of text, <link
 543 linkend="GtkLabel">GtkLabel</link> may also be appropriate of course.
 544 It can be made selectable with <link linkend="gtk-label-set-selectable">
 545 gtk_label_set_selectable()</link>. For a single-line text entry,
 546 see <link linkend="GtkEntry">GtkEntry</link>.
 547 </para>
 548 </answer>
 549 </qandaentry>
 550
 551
 552 <qandaentry>
 553 <question><para>
 554 ...to display an image or animation?
 555 </para></question>
 556
 557 <answer>
 558 <para>
 559 <link linkend="GtkImage">GtkImage</link> can display images
 560 in just about any format GTK+ understands. You can also
 561 use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need
 562 to do something more complex, such as draw text or graphics over the
 563 top of the image.
 564 </para>
 565 </answer>
 566 </qandaentry>
 567
 568 <qandaentry>
 569 <question><para>
 570 ...for presenting a set of mutually-exclusive choices, where Windows
 571 would use a combo box?
 572 </para></question>
 573
 574 <answer>
 575 <para>
 576 With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
 577 recommended instead of a combo box, if the user is selecting from a
 578 fixed set of options. That is, non-editable combo boxes are not
 579 encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
 580 much easier to use than <link linkend="GtkCombo">GtkCombo</link>
 581 as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you
 582 need the editable text entry.
 583 </para>
 584 <para>
 585 (As a future enhancement to GTK+, a new widget to replace <link
 586 linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
 587 linkend="GtkCombo">GtkCombo</link> is planned.  This widget will be
 588 themeable to look like either a combo box or the current option menu,
 589 and will address some shortcomings in the <link
 590 linkend="GtkCombo">GtkCombo</link> API.  <ulink
 591 url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
 592 50554</ulink> tracks this issue, if you want to check status or post
 593 comments.)
 594 </para>
 595 </answer>
 596 </qandaentry>
 597
 598 </qandadiv>
 599
 600 <qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
 601
 602 <qandaentry>
 603 <question><para>
 604 How do I change the color of a widget?
 605 </para></question>
 606
 607 <answer><para>
 608 See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,
 609 <link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
 610 <link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
 611 and <link
 612 linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>.  See
 613 <link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
 614 discussion. You can also change widget color by installing a resource
 615 file and parsing it with <link
 616 linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
 617 The advantage of a resource file is that users can then override the
 618 color you've chosen.
 619 </para>
 620
 621 <para>To change the background color for widgets such as <link
 622 linkend="GtkLabel">GtkLabel</link> that have no background, place them
 623 in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
 624 background of the event box.
 625 </para></answer>
 626 </qandaentry>
 627
 628 <qandaentry>
 629 <question><para>
 630 How do I change the font of a widget?
 631 </para></question>
 632
 633 <answer><para>
 634 This has several possible answers, depending on what exactly you want to
 635 achieve. One option is <link
 636 linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link>. Note that this function can be used to change only the font size, as in the following example:
 637 <programlisting>
 638  PangoFontDesc *font_desc = pango_font_description_new ();
 639  pango_font_description_set_size (font_desc, 40);
 640  gtk_widget_modify_font (widget, font);
 641  pango_font_description_free (font_desc);
 642 </programlisting>
 643 </para>
 644 <para>
 645 If you want to make the text of a label larger, you can use <link
 646 linkend="gtk-label-set-markup">gtk_label_set_markup()</link>:
 647 <programlisting>
 648 gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;");
 649 </programlisting>
 650 This is preferred for many apps because it's a relative size to the
 651 user's chosen font size. See <link
 652 linkend="g-markup-escape-text">g_markup_escape_text()</link>
 653 if you are constructing such strings on the fly.
 654 </para>
 655 <para>
 656 You can also change the font of a widget by putting
 657 <programlisting>
 658  gtk-font-name = "Sans 30"
 659 </programlisting>
 660 in a resource file and parsing it with <link
 661 linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
 662 The advantage of a resource file is that users can then override the
 663 font you've chosen. See
 664 <link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
 665 discussion.
 666 </para>
 667 </answer>
 668 </qandaentry>
 669
 670 <qandaentry>
 671 <question><para>
 672 How do I disable/ghost/desensitize a widget?
 673 </para></question>
 674
 675 <answer><para> In GTK+ a disabled widget is termed "insensitive." See
 676 <link
 677 linkend="gtk-widget-set-sensitive">gtk_widget_set_sensitive()</link>.
 678 </para></answer>
 679 </qandaentry>
 680
 681 </qandadiv>
 682
 683
 684 <qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>
 685
 686 <qandaentry>
 687 <question><para>
 688 How do I get the contents of the entire text widget as a string?
 689 </para></question>
 690
 691 <answer><para>
 692
 693 See <link
 694           linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
 695           and <link
 696           linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
 697 or <link
 698           linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
 699 </para>
 700 <para>
 701 <informalexample><programlisting>
 702   GtkTextIter start, end;
 703   GtkTextBuffer *buffer;
 704   char *text;
 705
 706   buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
 707   gtk_text_buffer_get_bounds (buffer, &amp;start, &amp;end);
 708   text = gtk_text_iter_get_text (&amp;start, &amp;end);
 709   /* use text */
 710   g_free (text);
 711 </programlisting></informalexample>
 712 </para></answer>
 713 </qandaentry>
 714
 715 <qandaentry>
 716 <question><para>
 717 How do I make a text widget display its complete contents in a specific font?
 718 </para></question>
 719
 720 <answer><para>
 721 If you use <link
 722               linkend="gtk-text-buffer-insert-with-tags">gtk_text_buffer_insert_with_tags()</link> 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.
 723 </para>
 724 <para>
 725 To ensure that all text has the desired appearance, use <link
 726                 linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link> to change the default font for the widget.
 727 </para></answer>
 728 </qandaentry>
 729
 730 <qandaentry>
 731 <question>
 732 <para>
 733 How do I make a text view scroll to the end of the buffer automatically ?
 734 </para>
 735 </question>
 736
 737 <answer>
 738 <para>
 739 The "insert" <link linkend="GtkTextMark">mark</link> marks the insertion point
 740 where <link linkend="gtk-text-buffer-insert">gtk_text_buffer_insert()</link>
 741 inserts new text into the buffer. The text is inserted
 742 <emphasis>before</emphasis> the "insert" mark, so that it generally stays
 743 at the end of the buffer. If it gets explicitly moved to some other position,
 744 e.g. when the user selects some text,
 745 use <link linkend="gtk-text-buffer-move-mark">gtk_text_buffer_move_mark()</link>
 746 to set it to the desired location before inserting more text.
 747 The "insert" mark of a buffer can be obtained with <link
 748 linkend="gtk-text-buffer-get-insert">gtk_text_buffer_get_insert()</link>.
 749 </para>
 750
 751 <para>
 752 To ensure that the end of the buffer remains visible, use
 753 <link
 754                 linkend="gtk-text-view-scroll-to-mark">gtk_text_view_scroll_to_mark()</link> to scroll to the "insert" mark after inserting new text.
 755 </para>
 756 </answer>
 757 </qandaentry>
 758 </qandadiv>
 759
 760
 761
 762 <qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
 763
 764 <qandaentry>
 765 <question><para>
 766 How do I associate some data with a row in the tree?
 767 </para></question>
 768
 769 <answer>
 770 <para>
 771 Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
 772 columns don't necessarily have to be displayed. So you can put
 773 non-user-visible data in your model just like any other data, and
 774 retrieve it with <link
 775 linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
 776 See the <link linkend="TreeWidget">tree widget overview</link>.
 777 </para>
 778 </answer>
 779 </qandaentry>
 780
 781 <qandaentry>
 782 <question><para>
 783 What's the <link linkend="GtkTreeView">GtkTreeView</link> equivalent of
 784 <link linkend="gtk-clist-find-row-from-data">gtk_clist_find_row_from_data()</link>?
 785 </para></question>
 786
 787 <answer>
 788 <para>
 789 As there is no separate data column in the <link linkend="GtkTreeModel">GtkTreeModel</link>, there's no
 790 built in function to find the iter from data.  You can write a custom
 791 searching function to walk the tree and find the data, or use
 792 <link linkend="gtk-tree-model-foreach">gtk_tree_model_foreach()</link>.
 793 </para>
 794 </answer>
 795 </qandaentry>
 796
 797 <qandaentry>
 798 <question><para>
 799 How do I put an image and some text in the same column?
 800 </para></question>
 801
 802 <answer>
 803 <para>
 804 You can pack more than one <link
 805 linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
 806 <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
 807 <link
 808       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
 809 linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
 810 and a <link
 811 linkend="GtkCellRendererText">GtkCellRendererText</link> into the
 812 column.
 813 </para>
 814 </answer>
 815 </qandaentry>
 816
 817 <qandaentry>
 818 <question><para>
 819 I can set data easily on my <link
 820                 linkend="GtkTreeStore">GtkTreeStore</link>/<link
 821                 linkend="GtkListStore">GtkListStore</link> models using  <link
 822 linkend="gtk-tree-model-get">gtk_list_store_set()</link> and <link
 823 linkend="gtk-tree-model-get">gtk_tree_store_set()</link>, but can't read
 824               it back?
 825 </para></question>
 826
 827 <answer>
 828 <para>
 829 Both the <link
 830                 linkend="GtkTreeStore">GtkTreeStore</link> and the <link
 831                 linkend="GtkListStore">GtkListStore</link> implement the
 832               <link linkend="GtkTreeModel">GtkTreeModel</link>
 833                 interface.  Consequentially, the can use any function
 834                 this interface implements.  The easiest way to read a
 835                 set of data back is to use
 836  <link
 837 linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
 838 </para>
 839 </answer>
 840 </qandaentry>
 841
 842 <qandaentry>
 843 <question><para>
 844 How do I change the way that numbers are formatted by <link linkend="GtkTreeView">GtkTreeView</link>?
 845 </para></question>
 846 <answer><para>
 847 Use <link linkend="gtk-tree-view-insert-column-with-data-func">gtk_tree_view_insert_column_with_data_func()</link>
 848 or <link linkend="gtk-tree-view-column-set-cell-data-func">gtk_tree_view_column_set_cell_data_func()</link>
 849 and do the conversion from number to string yourself (with, say,
 850 <link linkend="g-strdup-printf">g_strdup_printf()</link>).
 851 </para>
 852
 853 <para>
 854 The following example demonstrates this:
 855 <informalexample><programlisting>
 856 enum
 857 {
 858   DOUBLE_COLUMN,
 859   N_COLUMNS
 860 };
 861
 862 GtkListStore *mycolumns;
 863 GtkTreeView *treeview;
 864
 865 void
 866 my_cell_double_to_text (GtkTreeViewColumn *tree_column,
 867                         GtkCellRenderer   *cell,
 868                         GtkTreeModel      *tree_model,
 869                         GtkTreeIter       *iter,
 870                         gpointer           data)
 871 {
 872   GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
 873   gdouble d;
 874   gchar *text;
 875
 876   /* Get the double value from the model. */
 877   gtk_tree_model_get (tree_model, iter, (gint)data, &amp;d, -1);
 878   /* Now we can format the value ourselves. */
 879   text = g_strdup_printf ("&percnt;.2f", d);
 880   g_object_set (cell, "text", text, NULL);
 881   g_free (text);
 882 }
 883
 884 void
 885 set_up_new_columns (GtkTreeView *myview)
 886 {
 887   GtkCellRendererText *renderer;
 888   GtkTreeViewColumn *column;
 889   GtkListStore *mycolumns;
 890
 891   /* Create the data model and associate it with the given TreeView */
 892   mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
 893   gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));
 894
 895   /* Create a GtkCellRendererText */
 896   renderer = gtk_cell_renderer_text_new ();
 897
 898   /* Create a new column that has a title ("Example column"),
 899    * uses the above created renderer that will render the double
 900    * value into text from the associated model's rows.
 901    */
 902   column = gtk_tree_view_column_new ();
 903   gtk_tree_view_column_set_title  (column, "Example column");
 904   renderer = gtk_cell_renderer_text_new ();
 905   gtk_tree_view_column_pack_start (column, renderer, TRUE);
 906
 907   /* Append the new column after the GtkTreeView's previous columns. */
 908   gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
 909   /* Since we created the column by hand, we can set it up for our
 910    * needs, e.g. set its minimum and maximum width, etc.
 911    */
 912   /* Set up a custom function that will be called when the column content
 913    * is rendered. We use the func_data pointer as an index into our
 914    * model. This is convenient when using multi column lists.
 915    */
 916   gtk_tree_view_column_set_cell_data_func (column, renderer,
 917                                            my_cell_double_to_text,
 918                                            (gpointer)DOUBLE_COLUMN, NULL);
 919 }
 920 </programlisting></informalexample>
 921 </para></answer>
 922 </qandaentry>
 923
 924 </qandadiv>
 925
 926
 927
 928 </qandaset>
 929
 930 </refsect1>
 931
 932 </refentry>