diff --git a/docs/reference/gtk/getting_started.xml.in b/docs/reference/gtk/getting_started.xml.in index d8e638f6e1..dba22cf0de 100644 --- a/docs/reference/gtk/getting_started.xml.in +++ b/docs/reference/gtk/getting_started.xml.in @@ -9,7 +9,7 @@ widget toolkit. Each user interface created by GTK consists of widgets. This is implemented in C using GObject, an object-oriented framework for C. - Widgets are organized in a hierachy. The window widget is the main container. + Widgets are organized in a hierarchy. The window widget is the main container. The user interface is then built by adding buttons, drop-down menus, input fields, and other widgets to the window. If you are creating complex user interfaces it is recommended to @@ -77,7 +77,7 @@ For this example org.gtk.example is used. For choosing an identifier for your application, see this guide. - Lastly gtk_application_new() takes #GApplicationFlags as input for your + Lastly gtk_application_new() takes GApplicationFlags as input for your application, if your application would have special needs. @@ -112,14 +112,14 @@ here. - Finally the window size is set using gtk_window_set_default_sizei() + Finally the window size is set using gtk_window_set_default_size() and the window is then shown by GTK via gtk_widget_show(). - When you exit the window, by for example pressing the X, - the g_application_run() in the main loop returns with a number - which is saved inside an integer named "status". Afterwards, the + When you close the window, by for example pressing the X, the + g_application_run() call returns with a number which is saved inside + an integer variable named status. Afterwards, the GtkApplication object is freed from memory with g_object_unref(). - Finally the status integer is returned and the GTK application exits. + Finally the status integer is returned and the application exits. While the program is running, GTK is receiving events. These are typically input events caused by @@ -204,7 +204,7 @@ here. - The rest of the code in example-1.c is identical to example-0.c. Next + The rest of the code in example-1.c is identical to example-0.c. The next section will elaborate further on how to add several GtkWidgets to your GTK application. @@ -213,9 +213,8 @@ Packing When creating an application, you'll want to put more than one widget - inside a window. When you want to put more than one widget into a window, - it becomes important to control how each widget is positioned and sized. - This is where packing comes in. + inside a window. When you do so, it becomes important to control how each widget + is positioned and sized. This is where packing comes in. GTK comes with a large variety of layout containers whose purpose it is to control the layout of the child widgets that are @@ -245,16 +244,60 @@ +
+ Custom Drawing + + Many widgets, like buttons, do all their drawing themselves. You + just tell them the label you want to see, and they figure out what font + to use, draw the button outline and focus rectangle, etc. Sometimes, it + is necessary to do some custom drawing. In that case, a GtkDrawingArea + might be the right widget to use. It offers a canvas on which you can + draw by connecting to the ::draw signal. + + + The contents of a widget often need to be partially or fully redrawn, + e.g. when another window is moved and uncovers part of the widget, or + when the window containing it is resized. It is also possible to explicitly + cause part or all of the widget to be redrawn, by calling + gtk_widget_queue_draw() or its variants. GTK takes care of most of the + details by providing a ready-to-use cairo context to the ::draw signal + handler. + + The following example shows a ::draw signal handler. It is a bit + more complicated than the previous examples, since it also demonstrates + input event handling by means of event controllers. + + + + + + + + + + + Drawing in response to input + Create a new file with the following content named example-4.c. + MISSING XINCLUDE CONTENT + + + You can compile the program above with GCC using: + + gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4` + + +
+
Building user interfaces - When construcing a more complicated user interface, with dozens + When constructing a more complicated user interface, with dozens or hundreds of widgets, doing all the setup work in C code is cumbersome, and making changes becomes next to impossible. Thankfully, GTK supports the separation of user interface layout from your business logic, by using UI descriptions in an - XML format that can be parsed by the #GtkBuilder class. + XML format that can be parsed by the GtkBuilder class. Packing buttons with GtkBuilder @@ -333,8 +376,8 @@ application menus, settings, GtkHeaderBar, GtkStack, GtkSearchBar, GtkListBox, and more. - The full, buildable sources for these examples can be found - in the examples/ directory of the GTK source distribution, or + The full, buildable sources for these examples can be found in the + examples/ directory of the GTK source distribution, or online in the GTK git repository. You can build each example separately by using make with the Makefile.example file. For more information, see the README included in the @@ -887,10 +930,7 @@ example_app_window_init (ExampleAppWindow *win) The code to populate the sidebar with buttons for the words found in each file is a little too involved to go into here. But we'll - look at the code to add the gears menu. - - As expected by now, the gears menu is specified in a GtkBuilder - ui file. + look at the code to add a checkbutton for the new feature to the menu. MISSING XINCLUDE CONTENT @@ -1005,48 +1045,4 @@ example_app_window_init (ExampleAppWindow *win)
-
- Custom Drawing - - Many widgets, like buttons, do all their drawing themselves. You - just tell them the label you want to see, and they figure out what font - to use, draw the button outline and focus rectangle, etc. Sometimes, it - is necessary to do some custom drawing. In that case, a GtkDrawingArea - might be the right widget to use. It offers a canvas on which you can - draw by connecting to the ::draw signal. - - - The contents of a widget often need to be partially or fully redrawn, - e.g. when another window is moved and uncovers part of the widget, or - when the window containing it is resized. It is also possible to explicitly - cause part or all of the widget to be redrawn, by calling - gtk_widget_queue_draw() or its variants. GTK takes care of most of the - details by providing a ready-to-use cairo context to the ::draw signal - handler. - - The following example shows a ::draw signal handler. It is a bit - more complicated than the previous examples, since it also demonstrates - input event handling by means of event controllers. - - - - - - - - - - - Drawing in response to input - Create a new file with the following content named example-4.c. - MISSING XINCLUDE CONTENT - - - You can compile the program above with GCC using: - - gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4` - - -
- diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml index 32fa09d8bb..0503bf0e13 100644 --- a/docs/reference/gtk/migrating-3to4.xml +++ b/docs/reference/gtk/migrating-3to4.xml @@ -80,38 +80,52 @@ GTK 4 removes the GDK_WA_CURSOR flag. Instead, just use gdk_window_set_cursor() to set a cursor on the window after - creating it. - - - GTK 4 also removes the GDK_WA_VISUAL flag, and always uses - an RGBA visual for windows. To prepare your code for this, use + creating it. GTK 4 also removes the GDK_WA_VISUAL flag, and + always uses an RGBA visual for windows. To prepare your code + for this, use gdk_window_set_visual (gdk_screen_get_rgba_visual ()) after creating your window. - - GTK 4 also removes the GDK_WA_WMCLASS flag. If you need this X11-specific functionality, use XSetClassHint() directly. +
+ Stop using direct access to GdkEvent structs + + In GTK 4, event structs are opaque and immutable. Many fields already + have accessors in GTK 3, and you should use those to reduce the amount + of porting work you have to do at the time of the switch. + +
+ +
+ Stop using gdk_pointer_warp() + + Warping the pointer is disorienting and unfriendly to users. + GTK 4 does not support it. In special circumstances (such as when + implementing remote connection UIs) it can be necessary to + warp the pointer; in this case, use platform APIs such as + XWarpPointer() directly. + +
+
Stop using non-RGBA visuals GTK 4 always uses RGBA visuals for its windows; you should make - sure that your code works with that. - - - At the same time, you should stop using GdkVisual APIs, this object - not longer exist in GTK 4. Most of its APIs are deprecated already - and not useful when dealing with RGBA visuals. + sure that your code works with such visuals. At the same time, + you should stop using GdkVisual APIs, since this object not longer + exists in GTK 4. Most of its APIs are deprecated already and not + useful when dealing with RGBA visuals.
- Stop using GtkBox:padding, GtkBox:fill and GtkBox:expand + Stop using GtkBox padding, fill and expand child properties - GTK 4 removes these #GtkBox child properties, so you should not use them. - You can replace GtkBox:padding using the #GtkWidget:margin properties + GTK 4 removes these #GtkBox child properties, so you should stop using + them. You can replace GtkBox:padding using the #GtkWidget:margin properties on your #GtkBox child widgets. @@ -152,8 +166,9 @@
Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface() - These functions are not supported in GTK 4. Instead, either use backend-specific - APIs, or render your widgets using #GtkWidgetClass.snapshot(). + These functions are not supported in GTK 4. Instead, either use + backend-specific APIs, or render your widgets using + #GtkWidgetClass.snapshot() (once you are using GTK 4).
@@ -165,7 +180,7 @@ 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 gtk_button_set_icon_name(). + use gtk_button_new_from_icon_name().
@@ -180,12 +195,11 @@
Set a proper application ID - In GTK 4 we want the application's #GApplication - 'application-id' (and therefore the D-Bus name), the desktop - file basename and Wayland's xdg-shell app_id to match. In - order to achieve this with GTK 3.x call g_set_prgname() with the same - application ID you passed to #GtkApplication. Rename your - desktop files to match the application ID if needed. + In GTK 4 we want the application's #GApplication 'application-id' + (and therefore the D-Bus name), the desktop file basename and Wayland's + xdg-shell app_id to match. In order to achieve this with GTK 3.x call + g_set_prgname() with the same application ID you passed to #GtkApplication. + Rename your desktop files to match the application ID if needed. The call to g_set_prgname() can be removed once you fully migrated @@ -203,21 +217,19 @@ Stop using gtk_main() and related APIs - GTK4 removes the gtk_main_ family of APIs. The recommended replacement + GTK 4 removes the gtk_main_ family of APIs. The recommended replacement is GtkApplication, but you can also iterate the GLib mainloop directly, - 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(). + 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().
Reduce the use of gtk_widget_destroy() - GTK4 introduces a gtk_window_destroy() api. While that is not available - in GTK3, you can prepare for the switch by using gtk_widget_destroy() + GTK 4 introduces a gtk_window_destroy() api. While that is not available + in GTK 3, you can prepare for the switch by using gtk_widget_destroy() only on toplevel windows, and replace all other uses with gtk_container_remove() or g_object_unref(). @@ -226,8 +238,8 @@
Reduce the use of generic container APIs - GTK4 removes gtk_container_add() and gtk_container_remove(). While there - is not always a replacement for gtk_container_remove() in GTK3, you can + GTK 4 removes gtk_container_add() and gtk_container_remove(). While there + is not always a replacement for gtk_container_remove() in GTK 3, you can replace many uses of gtk_container_add() with equivalent container-specific APIs such as gtk_box_pack_start() or gtk_grid_attach(), and thereby reduce the amount of work you have to do at the time of the switch. @@ -245,17 +257,6 @@ have been either impossible or impractical. -
- Convert your ui files - - - A number of the changes outlined below affect .ui files. The - gtk4-builder-tool simplify command can perform many of the - necessary changes automatically, when called with the --3to4 - option. You should always review the resulting changes. - -
-
Stop using GdkScreen @@ -269,9 +270,8 @@ Stop using the root window The root window is an X11-centric concept that is no longer exposed in the - backend-neutral GDK API. gdk_surface_get_parent() will return %NULL for toplevel - windows. If you need to interact with the X11 root window, you can use - gdk_x11_display_get_xrootwindow() to get its XID. + 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.
@@ -297,113 +297,80 @@ GdkWindow has been renamed to GdkSurface. - The gdk_window_new() function has been replaced by a number of more - specialized constructors: gdk_surface_new_toplevel(), gdk_surface_new_popup(), - gdk_surface_new_temp(), gdk_wayland_surface_new_subsurface(). - Use the appropriate ones to create your windows. + 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, #GdkToplevel and #GdkPopup. 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, + #GdkPopupLayout or #GdkToplevelLayout. 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. - Native and foreign subwindows are no longer supported. These concepts were - complicating the code and could not be supported across backends. + As part of this reorganization, X11-only concepts such as sticky or + keep-below have been removed. If you need to use them on your X11 windows, + you will have to 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 + are no longer supported. These concepts were complicating the code and + could not be supported across backends. gdk_window_reparent() is no longer available. + + 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(). + +
+ +
+ The "iconified" window state has been renamed to "minimized" + + The GDK_SURFACE_STATE_ICONIFIED value of the + #GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED. + + + The #GdkWindow functions gdk_window_iconify() + and gdk_window_deiconify() have been renamed to + gdk_toplevel_minimize() and gdk_toplevel_present(), respectively. + + + The behavior of the minimization and unminimization operations have + not been changed, and they still require support from the underlying + windowing system. +
Adapt to GdkEvent API changes - Direct access to GdkEvent structs is no longer possible in - GTK 4. Some frequently-used fields already had accessors - in GTK 3, and the remaining fields have gained accessors - in GTK 4. + Direct access to GdkEvent structs is no longer possible in GTK 4. + 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. - GdkEvent is now a strictly read-only type, and you - can no longer change any of its fields, or construct new - events. - -
- -
- Stop using gdk_surface_set_event_compression - - Event compression is now always enabled. If you need to see the uncoalesced - motion history, use gdk_motion_event_get_history() on the latest motion event. - -
- -
- Stop using gdk_pointer_warp() - - Warping the pointer is disorienting and unfriendly to users. - GTK 4 does not support it. In special circumstances (such as when - implementing remote connection UIs) it can be necessary to - warp the pointer; in this case, use platform APIs such as - XWarpPointer() directly. + Event compression is always enabled in GTK 4. If you need to see + the uncoalesced motion history, use gdk_motion_event_get_history() + on the latest motion 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. - GtkPopover also has a #GtkPopover:autohide property. - - - If you need to prevent the user from interacting with a window - while a dialog is open, use #GtkWindow:modal on the dialog. - -
- -
- Stop using gtk_get_current_... APIs - - The function gtk_get_current_event() and its variants have been - replaced by equivalent event controller APIs: - gtk_event_controller_get_current_event(), etc. - -
- -
- Adapt to surface API changes - - 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, #GdkToplevel - and #GdkPopup. - - - 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, #GdkPopupLayout or - #GdkToplevelLayout. - - - 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 or keep-below have been removed. If you need - to use them on your X11 windows, you will have to set - the corresponding X11 properties (as specified in the - EWMH) yourself. - - - 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(). + 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. GtkPopover 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 #GtkWindow:modal property of the dialog.
@@ -418,13 +385,13 @@ Any APIs that deal with global (or root) coordinates have been - removed in GTK4, since not all backends support them. You should + removed in GTK 4, since not all backends support them. You should replace your use of such APIs with surface-relative equivalents. Examples of this are gdk_surface_get_origin(), gdk_surface_move() or gdk_event_get_root_coords().
- +
Adapt to GdkKeymap API changes @@ -435,15 +402,14 @@ 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 + #GdkDevice: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 modifiers, group and shift level, so there should be no need to - do manually call gdk_keymap_translate_keyboard_state() (which has + manually call gdk_keymap_translate_keyboard_state() (which has been removed). @@ -454,21 +420,6 @@
-
- Adapt to event controller API changes - - A few changes to the event controller and #GtkGesture APIs - did not make it back to GTK3, and have to be taken into account - when moving to GTK4. One is that the - #GtkEventControllerMotion::enter, - #GtkEventControllerMotion::leave, - #GtkEventControllerKey::focus-in and - #GtkEventControllerKey::focus-out signals - have gained new arguments. Another is that #GtkGestureMultiPress - has been renamed to #GtkGestureClick. - -
-
Adapt to changes in keyboard modifier handling @@ -501,6 +452,39 @@
+
+ Stop using gtk_get_current_... APIs + + The function gtk_get_current_event() and its variants have been + replaced by equivalent event controller APIs: + gtk_event_controller_get_current_event(), etc. + +
+ +
+ Convert your ui files + + + A number of the changes outlined below affect .ui files. The + gtk4-builder-tool simplify command can perform many of the + necessary changes automatically, when called with the --3to4 + option. You should always review the resulting changes. + +
+ +
+ Adapt to event controller API changes + + A few changes to the event controller and #GtkGesture APIs + did not make it back to GTK 3, and have to be taken into account + when moving to GTK 4. One is that the #GtkEventControllerMotion::enter + and #GtkEventControllerMotion::leave signals have gained new arguments. + Another is that #GtkGestureMultiPress has been renamed to #GtkGestureClick, + and has lost its area property. A #GtkEventControllerFocus has been + split off from #GtkEventcontrollerKey. + +
+
Focus handling changes @@ -509,17 +493,15 @@ accept keyboard input, but its children still might (in the case of containers). In GTK 4, if :can-focus is %FALSE, the focus cannot enter the widget or any of its descendents, and the default value has changed - from %FALSE to %TRUE. - - - The recommended way to influence focus behavior of custom widgets - in GTK 4 is to override the focus() and grab_focus() vfuncs. + from %FALSE to %TRUE. In addition, there is a #GtkWidget:focusable + property, which controls whether an individual widget can receive + the input focus. The feature to automatically keep the focus widget scrolled into view - with gtk_container_set_focus_vadjustment() has been removed from - GtkContainer, and is provided by scrollables instead. In the common case - that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus. + with gtk_container_set_focus_vadjustment() has been removed together with + GtkContainer, and is provided by scrollable widgets instead. In the common + case that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus.
@@ -541,8 +523,8 @@
Adapt to GtkBox API changes - GtkBox no longer has pack-start and -end. Pack your widgets in the - correct order, or reorder them as necessary. + The GtkBox pack-start and -end methods have been replaced by gtk_box_prepend() + and gtk_box_append(). You can also reorder box children as necessary.
@@ -550,8 +532,8 @@ Adapt to GtkHeaderBar and GtkActionBar API changes The gtk_header_bar_set_show_close_button() function has been renamed to - the more accurate name gtk_header_bar_set_show_title_buttons(). The corresponding - getter and the property itself have also been renamed. + the more accurate name gtk_header_bar_set_show_title_buttons(). The + corresponding getter and the property itself have also been renamed. The ::pack-type child properties of GtkHeaderBar and GtkActionBar have @@ -586,8 +568,11 @@ 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. The affected classes - are: + 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 affected classes are: GtkAspectFrame @@ -605,19 +590,30 @@ GtkWindow (and subclasses) - 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. + 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 + adding children with child in ui files.
Adapt to GtkContainer removal - The abstract bas class GtkContainer for general containers has been + 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 affected classes - are: + and have class-specific add() and remove() functions. + The most noticable 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 affected classes are: GtkActionBar @@ -637,11 +633,22 @@ GtkTreeView - The most noticable change will be to use 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. + 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. + +
+ +
+ 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 + of your containers, such as the CSS margin and padding properties on child + widgets.
@@ -677,22 +684,10 @@
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(). - -
- -
- Stop using GtkContainer::border-width - - GTK 4 has removed the #GtkContainer::border-width property. - Use other means to influence the spacing of your containers, - such as the CSS margin and padding properties on child widgets. + 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().
@@ -714,28 +709,33 @@ 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. + have to implement. 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 signal now takes the baseline as an - argument, so you no longer need to call gtk_widget_get_allocated_baseline() + The #GtkWidget.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. +
Switch to GtkWidget's children APIs - Instead of the GtkContainer subclass, in GTK 4, any widget can - have children, and there is new API to navigate the widget tree: - gtk_widget_get_first_child(), gtk_widget_get_last_child(), + 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(). - The GtkContainer API still works, but if you are implementing - your own widgets, you should consider using the new APIs.
@@ -757,18 +757,17 @@
- Don't use -gtk-outline-...-radius in your CSS + Don't use -gtk-icon-theme in your CSS - These non-standard properties have been removed from GTK - CSS. Just use regular border radius. + GTK now uses the current icon theme, without a way to change this.
- Use gtk_widget_measure + Don't use -gtk-outline-...-radius in your CSS - gtk_widget_measure() replaces the various gtk_widget_get_preferred_ functions - for querying sizes. + These non-standard properties have been removed from GTK + CSS. Just use regular border radius.
@@ -809,6 +808,8 @@ The default value of #GtkWidget: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 + windows, dialogs and popovers. A convenient way to remove unnecessary property assignments like this @@ -817,7 +818,8 @@ 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. + and its getter and setter have been removed in GTK 4, so you should stop + using them. @@ -848,11 +850,8 @@ 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. + classes instead. If you are dealing with pixbufs, you can use + gdk_texture_new_for_pixbuf() to convert them to texture objects where needed. @@ -878,7 +877,9 @@ 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 no longer possible. + #GtkWidgetClass.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(). @@ -926,24 +927,15 @@ to override the icon size. - The ::stock-size property of GtkCellRendererPixbuf has been renamed to + The :stock-size property of GtkCellRendererPixbuf has been renamed to #GtkCellRendererPixbuf:icon-size. -
- Convert .ui files - - The simplify command of gtk4-builder-tool has gained a --3to4 option, which - can help with some of the required changes in .ui files, such as converting - child properties to child meta objects. - -
-
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.
@@ -969,8 +961,8 @@
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: + The GtkOverlay :pass-through child property has been replaced by the + #GtkWidget:can-target property. Note that they have the opposite sense: pass-through == !can-target.
@@ -995,37 +987,15 @@ -
- Stop using child properties - - GtkContainer no longer provides 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. - -
- -
- Stop using gtk_menu_set_display() - - This function has been removed. Menus should always be - attached to a widget and get their display that way. - -
-
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() - 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 groups. + 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 + groups.
@@ -1042,7 +1012,7 @@
Stop using the GtkWidget::display-changed signal - To track the current display, use the GtkWidget::root property + To track the current display, use the #GtkWidget::root property instead.
@@ -1097,29 +1067,6 @@ -
- The "iconified" window state has been renamed to "minimized" - - The GDK_SURFACE_STATE_ICONIFIED value of the - #GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED. - - - The #GdkSurface functions gdk_surface_iconify() - and gdk_surface_deiconify() have been renamed to - gdk_toplevel_minimize() and gdk_toplevel_present(), respectively. - - - The corresponding #GtkWindow functions gtk_window_iconify() - and gtk_window_deiconify() have been renamed - to gtk_window_minimize() and gtk_window_unminimize(), respectively. - - - The behavior of the minimization and unminimization operations have - not been changed, and they still require support from the underlying - windowing system. - -
-
GtkMenu, GtkMenuBar and GtkMenuItem are gone @@ -1139,7 +1086,6 @@ complex layout in menu-like popups, consider directly using a #GtkPopover instead. - Since menus are gone, GtkMenuButton also lost its ability to show menus, and needs to be used with popovers in GTK 4. @@ -1150,10 +1096,8 @@ 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 instead. + widgets. Toolbars should be replaced by using a GtkBox with regular widgets + instead and the "toolbar" style class.
@@ -1177,46 +1121,36 @@
- Switch to the new DND api + Switch to the new Drag-and-Drop api - The source-side DND apis in GTK 4 have been changed to use an event controller, #GtkDragSource. + 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. - 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. - - - The destination-side DND apis in GTK 4 have also been changed to use and 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(). + The destination-side Drag-and-Drop apis 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().
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 have been removed. + 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 + have been removed.
diff --git a/docs/reference/gtk/question_index.xml b/docs/reference/gtk/question_index.xml index b083211ef7..c6da3c8f9a 100644 --- a/docs/reference/gtk/question_index.xml +++ b/docs/reference/gtk/question_index.xml @@ -37,8 +37,10 @@ How do I get started with GTK? The GTK website offers some tutorials and other -documentation (most of it about GTK 2.x, but mostly still applicable). -More documentation ranging from whitepapers to online books can be found at +documentation (most of it about GTK 2.x, but still somewhat applicable). This +reference manual also contains a introductory +Getting Started part. +More documentation ranging from whitepapers to online books can be found at the GNOME developer's site. After studying these materials you should be well prepared to come back to this reference manual for details. @@ -70,13 +72,9 @@ How do I port from one GTK version to another? See . -You may also find useful information in the documentation for -specific widgets and functions. - - - -If you have a question not covered in the manual, feel free to -ask on the mailing lists and please file a bug report against the documentation. @@ -108,6 +106,11 @@ undocumented exception to the rules, please file a bug report. + +The transfer annotations for gobject-introspection that are part of the +documentation can provide useful hints for memory handling semantics as well. + + @@ -126,24 +129,23 @@ If GtkFoo isn't a toplevel window, then foo = gtk_foo_new (); g_object_unref (foo); -is a memory leak, because no one assumed the initial floating -reference. If you are using a widget and you aren't immediately -packing it into a container, then you probably want standard -reference counting, not floating reference counting. +is a memory leak, because no one assumed the initial floating reference +(you will get a warning about this too). If you are using a widget and +you aren't immediately packing it into a container, then you probably +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 GTK parlance) after +floating reference (ref and sink in GObject parlance) after creating it: foo = gtk_foo_new (); g_object_ref_sink (foo); -When you immediately add a widget to a container, it takes care of -assuming the initial floating reference and you don't have to worry -about reference counting at all ... just call gtk_container_remove() -to get rid of the widget. +When you immediately add a widget to a container, it takes care of assuming +the initial floating reference and you don't have to worry about reference +counting at all ... just remove the widget from the container to get rid of it. @@ -156,9 +158,13 @@ How do I use GTK with threads? -This is covered in the GDK threads -documentation. See also the GThread -documentation for portable threading primitives. +GTK requires that all GTK API calls are made from the same thread in which +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. @@ -178,9 +184,9 @@ or Linux system with gettext installed, type info gettext to read the documentation. -The short checklist on how to use gettext is: call bindtextdomain() so +The short checklist on how to use gettext is: call bindtextdomain() so gettext can find the files containing your translations, call textdomain() -to set the default translation domain, call bind_textdomain_codeset() to +to set the default translation domain, call bind_textdomain_codeset() to request that all translated strings are returned in UTF-8, then call gettext() to look up each string to be translated in the default domain. @@ -352,7 +358,7 @@ g_free (text); If you are using gettext() to localize your application, you need to -call bind_textdomain_codeset() to ensure that translated strings are +call bind_textdomain_codeset() to ensure that translated strings are returned in UTF-8 encoding. @@ -425,19 +431,9 @@ 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() If the file load fails, -gtk_image_new_from_file() will display no image graphic — to detect -a failed load yourself, use gdk_pixbuf_new_from_file() directly, then -gtk_image_new_from_pixbuf().. -To load an image for another purpose, use gdk_pixbuf_new_from_file(). To -load an animation, use gdk_pixbuf_animation_new_from_file(). -gdk_pixbuf_animation_new_from_file() can also load non-animated images, so -use it in combination with gdk_pixbuf_animation_is_static_image() to load a -file of unknown type. - - -To load an image or animation file asynchronously (without blocking), use -#GdkPixbufLoader. +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(). @@ -450,7 +446,8 @@ How do I draw text ? -To draw a piece of text, use a Pango layout and pango_cairo_show_layout(). +To draw a piece of text onto a cairo surface, use a Pango layout and +pango_cairo_show_layout(). layout = gtk_widget_create_pango_layout (widget, text); @@ -468,6 +465,11 @@ See also the Cairo Rendering section of Pango manual. + + +To draw a piece of text in a widget snapshot() implementation, use +gtk_snapshot_append_layout(). + @@ -513,10 +515,10 @@ macro ? -The GTK_TYPE_BLAH macros are defined as calls to -gtk_blah_get_type(), and the _get_type() -functions are declared as %G_GNUC_CONST which allows the compiler to optimize -the call away if it appears that the value is not being used. +The %GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and +the _get_type() functions are declared as %G_GNUC_CONST which allows +the compiler to optimize the call away if it appears that the value is not +being used. @@ -606,6 +608,18 @@ Both can display images in just about any format GTK understands. You can also use #GtkDrawingArea 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 +it as a paintable: + + +mediafile = gtk_media_file_new_for_filename ("example.webm"); +picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile)); + + + + @@ -618,9 +632,7 @@ would use a combo box? With GTK, a #GtkComboBox is the recommended widget to use for this use case. -This widget looks like either a combo box or the current option menu, depending -on the current theme. If you need an editable text entry, use the -#GtkComboBox:has-entry property. +If you need an editable text entry, use the #GtkComboBox:has-entry property. @@ -638,7 +650,8 @@ How do I change the color of a widget? The background color of a widget is determined by the CSS style that applies to it. To change that, you can set style classes on the widget, and provide 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(). +gtk_css_provider_load_from_file() and its variants. +See gtk_style_context_add_provider(). @@ -912,8 +925,8 @@ How do I use cairo to draw in GTK applications ? -Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc to optain -a cairo context and draw with that. +Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc +to obtain a cairo context and draw with that. diff --git a/docs/reference/gtk/resources.xml b/docs/reference/gtk/resources.xml index f935011f27..1743708e2e 100644 --- a/docs/reference/gtk/resources.xml +++ b/docs/reference/gtk/resources.xml @@ -4,13 +4,13 @@ ]> -Mailing lists and bug reports +Contact information and bug reports 3 -Mailing lists and bug reports +Contact information and bug reports -Mailing lists and bug reports +Contact information and bug reports Getting help with GTK @@ -35,7 +35,7 @@ discussed, we'll add a note to that effect in the report. -The bug tracker should definitely be used for feature requests, it's +The issue tracker should definitely be used for feature requests, it's not only for bugs. We track all GTK development in GitLab, to ensure that nothing gets lost. @@ -61,83 +61,16 @@ for GTK, available on GitLab. If you want to discuss your approach before or after working on it, -send and email to gtk-devel-list@gnome.org. -You should not send a patch to the mailing list, as it will inevitably -get lost, or forgotten. Always open a merge request. +good ways to contact the GTK developers, apart from GitLab issues, +are + +the #gtk IRC channel on irc.gnome.org +the gtk tag on the GNOME Discourse instance + +You should not send patches by email, as they will inevitably get lost, +or forgotten. Always open a merge request. - -Mailing lists - - -There are several mailing lists dedicated to GTK and related -libraries. Discussion of GLib, Pango, and ATK in addition to GTK -proper is welcome on these lists. You can subscribe or view the -archives of these lists on -http://mail.gnome.org. -If you aren't subscribed to the list, any message you post to -the list will be held for manual moderation, which might take -some days to happen. - - - - - - -gtk-list@gnome.org - -gtk-list covers general GTK topics; questions about using GTK in programs, -GTK from a user standpoint, announcements of GTK-related projects -such as themes or GTK modules would all be on-topic. The bulk of the -traffic consists of GTK programming questions. - - - - -gtk-app-devel-list@gnome.org - -gtk-app-devel-list covers writing applications in GTK. It's narrower -in scope than gtk-list, but the two lists overlap quite a -bit. gtk-app-devel-list is a good place to ask questions about GTK -programming. - - - -gtk-devel-list@gnome.org - -gtk-devel-list is for discussion of work on GTK itself, it is -not for -asking questions about how to use GTK in applications. gtk-devel-list -is appropriate for discussion of patches, bugs, proposed features, -and so on. - - - - -gtk-i18n-list@gnome.org - -gtk-i18n-list is for discussion of internationalization in GTK; -Pango is the main focus of the list. Questions about the details of -using Pango, and discussion of proposed Pango patches or features, are -all on topic. - - - - -gtk-doc-list@gnome.org - -gtk-doc-list is for discussion of the gtk-doc -documentation system (used to document GTK), and for work on the GTK -documentation. - - - - - - - - - diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c index 90db5fde50..ff9df272de 100644 --- a/gtk/gtkcssprovider.c +++ b/gtk/gtkcssprovider.c @@ -52,23 +52,24 @@ * GtkCssProvider is an object implementing the #GtkStyleProvider interface. * It is able to parse [CSS-like][css-overview] input in order to style widgets. * - * An application can make GTK+ parse a specific CSS style sheet by calling + * An application can make GTK parse a specific CSS style sheet by calling * gtk_css_provider_load_from_file() or gtk_css_provider_load_from_resource() * and adding the provider with gtk_style_context_add_provider() or * gtk_style_context_add_provider_for_display(). - * In addition, certain files will be read when GTK+ is initialized. First, the - * file `$XDG_CONFIG_HOME/gtk-4.0/gtk.css` is loaded if it exists. Then, GTK+ + * In addition, certain files will be read when GTK is initialized. First, the + * file `$XDG_CONFIG_HOME/gtk-4.0/gtk.css` is loaded if it exists. Then, GTK * loads the first existing file among * `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, * `$HOME/.themes/THEME/gtk-VERSION/gtk-VARIANT.css`, * `$XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk-VARIANT.css` and - * `DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, where `THEME` is the name of - * the current theme (see the #GtkSettings:gtk-theme-name setting), - * VARIANT is the variant to load (see the #GtkSettings:gtk-application-prefer-dark-theme setting), `DATADIR` - * is the prefix configured when GTK+ was compiled (unless overridden by the - * `GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK+ version number. - * If no file is found for the current version, GTK+ tries older versions all the + * `DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, + * where `THEME` is the name of the current theme (see the #GtkSettings:gtk-theme-name + * setting), VARIANT is the variant to load (see the + * #GtkSettings:gtk-application-prefer-dark-theme setting), `DATADIR` + * is the prefix configured when GTK was compiled (unless overridden by the + * `GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK version number. + * If no file is found for the current version, GTK tries older versions all the * way back to 4.0. */