mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-08 09:40:10 +00:00
docs: Clean up docs syntax
Replace leftover gtk-doc syntax (#Type) with backquotes.
This commit is contained in:
Matthias Clasen
parent
0996552708
commit
2d0957b732
@ -3,7 +3,7 @@ Title: Key Values
|
||||
## Functions for manipulating keyboard codes
|
||||
|
||||
Key values are the codes which are sent whenever a key is pressed or released.
|
||||
They are included in the data contained in a key press or release #GdkEvent.
|
||||
They are included in the data contained in a key press or release `GdkEvent`.
|
||||
The complete list of key values can be found in the `gdk/gdkkeysyms.h` header
|
||||
file.
|
||||
|
||||
@ -45,7 +45,7 @@ information:
|
||||
or the “!” symbol. The letter keys are considered to have a lowercase
|
||||
letter at level 0, and an uppercase letter at level 1, though normally
|
||||
only the uppercase letter is printed on the key
|
||||
1. third, the #GdkKeymapKey contains a group; groups are not used on
|
||||
1. third, the [struct@Gdk.KeymapKey] contains a group; groups are not used on
|
||||
standard US keyboards, but are used in many other countries. On a
|
||||
keyboard with groups, there can be 3 or 4 symbols printed on a single
|
||||
key. The group indicates movement in a horizontal direction. Usually
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -33,13 +33,13 @@ the question you have, this list is a good place to start.
|
||||
|
||||
4. 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"
|
||||
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).
|
||||
|
||||
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
|
||||
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
|
||||
[file a bug report.](https://gitlab.gnome.org/GNOME/gtk/issues/new).
|
||||
|
||||
@ -47,7 +47,7 @@ the question you have, this list is a good place to start.
|
||||
documentation can provide useful hints for memory handling semantics as well.
|
||||
|
||||
5. 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
|
||||
|
||||
@ -60,7 +60,7 @@ the question you have, this list is a good place to start.
|
||||
want standard reference counting, not floating reference counting.
|
||||
|
||||
To get this, you must acquire a reference to the widget and drop the
|
||||
floating reference (_ref and sink_ in GObject parlance) after creating it:
|
||||
floating reference (_ref and sink_ in `GObject` parlance) after creating it:
|
||||
|
||||
foo = gtk_foo_new ();
|
||||
g_object_ref_sink (foo);
|
||||
@ -72,12 +72,12 @@ the question you have, this list is a good place to start.
|
||||
6. 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_).
|
||||
the `GtkApplication` was created, or `gtk_init()` was called (the _main thread_).
|
||||
|
||||
If you want to take advantage of multi-threading in a GTK application,
|
||||
it is usually best to send long-running tasks to worker threads, and feed
|
||||
the results back to the main thread using g_idle_add() or #GAsyncQueue. GIO
|
||||
offers useful tools for such an approach such as #GTask.
|
||||
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?
|
||||
|
||||
@ -239,7 +239,7 @@ the question you have, this list is a good place to start.
|
||||
|
||||
gdk_surface_set_events (gdk_surface,
|
||||
(GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
|
||||
|
||||
|
||||
There are very few functions that require this cast, however.
|
||||
|
||||
10. How do I use GTK with other non-C languages?
|
||||
@ -250,14 +250,14 @@ the question you have, this list is a good place to start.
|
||||
11. 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(). To load an image for another purpose, use
|
||||
gdk_texture_new_from_file(). To load a video from a file, use
|
||||
gtk_media_file_new_for_file().
|
||||
[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].
|
||||
|
||||
12. How do I draw text?
|
||||
|
||||
To draw a piece of text onto a cairo surface, use a Pango layout and
|
||||
pango_cairo_show_layout().
|
||||
[func@PangoCairo.show_layout].
|
||||
|
||||
layout = gtk_widget_create_pango_layout (widget, text);
|
||||
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
|
||||
@ -265,17 +265,17 @@ the question you have, this list is a good place to start.
|
||||
pango_cairo_show_layout (cr, layout);
|
||||
pango_font_description_free (fontdesc);
|
||||
g_object_unref (layout);
|
||||
|
||||
|
||||
See also the [Cairo Rendering](https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html)
|
||||
section of the [Pango documentation](https://developer.gnome.org/pango/stable/).
|
||||
|
||||
To draw a piece of text in a widget snapshot() implementation, use
|
||||
gtk_snapshot_append_layout().
|
||||
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?
|
||||
|
||||
To obtain the size of a piece of text, use a Pango layout and
|
||||
pango_layout_get_pixel_size(), using code like the following:
|
||||
[method@Pango.Layout.get_pixel_size], using code like the following:
|
||||
|
||||
layout = gtk_widget_create_pango_layout (widget, text);
|
||||
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
|
||||
@ -294,7 +294,7 @@ the question you have, this list is a good place to start.
|
||||
compiler to optimize the call away if it appears that the value is not
|
||||
being used.
|
||||
|
||||
GLib provides the g_type_ensure() function to work around this problem.
|
||||
GLib provides the `g_type_ensure()` function to work around this problem.
|
||||
|
||||
g_type_ensure (GTK_TYPE_BLAH);
|
||||
|
||||
@ -311,34 +311,34 @@ the question you have, this list is a good place to start.
|
||||
and the required formatting flexibility.
|
||||
|
||||
If you want to display a large amount of data in a uniform way, your best
|
||||
option is a #GtkTreeView widget. See the [tree widget overview](#TreeWidget).
|
||||
option is a [class@Gtk.TreeView] widget. See the [tree widget overview](#TreeWidget).
|
||||
A list is just a tree with no branches, so the treeview widget is used for
|
||||
lists as well.
|
||||
|
||||
If you want to display a small amount of items, but need flexible formatting
|
||||
and widgetry inside the list, then you probably want to use a #GtkListBox,
|
||||
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?
|
||||
|
||||
See the [text widget overview](#TextWidget) -- you should use the
|
||||
#GtkTextView widget.
|
||||
[class@Gtk.TextView] widget.
|
||||
|
||||
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.
|
||||
If you only have a small amount of text, [class@Gtk.Label] may also be appropriate
|
||||
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?
|
||||
|
||||
GTK has two widgets that are dedicated to displaying images. #GtkImage, for
|
||||
small, fixed-size icons and #GtkPicture for content images.
|
||||
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.
|
||||
|
||||
Both can display images in just about any format GTK understands.
|
||||
You can also use #GtkDrawingArea if you need to do something more complex,
|
||||
You can also use [class@Gtk.DrawingArea] if you need to do something more complex,
|
||||
such as draw text or graphics over the top of the image.
|
||||
|
||||
Both GtkImage and GtkPicture can display animations and videos as well.
|
||||
To show an webm file, load it with the GtkMediaFile API and then use
|
||||
Both [class@Gtk.Image] and [class@Gtk.Picture] can display animations and videos as well.
|
||||
To show an webm file, load it with the [class@Gtk.MediaFile] API and then use
|
||||
it as a paintable:
|
||||
|
||||
mediafile = gtk_media_file_new_for_filename ("example.webm");
|
||||
@ -347,8 +347,10 @@ the question you have, this list is a good place to start.
|
||||
19. ...for presenting a set of mutually-exclusive choices, where Windows
|
||||
would use a combo box?
|
||||
|
||||
With GTK, a #GtkComboBox is the recommended widget to use for this use case.
|
||||
If you need an editable text entry, use the #GtkComboBox:has-entry property.
|
||||
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].
|
||||
|
||||
## Questions about GtkWidget
|
||||
|
||||
@ -357,8 +359,8 @@ the question you have, this list is a good place to start.
|
||||
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
|
||||
custom CSS to change the appearance. Such CSS can be loaded with
|
||||
gtk_css_provider_load_from_file() and its variants.
|
||||
See gtk_style_context_add_provider().
|
||||
[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?
|
||||
|
||||
@ -368,7 +370,7 @@ the question you have, this list is a good place to start.
|
||||
gtk_label_set_markup (label, "<big>big tex</big>");
|
||||
|
||||
This is preferred for many apps because it's a relative size to the
|
||||
user's chosen font size. See g_markup_escape_text() if you are
|
||||
user's chosen font size. See `g_markup_escape_text()` if you are
|
||||
constructing such strings on the fly.
|
||||
|
||||
You can also change the font of a widget by putting
|
||||
@ -377,24 +379,24 @@ the question you have, this list is a good place to start.
|
||||
font: Sans 30;
|
||||
}
|
||||
|
||||
in a CSS file, loading it with gtk_css_provider_load_from_file(), and
|
||||
adding the provider with gtk_style_context_add_provider_for_display().
|
||||
in a CSS file, loading it with [method@Gtk.CssProvider.load_from_file], and
|
||||
adding the provider with [type_func@Gtk.StyleContext.add_provider_for_display].
|
||||
To associate this style information with your widget, set a style class
|
||||
on its #GtkStyleContext using gtk_style_context_add_class(). The advantage
|
||||
on the widget using [method@Gtk.Widget.add_css_class]. The advantage
|
||||
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?
|
||||
|
||||
In GTK a disabled widget is termed _insensitive_.
|
||||
See gtk_widget_set_sensitive().
|
||||
See [method@Gtk.Widget.set_sensitive].
|
||||
|
||||
## GtkTextView questions
|
||||
|
||||
23. 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().
|
||||
See [method@Gtk.TextBuffer.get_bounds] and [method@Gtk.TextBuffer.get_text]
|
||||
or [method@Gtk.TextIter.get_text].
|
||||
|
||||
GtkTextIter start, end;
|
||||
GtkTextBuffer *buffer;
|
||||
@ -405,10 +407,10 @@ the question you have, this list is a good place to start.
|
||||
text = gtk_text_iter_get_text (&start, &end);
|
||||
/* use text */
|
||||
g_free (text);
|
||||
|
||||
|
||||
24. How do I make a text widget display its complete contents in a specific font?
|
||||
|
||||
If you use gtk_text_buffer_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
|
||||
text typed in by the user before or after the tagged block will appear in
|
||||
the default style.
|
||||
@ -421,40 +423,40 @@ the question you have, this list is a good place to start.
|
||||
*before*, keeping the mark at the end.
|
||||
|
||||
To ensure that the end of the buffer remains visible, use
|
||||
gtk_text_view_scroll_to_mark() to scroll to the mark after
|
||||
[method@Gtk.TextView.scroll_to_mark] to scroll to the mark after
|
||||
inserting new text.
|
||||
|
||||
The gtk-demo application contains an example of this technique.
|
||||
The gtk4-demo application contains an example of this technique.
|
||||
|
||||
## GtkTreeView questions
|
||||
|
||||
26. How do I associate some data with a row in the tree?
|
||||
|
||||
Remember that the #GtkTreeModel columns don't necessarily have to be
|
||||
Remember that the [class@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 gtk_tree_model_get().
|
||||
See the [tree widget overview](#TreeWidget).
|
||||
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?
|
||||
|
||||
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
|
||||
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 #GtkTreeStore or #GtkListStore models using
|
||||
gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
|
||||
28. 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 #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
|
||||
Both the [class@Gtk.TreeStore] and the [class@Gtk.ListStore] implement the [class@Gtk.TreeModel]
|
||||
interface. As a consequence, you can use any function this interface
|
||||
implements. The easiest way to read a set of data back is to use
|
||||
gtk_tree_model_get().
|
||||
[method@Gtk.TreeModel.get].
|
||||
|
||||
29. How do I change the way that numbers are formatted by #GtkTreeView?
|
||||
29. How do I change the way that numbers are formatted by `GtkTreeView`?
|
||||
|
||||
Use gtk_tree_view_insert_column_with_data_func() or
|
||||
gtk_tree_view_column_set_cell_data_func() and do the conversion
|
||||
from number to string yourself (with, say, g_strdup_printf()).
|
||||
Use [method@Gtk.TreeView.insert_column_with_data_func] or
|
||||
[method@Gtk.TreeViewColumn.set_cell_data_func] and do the conversion
|
||||
from number to string yourself (with, say, `g_strdup_printf()`).
|
||||
|
||||
The following example demonstrates this:
|
||||
|
||||
@ -527,29 +529,29 @@ the question you have, this list is a good place to start.
|
||||
30. 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 gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
|
||||
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?
|
||||
|
||||
Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc
|
||||
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
|
||||
of cairo (such as GL)?
|
||||
|
||||
No. Most drawing in GTK is not done via cairo anymore (but instead
|
||||
by the GL or Vulkan renderers of GSK).
|
||||
|
||||
If you use cairo for drawing your own widgets, gtk_snapshot_append_cairo()
|
||||
If you use cairo for drawing your own widgets, [mehtod@Gtk.Snapshot.append_cairo]
|
||||
will choose the most appropriate surface type for you.
|
||||
|
||||
If you are interested in using GL for your own drawing, see #GtkGLArea.
|
||||
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?
|
||||
33. 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`.
|
||||
|
||||
If you need to get cairo drawing into a format that can be displayed efficiently
|
||||
by GTK, you may want to use an image surface and gdk_memory_texture_new().
|
||||
by GTK, you may want to use an image surface and [ctor@Gdk.MemoryTexture.new].
|
||||
|
||||
@ -8,7 +8,7 @@ an application's user interface elements. Assistive technology (AT)
|
||||
applications, like Orca, convey this information to users with disabilities,
|
||||
or reduced abilities, to help them use the application.
|
||||
|
||||
Standard GTK controls implement the #GtkAccessible interface and are thus
|
||||
Standard GTK controls implement the `GtkAccessible` interface and are thus
|
||||
accessible to ATs by default. This means that if you use GTK controls such
|
||||
as `GtkButton`, `GtkEntry`, or `GtkListView`, you only need to supply
|
||||
application-specific details when the defaults values are incomplete. You
|
||||
@ -103,39 +103,39 @@ for instance:
|
||||
|
||||
- a toggle button will change its %GTK_ACCESSIBLE_STATE_CHECKED state every
|
||||
time it is toggled, either by the user or programmatically
|
||||
- setting the mnemonic widget on a #GtkLabel will update the
|
||||
- setting the mnemonic widget on a `GtkLabel` will update the
|
||||
%GTK_ACCESSIBLE_RELATION_LABELLED_BY relation on the widget with a
|
||||
reference to the label
|
||||
- changing the #GtkAdjustment instance on a #GtkScrollbar will change the
|
||||
- changing the `GtkAdjustment` instance on a `GtkScrollbar` will change the
|
||||
%GTK_ACCESSIBLE_PROPERTY_VALUE_MAX, %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN,
|
||||
and %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW properties with the upper, lower,
|
||||
and value properties of the #GtkAdjustment
|
||||
and value properties of the `GtkAdjustment`
|
||||
|
||||
See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list
|
||||
of attributes for additional information.
|
||||
|
||||
#### List of accessible states
|
||||
|
||||
Each state name is part of the #GtkAccessibleState enumeration.
|
||||
Each state name is part of the `GtkAccessibleState` enumeration.
|
||||
|
||||
| State name | ARIA attribute | Value type | Notes |
|
||||
|------------|----------------|------------|-------|
|
||||
| %GTK_ACCESSIBLE_STATE_BUSY | “aria-busy” | boolean |
|
||||
| %GTK_ACCESSIBLE_STATE_CHECKED | “aria-checked” | #GtkAccessibleTristate | Indicates the current state of a [class@Gtk.CheckButton] |
|
||||
| %GTK_ACCESSIBLE_STATE_CHECKED | “aria-checked” | `GtkAccessibleTristate` | Indicates the current state of a [class@Gtk.CheckButton] |
|
||||
| %GTK_ACCESSIBLE_STATE_DISABLED | “aria-disabled” | boolean | Corresponds to the [property@Gtk.Widget:sensitive] property on [class@Gtk.Widget] |
|
||||
| %GTK_ACCESSIBLE_STATE_EXPANDED | “aria-expanded” | boolean or undefined | Corresponds to the [property@Gtk.Expander:expanded] property on [class@Gtk.Expander] |
|
||||
| %GTK_ACCESSIBLE_STATE_HIDDEN | “aria-hidden” | boolean | Corresponds to the [property@Gtk.Widget:visible] property on [class@Gtk.Widget] |
|
||||
| %GTK_ACCESSIBLE_STATE_INVALID | “aria-invalid” | #GtkAccessibleInvalidState | Set when a widget is showing an error |
|
||||
| %GTK_ACCESSIBLE_STATE_PRESSED | “aria-pressed” | #GtkAccessibleTristate | Indicates the current state of a [class@Gtk.ToggleButton] |
|
||||
| %GTK_ACCESSIBLE_STATE_INVALID | “aria-invalid” | `GtkAccessibleInvalidState` | Set when a widget is showing an error |
|
||||
| %GTK_ACCESSIBLE_STATE_PRESSED | “aria-pressed” | `GtkAccessibleTristate` | Indicates the current state of a [class@Gtk.ToggleButton] |
|
||||
| %GTK_ACCESSIBLE_STATE_SELECTED | “aria-selected” | boolean or undefined | Set when a widget is selected |
|
||||
|
||||
#### List of accessible properties
|
||||
|
||||
Each property name is part of the #GtkAccessibleProperty enumeration.
|
||||
Each property name is part of the `GtkAccessibleProperty` enumeration.
|
||||
|
||||
| State name | ARIA attribute | Value type |
|
||||
|------------|----------------|------------|
|
||||
| %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE | “aria-autocomplete” | #GtkAccessibleAutocomplete |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE | “aria-autocomplete” | `GtkAccessibleAutocomplete` |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_DESCRIPTION | “aria-description” | translatable string |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_HAS_POPUP | “aria-haspopup” | boolean |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS | “aria-keyshortcuts” | string |
|
||||
@ -144,12 +144,12 @@ Each property name is part of the #GtkAccessibleProperty enumeration.
|
||||
| %GTK_ACCESSIBLE_PROPERTY_MODAL | “aria-modal” | boolean |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_MULTI_LINE | “aria-multiline” | boolean |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_MULTI_SELECTABLE | “aria-multiselectable” | boolean |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_ORIENTATION | “aria-orientation” | #GtkOrientation |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_ORIENTATION | “aria-orientation” | `GtkOrientation` |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_PLACEHOLDER | “aria-placeholder” | translatable string |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_READ_ONLY | “aria-readonly” | boolean |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_REQUIRED | “aria-required” | boolean |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_ROLE_DESCRIPTION | “aria-roledescription” | translatable string |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_SORT | “aria-sort” | #GtkAccessibleSort |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_SORT | “aria-sort” | `GtkAccessibleSort` |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_VALUE_MAX | “aria-valuemax” | double |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN | “aria-valuemin” | double |
|
||||
| %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW | “aria-valuenow” | double |
|
||||
@ -157,22 +157,22 @@ Each property name is part of the #GtkAccessibleProperty enumeration.
|
||||
|
||||
#### List of accessible relations
|
||||
|
||||
Each relation name is part of the #GtkAccessibleRelation enumeration.
|
||||
Each relation name is part of the `GtkAccessibleRelation` enumeration.
|
||||
|
||||
| State name | ARIA attribute | Value type |
|
||||
|------------|----------------|------------|
|
||||
| %GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT | “aria-activedescendant” | #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT | “aria-activedescendant” | `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_COL_COUNT | “aria-colcount” | integer |
|
||||
| %GTK_ACCESSIBLE_RELATION_COL_INDEX | “aria-colindex” | integer |
|
||||
| %GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT | “aria-colindextext” | translatable string |
|
||||
| %GTK_ACCESSIBLE_RELATION_COL_SPAN | “aria-colspan” | integer |
|
||||
| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a list of #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a list of #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a list of #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a list of #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a list of #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a list of #GtkAccessible |
|
||||
| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a list of `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a list of `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a list of `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a list of `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a list of `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a list of `GtkAccessible` |
|
||||
| %GTK_ACCESSIBLE_RELATION_POS_IN_SET | “aria-posinset” | integer |
|
||||
| %GTK_ACCESSIBLE_RELATION_ROW_COUNT | “aria-rowcount” | integer |
|
||||
| %GTK_ACCESSIBLE_RELATION_ROW_INDEX | “aria-rowindex” | integer |
|
||||
@ -219,11 +219,11 @@ be used as part of the application's test suite to avoid regressions.
|
||||
|
||||
## Implementations
|
||||
|
||||
Each UI control implements the #GtkAccessible interface to allow widget and
|
||||
Each UI control implements the `GtkAccessible` interface to allow widget and
|
||||
application developers to specify the roles, state, and relations between UI
|
||||
controls. This API is purely descriptive.
|
||||
|
||||
Each `GtkAccessible` implementation must provide a #GtkATContext instance,
|
||||
Each `GtkAccessible` implementation must provide a `GtkATContext` instance,
|
||||
which acts as a proxy to the specific platform's accessibility API:
|
||||
|
||||
* AT-SPI on Linux/BSD
|
||||
@ -256,7 +256,7 @@ is a promise that the widget being created will provide the same keyboard
|
||||
interactions expected for a button. An accessible role of a button will not
|
||||
turn automatically any widget into a `GtkButton`; but if your widget behaves
|
||||
like a button, using the %GTK_ACCESSIBLE_ROLE_BUTTON will allow any
|
||||
assistive technology to handle it like they would a #GtkButton.
|
||||
assistive technology to handle it like they would a `GtkButton`.
|
||||
|
||||
### Attributes can both hide and enhance
|
||||
|
||||
@ -308,7 +308,7 @@ interface.
|
||||
|
||||
A "presentation" role should not be confused with the
|
||||
%GTK_ACCESSIBLE_STATE_HIDDEN state; the "hidden" state is transient, and is
|
||||
typically controlled by showing and hiding a widget using the #GtkWidget
|
||||
typically controlled by showing and hiding a widget using the `GtkWidget`
|
||||
API.
|
||||
|
||||
## Design patterns and custom widgets
|
||||
@ -322,7 +322,7 @@ as well.
|
||||
A button is a widget that enables users to trigger an action. While it is
|
||||
recommended you use `GtkButton` for anything that looks and behaves like a
|
||||
button, it is possible to apply a button behavior to UI elements like images
|
||||
by using a #GtkGestureClick gesture. When doing so, you should:
|
||||
by using a `GtkGestureClick` gesture. When doing so, you should:
|
||||
|
||||
- Give your widget the role %GTK_ACCESSIBLE_ROLE_BUTTON
|
||||
- Install an action with no parameters, which will activate the widget
|
||||
@ -336,7 +336,7 @@ in the same way as a `GtkSpinButton` or `GtkSearchEntry`.
|
||||
|
||||
### Tab-based UI
|
||||
|
||||
If you make a tab-based interface, you should consider using #GtkStack
|
||||
If you make a tab-based interface, you should consider using `GtkStack`
|
||||
as the core, and just make a custom tab widget to control the active
|
||||
stack page. When doing so, the following extra steps will ensure that
|
||||
your tabs are accessible in the same way as `GtkStackSwitcher` or `GtkNotebook`:
|
||||
@ -344,7 +344,7 @@ your tabs are accessible in the same way as `GtkStackSwitcher` or `GtkNotebook`:
|
||||
- Give your tab container the role %GTK_ACCESSIBLE_ROLE_TAB_LIST
|
||||
- Give your tab widgets the role %GTK_ACCESSIBLE_ROLE_TAB
|
||||
- Set up the %GTK_ACCESSIBLE_RELATION_CONTROLS relation between each
|
||||
tab and the #GtkStackPage object for its page
|
||||
tab and the `GtkStackPage` object for its page
|
||||
- Set the %GTK_ACCESSIBLE_PROPERTY_SELECTED property on each tab, with
|
||||
the active tab getting the value %TRUE, all others %FALSE
|
||||
|
||||
@ -357,7 +357,7 @@ or add a `activate-tab` action on each tab.
|
||||
### Value controls
|
||||
|
||||
A value control (ie a widget that controls a one-dimensional quantity
|
||||
that can be represented by a #GtkAdjustment) can be represented to
|
||||
that can be represented by a `GtkAdjustment`) can be represented to
|
||||
accessible technologies by setting the %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN,
|
||||
%GTK_ACCESSIBLE_PROPERTY_VALUE_MAX, and %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW
|
||||
properties.
|
||||
|
||||
@ -24,25 +24,25 @@ you should be aware of what they refer to. These are often generic terms that
|
||||
have a specific meaning in this context.
|
||||
|
||||
**_Views_** or **_list widgets_** are the widgets that hold and manage the lists.
|
||||
Examples of these widgets would be #GtkListView or #GtkGridView.
|
||||
Examples of these widgets would be `GtkListView` or `GtkGridView`.
|
||||
|
||||
Views display data from a **_model_**. A model is a #GListModel and models can
|
||||
Views display data from a **_model_**. A model is a `GListModel` and models can
|
||||
be provided in 3 ways or combinations thereof:
|
||||
|
||||
* Many list models implementations already exist. There are models that provide
|
||||
specific data, like #GtkDirectoryList. And there are models like #GListStore
|
||||
specific data, like `GtkDirectoryList`. And there are models like `GListStore`
|
||||
that allow building lists manually.
|
||||
|
||||
* Wrapping list models like #GtkFilterListModel or #GtkSortListModel
|
||||
* Wrapping list models like `GtkFilterListModel` or `GtkSortListModel`
|
||||
modify, adapt or combine other models.
|
||||
|
||||
* Last but not least, developers are encouraged to create their own #GListModel
|
||||
* Last but not least, developers are encouraged to create their own `GListModel`
|
||||
implementations. The interface is kept deliberately small to make this easy.
|
||||
|
||||
The same model can be used in multiple different views and wrapped with
|
||||
multiple different models at once.
|
||||
|
||||
The elements in a model are called **_items_**. All items are #GObjects.
|
||||
The elements in a model are called **_items_**. All items are `GObjects`.
|
||||
|
||||
Every item in a model has a **_position_** which is the unsigned integer that
|
||||
describes where in the model the item is located. The first item in a model is
|
||||
@ -56,11 +56,11 @@ with models. Oftentimes some things are really hard to do one way but very easy
|
||||
the other way.
|
||||
|
||||
The other important part of a view is a **_factory_**. Each factory is
|
||||
a #GtkListItemFactory implementation that takes care of mapping the items
|
||||
a `GtkListItemFactory` implementation that takes care of mapping the items
|
||||
of the model to widgets that can be shown in the view.
|
||||
|
||||
The way factories do this is by creating a **_listitem_** for each item that
|
||||
is currently in use. Listitems are always #GtkListItem objects. They are only
|
||||
is currently in use. Listitems are always `GtkListItem` objects. They are only
|
||||
ever created by GTK and provide information about what item they are meant
|
||||
to display.
|
||||
|
||||
@ -71,28 +71,28 @@ for the data displayed, the programming language and development environment
|
||||
is an important task that can simplify setting up the view tremendously.
|
||||
|
||||
Views support selections via a **_selection model_**. A selection model is an
|
||||
implementation of the #GtkSelectionModel interface on top of the #GListModel
|
||||
implementation of the `GtkSelectionModel` interface on top of the `GListModel`
|
||||
interface that allows marking each item in a model as either selected or not
|
||||
selected. Just like regular models, this can be implemented either by
|
||||
implementing #GtkSelectionModel directly or by wrapping a model with one of
|
||||
the GTK models provided for this purposes, such as #GtkNoSelection
|
||||
or #GtkSingleSelection.
|
||||
implementing `GtkSelectionModel` directly or by wrapping a model with one of
|
||||
the GTK models provided for this purposes, such as `GtkNoSelection`
|
||||
or `GtkSingleSelection`.
|
||||
|
||||
The behavior of selection models - ie which items they allow selecting and
|
||||
what effect this has on other items - is completely up to the selection model.
|
||||
As such, single-selections, multi-selections or sharing selection state between
|
||||
different selection models and/or views is possible. The selection state of an
|
||||
item is exposed in the listitem via the #GtkListItem:selected property.
|
||||
item is exposed in the listitem via the `GtkListItem:selected` property.
|
||||
|
||||
Views and listitems also support activation. Activation means that double
|
||||
clicking or pressing enter while inside a focused row will cause the view
|
||||
to emit and activation signal such as #GtkListView::activate. This provides
|
||||
to emit and activation signal such as `GtkListView::activate`. This provides
|
||||
an easy way to set up lists, but can also be turned off on listitems if undesired.
|
||||
|
||||
Both selections and activation are supported among other things via widget
|
||||
[actions](#actions-overview). This allows developers to add widgets to their
|
||||
lists that cause selections to change or to trigger activation via
|
||||
the #GtkActionable interface. For a list of all supported actions see the
|
||||
the `GtkActionable` interface. For a list of all supported actions see the
|
||||
relevant documentation.
|
||||
|
||||
## Behind the scenes
|
||||
@ -114,8 +114,8 @@ new position at any time causing any state to be lost.
|
||||
|
||||
Another important requirement for views is that they need to know which items
|
||||
are not visible so they can be recycled. Views achieve that by implementing
|
||||
the #GtkScrollable interface and expecting to be placed directly into
|
||||
a #GtkScrolledWindow.
|
||||
the `GtkScrollable` interface and expecting to be placed directly into
|
||||
a `GtkScrolledWindow`.
|
||||
|
||||
Of course, if you are only using models with few items, this is not important
|
||||
and you can treat views like any other widget. But if you use large lists and
|
||||
@ -128,8 +128,8 @@ tradeoffs of those and experiment with them.
|
||||
|
||||
GTK offers a wide variety of wrapping models which change or supplement an
|
||||
existing model (or models) in some way. But when it comes to storing your
|
||||
actual data, there are only a few ready-made choices available: #GListStore
|
||||
and #GtkStringList.
|
||||
actual data, there are only a few ready-made choices available: `GListStore`
|
||||
and `GtkStringList`.
|
||||
|
||||
GListStore is backed by a balanced tree and has performance characteristics
|
||||
that are expected for that data structure. It works reasonably well for dataset
|
||||
@ -143,7 +143,7 @@ place where you would otherwise use `char*[]` and works best if the dataset
|
||||
is not very dynamic.
|
||||
|
||||
If these models don't fit your use case or scalability requirements, you
|
||||
should make a custom #GListModel. It is a small interface and not very hard
|
||||
should make a custom `GListModel`. It is a small interface and not very hard
|
||||
to implement.
|
||||
|
||||
For asymptotic performance comparisons between tree- and array-based
|
||||
@ -152,23 +152,23 @@ implementations, see this
|
||||
|
||||
## Displaying trees
|
||||
|
||||
While #GtkTreeView provided built-in support for trees, the list widgets, and
|
||||
in particular #GListModel do not. This was a design choice because the common
|
||||
While `GtkTreeView` provided built-in support for trees, the list widgets, and
|
||||
in particular `GListModel` do not. This was a design choice because the common
|
||||
use case is displaying lists and not trees and it greatly simplifies the API
|
||||
interface provided.
|
||||
|
||||
However, GTK provides functionality to make trees look and behave like lists
|
||||
for the people who still want to display lists. This is achieved by using
|
||||
the #GtkTreeListModel model to flatten a tree into a list. The #GtkTreeExpander
|
||||
the `GtkTreeListModel` model to flatten a tree into a list. The `GtkTreeExpander`
|
||||
widget can then be used inside a listitem to allow users to expand and collapse
|
||||
rows and provide a similar experience to #GtkTreeView.
|
||||
rows and provide a similar experience to `GtkTreeView`.
|
||||
|
||||
Developers should refer to those objects' API reference for more discussion
|
||||
on the topic.
|
||||
|
||||
## List styles
|
||||
|
||||
One of the advantages of the new list widgets over #GtkTreeViews and cell
|
||||
One of the advantages of the new list widgets over `GtkTreeViews` and cell
|
||||
renderers is that they are fully themable using GTK CSS. This provides a
|
||||
lot of flexibility. The themes that ship with GTK provide a few predefined
|
||||
list styles that can be used in many situations:
|
||||
@ -192,7 +192,7 @@ style class.
|
||||
|
||||
## Comparison to GtkTreeView
|
||||
|
||||
Developers familiar with #GtkTreeView may wonder how this way of doing lists
|
||||
Developers familiar with `GtkTreeView` may wonder how this way of doing lists
|
||||
compares to the way they know. This section will try to outline the similarities
|
||||
and differences between the two.
|
||||
|
||||
@ -200,26 +200,26 @@ This new approach tries to provide roughly the same functionality as the old
|
||||
approach but often uses a very different approach to achieve these goals.
|
||||
|
||||
The main difference and one of the primary reasons for this new development is
|
||||
that items can be displayed using regular widgets and #GtkCellRenderer is no
|
||||
that items can be displayed using regular widgets and `GtkCellRenderer` is no
|
||||
longer necessary. This allows all benefits that widgets provide, such as complex
|
||||
layout and animating widgets and not only makes cell renderers obsolete, but
|
||||
also #GtkCellArea.
|
||||
also `GtkCellArea`.
|
||||
|
||||
The other big difference is the massive change to the data model. #GtkTreeModel
|
||||
was a rather complex interface for a tree data structure and #GListModel was
|
||||
The other big difference is the massive change to the data model. `GtkTreeModel`
|
||||
was a rather complex interface for a tree data structure and `GListModel` was
|
||||
deliberately designed to be a simple data structure for lists only. (See
|
||||
[above](#displaying-trees)) for how to still do trees with this new model.)
|
||||
Another big change is that the new model allows for bulk changes via
|
||||
the #GListModel:items-changed signal while #GtkTreeModel only allows a single
|
||||
the `GListModel:items-changed` signal while `GtkTreeModel` only allows a single
|
||||
item to change at once. The goal here is of course to encourage implementation
|
||||
of custom list models.
|
||||
|
||||
Another consequence of the new model is that it is now easily possible to
|
||||
refer to the contents of a row in the model directly by keeping the item,
|
||||
while #GtkTreeRowReference was a very slow mechanism to achieve the same.
|
||||
while `GtkTreeRowReference` was a very slow mechanism to achieve the same.
|
||||
And because the items are real objects, developers can make them emit change
|
||||
signals causing listitems and their children to update, which wasn't possible
|
||||
with #GtkTreeModel.
|
||||
with `GtkTreeModel`.
|
||||
|
||||
The selection handling is also different. While selections used to be managed
|
||||
via custom code in each widget, selection state is now meant to be managed by
|
||||
@ -229,24 +229,24 @@ specialized requirements.
|
||||
Finally here's a quick list of equivalent functionality to look for when
|
||||
transitioning code for easy lookup:
|
||||
|
||||
| Old | New |
|
||||
| ------------------- | ----------------------------------- |
|
||||
| #GtkTreeModel | #GListModel |
|
||||
| #GtkTreePath | #guint position, #GtkTreeListRow |
|
||||
| #GtkTreeIter | #guint position |
|
||||
| #GtkTreeRowReference | #GObject item |
|
||||
| #GtkListStore | #GListStore |
|
||||
| #GtkTreeStore | #GtkTreeListModel, #GtkTreeExpander |
|
||||
| #GtkTreeSelection | #GtkSelectionModel |
|
||||
| #GtkTreeViewColumn | #GtkColumnView |
|
||||
| #GtkTreeView | #GtkListView, #GtkColumnView |
|
||||
| #GtkCellView | #GtkListItemWidget |
|
||||
| #GtkComboBox | #GtkDropDown |
|
||||
| #GtkIconView | #GtkGridView |
|
||||
| #GtkTreeSortable | #GtkColumnView |
|
||||
| #GtkTreeModelSort | #GtkSortListModel |
|
||||
| #GtkTreeModelFilter | #GtkFilterListModel |
|
||||
| #GtkCellLayout | #GtkListItemFactory |
|
||||
| #GtkCellArea | #GtkWidget |
|
||||
| #GtkCellRenderer | #GtkWidget |
|
||||
| Old | New |
|
||||
| -------------------- | ------------------------------------ |
|
||||
| `GtkTreeModel` | `GListModel` |
|
||||
| `GtkTreePath` | `guint` position, `GtkTreeListRow` |
|
||||
| `GtkTreeIter` | `guint` position |
|
||||
| `GtkTreeRowReference`| `GObject` item |
|
||||
| `GtkListStore` | `GListStore` |
|
||||
| `GtkTreeStore` | `GtkTreeListModel`, `GtkTreeExpander`|
|
||||
| `GtkTreeSelection` | `GtkSelectionModel` |
|
||||
| `GtkTreeViewColumn` | `GtkColumnView` |
|
||||
| `GtkTreeView` | `GtkListView`, `GtkColumnView` |
|
||||
| `GtkCellView` | `GtkListItemWidget` |
|
||||
| `GtkComboBox` | `GtkDropDown` |
|
||||
| `GtkIconView` | `GtkGridView` |
|
||||
| `GtkTreeSortable` | `GtkColumnView` |
|
||||
| `GtkTreeModelSort` | `GtkSortListModel` |
|
||||
| `GtkTreeModelFilter` | `GtkFilterListModel` |
|
||||
| `GtkCellLayout` | `GtkListItemFactory` |
|
||||
| `GtkCellArea` | `GtkWidget` |
|
||||
| `GtkCellRenderer` | `GtkWidget` |
|
||||
|
||||
|
||||
@ -2,15 +2,15 @@ Title: Text Widget Overview
|
||||
Slug: gtk-textview
|
||||
|
||||
GTK has an extremely powerful framework for multiline text editing. The
|
||||
primary objects involved in the process are #GtkTextBuffer, which represents the
|
||||
text being edited, and #GtkTextView, a widget which can display a #GtkTextBuffer.
|
||||
primary objects involved in the process are `GtkTextBuffer`, which represents the
|
||||
text being edited, and `GtkTextView`, a widget which can display a `GtkTextBuffer`.
|
||||
Each buffer can be displayed by any number of views.
|
||||
|
||||
One of the important things to remember about text in GTK is that it's in
|
||||
the UTF-8 encoding. This means that one character can be encoded as multiple
|
||||
bytes. Character counts are usually referred to as _offsets_, while byte
|
||||
counts are called _indexes_. If you confuse these two, things will work fine
|
||||
with ASCII, but as soon as your buffer contains multibyte characters, bad
|
||||
with ASCII, but as soon as your buffer contains multibyte characters, bad
|
||||
things will happen.
|
||||
|
||||
Text in a buffer can be marked with _tags_. A tag is an attribute that can
|
||||
@ -19,10 +19,10 @@ and make the text inside the tag bold. However, the tag concept is more
|
||||
general than that; tags don't have to affect appearance. They can instead
|
||||
affect the behavior of mouse and key presses, "lock" a range of text so the
|
||||
user can't edit it, or countless other things. A tag is represented by a
|
||||
#GtkTextTag object. One #GtkTextTag can be applied to any number of text
|
||||
`GtkTextTag` object. One `GtkTextTag` can be applied to any number of text
|
||||
ranges in any number of buffers.
|
||||
|
||||
Each tag is stored in a #GtkTextTagTable. A tag table defines a set of
|
||||
Each tag is stored in a `GtkTextTagTable`. A tag table defines a set of
|
||||
tags that can be used together. Each buffer has one tag table associated with
|
||||
it; only tags from that tag table can be used with the buffer. A single tag
|
||||
table can be shared between multiple buffers, however.
|
||||
@ -32,36 +32,36 @@ your tag that makes things bold "bold"), but they can also be anonymous (which
|
||||
is convenient if you're creating tags on-the-fly).
|
||||
|
||||
Most text manipulation is accomplished with _iterators_, represented by a
|
||||
#GtkTextIter. An iterator represents a position between two characters in
|
||||
the text buffer. #GtkTextIter is a struct designed to be allocated on the
|
||||
`GtkTextIter`. An iterator represents a position between two characters in
|
||||
the text buffer. `GtkTextIter` is a struct designed to be allocated on the
|
||||
stack; it's guaranteed to be copiable by value and never contain any
|
||||
heap-allocated data. Iterators are not valid indefinitely; whenever the
|
||||
buffer is modified in a way that affects the number of characters in the
|
||||
buffer, all outstanding iterators become invalid. (Note that deleting 5
|
||||
characters and then reinserting 5 still invalidates iterators, though you
|
||||
end up with the same number of characters you pass through a state with a
|
||||
characters and then reinserting 5 still invalidates iterators, though you
|
||||
end up with the same number of characters you pass through a state with a
|
||||
different number).
|
||||
|
||||
Because of this, iterators can't be used to preserve positions across buffer
|
||||
modifications. To preserve a position, the #GtkTextMark object is ideal. You
|
||||
can think of a mark as an invisible cursor or insertion point; it floats in
|
||||
the buffer, saving a position. If the text surrounding the mark is deleted,
|
||||
the mark remains in the position the text once occupied; if text is inserted
|
||||
at the mark, the mark ends up either to the left or to the right of the new
|
||||
modifications. To preserve a position, the `GtkTextMark` object is ideal. You
|
||||
can think of a mark as an invisible cursor or insertion point; it floats in
|
||||
the buffer, saving a position. If the text surrounding the mark is deleted,
|
||||
the mark remains in the position the text once occupied; if text is inserted
|
||||
at the mark, the mark ends up either to the left or to the right of the new
|
||||
text, depending on its _gravity_. The standard text cursor in left-to-right
|
||||
languages is a mark with right gravity, because it stays to the right of
|
||||
inserted text.
|
||||
|
||||
Like tags, marks can be either named or anonymous. There are two marks
|
||||
built-in to #GtkTextBuffer; these are named "insert" and "selection_bound"
|
||||
built-in to `GtkTextBuffer`; these are named "insert" and "selection_bound"
|
||||
and refer to the insertion point and the boundary of the selection which
|
||||
is not the insertion point, respectively. If no text is selected, these
|
||||
two marks will be in the same position. You can manipulate what is selected
|
||||
and where the cursor appears by moving these marks around.
|
||||
|
||||
If you want to place the cursor in response to a user action, be sure to use
|
||||
gtk_text_buffer_place_cursor(), which moves both at once without causing a
|
||||
temporary selection (moving one then the other temporarily selects the range in
|
||||
gtk_text_buffer_place_cursor(), which moves both at once without causing a
|
||||
temporary selection (moving one then the other temporarily selects the range in
|
||||
between the old and new positions).
|
||||
|
||||
Text buffers always contain at least one line, but may be empty (that
|
||||
@ -69,7 +69,7 @@ is, buffers can contain zero characters). The last line in the text
|
||||
buffer never ends in a line separator (such as newline); the other
|
||||
lines in the buffer always end in a line separator. Line separators
|
||||
count as characters when computing character counts and character
|
||||
offsets. Note that some Unicode line separators are represented with
|
||||
offsets. Note that some Unicode line separators are represented with
|
||||
multiple bytes in UTF-8, and the two-character sequence "\r\n" is also
|
||||
considered a line separator.
|
||||
|
||||
@ -83,7 +83,7 @@ gtk_text_buffer_end_irreversible_action().
|
||||
|
||||
## Simple Example
|
||||
|
||||
The simplest usage of #GtkTextView might look like this:
|
||||
The simplest usage of `GtkTextView` might look like this:
|
||||
|
||||
``` {.c}
|
||||
GtkWidget *view;
|
||||
@ -101,17 +101,17 @@ gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1);
|
||||
*/
|
||||
```
|
||||
|
||||
In many cases it's also convenient to first create the buffer with
|
||||
gtk_text_buffer_new(), then create a widget for that buffer with
|
||||
gtk_text_view_new_with_buffer(). Or you can change the buffer the widget
|
||||
In many cases it's also convenient to first create the buffer with
|
||||
gtk_text_buffer_new(), then create a widget for that buffer with
|
||||
gtk_text_view_new_with_buffer(). Or you can change the buffer the widget
|
||||
displays after the widget is created with gtk_text_view_set_buffer().
|
||||
|
||||
## Example of Changing Text Attributes
|
||||
|
||||
The way to affect text attributes in #GtkTextView is to
|
||||
The way to affect text attributes in `GtkTextView` is to
|
||||
apply tags that change the attributes for a region of text.
|
||||
For text features that come from the theme — such as font and
|
||||
foreground color -- use CSS to override their default values.
|
||||
For text features that come from the theme — such as font and
|
||||
foreground color — use CSS to override their default values.
|
||||
|
||||
```
|
||||
GtkWidget *view;
|
||||
@ -148,11 +148,11 @@ gtk_text_view_set_left_margin (GTK_TEXT_VIEW (view), 30);
|
||||
/* Use a tag to change the color for just one part of the widget */
|
||||
tag = gtk_text_buffer_create_tag (buffer, "blue_foreground",
|
||||
"foreground", "blue",
|
||||
NULL);
|
||||
NULL);
|
||||
gtk_text_buffer_get_iter_at_offset (buffer, &start, 7);
|
||||
gtk_text_buffer_get_iter_at_offset (buffer, &end, 12);
|
||||
gtk_text_buffer_apply_tag (buffer, tag, &start, &end);
|
||||
```
|
||||
|
||||
The `gtk4-demo` application that comes with
|
||||
GTK contains more example code for #GtkTextView.
|
||||
GTK contains more example code for `GtkTextView`.
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
Title: Tree and List Widget Overview
|
||||
Slug: gtk-treeview
|
||||
|
||||
To create a tree or list in GTK, use the #GtkTreeModel interface in
|
||||
conjunction with the #GtkTreeView widget. This widget is designed around
|
||||
To create a tree or list in GTK, use the `GtkTreeModel` interface in
|
||||
conjunction with the `GtkTreeView` widget. This widget is designed around
|
||||
a _Model/View/Controller_ design and consists of four major parts:
|
||||
|
||||
- The tree view widget (GtkTreeView)
|
||||
@ -25,9 +25,9 @@ it be rendered as a checkbox?
|
||||
|
||||
## Creating a model
|
||||
|
||||
GTK provides two simple models that can be used: the #GtkListStore
|
||||
and the #GtkTreeStore. GtkListStore is used to model list widgets,
|
||||
while the GtkTreeStore models trees. It is possible to develop a new
|
||||
GTK provides two simple models that can be used: the `GtkListStore`
|
||||
and the `GtkTreeStore`. `GtkListStore` is used to model list widgets,
|
||||
while the `GtkTreeStore` models trees. It is possible to develop a new
|
||||
type of model, but the existing models should be satisfactory for all
|
||||
but the most specialized of situations. Creating the model is quite
|
||||
|
||||
@ -59,7 +59,7 @@ GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS, /* Total number of co
|
||||
|
||||
Adding data to the model is done using gtk_tree_store_set() or
|
||||
gtk_list_store_set(), depending upon which sort of model was
|
||||
created. To do this, a #GtkTreeIter must be acquired. The iterator
|
||||
created. To do this, a `GtkTreeIter` must be acquired. The iterator
|
||||
points to the location where data will be added.
|
||||
|
||||
Once an iterator has been acquired, gtk_tree_store_set() is used to
|
||||
@ -119,8 +119,8 @@ gtk_tree_store_set (store, &iter2,
|
||||
|
||||
While there are several different models to choose from, there is
|
||||
only one view widget to deal with. It works with either the list
|
||||
or the tree store. Setting up a #GtkTreeView is not a difficult
|
||||
matter. It needs a #GtkTreeModel to know where to retrieve its data
|
||||
or the tree store. Setting up a `GtkTreeView` is not a difficult
|
||||
matter. It needs a `GtkTreeModel` to know where to retrieve its data
|
||||
from.
|
||||
|
||||
``` {.c}
|
||||
@ -131,16 +131,16 @@ tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
|
||||
|
||||
## Columns and cell renderers
|
||||
|
||||
Once the #GtkTreeView widget has a model, it will need to know how
|
||||
Once the `GtkTreeView` widget has a model, it will need to know how
|
||||
to display the model. It does this with columns and cell renderers.
|
||||
|
||||
Cell renderers are used to draw the data in the tree model in a
|
||||
way. There are a number of cell renderers that come with GTK,
|
||||
including the #GtkCellRendererText, #GtkCellRendererPixbuf and
|
||||
the #GtkCellRendererToggle. It is relatively easy to write a
|
||||
including the `GtkCellRendererText`, `GtkCellRendererPixbuf` and
|
||||
the `GtkCellRendererToggle`. It is relatively easy to write a
|
||||
custom renderer.
|
||||
|
||||
A #GtkTreeViewColumn is the object that GtkTreeView uses to organize
|
||||
A `GtkTreeViewColumn` is the object that `GtkTreeView` uses to organize
|
||||
the vertical columns in the tree view. It needs to know the name of
|
||||
the column to label for the user, what type of cell renderer to use,
|
||||
and which piece of data to retrieve from the model for a given row.
|
||||
@ -166,7 +166,7 @@ created and columns are added to it.
|
||||
Most applications will need to not only deal with displaying data,
|
||||
but also receiving input events from users. To do this, simply get
|
||||
a reference to a selection object and connect to the
|
||||
#GtkTreeSelection::changed signal.
|
||||
`GtkTreeSelection::changed` signal.
|
||||
|
||||
``` {.c}
|
||||
/* Prototype for selection handler callback */
|
||||
@ -205,11 +205,11 @@ tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
|
||||
|
||||
## Simple Example
|
||||
|
||||
Here is a simple example of using a #GtkTreeView widget in context
|
||||
Here is a simple example of using a `GtkTreeView` widget in context
|
||||
of the other widgets. It simply creates a simple model and view,
|
||||
and puts them together. Note that the model is never populated
|
||||
with data — that is left as an exercise for the reader.
|
||||
More information can be found on this in the #GtkTreeModel section.
|
||||
with data — that is left as an exercise for the reader.
|
||||
More information can be found on this in the `GtkTreeModel` section.
|
||||
|
||||
``` {.c}
|
||||
enum
|
||||
|
||||
Loading…
Reference in New Issue
Block a user