AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2025-01-12 05:20:17 +00:00
Code Issues Projects Releases Wiki Activity

docs: Convert question index to markdown

Browse Source 
With this, the expand_content_files list has been
completely converted to markdown files. Whats left
in content_files is man pages, and a few special
cases.
This commit is contained in:
Matthias Clasen 2020-05-24 14:25:25 -04:00
parent 84437ee0e0
commit aca8090a09
4 changed files with 559 additions and 980 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/gtk/gtk4-docs.xml
View File

@ -23,7 +23,7 @@
<xi:include href="overview.xml"/>
<xi:include href="getting_started.xml"/>
<xi:include href="resources.xml" />
<xi:include href="xml/question_index.xml" />
<xi:include href="question_index.xml" />
</part>
<part id="concepts">

7
docs/reference/gtk/meson.build
View File

@ -351,14 +351,9 @@ content_files = [
'gtk4-update-icon-cache.xml',
'gtk4-widget-factory.xml',
'overview.xml',
'question_index.xml',
'visual_index.xml',
]
expand_content_files = [
'question_index.xml',
]
expand_content_md_files = [
'broadway.md',
'osx.md',
@ -379,6 +374,7 @@ expand_content_md_files = [
'css-properties.md',
'section-text-widget.md',
'section-tree-widget.md',
'question_index.md',
]
types_conf = configuration_data()
@ -438,7 +434,6 @@ if get_option('gtk_doc')
'--extra-dir=../gsk',
],
content_files: content_files + expand_md_targets,
expand_content_files: expand_content_files,
html_assets: images,
install: true)
endif

557
docs/reference/gtk/question_index.md Normal file
View File

@ -0,0 +1,557 @@
# Common Questions {#gtk-question-index}
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.
## General Questions
1. How do I get started with GTK?
The GTK [website](https://www.gtk.org) offers some
[tutorials](https://www.gtk.org/documentation.php) and other documentation
(most of it about GTK 2.x and 3.x, but still somewhat applicable). This
reference manual also contains a introductory
[Getting Started](#gtk-getting-started) part.
More documentation ranging from whitepapers to online books can be found at
the [GNOME developer's site](https://developer.gnome.org). After studying these
materials you should be well prepared to come back to this reference manual for details.
2. Where can I get help with GTK, submit a bug report, or make a feature request?
See the [documentation](#gtk-resources) on this topic.
3. How do I port from one GTK version to another?
See the [migration guide](#migrating). You may also find useful information in
the documentation for specific widgets and functions. If you have a question not
covered in the manual, feel free to ask, and please
[file a bug report](https://gitlab.gnome.org/GNOME/gtk/issues/new) against the
documentation.
4. How does memory management work in GTK? Should I free data returned from functions?
See the documentation for #GObject and #GInitiallyUnowned. For #GObject note
specifically g_object_ref() and g_object_unref(). #GInitiallyUnowned is a
subclass of #GObject so the same points apply, except that it has a "floating"
state (explained in its documentation).
For strings returned from functions, they will be declared "const" if they should
not be freed. Non-const strings should be freed with g_free(). Arrays follow the
same rule. If you find an undocumented exception to the rules, please
[file a bug report.](https://gitlab.gnome.org/GNOME/gtk/issues/new).
The transfer annotations for gobject-introspection that are part of the
documentation can provide useful hints for memory handling semantics as well.
5. Why does my program leak memory, if I destroy a widget immediately
after creating it ?
If `GtkFooi` isn't a toplevel window, then
foo = gtk_foo_new ();
g_object_unref (foo);
is a memory leak, because no one assumed the initial floating reference
(you will get a warning about this too). If you are using a widget and
you aren't immediately packing it into a container, then you probably
want standard reference counting, not floating reference counting.
To get this, you must acquire a reference to the widget and drop the
floating reference (_ref and sink_ in GObject parlance) after creating it:
foo = gtk_foo_new ();
g_object_ref_sink (foo);
When you immediately add a widget to a container, it takes care of assuming
the initial floating reference and you don't have to worry about reference
counting at all ... just remove the widget from the container to get rid of it.
6. How do I use GTK with threads?
GTK requires that all GTK API calls are made from the same thread in which
gtk_init() was called (the _main thread_).
If you want to take advantage of multi-threading in a GTK application,
it is usually best to send long-running tasks to worker threads, and feed
the results back to the main thread using g_idle_add() or GAsyncQueue. GIO
offers useful tools for such an approach such as GTask.
7. How do I internationalize a GTK program?
Most people use <[GNU gettext](https://www.gnu.org/software/gettext/),
already required in order to install GLib. On a UNIX or Linux system with
gettext installed, type `info gettext` to read the documentation.
The short checklist on how to use gettext is: call bindtextdomain() so
gettext can find the files containing your translations, call textdomain()
to set the default translation domain, call bind_textdomain_codeset() to
request that all translated strings are returned in UTF-8, then call
gettext() to look up each string to be translated in the default domain.
`gi18n.h` provides the following shorthand macros for convenience.
Conventionally, people define macros as follows for convenience:
#define _(x) gettext (x)
#define N_(x) x
#define C_(ctx,x) pgettext (ctx, x)
You use N_() (N stands for no-op) to mark a string for translation in
a location where a function call to gettext() is not allowed, such as
in an array initializer. You eventually have to call gettext() on the
string to actually fetch the translation. _() both marks the string for
translation and actually translates it. The C_() macro (C stands for
context) adds an additional context to the string that is marked for
translation, which can help to disambiguate short strings that might
need different translations in different parts of your program.
Code using these macros ends up looking like this:
#include &lt;gi18n.h&gt;
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));
...
Libraries using gettext should use dgettext() instead of gettext(),
which allows them to specify the translation domain each time they
ask for a translation. Libraries should also avoid calling textdomain(),
since they will be specifying the domain instead of using the default.
With the convention that the macro `GETTEXT_PACKAGE` is defined to hold
your libraries translation domain, `gi18n-lib.h` can be included to provide
the following convenience:
#define _(x) dgettext (GETTEXT_PACKAGE, x)
8. How do I use non-ASCII characters in GTK programs ?
GTK uses [Unicode](http://www.unicode.org) (more exactly UTF-8) for all text.
UTF-8 encodes each Unicode codepoint as a sequence of one to six bytes and
has a number of nice properties which make it a good choice for working with
Unicode text in C programs:
- ASCII characters are encoded by their familiar ASCII codepoints.
- ASCII characters never appear as part of any other character.
- The zero byte doesn't occur as part of a character, so that UTF-8
string can be manipulated with the usual C library functions for
handling zero-terminated strings.
More information about Unicode and UTF-8 can be found in the
[UTF-8 and Unicode FAQ](https://www.cl.cam.ac.uk/~mgk25/unicode.html).
GLib provides functions for converting strings between UTF-8 and other
encodings, see g_locale_to_utf8() and g_convert().
Text coming from external sources (e.g. files or user input), has to be
converted to UTF-8 before being handed over to GTK. The following example
writes the content of a IS0-8859-1 encoded text file to `stdout`:
char *text, *utf8_text;
gsize length;
GError *error = NULL;
if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
{
utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
NULL, NULL, &amp;error);
if (error != NULL)
{
fprintf ("Couldn't convert file %s to UTF-8\n", filename);
g_error_free (error);
}
else
g_print (utf8_text);
}
else
fprintf (stderr, "Unable to read file %s\n", filename);
For string literals in the source code, there are several alternatives
for handling non-ASCII content:
- Direct UTF-8
If your editor and compiler are capable of handling UTF-8 encoded
sources, it is very convenient to simply use UTF-8 for string literals,
since it allows you to edit the strings in "wysiwyg". Note that choosing
this option may reduce the portability of your code.
- Escaped UTF-8
Even if your toolchain can't handle UTF-8 directly, you can still
encode string literals in UTF-8 by using octal or hexadecimal escapes
like `\\212` or `\\xa8` to encode each byte. This is portable, but
modifying the escaped strings is not very convenient. Be careful when
mixing hexadecimal escapes with ordinary text; `"\\xa8abcd" is a string
of length 1 !
- Runtime conversion
If the string literals can be represented in an encoding which your
toolchain can handle (e.g. IS0-8859-1), you can write your source
files in that encoding and use g_convert() to convert the strings
to UTF-8 at runtime. Note that this has some runtime overhead, so
you may want to move the conversion out of inner loops.
Here is an example showing the three approaches using the copyright
sign © which has Unicode and ISO-8859-1 codepoint 169 and is represented
in UTF-8 by the two bytes 194, 169, or `"\\302\\251"` as a string literal:
g_print ("direct UTF-8: ©");
g_print ("escaped UTF-8: \302\251");
text = g_convert ("runtime conversion: ©", -1,
"ISO-8859-1", "UTF-8", NULL, NULL, NULL);
g_print (text);
g_free (text);
If you are using gettext() to localize your application, you need
to call bind_textdomain_codeset() to ensure that translated strings
are returned in UTF-8 encoding.
9. How do I use GTK with C++?
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
[gtkmm](https://www.gtkmm.org/) which provides a native C++ API.
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.
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:
gdk_surface_set_events (gdk_surface,
GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
while in C++ you must write:
gdk_surface_set_events (gdk_surface,
(GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
There are very few functions that require this cast, however.
10. How do I use GTK with other non-C languages?
See the list of [language bindings](https://www.gtk.org/language-bindings.php)
on the GTK [website](https://www.gtk.org).
11. How do I load an image or animation from a file?
To load an image file straight into a display widget, use
gtk_image_new_from_file(). To load an image for another purpose, use
gdk_texture_new_from_file(). To load a video from a file, use
gtk_media_file_new_for_file().
12. How do I draw text?
To draw a piece of text onto a cairo surface, use a Pango layout and
pango_cairo_show_layout().
layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
pango_layout_set_font_description (layout, fontdesc);
pango_cairo_show_layout (cr, layout);
pango_font_description_free (fontdesc);
g_object_unref (layout);
See also the [Cairo Rendering](https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html)
section of the [Pango documentation](https://developer.gnome.org/pango/stable/).
To draw a piece of text in a widget snapshot() implementation, use
gtk_snapshot_append_layout().
13. How do I measure the size of a piece of text?
To obtain the size of a piece of text, use a Pango layout and
pango_layout_get_pixel_size(), using code like the following:
layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
pango_layout_set_font_description (layout, fontdesc);
pango_layout_get_pixel_size (layout, &amp;width, &amp;height);
pango_font_description_free (fontdesc);
g_object_unref (layout);
See also the [Layout Objects](https://developer.gnome.org/pango/stable/pango-Layout-Objects.html)
section of the [Pango documentation](https://developer.gnome.org/pango/stable/).
14. Why are types not registered if I use their `GTK_TYPE_BLAH` macro?
The %GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and
the `_get_type()` 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.
GLib provides the g_type_ensure() function to work around this problem.
g_type_ensure (GTK_TYPE_BLAH);
15. How do I create a transparent toplevel window?
Any toplevel window can be transparent. It is just a matter of setting a
transparent background in the CSS style for it.
## Which widget should I use...
16. ...for lists and trees?
This question has different answers, depending on the size of the dataset
and the required formatting flexibility.
If you want to display a large amount of data in a uniform way, your best
option is a #GtkTreeView widget. See the [tree widget overview](#TreeWidget).
A list is just a tree with no branches, so the treeview widget is used for
lists as well.
If you want to display a small amount of items, but need flexible formatting
and widgetry inside the list, then you probably want to use a #GtkListBox,
which uses regular widgets for display.
17. ...for multi-line text display or editing?
See the [text widget overview](#TextWidget) -- you should use the
#GtkTextView widget.
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.
18. ...to display an image or animation?
GTK has two widgets that are dedicated to displaying images. #GtkImage, for
small, fixed-size icons and #GtkPicture for content images.
Both 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.
Both GtkImage and GtkPicture can display animations and videos as well.
To show an webm file, load it with the GtkMediaFile API and then use
it as a paintable:
mediafile = gtk_media_file_new_for_filename ("example.webm");
picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile));
19. ...for presenting a set of mutually-exclusive choices, where Windows
would use a combo box?
With GTK, a #GtkComboBox is the recommended widget to use for this use case.
If you need an editable text entry, use the #GtkComboBox:has-entry property.
## Questions about GtkWidget
20. How do I change the color of a widget?
The background color of a widget is determined by the CSS style that applies
to it. To change that, you can set style classes on the widget, and provide
custom CSS to change the appearance. Such CSS can be loaded with
gtk_css_provider_load_from_file() and its variants.
See gtk_style_context_add_provider().
21. How do I change the font of a widget?
If you want to make the text of a label larger, you can use
gtk_label_set_markup():
gtk_label_set_markup (label, "<big>big tex</big>");
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.
You can also change the font of a widget by putting
.my-widget-class {
font: Sans 30;
}
in a CSS file, loading it with gtk_css_provider_load_from_file(), and
adding the provider with gtk_style_context_add_provider_for_display().
To associate this style information with your widget, set a style class
on its #GtkStyleContext using gtk_style_context_add_class(). The advantage
of this approach is that users can then override the font you have chosen.
See the #GtkStyleContext documentation for more discussion.
22. How do I disable/ghost/desensitize a widget?
In GTK a disabled widget is termed _insensitive_.
See gtk_widget_set_sensitive().
## GtkTextView questions
23. How do I get the contents of the entire text widget as a string?
See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
or gtk_text_iter_get_text().
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);
24. How do I make a text widget display its complete contents in a specific font?
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.
To ensure that all text has the desired appearance, use
gtk_widget_override_font() to change the default font for the widget.
25. How do I make a text view scroll to the end of the buffer automatically ?
A good way to keep a text buffer scrolled to the end is to place a
[mark](#GtkTextMark) at the end of the buffer, and give it right gravity.
The gravity has the effect that text inserted at the mark gets inserted
*before*, keeping the mark at the end.
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.
The gtk-demo application contains an example of this technique.
## GtkTreeView questions
26. How do I associate some data with a row in the tree?
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 [tree widget overview](#TreeWidget).
27. How do I put an image and some text in the same column?
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.
28. 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?
Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
interface. Consequentially, you can use any function this interface
implements. The easiest way to read a set of data back is to use
gtk_tree_model_get().
29. How do I change the way that numbers are formatted by #GtkTreeView?
Use gtk_tree_view_insert_column_with_data_func() or
gtk_tree_view_column_set_cell_data_func() and do the conversion
from number to string yourself (with, say, g_strdup_printf()).
The following example demonstrates this:
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;
double d;
char *text;
/* Get the double value from the model. */
gtk_tree_model_get (tree_model, iter, (int)data, &d, -1);
/* Now we can format the value ourselves. */
text = g_strdup_printf ("%.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);
}
30. How do I hide the expander arrows in my tree view?
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().
## Using cairo with GTK
31. How do I use cairo to draw in GTK applications?
Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc
to obtain a cairo context and draw with that.
32. Can I improve the performance of my application by using another backend
of cairo (such as GL)?
No. Most drawing in GTK is not done via cairo anymore (but instead
by the GL or Vulkan renderers of GSK).
If you use cairo for drawing your own widgets, gtk_snapshot_append_cairo()
will choose the most appropriate surface type for you.
If you are interested in using GL for your own drawing, see #GtkGLArea.
33. Can I use cairo to draw on a #GdkPixbuf?
No. The cairo image surface does not support the pixel format used by GdkPixbuf.
If you need to get cairo drawing into a format that can be displayed efficiently
by GTK, you may want to use an image surface and gdk_memory_texture_new().

973
docs/reference/gtk/question_index.xml
View File

@ -1,973 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<refentry id="gtk-question-index">
<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>
How do I get started with GTK?
</para></question>
<answer><para>
The GTK <ulink url="https://www.gtk.org">website</ulink> offers some
<ulink url="https://www.gtk.org/documentation.php">tutorials</ulink> and other
documentation (most of it about GTK 2.x, but still somewhat applicable). This
reference manual also contains a introductory
<link linkend="gtk-getting-started">Getting Started</link> part.</para>
<para>More documentation ranging from whitepapers to online books can be found at
the <ulink url="https://developer.gnome.org">GNOME developer's site</ulink>.
After studying these materials you should be well prepared to come back to
this reference manual for details.
</para></answer>
</qandaentry>
<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 <xref linkend="migrating"/>.
You may also find useful information in the documentation for specific widgets
and functions. If you have a question not covered in the manual, feel free to
ask, and please <ulink
url="https://gitlab.gnome.org/GNOME/gtk/issues/new">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 #GObject and #GInitiallyUnowned. For #GObject note
specifically g_object_ref() and g_object_unref(). #GInitiallyUnowned is a
subclass of #GObject 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"
if they should not be freed. Non-const strings should be
freed with g_free(). Arrays follow the same rule. If you find an
undocumented exception to the rules, please
<ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>.
</para>
<para>
The transfer annotations for gobject-introspection that are part of the
documentation can provide useful hints for memory handling semantics as well.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Why does my program leak memory, if I destroy a widget immediately
after creating it ?
</para>
</question>
<answer>
<para>
If <structname>GtkFoo</structname> isn't a toplevel window, then
<informalexample><programlisting>
foo = gtk_foo_new ();
g_object_unref (foo);
</programlisting></informalexample>
is a memory leak, because no one assumed the initial floating reference
(you will get a warning about this too). If you are using a widget and
you aren't immediately packing it into a container, then you probably
want standard reference counting, not floating reference counting.
</para>
<para>
To get this, you must acquire a reference to the widget and drop the
floating reference (<quote>ref and sink</quote> in GObject parlance) after
creating it:
<informalexample><programlisting>
foo = gtk_foo_new ();
g_object_ref_sink (foo);
</programlisting></informalexample>
When you immediately add a widget to a container, it takes care of assuming
the initial floating reference and you don't have to worry about reference
counting at all ... just remove the widget from the container to get rid of it.
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
How do I use GTK with threads?
</para></question>
<answer>
<para>
GTK requires that all GTK API calls are made from the same thread in which
gtk_init() was called (the <quote>main thread</quote>).</para>
<para>If you want to take advantage of multi-threading in a GTK application,
it is usually best to send long-running tasks to worker threads, and feed
the results back to the main thread using g_idle_add() or GAsyncQueue. GIO
offers useful tools for such an approach such as GTask.
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
How do I internationalize a GTK program?
</para></question>
<answer>
<para>
Most people use <ulink url="https://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 bindtextdomain() so
gettext can find the files containing your translations, call textdomain()
to set the default translation domain, call bind_textdomain_codeset() to
request that all translated strings are returned in UTF-8, then call
gettext() to look up each string to be translated in the default domain.
</para>
<para>
<filename>gi18n.h</filename> provides the following shorthand macros for
convenience.
Conventionally, people define macros as follows for convenience:
<informalexample>
<programlisting>
#define _(x) gettext (x)
#define N_(x) x
#define C_(ctx,x) pgettext (ctx, x)
</programlisting>
</informalexample>
You use N_() (N stands for no-op) to mark a string for translation in
a location where a function call to gettext() is not allowed, such as
in an array initializer.
You eventually have to call gettext() on the string to actually fetch
the translation. _() both marks the string for translation and actually
translates it.
The C_() macro (C stands for context) adds an additional context to
the string that is marked for translation, which can help to disambiguate
short strings that might need different translations in different
parts of your program.
</para>
<para>
Code using these macros ends up looking like this:
<informalexample>
<programlisting>
#include &lt;gi18n.h&gt;
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 dgettext() instead of gettext(), which
allows them to specify the translation domain each time they ask for a
translation. Libraries should also avoid calling textdomain(), since
they will be specifying the domain instead of using the default.
</para>
<para>
With the convention that the macro <literal>GETTEXT_PACKAGE</literal> is
defined to hold your libraries translation domain,
<filename>gi18n-lib.h</filename> can be included to provide
the following convenience:
<informalexample>
<programlisting>
#define _(x) dgettext (GETTEXT_PACKAGE, x)
</programlisting>
</informalexample>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I use non-ASCII characters in GTK programs ?
</para>
</question>
<answer>
<para>
GTK uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of
one to six bytes and has a number of nice properties which make it a good
choice for working with Unicode text in C programs:
<itemizedlist>
<listitem><para>
ASCII characters are encoded by their familiar ASCII codepoints.
</para></listitem>
<listitem><para>
ASCII characters never appear as part of any other character.
</para></listitem>
<listitem><para>
The zero byte doesn't occur as part of a character, so that UTF-8 strings
can be manipulated with the usual C library functions for handling
zero-terminated strings.
</para></listitem>
</itemizedlist>
More information about Unicode and UTF-8 can be found in the
<ulink url="https://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode
FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other
encodings, see g_locale_to_utf8() and g_convert().
</para>
<para>
Text coming from external sources (e.g. files or user input), has to be
converted to UTF-8 before being handed over to GTK. The following example
writes the content of a IS0-8859-1 encoded text file to
<literal>stdout</literal>:
<informalexample><programlisting>
gchar *text, *utf8_text;
gsize length;
GError *error = NULL;
if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
{
utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
NULL, NULL, &amp;error);
if (error != NULL)
{
fprintf ("Couldn't convert file &percnt;s to UTF-8\n", filename);
g_error_free (error);
}
else
g_print (utf8_text);
}
else
fprintf (stderr, "Unable to read file &percnt;s\n", filename);
</programlisting></informalexample>
</para>
<para>
For string literals in the source code, there are several alternatives for
handling non-ASCII content:
<variablelist>
<varlistentry><term>direct UTF-8</term>
<listitem><para>
If your editor and compiler are capable of handling UTF-8 encoded sources,
it is very convenient to simply use UTF-8 for string literals, since it
allows you to edit the strings in "wysiwyg". Note that choosing this option
may reduce the portability of your code.
</para></listitem>
</varlistentry>
<varlistentry><term>escaped UTF-8</term>
<listitem><para>
Even if your toolchain can't handle UTF-8 directly, you can still encode
string literals in UTF-8 by using octal or hexadecimal escapes like
<literal>\212</literal> or <literal>\xa8</literal> to encode each byte.
This is portable, but modifying the escaped strings is not very convenient.
Be careful when mixing hexadecimal escapes with ordinary text;
<literal>"\xa8abcd"</literal> is a string of length 1 !
</para></listitem>
</varlistentry>
<varlistentry><term>runtime conversion</term>
<listitem><para>
If the string literals can be represented in an encoding which your
toolchain can handle (e.g. IS0-8859-1), you can write your source files
in that encoding and use g_convert() to convert the strings to UTF-8 at
runtime. Note that this has some runtime overhead, so you may want to move
the conversion out of inner loops.
</para></listitem>
</varlistentry>
</variablelist>
Here is an example showing the three approaches using the copyright sign
&copy; which has Unicode and ISO-8859-1 codepoint 169 and is represented
in UTF-8 by the two bytes 194, 169, or <literal>"\302\251"</literal> as
a string literal:
<informalexample><programlisting>
g_print ("direct UTF-8: &copy;");
g_print ("escaped UTF-8: \302\251");
text = g_convert ("runtime conversion: &copy;", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
g_print(text);
g_free (text);
</programlisting></informalexample>
</para>
<para>
If you are using gettext() to localize your application, you need to
call bind_textdomain_codeset() to ensure that translated strings are
returned in UTF-8 encoding.
</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="https://www.gtkmm.org/">gtkmm</ulink>
which provides a native C++ 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_surface_set_events (gdk_surface,
GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</programlisting>
</informalexample>
while in C++ you must write:
<informalexample>
<programlisting>
gdk_surface_set_events (gdk_surface,
(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="https://www.gtk.org/language-bindings.php">list of language
bindings</ulink> on <ulink
url="https://www.gtk.org">https://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
gtk_image_new_from_file(). To load an image for another purpose, use
gdk_texture_new_from_file(). To load a video from a file, use
gtk_media_file_new_for_file().
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
How do I draw text ?
</para></question>
<answer>
<para>
To draw a piece of text onto a cairo surface, use a Pango layout and
pango_cairo_show_layout().
<informalexample>
<programlisting>
layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
pango_layout_set_font_description (layout, fontdesc);
pango_cairo_show_layout (cr, layout);
pango_font_description_free (fontdesc);
g_object_unref (layout);
</programlisting>
</informalexample>
</para>
<para>
See also the
<ulink url="https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html">Cairo Rendering</ulink>
section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
</para>
<para>
To draw a piece of text in a widget snapshot() implementation, use
gtk_snapshot_append_layout().
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I measure the size of a piece of text ?
</para>
</question>
<answer>
<para>
To obtain the size of a piece of text, use a Pango layout and
pango_layout_get_pixel_size(), using code like the following:
<informalexample>
<programlisting>
layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
pango_layout_set_font_description (layout, fontdesc);
pango_layout_get_pixel_size (layout, &amp;width, &amp;height);
pango_font_description_free (fontdesc);
g_object_unref (layout);
</programlisting>
</informalexample>
</para>
<para>
See also the
<ulink url="https://developer.gnome.org/pango/stable/pango-Layout-Objects.html">Layout Objects</ulink>
section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
macro ?
</para>
</question>
<answer>
<para>
The %GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and
the _get_type(<!-- -->) 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>
GLib provides the g_type_ensure() function to work around this problem.
<informalexample><programlisting>
g_type_ensure (GTK_TYPE_BLAH);
</programlisting></informalexample>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I create a transparent toplevel window ?
</para>
</question>
<answer>
<para>
Any toplevel window can be transparent.
It is just a matter of setting a transparent background
in the CSS style for it.
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv><title>Which widget should I use...</title>
<qandaentry>
<question><para>
...for lists and trees?
</para></question>
<answer>
<para>
This question has different answers, depending on the size of the dataset
and the required formatting flexibility.
</para>
<para>
If you want to display a large amount of data in a uniform way, your
best option is a #GtkTreeView widget. See <link linkend="TreeWidget">tree
widget overview</link>. A list is just a tree with no branches, so the treeview
widget is used for lists as well.
</para>
<para>
If you want to display a small amount of items, but need flexible formatting
and widgetry inside the list, then you probably want to use a #GtkListBox,
which uses regular widgets for display.
</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.
</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>
GTK has two widgets that are dedicated to displaying images. #GtkImage, for
small, fixed-size icons and #GtkPicture for content images.
</para>
<para>
Both 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>
<para>
Both GtkImage and GtkPicture can display animations and videos as well.
To show an webm file, load it with the GtkMediaFile API and then use
it as a paintable:
<informalexample>
<programlisting>
mediafile = gtk_media_file_new_for_filename ("example.webm");
picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile));
</programlisting>
</informalexample>
</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.
If you need an editable text entry, use the #GtkComboBox:has-entry property.
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv><title>GtkWidget</title>
<qandaentry>
<question><para>
How do I change the color of a widget?
</para></question>
<answer><para>
The background color of a widget is determined by the CSS style that applies
to it. To change that, you can set style classes on the widget, and provide
custom CSS to change the appearance. Such CSS can be loaded with
gtk_css_provider_load_from_file() and its variants.
See gtk_style_context_add_provider().
</para></answer>
</qandaentry>
<qandaentry>
<question><para>
How do I change the font of a widget?
</para></question>
<answer><para>
If you want to make the text of a label larger, you can use
gtk_label_set_markup():
<informalexample><programlisting>
gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;");
</programlisting></informalexample>
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>
.my-widget-class {
font: Sans 30;
}
</programlisting>
in a CSS file, loading it with gtk_css_provider_load_from_file(), and
adding the provider with gtk_style_context_add_provider_for_display().
To associate this style information with your widget, set a style class
on its #GtkStyleContext using gtk_style_context_add_class().
The advantage of this approach is that users can then override the font
you have chosen. See the #GtkStyleContext documentation 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_override_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>
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, you 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 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 gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc
to obtain a cairo context and draw with that.
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
Can I improve the performance of my application by using another backend
of cairo (such as GL) ?
</para></question>
<answer><para>
No. Most drawing in GTK is not done via cairo anymore (but instead
by the GL or Vulkan renderers of GSK).
</para>
<para>
If you use cairo for drawing your own widgets, gtk_snapshot_append_cairo()
will choose the most appropriate surface type for you.
</para>
<para>
If you are interested in using GL for your own drawing, see #GtkGLArea.
</para></answer>
</qandaentry>
<qandaentry>
<question><para>
Can I use cairo to draw on a #GdkPixbuf ?
</para></question>
<answer><para>
No. The cairo image surface does not support the pixel format used by GdkPixbuf.
</para>
<para>
If you need to get cairo drawing into a format that can be displayed efficiently
by GTK, you may want to use an image surface and gdk_memory_texture_new().
</para></answer>
</qandaentry>
</qandadiv>
</qandaset>
</refsect1>
</refentry>