[gtk/matthiasc/for-master: 19/41] docs: Clean up docs syntax
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/matthiasc/for-master: 19/41] docs: Clean up docs syntax
- Date: Sun, 23 May 2021 00:56:50 +0000 (UTC)
commit 2d0957b7324c51144cee78c2c1aa33c38e7883d9
Author: Matthias Clasen <mclasen redhat com>
Date: Wed May 19 23:40:14 2021 -0400
docs: Clean up docs syntax
Replace leftover gtk-doc syntax (#Type) with backquotes.
docs/reference/gdk/keys.md | 4 +-
docs/reference/gtk/migrating-3to4.md | 712 ++++++++++++++--------------
docs/reference/gtk/question_index.md | 138 +++---
docs/reference/gtk/section-accessibility.md | 58 +--
docs/reference/gtk/section-list-widget.md | 106 ++---
docs/reference/gtk/section-text-widget.md | 54 +--
docs/reference/gtk/section-tree-widget.md | 32 +-
7 files changed, 565 insertions(+), 539 deletions(-)
---
diff --git a/docs/reference/gdk/keys.md b/docs/reference/gdk/keys.md
index e44d0e13ce..c377a90ddd 100644
--- a/docs/reference/gdk/keys.md
+++ b/docs/reference/gdk/keys.md
@@ -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
diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md
index ea7b4cefd6..4092ad721e 100644
--- a/docs/reference/gtk/migrating-3to4.md
+++ b/docs/reference/gtk/migrating-3to4.md
@@ -54,7 +54,7 @@ G_ENABLE_DIAGNOSTIC=1 ./your-app
### Do not use GTK-specific command line arguments
-GTK4 does not parse command line arguments any more. If you are using
+GTK 4 does not parse command line arguments any more. If you are using
command line arguments like `--gtk-debug` you should use the `GTK_DEBUG`
environment variable instead. If you are using `--g-fatal-warnings` for
debugging purposes, you should use the `G_DEBUG` environment variable, as
@@ -103,7 +103,7 @@ useful when dealing with RGBA visuals.
GTK 4 removes these [class Gtk Box] child properties, so you should stop using
them. You can replace `GtkBox:padding` using `GtkWidget`'s `margin-*` properties
-on your [class Gtk Box] child widgets.
+on your child widgets.
The fill child property can be replaced by setting appropriate values for
the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties
@@ -114,7 +114,7 @@ horizontal box, `valign` for a vertical one.
[class Gtk Box] also uses the expand child property. It can be replaced by
setting [property@Gtk.Widget:hexpand] or [property@Gtk.Widget:vexpand] on
-the child widgets. To match the old behavior of the #GtkBox's expand child
+the child widgets. To match the old behavior of the `GtkBox`'s expand child
property, you need to set `hexpand` on the child widgets of a horizontal
`GtkBox` and `vexpand` on the child widgets of a vertical `GtkBox`.
@@ -146,7 +146,7 @@ The functions and properties related to automatically add a
control its visibility, are not supported in GTK 4. Instead, you can just
pack a GtkImage inside a GtkButton, and control its visibility like you
would for any other widget. If you only want to add a named icon to a
-GtkButton, you can use [`ctor@Gtk.Button.new_from_icon_name`].
+GtkButton, you can use [ctor@Gtk.Button.new_from_icon_name].
### Stop using `GtkWidget` event signals
@@ -157,30 +157,30 @@ for this change.
| Signal | Event controller |
| --- | --- |
-| ::event | #GtkEventControllerLegacy |
-| ::event-after | #GtkEventControllerLegacy |
-| ::button-press-event | #GtkGestureClick |
-| ::button-release-event | #GtkGestureClick |
+| ::event | [class@Gtk.EventControllerLegacy] |
+| ::event-after | [class@Gtk.EventControllerLegacy] |
+| ::button-press-event | [class@Gtk.GestureClick] |
+| ::button-release-event | [class@Gtk.GestureClick] |
| ::touch-event | various touch gestures |
-| ::scroll-event | #GtkEventControllerScroll |
-| ::motion-notify-event | #GtkEventControllerMotion |
+| ::scroll-event | [class@Gtk.EventControllerScroll] |
+| ::motion-notify-event | [class@Gtk.EventControllerMotion] |
| ::delete-event | - |
-| ::key-press-event | #GtkEventControllerKey |
-| ::key-release-event | #GtkEventControllerKey |
-| ::enter-notify-event | #GtkEventControllerMotion |
-| ::leave-notify-event | #GtkEventControllerMotion |
+| ::key-press-event | [class@Gtk.EventControllerKey] |
+| ::key-release-event | [class@Gtk.EventControllerKey] |
+| ::enter-notify-event | [class@Gtk.EventControllerMotion] |
+| ::leave-notify-event | [class@Gtk.EventControllerMotion] |
| ::configure-event | - |
-| ::focus-in-event | #GtkEventControllerFocus |
-| ::focus-out-event | #GtkEventControllerFocus |
+| ::focus-in-event | [class@Gtk.EventControllerFocus] |
+| ::focus-out-event | [class@Gtk.EventControllerFocus] |
| ::map-event | - |
| ::unmap-event | - |
-| ::property-notify-event | replaced by #GdkClipboard |
-| ::selection-clear-event | replaced by #GdkClipboard |
-| ::selection-request-event | replaced by #GdkClipboard |
-| ::selection-notify-event | replaced by #GdkClipboard |
-| Drag-and-Drop signals | #GtkDragSource, #GtkDropTarget |
-| ::proximity-in-event | #GtkGestureStylus |
-| ::proximity-out-event | #GtkGestureStylus |
+| ::property-notify-event | replaced by [class@Gdk.Clipboard] |
+| ::selection-clear-event | replaced by [class@Gdk.Clipboard] |
+| ::selection-request-event | replaced by [class@Gdk.Clipboard] |
+| ::selection-notify-event | replaced by [class@Gdk.Clipboard] |
+| Drag-and-Drop signals | [class@Gtk.DragSource], [class@Gtk.DropTarget] |
+| ::proximity-in-event | [class@Gtk.GestureStylus] |
+| ::proximity-out-event | [class@Gtk.GestureStylus] |
| ::visibility-notify-event | - |
| ::window-state-event | - |
| ::damage-event | - |
@@ -217,6 +217,14 @@ using `GMainContext` APIs. The replacement for `gtk_events_pending()` is
`g_main_context_pending()`, the replacement for `gtk_main_iteration()` is
`g_main_context_iteration()`.
+Here is a replacement that will iterate the default main loop until
+all windows have been closed:
+
+```
+while (g_list_model_get_n_items (gtk_window_get_toplevels ()) > 0)
+ g_main_context_iteration (NULL, TRUE);
+```
+
### Reduce the use of `gtk_widget_destroy()`
GTK 4 introduces a [method@Gtk.Window.destroy] api. While that is not available
@@ -272,8 +280,8 @@ and cause the whole widget hierarchy to be finalized unless there are other
references that keep widgets alive.
The [signals@Gtk.Widget::destroy] signal is emitted when a widget is
-disposed, and therefore can no longer be used to break reference cycles. A
-typical sign of a reference cycle involving a toplevel window is when
+disposed, and therefore can no longer be used to break reference cycles.
+A typical sign of a reference cycle involving a toplevel window is when
closing the window does not make the application quit.
### Stop using GdkScreen
@@ -286,7 +294,7 @@ have been added to `GdkDisplay`.
The root window is an X11-centric concept that is no longer exposed in the
backend-neutral GDK API. If you need to interact with the X11 root window,
-you can use `gdk_x11_display_get_xrootwindow()` to get its XID.
+you can use [method@GdkX11.Display.get_xrootwindow] to get its XID.
### Stop using `GdkVisual`
@@ -295,7 +303,7 @@ without replacement.
### Stop using `GdkDeviceManager`
-The GdkDeviceManager object has been removed in GTK 4. Most of its APIs already
+The `GdkDeviceManager` object has been removed in GTK 4. Most of its APIs already
had replacements in GTK 3 and were deprecated in favor of `GdkSeat`.
### Adapt to `GdkWindow` API changes
@@ -305,13 +313,14 @@ had replacements in GTK 3 and were deprecated in favor of `GdkSeat`.
In GTK 4, the two roles of a standalone toplevel window and of a popup that
is placed relative to a parent window have been separated out into two
interfaces, [class@Gdk.Toplevel] and [class@Gdk.Popup]. Surfaces
-implementing these interfaces are created with `gdk_surface_new_toplevel()`
-and `gdk_surface_new_popup()`, respectively, and they are presented on
-screen using `gdk_toplevel_present()` and `gdk_popup_present()`. The
-`present()` functions take parameters in the form of an auxiliary layout
-struct, [struct@Gdk.PopupLayout] or [struct@Gdk.ToplevelLayout]. If your
-code is dealing directly with surfaces, you may have to change it to call
-the API in these interfaces, depending on whether the surface you are
+implementing these interfaces are created with [ctor@Gdk.Surface.new_toplevel]
+and [ctor@Gdk.Surface.new_popup], respectively, and they are presented on
+screen using [method@Gdk.Toplevel.present] and [method@Gdk.Popup.present].
+The `present()` functions take parameters in the form of an auxiliary layout
+struct, [struct@Gdk.PopupLayout] or [struct@Gdk.ToplevelLayout].
+
+If your code is dealing directly with surfaces, you may have to change it
+to call the API in these interfaces, depending on whether the surface you are
dealing with is a toplevel or a popup.
As part of this reorganization, X11-only concepts such as sticky,
@@ -320,8 +329,7 @@ removed or moved to X11 backend api. If you need to use them on your
X11 windows, you will have to use those backend apis or set the
corresponding X11 properties (as specified in the EWMH) yourself.
-Subsurfaces are only supported with the Wayland backend, using
-`gdk_wayland_surface_new_subsurface()`. Native and foreign subwindows
+Subsurfaces are not currently supported. Native and foreign subwindows
are no longer supported. These concepts were complicating the code
and could not be supported across backends.
@@ -333,9 +341,9 @@ windows, you you will have to use Xlib apis.
A number of minor API cleanups have happened in `GdkSurface`
as well. For example, `gdk_surface_input_shape_combine_region()`
-has been renamed to `gdk_surface_set_input_region()`, and
+has been renamed to [method@Gdk.Surface.set_input_region], and
`gdk_surface_begin_resize_drag()` has been renamed to
-`gdk_toplevel_begin_resize()`.
+[method@Gdk.Toplevel.begin_resize].
### The "iconified" window state has been renamed to "minimized"
@@ -343,8 +351,8 @@ The `GDK_TOPLEVEL_STATE_ICONIFIED` value of the `GdkSurfaceState` enumeration
is now `GDK_TOPLEVEL_STATE_MINIMIZED` in the `GdkToplevelState` enumeration.
The `GdkWindow` functions `gdk_window_iconify()` and
-`gdk_window_deiconify()` have been renamed to `gdk_toplevel_minimize()` and
-`gdk_toplevel_present()`, respectively.
+`gdk_window_deiconify()` have been renamed to [method@Gdk.Toplevel.minimize]
+and [method@Gdk.Toplevel.present], respectively.
The behavior of the minimization and unminimization operations have
not been changed, and they still require support from the underlying
@@ -353,27 +361,27 @@ windowing system.
### Adapt to `GdkEvent` API changes
Direct access to [class@Gdk.Event] structs is no longer possible in GTK 4.
-GdkEvent is now a strictly read-only type, and you can no longer
+`GdkEvent` is now a strictly read-only type, and you can no longer
change any of its fields, or construct new events. All event fields
have accessors that you will have to use.
Event compression is always enabled in GTK 4, for both motion and
scroll events. If you need to see the uncoalesced motion or scroll
-history, use `gdk_event_get_history()` on the latest event.
+history, use [method@Gdk.Event.get_history] on the latest event.
### Stop using grabs
GTK 4 no longer provides the `gdk_device_grab()` or `gdk_seat_grab()`
apis. If you need to dismiss a popup when the user clicks outside
(the most common use for grabs), you can use the `GdkPopup`
-`GdkPopup:autohide` property instead. [class@Gtk.Popover] also has a
-`GtkPopover:autohide` property for this. If you need to prevent
-the user from interacting with a window while a dialog is open,
-use the [property@Gtk.Window:modal] property of the dialog.
+[property@Gdk.Popup:autohide] property instead. [class@Gtk.Popover]
+also has a [property@Gtk.Popover:autohide] property for this. If you
+need to prevent the user from interacting with a window while a dialog
+is open, use the [property@Gtk.Window:modal] property of the dialog.
### Adapt to coordinate API changes
-A number of coordinate APIs in GTK 3 had `double` variants:
+A number of coordinate APIs in GTK 3 had `double` variants:
`gdk_device_get_surface_at_position()`, `gdk_surface_get_device_position()`.
These have been changed to use doubles, and the `double` variants
have been removed. Update your code accordingly.
@@ -389,11 +397,18 @@ or `gdk_event_get_root_coords()`.
`GdkKeymap` no longer exists as an independent object.
If you need access to keymap state, it is now exposed as properties
-on the `GdkDevice` representing the keyboard: `GdkDevice:direction`,
-`GdkDevice:has-bidi-layouts`, `GdkDevice:caps-lock-state`,
-`GdkDevice:num-lock-state`, `GdkDevice:scroll-lock-state` and
-`GdkDevice:modifier-state`. To obtain the keyboard device, you can use
-`gdk_seat_get_keyboard (gdk_display_get_default_seat (display)`.
+on the `GdkDevice` representing the keyboard:
+[property@Gdk.Device:direction],
+[property@Gdk.Device:has-bidi-layouts],
+[property@Gdk.Device:caps-lock-state],
+[property@Gdk.Device:num-lock-state],
+[property@Gdk.Device:scroll-lock-state] and
+[property@Gdk.Device:modifier-state]. To obtain the keyboard device,
+you can use
+
+```
+gdk_seat_get_keyboard (gdk_display_get_default_seat (display)
+```
If you need access to translated keys for event handling, `GdkEvent`
now includes all of the translated key state, including consumed
@@ -402,9 +417,10 @@ manually call `gdk_keymap_translate_keyboard_state()` (which has
been removed).
If you need to do forward or backward mapping between key codes
-and key values, use `gdk_display_map_keycode()` and `gdk_display_map_keyval()`,
-which are the replacements for `gdk_keymap_get_entries_for_keycode()`
-and `gdk_keymap_get_entries_for_keyval()`.
+and key values, use [method@Gdk.Display.map_keycode] and
+[method@Gdk.Display.map_keyval], which are the replacements for
+`gdk_keymap_get_entries_for_keycode()` and
+`gdk_keymap_get_entries_for_keyval()`.
### Adapt to changes in keyboard modifier handling
@@ -509,7 +525,7 @@ replaced by their corresponding GType:
| `gtk_clipboard_request_uris()` |` GDK_TYPE_FILE_LIST` |
**Note**: Support for rich text serialization across different processes
-for #GtkTextBuffer is not available any more.
+for `GtkTextBuffer` is not available any more.
If you are copying the contents of an image, it is recommended to use
`GDK_TYPE_PAINTABLE` instead of `GDK_TYPE_PIXBUF`, to minimize the amount of
@@ -519,7 +535,7 @@ potential copies.
The function `gtk_get_current_event()` and its variants have been
replaced by equivalent event controller APIs:
-`gtk_event_controller_get_current_event()`, etc.
+[method@Gtk.EventController.get_current_event], etc.
### Convert your UI files
@@ -535,14 +551,14 @@ The `<requires>` tag now supports for the `lib` attribute the
`gtk_builder_connect_signals()` no longer exists. Instead, signals are
always connected automatically. If you need to add user data to your
-signals, `gtk_builder_set_current_object()` must be called. An important
+signals, [method@Gtk.Builder.set_current_object] must be called. An important
caveat is that you have to do this before loading any XML. This means if
-you need to use `gtk_builder_set_current_object()`, you can no longer use
-`gtk_builder_new_from_file()`, `gtk_builder_new_from_resource()`, or
-`gtk_builder_new_from_string()`. Instead, you must use vanilla `gtk_builder_new()`,
-then call `gtk_builder_set_current_object()`, then load the XML using
-`gtk_builder_add_from_file()`, `gtk_builder_add_from_resource()`, or
-`gtk_builder_add_from_string()`. You must check the return value for
+you need to use [method@Gtk.Builder.set_current_object], you can no longer use
+[ctor@Gtk.Builder.new_from_file], [ctor@Gtk.Builder.new_from_resource], or
+[ctor@Gtk.Builder.new_from_string]. Instead, you must use vanilla [ctor Gtk Builder new],
+then call [method@Gtk.Builder.set_current_object], then load the XML using
+[method@Gtk.Builder.add_from_file], [method@Gtk.Builder.add_from_resource], or
+[method@Gtk.Builder.add_from_string]. You must check the return value for
failure and manually abort with `g_error()` if something went wrong.
You only have to worry about this if you were previously using
@@ -561,21 +577,21 @@ and has lost its area property. A [class@Gtk.EventControllerFocus] has been
split off from [class@Gtk.EventControllerKey].
In GTK 3, `GtkEventController:widget` was a construct-only property, so a
-`GtkWidget` was provided whenever constructing a `GtkEventController`. In
+`GtkWidget` was provided whenever constructing a `GtkEventController`. In
GTK 4, [property@Gtk.EventController:widget] is now read-only. Use
-[`method@Gtk.Widget.add_controller`] to add an event controller to a widget.
+[method@Gtk.Widget.add_controller] to add an event controller to a widget.
In GTK 3, widgets did not own their event controllers, and event
controllers did not own their widgets, so developers were responsible
for manually keeping event controllers alive for the lifetime of their
associated widgets. In GTK 4, widgets own their event controllers.
-[`method@Gtk.Widget.add_controller`] takes ownership of the event controller, so
+[method@Gtk.Widget.add_controller] takes ownership of the event controller, so
there is no longer any need to store a reference to the event controller
after it has been added to a widget.
Although not normally needed, an event controller could be removed from
a widget in GTK 3 by destroying the event controller with `g_object_unref()`.
-In GTK 4, you must use [`method@Gtk.Widget.remove_controller()`].
+In GTK 4, you must use [method@Gtk.Widget.remove_controller].
### Focus handling changes
@@ -599,15 +615,15 @@ case that the scrollable is a [class@Gtk.Viewport], use
The APIs for keyboard shortcuts and accelerators have changed in GTK 4.
Instead of `GtkAccelGroup`, you now use a [class@Gtk.ShortcutController] with global
-scope, and instead of `GtkBindingSet`, you now use `gtk_widget_class_add_shortcut()`,
-`gtk_widget_class_add_binding()` and its variants. In both cases, you probably
+scope, and instead of `GtkBindingSet`, you now use [method@Gtk.WidgetClass.add_shortcut],
+[method@Gtk.WidgetClass.add_binding] and its variants. In both cases, you probably
want to add actions that can be triggered by your shortcuts.
There is no direct replacement for loading and saving accelerators with
`GtkAccelMap`. But since `GtkShortcutController` implements `GListModel` and
both [class@Gtk.ShortcutTrigger] and [class@Gtk.ShortcutAction] can be
serialized to strings, it is relatively easy to implement saving and loading
-yourself.
+yourself.
### Stop using `GtkEventBox`
@@ -634,22 +650,22 @@ X11-specific have been removed. This includes `gtk_window_set_geometry_hints()`,
`gtk_window_begin_resize_drag()`, `gtk_window_begin_move_drag()`.
Most likely, you should just stop using them. In some cases, you can
fall back to using the underlying `GdkToplevel` APIs (for example,
-`gdk_toplevel_begin_resize()`).
+[method@Gdk.Toplevel.begin_resize]).
The APIs for controlling `GtkWindow` size have changed to be better aligned
with the way size changes are integrated in the frame cycle. `gtk_window_resize()`
and `gtk_window_get_size()` have been removed. Instead, use
-`gtk_window_set_default_size()` and `gtk_window_get_default_size()`.
+[method@Gtk.Window.set_default_size] and [method@Gtk.Window.get_default_size].
### Adapt to `GtkHeaderBar` and `GtkActionBar` API changes
The `gtk_header_bar_set_show_close_button()` function has been renamed to
-the more accurate name [`method@Gtk.HeaderBar.set_show_title_buttons`]. The
+the more accurate name [method@Gtk.HeaderBar.set_show_title_buttons]. The
corresponding getter and the property itself have also been renamed.
The default value of the property is now `TRUE` instead of `FALSE`.
The `gtk_header_bar_set_custom_title()` function has been renamed to
-the more accurate name [`method@Gtk.HeaderBar.set_title_widget`]. The
+the more accurate name [method@Gtk.HeaderBar.set_title_widget]. The
corresponding getter and the property itself have also been renamed.
The `gtk_header_bar_set_title()` function has been removed along with its
@@ -680,210 +696,216 @@ have unusual needs for custom headerbars, these might be useful to you.
The `:pack-type` child properties of `GtkHeaderBar` and `GtkActionBar` have
been removed. If you need to programmatically place children, use the
-`pack_start()` and `pack_end()` methods. In UI files, use the `type` attribute
-on the `child` element.
+[method@Gtk.HeaderBar.pack_start] and [method@Gtk.HeaderBar.pack_end] methods.
+In UI files, use the `type` attribute on the `child` element.
The `gtk4-builder-tool` utility can help with this conversion, with the
`--3to4` option of the `simplify` command.
### Adapt to GtkStack, GtkAssistant and GtkNotebook API changes
-The child properties of GtkStack, GtkAssistant and GtkNotebook have been
+The child properties of `GtkStack`, `GtkAssistant` and `GtkNotebook` have been
converted into child meta objects.
-Instead of gtk_container_child_set (stack, child, …), you can now use
-g_object_set (gtk_stack_get_page (stack, child), …). In .ui files, the
-GtkStackPage objects must be created explicitly, and take the child widget
-as property. The changes to GtkNotebook and GtkAssistant are similar.
-gtk4-builder-tool can help with this conversion, with the --3to4 option
-of the simplify command.
+Instead of `gtk_container_child_set (stack, child, …)`, you can now use
+`g_object_set (gtk_stack_get_page (stack, child), …)`. In .ui files, the
+`GtkStackPage` objects must be created explicitly, and take the child widget
+as property. The changes to `GtkNotebook` and `GtkAssistant` are similar.
+
+`gtk4-builder-tool` can help with this conversion, with the `--3to4` option
+of the `simplify` command.
### Adapt to button class hierarchy changes
-#GtkCheckButton is no longer derived from #GtkToggleButton. Call
-gtk_check_button_set_active() instead of gtk_toggle_button_set_active().
+`GtkCheckButton` is no longer derived from `GtkToggleButton`. Call
+[method@Gtk.CheckButton.set_active] instead of [method@Gtk.ToggleButton.set_active].
-#GtkRadioButton has been removed, and its grouping functionality has
-been added to #GtkCheckButton and #GtkToggleButton. Use grouped
+`GtkRadioButton` has been removed, and its grouping functionality has
+been added to `GtkCheckButton` and `GtkToggleButton`. Use grouped
check buttons for traditional radio groups, and used grouped toggle
buttons for view switchers. The new API to set up groups of buttons
-is gtk_check_button_set_group() and gtk_toggle_button_set_group().
+is [method@Gtk.CheckButton.set_group] and [method@Gtk.ToggleButton.set_group].
-gtk4-builder-tool can help with this conversion, with the --3to4 option
-of the simplify command.
+`gtk4-builder-tool` can help with this conversion, with the `--3to4` option
+of the `simplify` command.
### Adapt to GtkScrolledWindow API changes
-The constructor for GtkScrolledWindow no longer takes the adjustments
-as arguments - these were almost always %NULL.
+The constructor for `GtkScrolledWindow` no longer takes the adjustments
+as arguments - these were almost always `NULL`.
### Adapt to GtkBin removal
-The abstract base class GtkBin for single-child containers has been
-removed. The former subclasses are now derived directly from GtkWidget,
+The abstract base class `GtkBin` for single-child containers has been
+removed. The former subclasses are now derived directly from `GtkWidget`,
and have a "child" property for their child widget. To add a child, use
-the setter for the "child" property (e.g. gtk_frame_set_child()) instead
-of gtk_container_add(). Adding a child in a ui file with <child> still works.
+the setter for the "child" property (e.g. [method@Gtk.Frame.set_child]) instead
+of `gtk_container_add()`. Adding a child in a ui file with <child> still works.
The affected classes are:
-- GtkAspectFrame
-- GtkButton (and subclasses)
-- GtkComboBox
-- GtkFlowBoxChild
-- GtkFrame
-- GtkListBoxRow
-- GtkOverlay
-- GtkPopover
-- GtkRevealer
-- GtkScrolledWindow
-- GtkSearchBar
-- GtkViewport
-- GtkWindow (and subclasses)
-
-If you have custom widgets that were derived from GtkBin, you should
-port them to derive from GtkWidget. Notable vfuncs that you will have
-to implement include dispose() (to unparent your child), compute_expand()
-(if you want your container to propagate expand flags) and
-get_request_mode() (if you want your container to support height-for-width.
-
-You may also want to implement the GtkBuildable interface, to support
+- [class@Gtk.AspectFrame]
+- [class@Gtk.Button] (and subclasses)
+- [class@Gtk.ComboBox]
+- [class@Gtk.FlowBoxChild]
+- [class@Gtk.Frame]
+- [class@Gtk.ListBoxRow]
+- [class@Gtk.Overlay]
+- [class@Gtk.Popover]
+- [class@Gtk.Revealer]
+- [class@Gtk.ScrolledWindow]
+- [class@Gtk.SearchBar]
+- [class@Gtk.Viewport]
+- [class@Gtk.Window] (and subclasses)
+
+If you have custom widgets that were derived from `GtkBin`, you should
+port them to derive from `GtkWidget`. Notable vfuncs that you will have
+to implement include the `GObject` dispose vfunc (to unparent your child),
+[vfunc@Gtk.Widget.compute_expand] (if you want your container to propagate
+expand flags) and [vfunc@Gtk.Widget.get_request_mode] (if you want your
+container to support height-for-width).
+
+You may also want to implement the [iface@Gtk.Buildable] interface, to support
adding children with <child> in ui files.
### Adapt to GtkContainer removal
-The abstract base class GtkContainer for general containers has been
-removed. The former subclasses are now derived directly from GtkWidget,
+The abstract base class `GtkContainer` for general containers has been
+removed. The former subclasses are now derived directly from `GtkWidget`,
and have class-specific add() and remove() functions.
-The most noticeable change is the use of gtk_box_append() or gtk_box_prepend()
-instead of gtk_container_add() for adding children to GtkBox, and the change
-to use container-specific remove functions, such as gtk_stack_remove() instead
-of gtk_container_remove(). Adding a child in a ui file with <child> still works.
+
+The most noticeable change is the use of [method Gtk Box.append] or [method Gtk Box.prepend]
+instead of `gtk_container_add()` for adding children to `GtkBox`, and the change
+to use container-specific remove functions, such as [method@Gtk.Stack.remove] instead
+of `gtk_container_remove()`. Adding a child in a ui file with <child> still works.
The affected classes are:
-- GtkActionBar
-- GtkBox (and subclasses)
-- GtkExpander
-- GtkFixed
-- GtkFlowBox
-- GtkGrid
-- GtkHeaderBar
-- GtkIconView
-- GtkInfoBar
-- GtkListBox
-- GtkNotebook
-- GtkPaned
-- GtkStack
-- GtkTextView
-- GtkTreeView
-
-Without GtkContainer, there are no longer facilities for defining and
+- [class@Gtk.ActionBar]
+- [class Gtk Box] (and subclasses)
+- [class@Gtk.Expander]
+- [class@Gtk.Fixed]
+- [class@Gtk.FlowBox]
+- [class Gtk Grid]
+- [class@Gtk.HeaderBar]
+- [class@Gtk.IconView]
+- [class@Gtk.InfoBar]
+- [class@Gtk.ListBox]
+- [class@Gtk.Notebook]
+- [class@Gtk.Paned]
+- [class@Gtk.Stack]
+- [class@Gtk.TextView]
+- [class@Gtk.TreeView]
+
+Without `GtkContainer`, there are no longer facilities for defining and
using child properties. If you have custom widgets using child properties,
they will have to be converted either to layout properties provided
by a layout manager (if they are layout-related), or handled in some
other way. One possibility is to use child meta objects, as seen with
-#GtkAssistantPage, #GtkStackPage and the like.
+[class@Gtk.AssistantPage], [class@Gtk.StackPage] and the like.
The replacements for gtk_container_add() are:
| Widget | Replacement |
| ------ | ----------- |
-| GtkActionBar | gtk_action_bar_pack_start(), gtk_action_bar_pack_end() |
-| GtkBox | gtk_box_prepend(), gtk_box_append() |
-| GtkExpander | gtk_expander_set_child() |
-| GtkFixed | gtk_fixed_put() |
-| GtkFlowBox | gtk_flow_box_insert() |
-| GtkGrid | gtk_grid_attach() |
-| GtkHeaderBar | gtk_header_bar_pack_start(), gtk_header_bar_pack_end() |
-| GtkIconView | - |
-| GtkInfoBar | gtk_info_bar_add_child() |
-| GtkListBox | gtk_list_box_insert() |
-| GtkNotebook | gtk_notebook_append_page() |
-| GtkPaned | gtk_paned_set_start_child(), gtk_paned_set_end_child() |
-| GtkStack | gtk_stack_add_child() |
-| GtkTextView | gtk_text_view_add_child_at_anchor(), gtk_text_view_add_overlay() |
-| GtkTreeView | - |
+| `GtkActionBar` | [method@Gtk.ActionBar.pack_start], [method@Gtk.ActionBar.pack_end] |
+| `GtkBox` | [method Gtk Box.prepend], [method Gtk Box.append] |
+| `GtkExpander` | [method@Gtk.Expander.set_child] |
+| `GtkFixed` | [method Gtk Fixed put] |
+| `GtkFlowBox` | [method@Gtk.FlowBox.insert] |
+| `GtkGrid` | [method Gtk Grid.attach] |
+| `GtkHeaderBar` | [method@Gtk.HeaderBar.pack_start], [method@Gtk.HeaderBar.pack_end] |
+| `GtkIconView` | - |
+| `GtkInfoBar` | [method@Gtk.InfoBar.add_child] |
+| `GtkListBox` | [method@Gtk.ListBox.insert] |
+| `GtkNotebook` | [method@Gtk.Notebook.append_page] |
+| `GtkPaned` | [method@Gtk.Paned.set_start_child], [method@Gtk.Paned.set_end_child] |
+| `GtkStack` | [method@Gtk.Stack.add_child] |
+| `GtkTextView` | [method@Gtk.TextView.add_child_at_anchor], [method@Gtk.TextView.add_overlay] |
+| `GtkTreeView` | - |
### Stop using GtkContainer::border-width
-GTK 4 has removed the #GtkContainer::border-width property (together
-with the rest of GtkContainer). Use other means to influence the spacing
+GTK 4 has removed the `GtkContainer::border-width` property (together
+with the rest of `GtkContainer`). Use other means to influence the spacing
of your containers, such as the CSS margin and padding properties on child
widgets, or the CSS border-spacing property on containers.
### Adapt to gtk_widget_destroy() removal
-The function gtk_widget_destroy() has been removed. To explicitly destroy
-a toplevel window, use gtk_window_destroy(). To destroy a widget that is
+The function `gtk_widget_destroy()` has been removed. To explicitly destroy
+a toplevel window, use [method@Gtk.Window.destroy]. To destroy a widget that is
part of a hierarchy, remove it from its parent using a container-specific
-remove API, such as gtk_box_remove() or gtk_stack_remove(). To destroy
-a freestanding non-toplevel widget, use g_object_unref() to drop your
+remove API, such as [method Gtk Box.remove] or [method@Gtk.Stack.remove]. To
+destroy a freestanding non-toplevel widget, use `g_object_unref()` to drop your
reference.
### Adapt to coordinate API changes
A number of APIs that are accepting or returning coordinates have
-been changed from ints to doubles: gtk_widget_translate_coordinates(),
-gtk_fixed_put(), gtk_fixed_move(). This change is mostly transparent,
+been changed from ints to doubles: `gtk_widget_translate_coordinates()`,
+`gtk_fixed_put()`, `gtk_fixed_move()`. This change is mostly transparent,
except for cases where out parameters are involved: you need to
pass double* now, instead of int*.
### Adapt to GtkStyleContext API changes
The getters in the GtkStyleContext API, such as
-gtk_style_context_get_property(), gtk_style_context_get(),
-or gtk_style_context_get_color() have lost their state argument,
+[method@Gtk.StyleContext.get_color], [method@Gtk.StyleContext.get_border],
+or [method@Gtk.StyleContext.get_margin] have lost their state argument,
and always use the context's current state. Update all callers
to omit the state argument.
-The most commonly used GtkStyleContext API, gtk_style_context_add_class(),
-has been moved to GtkWidget as gtk_widget_add_css_class(), as have the
-corresponding gtk_style_context_remove_class() and
-gtk_style_context_has_class() APIs.
+The most commonly used GtkStyleContext API, `gtk_style_context_add_class()`,
+has been moved to GtkWidget as [method@Gtk.Widget.add_css_class], as have the
+corresponding `gtk_style_context_remove_class()` and
+`gtk_style_context_has_class()` APIs.
### Adapt to GtkCssProvider API changes
-In GTK 4, the various #GtkCssProvider load functions have lost their
-#GError argument. If you want to handle CSS loading errors, use the
-#GtkCssProvider::parsing-error signal instead. gtk_css_provider_get_named()
-has been replaced by gtk_css_provider_load_named().
+In GTK 4, the various `GtkCssProvider` load functions have lost their
+`GError` argument. If you want to handle CSS loading errors, use the
+[signal@Gtk.CssProvider::parsing-error] signal instead. gtk_css_provider_get_named()
+has been replaced by [method@Gtk.CssProvider.load_named].
### Stop using GtkShadowType and GtkRelief properties
-The shadow-type properties in GtkScrolledWindow, GtkViewport,
-and GtkFrame, as well as the relief properties in GtkButton
-and its subclasses have been removed. GtkScrolledWindow, GtkButton
-and GtkMenuButton have instead gained a boolean has-frame
-property.
+The shadow-type properties in `GtkScrolledWindow`, `GtkViewport`,
+and `GtkFrame`, as well as the relief properties in `GtkButton`
+and its subclasses have been removed. `GtkScrolledWindow`, `GtkButton`
+and `GtkMenuButton` have instead gained a boolean has-frame property.
### Adapt to GtkWidget's size request changes
GTK 3 used five different virtual functions in GtkWidget to
-implement size requisition, namely the gtk_widget_get_preferred_width()
+implement size requisition, namely the `gtk_widget_get_preferred_width()`
family of functions. To simplify widget implementations, GTK 4 uses
-only one virtual function, GtkWidgetClass::measure() that widgets
-have to implement. gtk_widget_measure() replaces the various
-gtk_widget_get_preferred_ functions for querying sizes.
+only one virtual function, [vfunc@Gtk.Widget.measure], that widgets
+have to implement. [method@Gtk.Widget.measure] replaces the various
+`gtk_widget_get_preferred_` functions for querying sizes.
### Adapt to GtkWidget's size allocation changes
-The #GtkWidget.size_allocate() vfunc takes the baseline as an argument
-now, so you no longer need to call gtk_widget_get_allocated_baseline()
+The [vfunc@Gtk.Widget.size_allocate] vfunc takes the baseline as an argument
+now, so you no longer need to call `gtk_widget_get_allocated_baseline()`
to get it.
The ::size-allocate signal has been removed, since it is easy
to misuse. If you need to learn about sizing changes of custom
-drawing widgets, use the #GtkDrawingArea::resize or #GtkGLArea::resize
-signals. If you want to track the size of toplevel windows, use
-property notification for #GtkWindow:default-width and #GtkWindow:default-height.
+drawing widgets, use the [signal@Gtk.DrawingArea::resize] or
+[signal@Gtk.GLArea::resize] signals. If you want to track the size
+of toplevel windows, use property notification for
+[property@Gtk.Window:default-width] and [property@Gtk.Window:default-height].
### Switch to GtkWidget's children APIs
-In GTK 4, any widget can have children (and GtkContainer is gone).
+In GTK 4, any widget can have children (and `GtkContainer` is gone).
There is new API to navigate the widget tree, for use in widget
-implementations: gtk_widget_get_first_child(), gtk_widget_get_last_child(),
-gtk_widget_get_next_sibling(), gtk_widget_get_prev_sibling().
+implementations:
+[method@Gtk.Widget.get_first_child],
+[method@Gtk.Widget.get_last_child],
+[method@Gtk.Widget.get_next_sibling],
+[method@Gtk.Widget.get_prev_sibling].
### Don't use -gtk-gradient in your CSS
@@ -914,28 +936,28 @@ CSS. Just use regular border radius.
This area has seen the most radical changes in the transition from GTK 3
to GTK 4. Widgets no longer use a draw() function to render their contents
-to a cairo surface. Instead, they have a snapshot() function that creates
-one or more GskRenderNodes to represent their content. Third-party widgets
-that use a draw() function or a #GtkWidget::draw signal handler for custom
-drawing will need to be converted to use gtk_snapshot_append_cairo().
+to a cairo surface. Instead, they have a [vfunc@Gtk.Widget.snapshot] function
+that creates one or more GskRenderNodes to represent their content. Third-party
+widgets that use a draw() function or a `GtkWidget::draw` signal handler for
+custom drawing will need to be converted to use [method@Gtk.Snapshot.append_cairo].
-The auxiliary #GtkSnapshot object has APIs to help with creating render
+The auxiliary [class@Gtk.Snapshot] object has APIs to help with creating render
nodes.
-If you are using a #GtkDrawingArea for custom drawing, you need to switch
-to using gtk_drawing_area_set_draw_func() to set a draw function instead
-of connecting a handler to the #GtkWidget::draw signal.
+If you are using a `GtkDrawingArea` for custom drawing, you need to switch
+to using [method@Gtk.DrawingArea.set_draw_func] to set a draw function instead
+of connecting a handler to the `GtkWidget::draw` signal.
### Stop using APIs to query GdkSurfaces
A number of APIs for querying special-purpose windows have been removed,
-since these windows are no longer publicly available:
-gtk_tree_view_get_bin_window(), gtk_viewport_get_bin_window(),
-gtk_viewport_get_view_window().
+since these windows no longer exist:
+`gtk_tree_view_get_bin_window()`, `gtk_viewport_get_bin_window()`,
+`gtk_viewport_get_view_window()`.
### Widgets are now visible by default
-The default value of #GtkWidget:visible in GTK 4 is %TRUE, so you no
+The default value of [property@Gtk.Widget:visible] in GTK 4 is %TRUE, so you no
longer need to explicitly show all your widgets. On the flip side, you
need to hide widgets that are not meant to be visible from the start.
The only widgets that still need to be explicitly shown are toplevel
@@ -945,203 +967,208 @@ A convenient way to remove unnecessary property assignments like this
from ui files it run the command `gtk4-builder-tool simplify --replace`
on them.
-The function gtk_widget_show_all(), the #GtkWidget:no-show-all property
-and its getter and setter have been removed in GTK 4, so you should stop
+The function `gtk_widget_show_all()`, the `GtkWidget:no-show-all` property
+and its getter and setter have been removed in GTK 4, so you should stop
using them.
### Adapt to changes in animated hiding and showing of widgets
-Widgets that appear and disappear with an animation, such as GtkPopover,
-GtkInfoBar, GtkRevealer no longer use gtk_widget_show() and gtk_widget_hide()
-for this, but have gained dedicated APIs for this purpose that you should
-use instead.
+Widgets that appear and disappear with an animation, such as
+`GtkInfoBar`, `GtkRevealer` no longer use `gtk_widget_show()` and
+`gtk_widget_hide()` for this, but have gained dedicated APIs for this
+purpose that you should use instead, such as [method@Gtk.InfoBar.set_revealed].
### Stop passing commandline arguments to gtk_init
-The gtk_init() and gtk_init_check() functions no longer accept commandline
-arguments. Just call them without arguments. Other initialization functions
-that were purely related to commandline argument handling, such as
-gtk_parse_args() and gtk_get_option_group(), are gone.
+The [func Gtk init] and [func@Gtk.init_check] functions no longer accept
+commandline arguments. Just call them without arguments. Other initialization
+functions that were purely related to commandline argument handling, such as
+`gtk_parse_args()` and `gtk_get_option_group()`, are gone.
The APIs to initialize GDK separately are also gone, but it is very unlikely
that you are affected by that.
### GdkPixbuf is deemphasized
-A number of #GdkPixbuf-based APIs have been removed. The available replacements
-are either using #GIcon, or the newly introduced #GdkTexture or #GdkPaintable
-classes instead. If you are dealing with pixbufs, you can use
-gdk_texture_new_for_pixbuf() to convert them to texture objects where needed.
+A number of `GdkPixbuf`-based APIs have been removed. The available replacements
+are either using `GIcon`, or the newly introduced [class@Gdk.Texture] or
+[iface@Gdk.Paintable] classes instead. If you are dealing with pixbufs, you can use
+[ctor@Gdk.Texture.new_for_pixbuf] to convert them to texture objects where needed.
### GtkWidget event signals are removed
-Event controllers and #GtkGestures have already been introduced in GTK 3 to handle
+Event controllers and GtkGestures have already been introduced in GTK 3 to handle
input for many cases. In GTK 4, the traditional widget signals for handling input,
-such as #GtkWidget::motion-event or #GtkWidget::event have been removed. All event
+such as `GtkWidget::motion-event` or `GtkWidget::event` have been removed. All event
handling is done via event controllers now.
### Invalidation handling has changed
-Only gtk_widget_queue_draw() is left to mark a widget as needing redraw.
-Variations like gtk_widget_queue_draw_rectangle() or gtk_widget_queue_draw_region()
+Only [method@Gtk.Widget.queue_draw] is left to mark a widget as needing redraw.
+Variations like `gtk_widget_queue_draw_rectangle()` or `gtk_widget_queue_draw_region()`
are no longer available.
### Stop using GtkWidget::draw
-The #GtkWidget::draw signal has been removed. Widgets need to implement the
-#GtkWidgetClass.snapshot() function now. Connecting draw signal handlers is
+The `GtkWidget::draw` signal has been removed. Widgets need to implement the
+[vfunc@Gtk.Widget.snapshot] function now. Connecting draw signal handlers is
no longer possible. If you want to keep using cairo for drawing, use
-gtk_snaphot_append_cairo().
+[method@Gtk.Snapshot.append_cairo].
### Window content observation has changed
Observing widget contents and widget size is now done by using the
-#GtkWidgetPaintable object instead of connecting to widget signals.
+[class@Gtk.WidgetPaintable] object instead of connecting to widget signals.
### Monitor handling has changed
-Instead of a monitor number, #GdkMonitor is now used throughout.
-gdk_display_get_monitors() returns the list of monitors that can be queried
-or observed for monitors to pass to APIs like gtk_window_fullscreen_on_monitor().
+Instead of a monitor number, [class@Gdk.Monitor] is now used throughout.
+[method@Gdk.Display.get_monitors] returns the list of monitors that can be queried
+or observed for monitors to pass to APIs like [method@Gtk.Window.fullscreen_on_monitor].
### Adapt to monitor API changes
-The gdk_monitor_get_workarea() API is gone. Individual backends can still
-provide this information, for example with gdk_x11_monitor_get_workarea().
+The `gdk_monitor_get_workarea()` API is gone. Individual backends can still
+provide this information, for example with [method@GdkX11.Monitor.get_workarea].
If you use this information, your code should check which backend is in
use and then call the appropriate backend API.
### Adapt to cursor API changes
-Use the new gtk_widget_set_cursor() function to set cursors, instead of
+Use the new [method@Gtk.Widget.set_cursor] function to set cursors, instead of
setting the cursor on the underlying window directly. This is necessary
because most widgets don't have their own window anymore, turning any
such calls into global cursor changes.
-For creating standard cursors, gdk_cursor_new_for_display() has been removed,
-you have to use cursor names instead of GdkCursorType. For creating custom cursors,
-use gdk_cursor_new_from_texture(). The ability to get cursor images has been removed.
+For creating standard cursors, `gdk_cursor_new_for_display()` has been removed,
+you have to use cursor names instead of `GdkCursorType`. For creating custom cursors,
+use [ctor@Gdk.Cursor.new_from_texture]. The ability to get cursor images has been removed.
### Adapt to icon size API changes
Instead of the existing extensible set of symbolic icon sizes, GTK now only
-supports normal and large icons with the #GtkIconSize enumeration. The actual sizes
+supports normal and large icons with the [enum@Gtk.IconSize] enumeration. The actual sizes
can be defined by themes via the CSS property -gtk-icon-size.
-GtkImage setters like gtk_image_set_from_icon_name() no longer take a #GtkIconSize
-argument. You can use the separate gtk_image_set_icon_size() setter if you need
+GtkImage setters like [method@Gtk.Image.set_from_icon_name] no longer take a `GtkIconSize`
+argument. You can use the separate [method@Gtk.Image.set_icon_size] setter if you need
to override the icon size.
The :stock-size property of GtkCellRendererPixbuf has been renamed to
-#GtkCellRendererPixbuf:icon-size.
+[property@Gtk.CellRendererPixbuf:icon-size].
### Adapt to changes in the GtkAssistant API
-The :has-padding property is gone, and GtkAssistant no longer adds padding
+The :has-padding property is gone, and `GtkAssistant` no longer adds padding
to pages. You can easily do that yourself.
### Adapt to changes in the API of GtkEntry, GtkSearchEntry and GtkSpinButton
-The GtkEditable interface has been made more useful, and the core functionality of
-GtkEntry has been broken out as a GtkText widget. GtkEntry, GtkSearchEntry,
-GtkSpinButton and the new GtkPasswordEntry now use a GtkText widget internally
-and implement GtkEditable. In particular, this means that it is no longer
-possible to use GtkEntry API such as gtk_entry_grab_focus_without_selecting()
+The [iface@Gtk.Editable] interface has been made more useful, and the core functionality of
+`GtkEntry` has been broken out as a [class Gtk Text] widget.
+[class@Gtk.Entry],
+[class@Gtk.SearchEntry],
+[class@Gtk.SpinButton] and the new
+[class@Gtk.PasswordEntry] now use a [class Gtk Text] widget internally
+and implement [iface@Gtk.Editable]. In particular, this means that it is no longer
+possible to use `GtkEntry` API such as `gtk_entry_grab_focus_without_selecting()`
on a search entry.
-Use GtkEditable API for editable functionality, and widget-specific APIs for
+Use `GtkEditable` API for editable functionality, and widget-specific APIs for
things that go beyond the common interface. For password entries, use
-GtkPasswordEntry. As an example, gtk_spin_button_set_max_width_chars()
-has been removed in favor of gtk_editable_set_max_width_chars().
+[class@Gtk.PasswordEntry]. As an example, `gtk_spin_button_set_max_width_chars()`
+has been removed in favor of [method@Gtk.Editable.set_max_width_chars].
### Adapt to changes in GtkOverlay API
The GtkOverlay :pass-through child property has been replaced by the
-#GtkWidget:can-target property. Note that they have the opposite sense:
+[property@Gtk.Widget:can-target] property. Note that they have the opposite sense:
pass-through == !can-target.
### Use GtkFixed instead of GtkLayout
-Since GtkScrolledWindow can deal with widgets that do not implement
-the GtkScrollable interface by automatically wrapping them into a
-GtkViewport, GtkLayout is redundant, and has been removed in favor
-of the existing GtkFixed container widget.
+Since `GtkScrolledWindow` can deal with widgets that do not implement
+the `GtkScrollable` interface by automatically wrapping them into a
+`GtkViewport`, `GtkLayout` is redundant, and has been removed in favor
+of the existing [class@Gtk.Fixed] widget.
### Adapt to search entry changes
The way search entries are connected to global events has changed;
-gtk_search_entry_handle_event() has been dropped and replaced by
-gtk_search_entry_set_key_capture_widget() and
-gtk_event_controller_key_forward().
+`gtk_search_entry_handle_event()` has been dropped and replaced by
+[method@Gtk.SearchEntry.set_key_capture_widget] and
+[method@Gtk.EventControllerKey.forward].
### Adapt to GtkScale changes
-The default value of #GtkScale:draw-value has been changed to %FALSE.
+The default value of `GtkScale:draw-value` has been changed to %FALSE.
If you want your scales to draw values, you will have to set this
property explicitly now.
-gtk4-builder-tool can help with this conversion, with the --3to4 option
-of the simplify command.
+`gtk4-builder-tool` can help with this conversion, with the `--3to4` option
+of the `simplify` command.
### Stop using gtk_window_activate_default()
The handling of default widgets has been changed, and activating
-the default now works by calling gtk_widget_activate_default()
+the default now works by calling [method@Gtk.Widget.activate_default]
on the widget that caused the activation. If you have a custom widget
that wants to override the default handling, you can provide an
-implementation of the default.activate action in your widgets' action
+implementation of the "default.activate" action in your widgets' action
groups.
### Stop using gtk_widget_grab_default()
-The function gtk_widget_grab_default() has been removed. If you need
-to mark a widget as default, use gtk_window_set_default_widget() directly.
+The function `gtk_widget_grab_default()` has been removed. If you need
+to mark a widget as default, use [method@Gtk.Window.set_default_widget]
+directly.
### Stop setting ::has-default and ::has-focus in .ui files
-The special handling for the ::has-default and ::has-focus properties
+The special handling for the :has-default and :has-focus properties
has been removed. If you want to define the initial focus or the
-the default widget in a .ui file, set the ::default-widget or
-::focus-widget properties of the toplevel window.
+the default widget in a .ui file, set the [property@Gtk.Window:default-widget] or
+[property@Gtk.Window:focus-widget] properties of the toplevel window.
### Stop using the GtkWidget::display-changed signal
-To track the current display, use the #GtkWidget::root property instead.
+To track the current display, use the [property@Gtk.Widget:root] property instead.
### GtkPopover::modal has been renamed to autohide
-The modal property has been renamed to autohide.
-gtk-builder-tool can assist with the rename in ui files.
+The modal property has been renamed to [property@Gtk.Popover:autohide].
+
+`gtk-builder-tool` can assist with the rename in ui files.
### gtk_widget_get_surface has been removed
-gtk_widget_get_surface() has been removed.
-Use gtk_native_get_surface() in combination with
-gtk_widget_get_native() instead.
+`gtk_widget_get_surface()` has been removed.
+Use [method@Gtk.Native.get_surface] in combination with
+[method@Gtk.Widget.get_native] instead.
### gtk_widget_is_toplevel has been removed
-gtk_widget_is_toplevel() has been removed.
-Use GTK_IS_ROOT, GTK_IS_NATIVE or GTK_IS_WINDOW
+`gtk_widget_is_toplevel()` has been removed.
+Use `GTK_IS_ROOT`, `GTK_IS_NATIVE` or `GTK_IS_WINDOW`
instead, as appropriate.
### gtk_widget_get_toplevel has been removed
-gtk_widget_get_toplevel() has been removed.
-Use gtk_widget_get_root() or gtk_widget_get_native()
+`gtk_widget_get_toplevel()` has been removed.
+Use [method@Gtk.Widget.get_root] or [method@Gtk.Widget.get_native]
instead, as appropriate.
### GtkEntryBuffer ::deleted-text has changed
To allow signal handlers to access the deleted text before it
-has been deleted #GtkEntryBuffer::deleted-text has changed from
-%G_SIGNAL_RUN_FIRST to %G_SIGNAL_RUN_LAST. The default handler
-removes the text from the #GtkEntryBuffer.
+has been deleted, the [signal@Gtk.EntryBuffer::deleted-text] signal
+has changed from %G_SIGNAL_RUN_FIRST to %G_SIGNAL_RUN_LAST. The default
+handler removes the text from the [class@Gtk.EntryBuffer].
-To adapt existing code, use g_signal_connect_after() or
-%G_CONNECT_AFTER when using g_signal_connect_data() or
-g_signal_connect_object().
+To adapt existing code, use `g_signal_connect_after()` or
+%G_CONNECT_AFTER when using `g_signal_connect_data()` or
+`g_signal_connect_object()`.
### GtkMenu, GtkMenuBar and GtkMenuItem are gone
@@ -1155,98 +1182,95 @@ can only be constructed from menu models, so the porting effort involves
switching to menu models and actions.
Tabular menus were rarely used and complicated the menu code,
-so they have not been brought over to #GtkPopoverMenu. If you need
-complex layout in menu-like popups, consider directly using a
-#GtkPopover instead.
+so they have not been brought over to [class@Gtk.PopoverMenu].
+If you need complex layout in menu-like popups, consider directly using a
+[class@Gtk.Popover] instead.
-Since menus are gone, GtkMenuButton also lost its ability to show menus,
+Since menus are gone, `GtkMenuButton` also lost its ability to show menus,
and needs to be used with popovers in GTK 4.
### GtkToolbar has been removed
Toolbars were using outdated concepts such as requiring special toolitem
-widgets. Toolbars should be replaced by using a GtkBox with regular widgets
+widgets. Toolbars should be replaced by using a `GtkBox` with regular widgets
instead and the "toolbar" style class.
### GtkAspectFrame is no longer a frame
-GtkAspectFrame is no longer derived from GtkFrame and does not
+`GtkAspectFrame` is no longer derived from `GtkFrame` and does not
place a label and frame around its child anymore. It still lets
you control the aspect ratio of its child.
### Stop using custom tooltip windows
-Tooltips no longer use GtkWindows in GTK 4, and it is no longer
+Tooltips no longer use `GtkWindow`s in GTK 4, and it is no longer
possible to provide a custom window for tooltips. Replacing the content
of the tooltip with a custom widget is still possible, with
-gtk_tooltip_set_custom().
+[method@Gtk.Tooltip.set_custom].
### Switch to the new Drag-and-Drop api
The source-side Drag-and-Drop apis in GTK 4 have been changed to use an event
-controller, #GtkDragSource. Instead of calling gtk_drag_source_set()
-and connecting to #GtkWidget signals, you create a #GtkDragSource object,
-attach it to the widget with gtk_widget_add_controller(), and connect
-to #GtkDragSource signals. Instead of calling gtk_drag_begin() on a widget
-to start a drag manually, call gdk_drag_begin().
-The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare
-signal, which returns a #GdkContentProvider for the drag operation.
+controller, [class@Gtk.DragSource]. Instead of calling `gtk_drag_source_set()`
+and connecting to `GtkWidget` signals, you create a [class@Gtk.DragSource] object,
+attach it to the widget with [method@Gtk.Widget.add_controller], and connect
+to `GtkDragSource` signals. Instead of calling `gtk_drag_begin()` on a widget
+to start a drag manually, call [type_func Gdk Drag.begin].
+The `::drag-data-get` signal has been replaced by the [signal@Gtk.DragSource::prepare]
+signal, which returns a [class@Gdk.ContentProvider] for the drag operation.
The destination-side Drag-and-Drop API in GTK 4 have also been changed
-to use an event controller, #GtkDropTarget. Instead of calling
-gtk_drag_dest_set() and connecting to #GtkWidget signals, you create
-a #GtkDropTarget object, attach it to the widget with
-gtk_widget_add_controller(), and connect to #GtkDropTarget signals.
-The ::drag-motion signal has been renamed to #GtkDropTarget::accept, and
-instead of ::drag-data-received, you need to use async read methods on the
-#GdkDrop object, such as gdk_drop_read_async() or gdk_drop_read_value_async().
+to use an event controller, [class@Gtk.DropTarget]. Instead of calling
+`gtk_drag_dest_set()` and connecting to `GtkWidget` signals, you create
+a [class@Gtk.DropTarget] object, attach it to the widget with
+[method@Gtk.Widget.add_controller], and connect to `GtkDropTarget` signals.
+The `::drag-motion` signal has been renamed to [signal@Gtk.DropTarget::accept],
+and instead of `::drag-data-received`, you need to use async read methods on the
+[class Gdk Drop] object, such as [method Gdk Drop.read_async] or
+[method Gdk Drop.read_value_async].
### Adapt to GtkIconTheme API changes
-gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable object now, instead
-of a #GtkIconInfo. It always returns a paintable in the requested size, and
-never fails. A number of no-longer-relevant lookup flags and API variants
+`gtk_icon_theme_lookup_icon()` returns a [class@Gtk.IconPaintable] object now,
+instead of a `GtkIconInfo`. It always returns a paintable in the requested size,
+and never fails. A number of no-longer-relevant lookup flags and API variants
have been removed.
-Note that while GTK 4 is moving towards #GdkPaintable as a primary API
+Note that while GTK 4 is moving towards [iface@Gdk.Paintable] as a primary API
for paintable content, it is meant to be a 'pure' content producer, therefore
-a #GtkIconPaintable for a symbolic icon will *not* get recolored depending
+a [class@Gtk.IconPaintable] for a symbolic icon will *not* get recolored depending
on the context it is rendered it. To properly render a symbolic icon that
-is provided in the form of a #GtkIconPaintable (this can be checked with
-gtk_icon_paintable_is_symbolic()), you have to call
-gtk_icon_paintable_get_icon_name() and set the icon name on a #GtkImage.
+is provided in the form of a `GtkIconPaintable` (this can be checked with
+[method@Gtk.IconPaintable.is_symbolic]), you have to call
+[method@Gtk.IconPaintable.get_icon_name] and set the icon name on a `GtkImage`.
### Update to GtkFileChooser API changes
-GtkFileChooser moved to a GFile-based API. If you need to convert a path
-or a URI, use g_file_new_for_path(), g_file_new_for_commandline_arg(),
-or g_file_new_for_uri(); similarly, if you need to get a path, name or URI
-from a GFile, use g_file_get_path(), g_file_get_basename() or g_file_get_uri().
+`GtkFileChooser` moved to a GFile-based API. If you need to convert a path
+or a URI, use `g_file_new_for_path()`, `g_file_new_for_commandline_arg()`,
+or `g_file_new_for_uri()`; similarly, if you need to get a path, name or URI
+from a `GFile`, use `g_file_get_path()`, `g_file_get_basename()` or `g_file_get_uri()`.
With the removal or path and URI-based functions, the "local-only" property
has been removed; GFile can be used to access non-local as well as local
resources.
-The GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER action has been removed. Use
+The `GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER` action has been removed. Use
%GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER, instead. If a new folder is needed,
the user can create one.
The "confirm-overwrite" signal, and the "do-overwrite-confirmation"
-property have been removed from GtkFileChooser. The file chooser widgets
+property have been removed from `GtkFileChooser`. The file chooser widgets
will automatically handle the confirmation of overwriting a file when
-using GTK_FILE_CHOOSER_ACTION_SAVE.
+using `GTK_FILE_CHOOSER_ACTION_SAVE`.
-GtkFileChooser does not support a custom extra widget any more. If you
-need to add extra widgets, use gtk_file_chooser_add_choice() instead.
+`GtkFileChooser` does not support a custom extra widget any more. If you
+need to add extra widgets, use [method@Gtk.FileChooser.add_choice] instead.
-GtkFileChooser does not support a custom preview widget any more. If
-you need to show a custom preview, you can create your own GtkDialog
-with a GtkFileChooserWidget and your own preview widget that you
-update whenever the #GtkFileChooser::selection-changed signal is
-emitted.
+`GtkFileChooser` does not support a custom preview widget any more.
### Stop using blocking dialog functions
-GtkDialog, GtkNativeDialog, and GtkPrintOperation removed their
+`GtkDialog`, `GtkNativeDialog`, and `GtkPrintOperation` removed their
blocking API using nested main loops. Nested main loops present
re-entrancy issues and other hard to debug issues when coupled
with other event sources (IPC, accessibility, network operations)
@@ -1254,43 +1278,43 @@ that are not under the toolkit or the application developer's
control. Additionally, "stop-the-world" functions do not fit
the event-driven programming model of GTK.
-You can replace calls to gtk_dialog_run() by specifying that the
-#GtkDialog must be modal using gtk_window_set_modal() or the
-%GTK_DIALOG_MODAL flag, and connecting to the #GtkDialog::response
+You can replace calls to `gtk_dialog_run()` by specifying that the
+`GtkDialog` must be modal using [method@Gtk.Window.set_modal] or the
+%GTK_DIALOG_MODAL flag, and connecting to the [signal@Gtk.Dialog::response]
signal.
### Stop using GtkBuildable API
-All the GtkBuildable API was made private, except for the
+All the `GtkBuildable` API was made private, except for the
getter function to retrieve the buildable ID. If you are
-using gtk_buildable_get_name() you should replace it with
-gtk_buildable_get_buildable_id().
+using `gtk_buildable_get_name()` you should replace it with
+[method@Gtk.Buildable.get_buildable_id].
### Adapt to GtkAboutDialog API changes
-GtkAboutDialog now directly derives from GtkWindow, the GtkDialog API can no
-longer be used on it.
+`GtkAboutDialog` now directly derives from `GtkWindow`, the `GtkDialog`
+API can no longer be used on it.
### Adapt to GtkTreeView and GtkIconView tooltip context changes
-The getter functions for retrieving the data from #GtkTreeView
-and #GtkIconView inside a #GtkWidget::query-tooltip signal do not take the
+The getter functions for retrieving the data from `GtkTreeView`
+and `GtkIconView` inside a `GtkWidget::query-tooltip` signal do not take the
pointer coordinates as inout arguments any more, but as normal in ones.
-See: gtk_tree_view_get_tooltip_context(), gtk_icon_view_get_tooltip_context()
+See: [method@Gtk.TreeView.get_tooltip_context], [method@Gtk.IconView.get_tooltip_context]
### Stop using GtkFileChooserButton
The `GtkFileChooserButton` widget was removed, due to its shortcomings in
-the user interaction. You can replace it with a simple #GtkButton that
-shows a #GtkFileChooserNative dialog when clicked; once the file selection
-has completed, you can update the label of the #GtkButton with the selected
+the user interaction. You can replace it with a simple `GtkButton` that
+shows a [class@Gtk.FileChooserNative] dialog when clicked; once the file selection
+has completed, you can update the label of the `GtkButton` with the selected
file.
### Adapt to changed GtkSettings properties
-In GTK 3 the #GtkSettings:gtk-cursor-aspect-ratio property of #GtkSettings was
-a float. In GTK 4 this has been changed to a double.
+In GTK 3 the [property@Gtk.Settings:gtk-cursor-aspect-ratio] property of
+`GtkSettings` was a `float`. In GTK 4 this has been changed to a `double`.
## Changes to consider after the switch
@@ -1299,7 +1323,7 @@ advantage of once the dust has settled over the initial migration.
### Consider porting to the new list widgets
-In GTK 2 and 3, GtkTreeModel and GtkCellRenderer and widgets using
+In GTK 2 and 3, `GtkTreeModel` and `GtkCellRenderer` and widgets using
these were the primary way of displaying data and lists. GTK 4 brings
a new family of widgets for this purpose that uses list models instead
of tree models, and widgets instead of cell renderers.
diff --git a/docs/reference/gtk/question_index.md b/docs/reference/gtk/question_index.md
index 505b20418d..c4c5f4e4c2 100644
--- a/docs/reference/gtk/question_index.md
+++ b/docs/reference/gtk/question_index.md
@@ -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].
diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md
index c657be65ad..37c1f33388 100644
--- a/docs/reference/gtk/section-accessibility.md
+++ b/docs/reference/gtk/section-accessibility.md
@@ -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.
diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md
index ae831c3eaf..3bd3b6fe73 100644
--- a/docs/reference/gtk/section-list-widget.md
+++ b/docs/reference/gtk/section-list-widget.md
@@ -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` |
diff --git a/docs/reference/gtk/section-text-widget.md b/docs/reference/gtk/section-text-widget.md
index 7eccd80680..1f5d0feca8 100644
--- a/docs/reference/gtk/section-text-widget.md
+++ b/docs/reference/gtk/section-text-widget.md
@@ -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`.
diff --git a/docs/reference/gtk/section-tree-widget.md b/docs/reference/gtk/section-tree-widget.md
index 8db94e7d13..2fcf467ba1 100644
--- a/docs/reference/gtk/section-tree-widget.md
+++ b/docs/reference/gtk/section-tree-widget.md
@@ -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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
