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

faq: Don't number questions

Browse Source 
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 2023-02-13 08:50:36 -05:00
parent 537c2f6c7a
commit 3dcea74e85
1 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,7 +7,7 @@ the question you have, this list is a good place to start.
## General Questions ## 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 The GTK [website](https://www.gtk.org) offers some
[tutorials](https://www.gtk.org/documentation.php) and other documentation [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 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. 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. 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 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 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 [file a bug report](https://gitlab.gnome.org/GNOME/gtk/issues/new) against the
documentation. 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 See the documentation for `GObject` and `GInitiallyUnowned`. For `GObject` note
specifically `g_object_ref()` and `g_object_unref()`. `GInitiallyUnowned` is a 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 The transfer annotations for gobject-introspection that are part of the
documentation can provide useful hints for memory handling semantics as well. 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? after creating it?
If `GtkFoo` isn't a toplevel window, then 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 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. 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 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_). 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 the results back to the main thread using `g_idle_add()` or `GAsyncQueue`. GIO
offers useful tools for such an approach such as `GTask`. 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/), 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 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) #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. 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 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 to call bind_textdomain_codeset() to ensure that translated strings
are returned in UTF-8 encoding. 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 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 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. 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) See the list of [language bindings](https://www.gtk.org/language-bindings.php)
on the GTK [website](https://www.gtk.org). 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 To load an image file straight into a display widget, use
[ctor@Gtk.Picture.new_for_file] or [ctor@GTk.Picture.new_for_filename]. [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 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]. 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 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, 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, To draw a piece of text in a widget [vfunc@Gtk.Widget.snapshot] implementation,
use [method@Gtk.Snapshot.append_layout]. 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 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: [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) 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/). 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 %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 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); 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 Any toplevel window can be transparent. It is just a matter of setting a
transparent background in the CSS style for it. transparent background in the CSS style for it.
## Which widget should I use... ## 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 This question has different answers, depending on the size of the dataset
and the required formatting flexibility. 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], and widgetry inside the list, then you probably want to use a [class@Gtk.ListBox],
which uses regular widgets for display. 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 See the [text widget overview](#TextWidget) -- you should use the
[class@Gtk.TextView] widget. [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 of course. It can be made selectable with [method@Gtk.Label.set_selectable]. For a
single-line text entry, see [class@Gtk.Entry]. 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 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. 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"); mediafile = gtk_media_file_new_for_filename ("example.webm");
picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile)); 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? would use a combo box?
With GTK, a [class@Gtk.DropDown] is the recommended widget to use for this use case. With GTK, a [class@Gtk.DropDown] is the recommended widget to use for this use case.
## Questions about GtkWidget ## 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 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 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. [method@Gtk.CssProvider.load_from_file] and its variants.
See [method@Gtk.StyleContext.add_provider]. 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 If you want to make the text of a label larger, you can use
gtk_label_set_markup(): 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. of this approach is that users can then override the font you have chosen.
See the `GtkStyleContext` documentation for more discussion. 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_. In GTK a disabled widget is termed _insensitive_.
See [method@Gtk.Widget.set_sensitive]. See [method@Gtk.Widget.set_sensitive].
## GtkTextView questions ## 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] See [method@Gtk.TextBuffer.get_bounds] and [method@Gtk.TextBuffer.get_text]
or [method@Gtk.TextIter.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 */ /* use text */
g_free (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 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 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 text typed in by the user before or after the tagged block will appear in
the default style. 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 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. [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 ## 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 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 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]. like any other data, and retrieve it with [method@Gtk.TreeModel.get].
See the [tree widget overview](#TreeWidget). 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] 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]. 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 So pack both a [class@Gtk.CellRendererPixbuf] and a [class@Gtk.CellRendererText] into the
column. 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? [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] 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 implements. The easiest way to read a set of data back is to use
[method@Gtk.TreeModel.get]. [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 Use [method@Gtk.TreeView.insert_column_with_data_func] or
[method@Gtk.TreeViewColumn.set_cell_data_func] and do the conversion [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); (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. 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]. See [method@Gtk.TreeView.set_expander_column] and [method@Gtk.TreeViewColumn.set_visible].
## Using cairo with GTK ## 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. [class@Gtk.DrawingArea] is a ready-made widget for drawing with cairo.
If you implement a custom widget, use [method@Gtk.Snapshot.append_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. 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)? of cairo (such as GL)?
No. Most drawing in GTK is not done via cairo anymore (but instead 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]. 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`. No. The cairo image surface does not support the pixel format used by `GdkPixbuf`.