summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2023-02-13 08:50:36 -0500
committerMatthias Clasen <mclasen@redhat.com>2023-02-13 08:52:04 -0500
commit3dcea74e8563b949154425caeae8cebb62b3ba3f (patch)
treea2532972cd73210de6c33bf7335dbf99def6c011 /docs
parent537c2f6c7a7b0ec32bc499fda02b6099a6282352 (diff)
downloadgtk+-3dcea74e8563b949154425caeae8cebb62b3ba3f.tar.gz
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.
Diffstat (limited to 'docs')
-rw-r--r--docs/reference/gtk/question_index.md66
1 files changed, 33 insertions, 33 deletions
diff --git a/docs/reference/gtk/question_index.md b/docs/reference/gtk/question_index.md
index 5a60581efa..d466234ec4 100644
--- a/docs/reference/gtk/question_index.md
+++ b/docs/reference/gtk/question_index.md
@@ -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`.