AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-15 05:00:09 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'faq-updates' into 'main'

Browse Source 
faq: Some updates

See merge request GNOME/gtk!5512
This commit is contained in:
Emmanuele Bassi 2023-02-13 14:50:35 +00:00
commit bb15a7ef46
1 changed files with 63 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
docs/reference/gtk/question_index.md
View File

@ -7,37 +7,50 @@ 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
(most of it about GTK 2.x and 3.x, but still somewhat applicable). This
reference manual also contains a introductory
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?
* 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?
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
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
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?
* Should I maintain parallel versions of my UI in GTK x and GTK y?
At the end of the day, that is up to you.
Our experience is that it is a lot of work, and usually not a good idea.
If you are not ready to make the jump to the next major version of GTK,
it is perfectly fine to stick with the stable release. We maintain them
for that reason.
* 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).
In a widget tree, each container owns a reference to its children. The root
object (typically a `GtkWindow`) is owned by GTK. GTK will drop its reference
when you call [method@Gtk.Window.destroy].
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
@ -46,7 +59,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
@ -69,7 +82,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_).
@ -79,7 +92,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
@ -134,7 +147,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
@ -217,7 +230,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
@ -242,19 +255,23 @@ 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.Image.new_from_file]. 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].
[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,
such as [class@Gtk.Label].
To draw a piece of text onto a cairo surface, use a Pango layout and
[func@PangoCairo.show_layout].
@ -272,7 +289,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:
@ -287,7 +304,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
@ -298,14 +315,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.
@ -321,7 +338,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.
@ -330,7 +347,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.
@ -346,17 +363,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.ComboBox] is the recommended widget to use for this use case.
If you need an editable text entry, use the [property@Gtk.ComboBox:has-entry] property.
A newer alternative is [class@Gtk.DropDown].
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
@ -364,7 +378,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():
@ -388,14 +402,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].
@ -410,14 +424,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.
@ -432,21 +446,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]
@ -454,7 +468,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
@ -528,19 +542,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?
Use [method@Gtk.Snapshot.append_cairo] in your [vfunc@Gtk.Widget.snapshot] vfunc
to obtain a cairo context and draw with that.
[class@Gtk.DrawingArea] is a ready-made widget for drawing with cairo.
32. Can I improve the performance of my application by using another backend
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.
* 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
@ -551,7 +567,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`.