question_index.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

<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> 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.
<informalexample><programlisting>
volatile GType dummy = GTK_TYPE_BLAH;
</programlisting></informalexample>
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
How do I create a transparent toplevel window ?
</para>
</question>

<answer>
<para>
To make a window transparent, it needs to use a visual which supports that.
This is done by getting the RGBA colormap of the screen with 
gdk_screen_get_rgba_colormap() and setting it on the window. Note that
gdk_screen_get_rgba_colormap() will return %NULL if transparent windows
are not supported on the screen; also note that this may change from
screen to screen, so it needs to be repeated whenever the window is moved
to a different screen.
<informalexample><programlisting>
GdkColormap *colormap;

colormap = gdk_screen_get_rgba_colormap (screen);
if (!colormap)
  colormap = gtk_screen_get_rgb_colormap (screen);

gtk_widget_set_colormap (widget, colormap);
</programlisting></informalexample>
One possibility to fill the alpha channel on the window is to use
gdk_draw_rgb_32_image().
</para>
<para>
Note that the presence of an RGBA visual is no guarantee that the
window will actually appear transparent on screen. On X11, this 
requires a compositing manager to be running. See 
gtk_widget_is_composited() for a way to find out if the alpha
channel will be respected.
</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 #GtkTreeView 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 #GtkTree or #GtkCList/#GtkCTree 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 #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.
</para>
</answer>
</qandaentry>


<qandaentry>
<question><para>
...to display an image or animation?
</para></question>

<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.
</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 #GtkComboBox is the recommended widget to use for this use case.
This widget looks like either a combo box or the current option menu, depending
on the current theme. If you need an editable text entry, use #GtkComboBoxEntry.
</para>
</answer>
</qandaentry>

</qandadiv>

<qandadiv><title>#GtkWidget</title>

<qandaentry>
<question><para>
How do I change the color of a widget?
</para></question>

<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().
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></answer>
</qandaentry>

<qandaentry>
<question><para>
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:
<programlisting>
 PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
 pango_font_description_set_size (font_desc, 40);
 gtk_widget_modify_font (widget, font);
 pango_font_description_free (font_desc);
</programlisting>
</para>
<para>
If you want to make the text of a label larger, you can use 
gtk_label_set_markup():
<programlisting>
gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;");
</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.
</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
have chosen. See <link linkend="gtk-Resource-Files">GTK+ resource files</link> 
for more discussion. 
</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
gtk_widget_set_sensitive().
</para></answer>
</qandaentry>

</qandadiv>


<qandadiv><title>#GtkTextView</title>

<qandaentry>
<question><para>
How do I get the contents of the entire text widget as a string?
</para></question>

<answer><para>
See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
or gtk_text_iter_get_text().
</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, &amp;start, &amp;end);
  text = gtk_text_iter_get_text (&amp;start, &amp;end);
  /* use text */
  g_free (text);
</programlisting></informalexample>
</para></answer>
</qandaentry>

<qandaentry>
<question><para>
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. 
</para>
<para>
To ensure that all text has the desired appearance, use gtk_widget_modify_font() 
to change the default font for the widget.
</para></answer>
</qandaentry>

<qandaentry>
<question>
<para>
How do I make a text view scroll to the end of the buffer automatically ?
</para>
</question>

<answer>
<para>
A good way to keep a text buffer scrolled to the end is to place a
<link linkend="GtkTextMark">mark</link> at the end of the buffer, and
give it right gravity. The gravity has the effect that text inserted
at the mark gets inserted <emphasis>before</emphasis>, keeping the mark
at the end. 
</para>

<para> 
To ensure that the end of the buffer remains visible, use
gtk_text_view_scroll_to_mark() to scroll to the mark after
inserting new text.
</para>

<para>
The gtk-demo application contains an example of this technique. 
</para>
</answer>
</qandaentry>
</qandadiv>



<qandadiv><title>#GtkTreeView</title>

<qandaentry>
<question><para>
How do I associate some data with a row in the tree?
</para></question>

<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 
<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 #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>

<qandaentry>
<question><para>
I can set data easily on my #GtkTreeStore/#GtkListStore models using 
gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
</para></question>

<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().
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
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 i
number to string yourself (with, say, g_strdup_printf()).
</para>

<para>
The following example demonstrates this:
<informalexample><programlisting>
enum 
{
  DOUBLE_COLUMN,
  N_COLUMNS
};

GtkListStore *mycolumns;
GtkTreeView *treeview;

void 
my_cell_double_to_text (GtkTreeViewColumn *tree_column,
	                GtkCellRenderer   *cell, 
                        GtkTreeModel      *tree_model,
	                GtkTreeIter       *iter, 
                        gpointer           data)
{
  GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
  gdouble d;
  gchar *text;

  /* Get the double value from the model. */
  gtk_tree_model_get (tree_model, iter, (gint)data, &amp;d, -1);
  /* Now we can format the value ourselves. */
  text = g_strdup_printf ("&percnt;.2f", d);
  g_object_set (cell, "text", text, NULL);
  g_free (text);
}

void 
set_up_new_columns (GtkTreeView *myview)
{
  GtkCellRendererText *renderer;
  GtkTreeViewColumn *column;
  GtkListStore *mycolumns;

  /* Create the data model and associate it with the given TreeView */
  mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
  gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));

  /* Create a GtkCellRendererText */
  renderer = gtk_cell_renderer_text_new (<!-- -->);

  /* Create a new column that has a title ("Example column"),
   * uses the above created renderer that will render the double
   * value into text from the associated model's rows. 
   */
  column = gtk_tree_view_column_new (<!-- -->);
  gtk_tree_view_column_set_title  (column, "Example column");
  renderer = gtk_cell_renderer_text_new (<!-- -->);
  gtk_tree_view_column_pack_start (column, renderer, TRUE);

  /* Append the new column after the GtkTreeView's previous columns. */
  gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
  /* Since we created the column by hand, we can set it up for our
   * needs, e.g. set its minimum and maximum width, etc.
   */
  /* Set up a custom function that will be called when the column content
   * is rendered. We use the func_data pointer as an index into our
   * model. This is convenient when using multi column lists. 
   */
  gtk_tree_view_column_set_cell_data_func (column, renderer,
	                                   my_cell_double_to_text, 
                                           (gpointer)DOUBLE_COLUMN, NULL);
}
</programlisting></informalexample>
</para></answer>
</qandaentry>

<qandaentry>
<question><para>
How do I hide the expander arrows in my tree view ?
</para></question>

<answer><para>
Set the expander-column property of the tree view to a hidden column.
See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
</para></answer>
</qandaentry>

</qandadiv>

<qandadiv><title>Using cairo with GTK+</title>

<qandaentry>
<question><para>
How do I use cairo to draw in GTK+ applications ?
</para></question>

<answer><para>
USe gdk_cairo_create() to obtain a cairo context for drawing
on a GDK window or pixmap. See <link linkend="gdk-Cairo-Interaction">Cairo 
Interaction</link> for some more useful functions.
</para></answer>
</qandaentry>

<qandaentry>
<question><para>
I have created a cairo context with gdk_cairo_create(), but when I
later use it, my drawing does not show up. Why is that ?
</para></question>

<answer>
<para>
All drawing in GTK+ is normally done in an expose handler, and GTK+
creates a temporary pixmap for double-buffering the drawing. If you 
create a cairo context outside the expose handler, it is backed
by the GDK window itself, not the double-buffering pixmap. Consequently,
any drawing you do with that cairo context gets overwritten at the 
end of the expose handler, when the double-buffering pixmap is copied
back.
</para>
<para>
Possible solutions to this problem are:
<itemizedlist>
<listitem><para>
Turn off double-buffering, with gtk_widget_set_double_buffered().
This is not ideal, since it can cause some flickering.
</para></listitem>
<listitem><para>
Create the cairo context inside the expose handler. If you do this,
gdk_create_cairo() arranges for it to be backed by the double-buffering 
pixmap. This is the preferred solution, and is used throughout GTK+
itself.
</para></listitem>
</itemizedlist>
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
Can I improve the performance of my application by using the
Glitz backend of cairo ?
</para></question>

<answer><para>
No. The GDK X11 backend uses the cairo X backend (and the other
GDK backends use their respective native cairo backends). The
GTK+ developers believe that the best way to improving the GDK
drawing performance is to optimize the cairo X backend and the
relevant code paths in the X server that is uses (mostly the
Render extension).
</para></answer>
</qandaentry>

<qandaentry>
<question><para>
Can I use cairo to draw on a #GdkPixbuf ?
</para></question>

<answer><para>
No, at least not yet. The cairo image surface does not support the
pixel format used by GdkPixbuf. 
</para></answer>
</qandaentry>

</qandadiv>

</qandaset>

</refsect1>

</refentry>