![]() | ![]() | ![]() | GTK+ Reference Manual | ![]() |
---|
Common Questions — Find answers to common questions in the GTK+ manual
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.
1. General | |
1.1. | Where can I get help with GTK+, submit a bug report, or make a feature request? |
See the documentation on this topic. | |
1.2. | How do I port from one GTK+ version to another? |
See the list of incompatible changes from 1.2 to 2.0. Also, the GNOME 2.0 porting guide on http://developer.gnome.org has some more detailed discussion of porting from 1.2 to 2.0. You may also find useful information in the documentation for specific widgets and functions. If you have a question not covered in the manual, feel free to ask on the mailing lists and please file a bug report against the documentation. | |
1.3. | How does memory management work in GTK+? Should I free data returned from functions? |
See the documentation for
For strings returned from functions, they will be declared "const"
(using | |
1.4. | How do I use GTK+ with threads? |
This is covered in the
| |
1.5. | How do I internationalize a GTK+ program? |
Most people use GNU gettext, already required in order to install GLib. On a UNIX or Linux system with gettext installed, type info gettext to read the documentation. #define _(x) gettext (x) #define N_(x) x #include <libintl.h> #define _(x) gettext (x) #define N_(x) x 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)); ... #define _(x) dgettext ("MyDomain", x) | |
1.6. | 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 which provides a C++-native 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. gdk_window_set_events (gdk_window, GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); gdk_window_set_events (gdk_window, (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); | |
1.7. | How do I use GTK+ with other non-C languages? |
See the list of language bindings on http://www.gtk.org. | |
1.8. | 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()
[1]. To load an image for another purpose, use
To load an image or animation file asynchronously (without blocking), use
| |
2. Which widget should I use... | |
2.1. | ...for lists and trees? |
See tree widget overview — 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. | |
2.2. | ...for multi-line text display or editing? |
See text widget overview — 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. 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. | |
2.3. | ...to display an image or animation? |
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. | |
2.4. | ...for presenting a set of mutually-exclusive choices, where Windows would use a combo box? |
With GTK+, a GtkOptionMenu is recommended instead of a combo box, if the user is selecting from a fixed set of options. That is, non-editable combo boxes are not encouraged. GtkOptionMenu is much easier to use than GtkCombo as well. Use GtkCombo only when you need the editable text entry. (As a future enhancement to GTK+, a new widget to replace GtkOptionMenu and GtkCombo is planned. This widget will be themeable to look like either a combo box or the current option menu, and will address some shortcomings in the GtkCombo API. Bug 50554 tracks this issue, if you want to check status or post comments.) | |
3. GtkWidget | |
3.1. | How do I change the color of a widget? |
See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(), and gtk_widget_modify_text(). See GTK+ resource files 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. 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. | |
3.2. | How do I disable/ghost/desensitize a widget? |
In GTK+ a disabled widget is termed "insensitive." See gtk_widget_set_sensitive(). | |
4. GtkTextView | |
4.1. | 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); | |
5. GtkTreeView | |
5.1. | 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. | |
5.2. | What's the GtkTreeView equivalent of gtk_clist_find_row_from_data()? |
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(). | |
5.3. | 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. | |
5.4. | 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, 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(). |
[1] [1] If the file load fails, gtk_image_new_from_file()
will display a "broken image" graphic — to detect a failed load
yourself, use
<< Mailing lists and bug reports | Part II. GTK+ Core Reference >> |