forked from AuroraMiddleware/gtk
faq: Don't number questions
The numbering makes it unnecessarily hard to add and remove questions, and does not really seem necessary. Just use bullets.
This commit is contained in:
Matthias Clasen
parent
537c2f6c7a
commit
3dcea74e85
@ -7,7 +7,7 @@ the question you have, this list is a good place to start.
|
||||
|
||||
## General Questions
|
||||
|
||||
1. How do I get started with GTK?
|
||||
* 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
|
||||
@ -18,11 +18,11 @@ the question you have, this list is a good place to start.
|
||||
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?
|
||||
* 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?
|
||||
* How do I port from one GTK version to another?
|
||||
|
||||
Every major version of GTK comes with a [migration guide](#migrating). You may also
|
||||
find useful information in the documentation for specific widgets and functions. If
|
||||
@ -30,7 +30,7 @@ the question you have, this list is a good place to start.
|
||||
[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?
|
||||
* 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
|
||||
@ -49,7 +49,7 @@ the question you have, this list is a good place to start.
|
||||
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
|
||||
* Why does my program leak memory, if I destroy a widget immediately
|
||||
after creating it?
|
||||
|
||||
If `GtkFoo` isn't a toplevel window, then
|
||||
@ -72,7 +72,7 @@ the question you have, this list is a good place to start.
|
||||
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?
|
||||
* How do I use GTK with threads?
|
||||
|
||||
GTK requires that all GTK API calls are made from the same thread in which
|
||||
the `GtkApplication` was created, or `gtk_init()` was called (the _main thread_).
|
||||
@ -82,7 +82,7 @@ the question you have, this list is a good place to start.
|
||||
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?
|
||||
* 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
|
||||
@ -137,7 +137,7 @@ the question you have, this list is a good place to start.
|
||||
|
||||
#define _(x) dgettext (GETTEXT_PACKAGE, x)
|
||||
|
||||
8. How do I use non-ASCII characters in GTK programs ?
|
||||
* 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
|
||||
@ -220,7 +220,7 @@ the question you have, this list is a good place to start.
|
||||
to call bind_textdomain_codeset() to ensure that translated strings
|
||||
are returned in UTF-8 encoding.
|
||||
|
||||
9. How do I use GTK with C++?
|
||||
* 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
|
||||
@ -245,19 +245,19 @@ the question you have, this list is a good place to start.
|
||||
|
||||
There are very few functions that require this cast, however.
|
||||
|
||||
10. How do I use GTK with other non-C languages?
|
||||
* 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?
|
||||
* How do I load an image or animation from a file?
|
||||
|
||||
To load an image file straight into a display widget, use
|
||||
[ctor@Gtk.Picture.new_for_file] or [ctor@GTk.Picture.new_for_filename].
|
||||
To load an image for another purpose, use [ctor@Gdk.Texture.new_from_file].
|
||||
To load a video from a file, use [ctor@Gtk.MediaFile.new_for_file].
|
||||
|
||||
12. How do I draw text?
|
||||
* How do I draw text?
|
||||
|
||||
If you just want to put text into your user interface somewhere, it is
|
||||
usually easiest to just use one of ready-made widgets for this purpose,
|
||||
@ -279,7 +279,7 @@ the question you have, this list is a good place to start.
|
||||
To draw a piece of text in a widget [vfunc@Gtk.Widget.snapshot] implementation,
|
||||
use [method@Gtk.Snapshot.append_layout].
|
||||
|
||||
13. How do I measure the size of a piece of text?
|
||||
* 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
|
||||
[method@Pango.Layout.get_pixel_size], using code like the following:
|
||||
@ -294,7 +294,7 @@ the question you have, this list is a good place to start.
|
||||
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?
|
||||
* 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
|
||||
@ -305,14 +305,14 @@ the question you have, this list is a good place to start.
|
||||
|
||||
g_type_ensure (GTK_TYPE_BLAH);
|
||||
|
||||
15. How do I create a transparent toplevel window?
|
||||
* 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?
|
||||
* ...for lists and trees?
|
||||
|
||||
This question has different answers, depending on the size of the dataset
|
||||
and the required formatting flexibility.
|
||||
@ -328,7 +328,7 @@ the question you have, this list is a good place to start.
|
||||
and widgetry inside the list, then you probably want to use a [class@Gtk.ListBox],
|
||||
which uses regular widgets for display.
|
||||
|
||||
17. ...for multi-line text display or editing?
|
||||
* ...for multi-line text display or editing?
|
||||
|
||||
See the [text widget overview](#TextWidget) -- you should use the
|
||||
[class@Gtk.TextView] widget.
|
||||
@ -337,7 +337,7 @@ the question you have, this list is a good place to start.
|
||||
of course. It can be made selectable with [method@Gtk.Label.set_selectable]. For a
|
||||
single-line text entry, see [class@Gtk.Entry].
|
||||
|
||||
18. ...to display an image or animation?
|
||||
* ...to display an image or animation?
|
||||
|
||||
GTK has two widgets that are dedicated to displaying images. [class@Gtk.Image], for
|
||||
small, fixed-size icons and [class@Gtk.Picture] for content images.
|
||||
@ -353,14 +353,14 @@ the question you have, this list is a good place to start.
|
||||
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
|
||||
* ...for presenting a set of mutually-exclusive choices, where Windows
|
||||
would use a combo box?
|
||||
|
||||
With GTK, a [class@Gtk.DropDown] is the recommended widget to use for this use case.
|
||||
|
||||
## Questions about GtkWidget
|
||||
|
||||
20. How do I change the color of a widget?
|
||||
* 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
|
||||
@ -368,7 +368,7 @@ the question you have, this list is a good place to start.
|
||||
[method@Gtk.CssProvider.load_from_file] and its variants.
|
||||
See [method@Gtk.StyleContext.add_provider].
|
||||
|
||||
21. How do I change the font of a widget?
|
||||
* 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():
|
||||
@ -392,14 +392,14 @@ the question you have, this list is a good place to start.
|
||||
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?
|
||||
* How do I disable/ghost/desensitize a widget?
|
||||
|
||||
In GTK a disabled widget is termed _insensitive_.
|
||||
See [method@Gtk.Widget.set_sensitive].
|
||||
|
||||
## GtkTextView questions
|
||||
|
||||
23. How do I get the contents of the entire text widget as a string?
|
||||
* How do I get the contents of the entire text widget as a string?
|
||||
|
||||
See [method@Gtk.TextBuffer.get_bounds] and [method@Gtk.TextBuffer.get_text]
|
||||
or [method@Gtk.TextIter.get_text].
|
||||
@ -414,14 +414,14 @@ the question you have, this list is a good place to start.
|
||||
/* use text */
|
||||
g_free (text);
|
||||
|
||||
24. How do I make a text widget display its complete contents in a specific font?
|
||||
* How do I make a text widget display its complete contents in a specific font?
|
||||
|
||||
If you use [method@Gtk.TextBuffer.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.
|
||||
|
||||
25. How do I make a text view scroll to the end of the buffer automatically ?
|
||||
* 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.
|
||||
@ -436,21 +436,21 @@ the question you have, this list is a good place to start.
|
||||
|
||||
## GtkTreeView questions
|
||||
|
||||
26. How do I associate some data with a row in the tree?
|
||||
* How do I associate some data with a row in the tree?
|
||||
|
||||
Remember that the [iface@Gtk.TreeModel] 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 [method@Gtk.TreeModel.get].
|
||||
See the [tree widget overview](#TreeWidget).
|
||||
|
||||
27. How do I put an image and some text in the same column?
|
||||
* How do I put an image and some text in the same column?
|
||||
|
||||
You can pack more than one [class@Gtk.CellRenderer] into a single [class@Gtk.TreeViewColumn]
|
||||
using [method@Gtk.TreeViewColumn.pack_start] or [method@Gtk.TreeViewColumn.pack_end].
|
||||
So pack both a [class@Gtk.CellRendererPixbuf] and a [class@Gtk.CellRendererText] into the
|
||||
column.
|
||||
|
||||
28. I can set data easily on my [class@Gtk.TreeStore] or [class@Gtk.ListStore] models using
|
||||
* I can set data easily on my [class@Gtk.TreeStore] or [class@Gtk.ListStore] models using
|
||||
[method@Gtk.ListStore.set] and [method@Gtk.TreeStore.set], but can't read it back?
|
||||
|
||||
Both the [class@Gtk.TreeStore] and the [class@Gtk.ListStore] implement the [iface@Gtk.TreeModel]
|
||||
@ -458,7 +458,7 @@ the question you have, this list is a good place to start.
|
||||
implements. The easiest way to read a set of data back is to use
|
||||
[method@Gtk.TreeModel.get].
|
||||
|
||||
29. How do I change the way that numbers are formatted by `GtkTreeView`?
|
||||
* How do I change the way that numbers are formatted by `GtkTreeView`?
|
||||
|
||||
Use [method@Gtk.TreeView.insert_column_with_data_func] or
|
||||
[method@Gtk.TreeViewColumn.set_cell_data_func] and do the conversion
|
||||
@ -532,21 +532,21 @@ the question you have, this list is a good place to start.
|
||||
(gpointer)DOUBLE_COLUMN, NULL);
|
||||
}
|
||||
|
||||
30. How do I hide the expander arrows in my tree view?
|
||||
* 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 [method@Gtk.TreeView.set_expander_column] and [method@Gtk.TreeViewColumn.set_visible].
|
||||
|
||||
## Using cairo with GTK
|
||||
|
||||
31. How do I use cairo to draw in GTK applications?
|
||||
* How do I use cairo to draw in GTK applications?
|
||||
|
||||
[class@Gtk.DrawingArea] is a ready-made widget for drawing with cairo.
|
||||
|
||||
If you implement a custom widget, use [method@Gtk.Snapshot.append_cairo]
|
||||
in your [vfunc@Gtk.Widget.snapshot] vfunc to obtain a cairo context and draw with that.
|
||||
|
||||
32. Can I improve the performance of my application by using another backend
|
||||
* 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
|
||||
@ -557,7 +557,7 @@ the question you have, this list is a good place to start.
|
||||
|
||||
If you are interested in using GL for your own drawing, see [class@Gtk.GLArea].
|
||||
|
||||
33. Can I use cairo to draw on a `GdkPixbuf`?
|
||||
* Can I use cairo to draw on a `GdkPixbuf`?
|
||||
|
||||
No. The cairo image surface does not support the pixel format used by `GdkPixbuf`.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user