AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2025-01-14 14:20:21 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'matthiasc/for-master' into 'master'

Browse Source 
Documentation work

See merge request GNOME/gtk!1880
This commit is contained in:
Matthias Clasen 2020-05-12 14:52:01 +00:00
commit 450879b1da
5 changed files with 394 additions and 517 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
docs/reference/gtk/getting_started.xml.in
View File

@ -9,7 +9,7 @@
widget toolkit</ulink>. Each user interface created by widget toolkit</ulink>. Each user interface created by
GTK consists of widgets. This is implemented in C using GTK consists of widgets. This is implemented in C using
<link linkend="gobject">GObject</link>, an object-oriented framework for C. <link linkend="gobject">GObject</link>, 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 The user interface is then built by adding buttons, drop-down menus, input
fields, and other widgets to the window. fields, and other widgets to the window.
If you are creating complex user interfaces it is recommended to If you are creating complex user interfaces it is recommended to
@ -77,7 +77,7 @@
For this example <varname>org.gtk.example</varname> is used. For For this example <varname>org.gtk.example</varname> is used. For
choosing an identifier for your application, see choosing an identifier for your application, see
<ulink url="https://wiki.gnome.org/HowDoI/ChooseApplicationID">this guide</ulink>. <ulink url="https://wiki.gnome.org/HowDoI/ChooseApplicationID">this guide</ulink>.
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. application, if your application would have special needs.
</para> </para>
@ -112,14 +112,14 @@
<ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html"> <ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html">
here</ulink>.</para> here</ulink>.</para>
<para>Finally the window size is set using gtk_window_set_default_sizei() <para>Finally the window size is set using gtk_window_set_default_size()
and the window is then shown by GTK via gtk_widget_show().</para> and the window is then shown by GTK via gtk_widget_show().</para>
<para>When you exit the window, by for example pressing the X, <para>When you close the window, by for example pressing the X, the
the g_application_run() in the main loop returns with a number g_application_run() call returns with a number which is saved inside
which is saved inside an integer named "status". Afterwards, the an integer variable named <varname>status</varname>. Afterwards, the
GtkApplication object is freed from memory with g_object_unref(). GtkApplication object is freed from memory with g_object_unref().
Finally the status integer is returned and the GTK application exits.</para> Finally the status integer is returned and the application exits.</para>
<para>While the program is running, GTK is receiving <para>While the program is running, GTK is receiving
<firstterm>events</firstterm>. These are typically input events caused by <firstterm>events</firstterm>. These are typically input events caused by
@ -204,7 +204,7 @@
<ulink url="https://wiki.gnome.org/HowDoI/Buttons">here</ulink>. <ulink url="https://wiki.gnome.org/HowDoI/Buttons">here</ulink>.
</para> </para>
<para>The rest of the code in example-1.c is identical to example-0.c. Next <para>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 section will elaborate further on how to add several GtkWidgets to your GTK
application.</para> application.</para>
</section> </section>
@ -213,9 +213,8 @@
<title>Packing</title> <title>Packing</title>
<para>When creating an application, you'll want to put more than one widget <para>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, inside a window. When you do so, it becomes important to control how each widget
it becomes important to control how each widget is positioned and sized. is positioned and sized. This is where packing comes in.</para>
This is where packing comes in.</para>
<para>GTK comes with a large variety of <firstterm>layout containers</firstterm> <para>GTK comes with a large variety of <firstterm>layout containers</firstterm>
whose purpose it is to control the layout of the child widgets that are whose purpose it is to control the layout of the child widgets that are
@ -245,16 +244,60 @@
</para> </para>
</section> </section>
<section>
<title>Custom Drawing</title>
<para>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.
</para>
<para>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.</para>
<para>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.</para>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="drawing.png" format="PNG"/>
</imageobject>
</mediaobject>
</informalfigure>
<example id="gtk-getting-started-drawing">
<title>Drawing in response to input</title>
<para>Create a new file with the following content named example-4.c.</para>
<programlisting><xi:include href="@SRC_DIR@/examples/drawing.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
</example>
<para>
You can compile the program above with GCC using:
<literallayout>
<literal>gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`</literal>
</literallayout>
</para>
</section>
<section> <section>
<title>Building user interfaces</title> <title>Building user interfaces</title>
<para>When construcing a more complicated user interface, with dozens <para>When constructing a more complicated user interface, with dozens
or hundreds of widgets, doing all the setup work in C code is or hundreds of widgets, doing all the setup work in C code is
cumbersome, and making changes becomes next to impossible.</para> cumbersome, and making changes becomes next to impossible.</para>
<para>Thankfully, GTK supports the separation of user interface <para>Thankfully, GTK supports the separation of user interface
layout from your business logic, by using UI descriptions in an layout from your business logic, by using UI descriptions in an
XML format that can be parsed by the #GtkBuilder class.</para> XML format that can be parsed by the GtkBuilder class.</para>
<example> <example>
<title>Packing buttons with GtkBuilder</title> <title>Packing buttons with GtkBuilder</title>
@ -333,8 +376,8 @@
application menus, settings, GtkHeaderBar, GtkStack, GtkSearchBar, application menus, settings, GtkHeaderBar, GtkStack, GtkSearchBar,
GtkListBox, and more.</para> GtkListBox, and more.</para>
<para>The full, buildable sources for these examples can be found <para>The full, buildable sources for these examples can be found in the
in the examples/ directory of the GTK source distribution, or <filename>examples/</filename> directory of the GTK source distribution, or
<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/master/examples">online</ulink> in the GTK git repository. <ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/master/examples">online</ulink> in the GTK git repository.
You can build each example separately by using make with the <filename>Makefile.example</filename> You can build each example separately by using make with the <filename>Makefile.example</filename>
file. For more information, see the <filename>README</filename> included in the file. For more information, see the <filename>README</filename> included in the
@ -887,10 +930,7 @@ example_app_window_init (ExampleAppWindow *win)
<para>The code to populate the sidebar with buttons for the words <para>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 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.</para> look at the code to add a checkbutton for the new feature to the menu.</para>
<para>As expected by now, the gears menu is specified in a GtkBuilder
ui file.</para>
<informalexample> <informalexample>
<programlisting><xi:include href="@SRC_DIR@/examples/application8/gears-menu.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting> <programlisting><xi:include href="@SRC_DIR@/examples/application8/gears-menu.ui" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
@ -1005,48 +1045,4 @@ example_app_window_init (ExampleAppWindow *win)
</section> </section>
</section> </section>
<section>
<title>Custom Drawing</title>
<para>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.
</para>
<para>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.</para>
<para>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.</para>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="drawing.png" format="PNG"/>
</imageobject>
</mediaobject>
</informalfigure>
<example id="gtk-getting-started-drawing">
<title>Drawing in response to input</title>
<para>Create a new file with the following content named example-4.c.</para>
<programlisting><xi:include href="@SRC_DIR@/examples/drawing.c" parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
</example>
<para>
You can compile the program above with GCC using:
<literallayout>
<literal>gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`</literal>
</literallayout>
</para>
</section>
</chapter> </chapter>

568
docs/reference/gtk/migrating-3to4.xml
View File

@ -80,38 +80,52 @@
<para> <para>
GTK 4 removes the GDK_WA_CURSOR flag. Instead, just use GTK 4 removes the GDK_WA_CURSOR flag. Instead, just use
gdk_window_set_cursor() to set a cursor on the window after gdk_window_set_cursor() to set a cursor on the window after
creating it. creating it. GTK 4 also removes the GDK_WA_VISUAL flag, and
</para> always uses an RGBA visual for windows. To prepare your code
<para> for this, use
GTK 4 also removes the GDK_WA_VISUAL flag, and always uses
an RGBA visual for windows. To prepare your code for this, use
<literal>gdk_window_set_visual (gdk_screen_get_rgba_visual ())</literal> <literal>gdk_window_set_visual (gdk_screen_get_rgba_visual ())</literal>
after creating your window. after creating your window.
</para>
<para>
GTK 4 also removes the GDK_WA_WMCLASS flag. If you need this GTK 4 also removes the GDK_WA_WMCLASS flag. If you need this
X11-specific functionality, use XSetClassHint() directly. X11-specific functionality, use XSetClassHint() directly.
</para> </para>
</section> </section>
<section>
<title>Stop using direct access to GdkEvent structs</title>
<para>
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.
</para>
</section>
<section>
<title>Stop using gdk_pointer_warp()</title>
<para>
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
<function>XWarpPointer()</function> directly.
</para>
</section>
<section> <section>
<title>Stop using non-RGBA visuals</title> <title>Stop using non-RGBA visuals</title>
<para> <para>
GTK 4 always uses RGBA visuals for its windows; you should make GTK 4 always uses RGBA visuals for its windows; you should make
sure that your code works with that. sure that your code works with such visuals. At the same time,
</para> you should stop using GdkVisual APIs, since this object not longer
<para> exists in GTK 4. Most of its APIs are deprecated already and not
At the same time, you should stop using GdkVisual APIs, this object useful when dealing with RGBA visuals.
not longer exist in GTK 4. Most of its APIs are deprecated already
and not useful when dealing with RGBA visuals.
</para> </para>
</section> </section>
<section> <section>
<title>Stop using GtkBox:padding, GtkBox:fill and GtkBox:expand</title> <title>Stop using GtkBox padding, fill and expand child properties</title>
<para> <para>
GTK 4 removes these #GtkBox child properties, so you should not use them. GTK 4 removes these #GtkBox child properties, so you should stop using
You can replace GtkBox:padding using the #GtkWidget:margin properties them. You can replace GtkBox:padding using the #GtkWidget:margin properties
on your #GtkBox child widgets. on your #GtkBox child widgets.
</para> </para>
<para> <para>
@ -152,8 +166,9 @@
<section> <section>
<title>Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()</title> <title>Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()</title>
<para> <para>
These functions are not supported in GTK 4. Instead, either use backend-specific These functions are not supported in GTK 4. Instead, either use
APIs, or render your widgets using #GtkWidgetClass.snapshot(). backend-specific APIs, or render your widgets using
#GtkWidgetClass.snapshot() (once you are using GTK 4).
</para> </para>
</section> </section>
@ -165,7 +180,7 @@
not supported in GTK 4. Instead, you can just pack a GtkImage inside 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 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 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().
</para> </para>
</section> </section>
@ -180,12 +195,11 @@
<section> <section>
<title>Set a proper application ID</title> <title>Set a proper application ID</title>
<para> <para>
In GTK 4 we want the application's #GApplication In GTK 4 we want the application's #GApplication 'application-id'
'application-id' (and therefore the D-Bus name), the desktop (and therefore the D-Bus name), the desktop file basename and Wayland's
file basename and Wayland's xdg-shell app_id to match. In xdg-shell app_id to match. In order to achieve this with GTK 3.x call
order to achieve this with GTK 3.x call g_set_prgname() with the same g_set_prgname() with the same application ID you passed to #GtkApplication.
application ID you passed to #GtkApplication. Rename your Rename your desktop files to match the application ID if needed.
desktop files to match the application ID if needed.
</para> </para>
<para> <para>
The call to g_set_prgname() can be removed once you fully migrated The call to g_set_prgname() can be removed once you fully migrated
@ -203,21 +217,19 @@
<title>Stop using gtk_main() and related APIs</title> <title>Stop using gtk_main() and related APIs</title>
<para> <para>
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, is GtkApplication, but you can also iterate the GLib mainloop directly,
using GMainContext APIs. using GMainContext APIs. The replacement for gtk_events_pending() is
</para> g_main_context_pending(), the replacement for gtk_main_iteration() is
<para> g_main_context_iteration().
The replacement for gtk_events_pending() is g_main_context_pending(),
the replacement for gtk_main_iteration() is g_main_context_iteration().
</para> </para>
</section> </section>
<section> <section>
<title>Reduce the use of gtk_widget_destroy()</title> <title>Reduce the use of gtk_widget_destroy()</title>
<para> <para>
GTK4 introduces a gtk_window_destroy() api. While that is not available GTK 4 introduces a gtk_window_destroy() api. While that is not available
in GTK3, you can prepare for the switch by using gtk_widget_destroy() in GTK 3, you can prepare for the switch by using gtk_widget_destroy()
only on toplevel windows, and replace all other uses with only on toplevel windows, and replace all other uses with
gtk_container_remove() or g_object_unref(). gtk_container_remove() or g_object_unref().
</para> </para>
@ -226,8 +238,8 @@
<section> <section>
<title>Reduce the use of generic container APIs</title> <title>Reduce the use of generic container APIs</title>
<para> <para>
GTK4 removes gtk_container_add() and gtk_container_remove(). While there GTK 4 removes gtk_container_add() and gtk_container_remove(). While there
is not always a replacement for gtk_container_remove() in GTK3, you can 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 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 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. the amount of work you have to do at the time of the switch.
@ -245,17 +257,6 @@
have been either impossible or impractical. have been either impossible or impractical.
</para> </para>
<section>
<title>Convert your ui files</title>
<para>
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.
</para>
</section>
<section> <section>
<title>Stop using GdkScreen</title> <title>Stop using GdkScreen</title>
<para> <para>
@ -269,9 +270,8 @@
<title>Stop using the root window</title> <title>Stop using the root window</title>
<para> <para>
The root window is an X11-centric concept that is no longer exposed in the 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 backend-neutral GDK API. If you need to interact with the X11 root window,
windows. If you need to interact with the X11 root window, you can use you can use gdk_x11_display_get_xrootwindow() to get its XID.
gdk_x11_display_get_xrootwindow() to get its XID.
</para> </para>
</section> </section>
@ -297,113 +297,80 @@
GdkWindow has been renamed to GdkSurface. GdkWindow has been renamed to GdkSurface.
</para> </para>
<para> <para>
The gdk_window_new() function has been replaced by a number of more In GTK 4, the two roles of a standalone toplevel window and of a popup
specialized constructors: gdk_surface_new_toplevel(), gdk_surface_new_popup(), that is placed relative to a parent window have been separated out into
gdk_surface_new_temp(), gdk_wayland_surface_new_subsurface(). two interfaces, #GdkToplevel and #GdkPopup. Surfaces implementing these
Use the appropriate ones to create your windows. 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.
</para> </para>
<para> <para>
Native and foreign subwindows are no longer supported. These concepts were As part of this reorganization, X11-only concepts such as sticky or
complicating the code and could not be supported across backends. 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.
</para> </para>
<para> <para>
gdk_window_reparent() is no longer available. gdk_window_reparent() is no longer available.
</para> </para>
<para>
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().
</para>
</section>
<section>
<title>The "iconified" window state has been renamed to "minimized"</title>
<para>
The <literal>GDK_SURFACE_STATE_ICONIFIED</literal> value of the
#GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED.
</para>
<para>
The #GdkWindow functions <function>gdk_window_iconify()</function>
and <function>gdk_window_deiconify()</function> have been renamed to
gdk_toplevel_minimize() and gdk_toplevel_present(), respectively.
</para>
<para>
The behavior of the minimization and unminimization operations have
not been changed, and they still require support from the underlying
windowing system.
</para>
</section> </section>
<section> <section>
<title>Adapt to GdkEvent API changes</title> <title>Adapt to GdkEvent API changes</title>
<para> <para>
Direct access to GdkEvent structs is no longer possible in Direct access to GdkEvent structs is no longer possible in GTK 4.
GTK 4. Some frequently-used fields already had accessors GdkEvent is now a strictly read-only type, and you can no longer
in GTK 3, and the remaining fields have gained accessors change any of its fields, or construct new events. All event fields
in GTK 4. have accessors that you will have to use.
</para> </para>
<para> <para>
GdkEvent is now a strictly read-only type, and you Event compression is always enabled in GTK 4. If you need to see
can no longer change any of its fields, or construct new the uncoalesced motion history, use gdk_motion_event_get_history()
events. on the latest motion event.
</para>
</section>
<section>
<title>Stop using gdk_surface_set_event_compression</title>
<para>
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.
</para>
</section>
<section>
<title>Stop using gdk_pointer_warp()</title>
<para>
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
<function>XWarpPointer()</function> directly.
</para> </para>
</section> </section>
<section> <section>
<title>Stop using grabs</title> <title>Stop using grabs</title>
<para> <para>
GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() apis. GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab()
</para> apis. If you need to dismiss a popup when the user clicks outside
<para> (the most common use for grabs), you can use the GdkPopup
If you need to dismiss a popup when the user clicks outside (the most common #GdkPopup:autohide property instead. GtkPopover also has a
use for grabs), you can use the GdkPopup #GdkPopup:autohide property instead. #GtkPopover:autohide property for this. If you need to prevent
GtkPopover also has a #GtkPopover:autohide property. the user from interacting with a window while a dialog is open,
</para> use the #GtkWindow:modal property of the dialog.
<para>
If you need to prevent the user from interacting with a window
while a dialog is open, use #GtkWindow:modal on the dialog.
</para>
</section>
<section>
<title>Stop using gtk_get_current_... APIs</title>
<para>
The function gtk_get_current_event() and its variants have been
replaced by equivalent event controller APIs:
gtk_event_controller_get_current_event(), etc.
</para>
</section>
<section>
<title>Adapt to surface API changes</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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().
</para> </para>
</section> </section>
@ -418,7 +385,7 @@
</para> </para>
<para> <para>
Any APIs that deal with global (or root) coordinates have been 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. replace your use of such APIs with surface-relative equivalents.
Examples of this are gdk_surface_get_origin(), gdk_surface_move() Examples of this are gdk_surface_get_origin(), gdk_surface_move()
or gdk_event_get_root_coords(). or gdk_event_get_root_coords().
@ -435,15 +402,14 @@
on the #GdkDevice representing the keyboard: #GdkDevice:direction, on the #GdkDevice representing the keyboard: #GdkDevice:direction,
#GdkDevice:has-bidi-layouts, #GdkDevice:caps-lock-state, #GdkDevice:has-bidi-layouts, #GdkDevice:caps-lock-state,
#GdkDevice:num-lock-state, #GdkDevice:scroll-lock-state and #GdkDevice:num-lock-state, #GdkDevice:scroll-lock-state and
#GdkDevice:modifier-state. #GdkDevice:modifier-state. To obtain the keyboard device, you can use
To obtain the keyboard device, you can use
<literal>gdk_seat_get_keyboard (gdk_display_get_default_seat (display))</literal>. <literal>gdk_seat_get_keyboard (gdk_display_get_default_seat (display))</literal>.
</para> </para>
<para> <para>
If you need access to translated keys for event handling, #GdkEvent If you need access to translated keys for event handling, #GdkEvent
now includes all of the translated key state, including consumed now includes all of the translated key state, including consumed
modifiers, group and shift level, so there should be no need to 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). been removed).
</para> </para>
<para> <para>
@ -454,21 +420,6 @@
</para> </para>
</section> </section>
<section>
<title>Adapt to event controller API changes</title>
<para>
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.
</para>
</section>
<section> <section>
<title>Adapt to changes in keyboard modifier handling</title> <title>Adapt to changes in keyboard modifier handling</title>
<para> <para>
@ -501,6 +452,39 @@
</para> </para>
</section> </section>
<section>
<title>Stop using gtk_get_current_... APIs</title>
<para>
The function gtk_get_current_event() and its variants have been
replaced by equivalent event controller APIs:
gtk_event_controller_get_current_event(), etc.
</para>
</section>
<section>
<title>Convert your ui files</title>
<para>
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.
</para>
</section>
<section>
<title>Adapt to event controller API changes</title>
<para>
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.
</para>
</section>
<section> <section>
<title>Focus handling changes</title> <title>Focus handling changes</title>
<para> <para>
@ -509,17 +493,15 @@
accept keyboard input, but its children still might (in the case of 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 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 the widget or any of its descendents, and the default value has changed
from %FALSE to %TRUE. from %FALSE to %TRUE. In addition, there is a #GtkWidget:focusable
</para> property, which controls whether an individual widget can receive
<para> the input focus.
The recommended way to influence focus behavior of custom widgets
in GTK 4 is to override the focus() and grab_focus() vfuncs.
</para> </para>
<para> <para>
The feature to automatically keep the focus widget scrolled into view The feature to automatically keep the focus widget scrolled into view
with gtk_container_set_focus_vadjustment() has been removed from with gtk_container_set_focus_vadjustment() has been removed together with
GtkContainer, and is provided by scrollables instead. In the common case GtkContainer, and is provided by scrollable widgets instead. In the common
that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus. case that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus.
</para> </para>
</section> </section>
@ -541,8 +523,8 @@
<section> <section>
<title>Adapt to GtkBox API changes</title> <title>Adapt to GtkBox API changes</title>
<para> <para>
GtkBox no longer has pack-start and -end. Pack your widgets in the The GtkBox pack-start and -end methods have been replaced by gtk_box_prepend()
correct order, or reorder them as necessary. and gtk_box_append(). You can also reorder box children as necessary.
</para> </para>
</section> </section>
@ -550,8 +532,8 @@
<title>Adapt to GtkHeaderBar and GtkActionBar API changes</title> <title>Adapt to GtkHeaderBar and GtkActionBar API changes</title>
<para> <para>
The gtk_header_bar_set_show_close_button() function has been renamed to 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 the more accurate name gtk_header_bar_set_show_title_buttons(). The
getter and the property itself have also been renamed. corresponding getter and the property itself have also been renamed.
</para> </para>
<para> <para>
The ::pack-type child properties of GtkHeaderBar and GtkActionBar have The ::pack-type child properties of GtkHeaderBar and GtkActionBar have
@ -586,8 +568,11 @@
<para> <para>
The abstract base class GtkBin for single-child containers has been The abstract base class GtkBin for single-child containers has been
removed. The former subclasses are now derived directly from GtkWidget, removed. The former subclasses are now derived directly from GtkWidget,
and have a "child" property for their child widget. The affected classes and have a "child" property for their child widget. To add a child, use
are: 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
<tag class="starttag">child</tag> still works.
The affected classes are:
</para> </para>
<simplelist> <simplelist>
<member>GtkAspectFrame</member> <member>GtkAspectFrame</member>
@ -605,19 +590,30 @@
<member>GtkWindow (and subclasses)</member> <member>GtkWindow (and subclasses)</member>
</simplelist> </simplelist>
<para> <para>
To add a child, use the setter for the "child" property (e.g. If you have custom widgets that were derived from GtkBin, you should
gtk_frame_set_child()) instead of gtk_container_add(). Adding a child port them to derive from GtkWidget. Notable vfuncs that you will have
in a ui file with <tag class="starttag">child</tag> still works. 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.
</para>
<para>
You may also want to implement the GtkBuildable interface, to support
adding children with <tag class="starttag">child</tag> in ui files.
</para> </para>
</section> </section>
<section> <section>
<title>Adapt to GtkContainer removal</title> <title>Adapt to GtkContainer removal</title>
<para> <para>
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, removed. The former subclasses are now derived directly from GtkWidget,
and have class-specific add and remove functions. The affected classes and have class-specific add() and remove() functions.
are: 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
<tag class="starttag">child</tag> still works.
The affected classes are:
</para> </para>
<simplelist> <simplelist>
<member>GtkActionBar</member> <member>GtkActionBar</member>
@ -637,11 +633,22 @@
<member>GtkTreeView</member> <member>GtkTreeView</member>
</simplelist> </simplelist>
<para> <para>
The most noticable change will be to use gtk_box_append() or gtk_box_prepend() Without GtkContainer, there are no longer facilities for defining and
instead of gtk_container_add() for adding children to GtkBox, and the change using child properties. If you have custom widgets using child properties,
to use container-specific remove functions, such as gtk_stack_remove() instead they will have to be converted either to layout properties provided
of gtk_container_remove(). Adding a child in a ui file with by a layout manager (if they are layout-related), or handled in some
<tag class="starttag">child</tag> still works. other way. One possibility is to use child meta objects, as seen with
GtkAssistantPage, GtkStackPage and the like.
</para>
</section>
<section>
<title>Stop using GtkContainer::border-width</title>
<para>
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.
</para> </para>
</section> </section>
@ -677,22 +684,10 @@
<section> <section>
<title>Adapt to GtkCssProvider API changes</title> <title>Adapt to GtkCssProvider API changes</title>
<para> <para>
In GTK 4, the various #GtkCssProvider load functions have lost In GTK 4, the various #GtkCssProvider load functions have lost their
their #GError argument. If you want to handle CSS loading errors, #GError argument. If you want to handle CSS loading errors, use the
use the #GtkCssProvider::parsing-error signal instead. #GtkCssProvider::parsing-error signal instead. gtk_css_provider_get_named()
</para> has been replaced by gtk_css_provider_load_named().
<para>
gtk_css_provider_get_named() has been replaced by
gtk_css_provider_load_named().
</para>
</section>
<section>
<title>Stop using GtkContainer::border-width</title>
<para>
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.
</para> </para>
</section> </section>
@ -714,28 +709,33 @@
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 family of functions. To simplify widget implementations, GTK 4 uses
only one virtual function, GtkWidgetClass::measure() that widgets 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.
</para> </para>
</section> </section>
<section> <section>
<title>Adapt to GtkWidget's size allocation changes</title> <title>Adapt to GtkWidget's size allocation changes</title>
<para> <para>
The #GtkWidget::size-allocate signal now takes the baseline as an The #GtkWidget.size_allocate() vfunc takes the baseline as an argument
argument, so you no longer need to call gtk_widget_get_allocated_baseline() now, so you no longer need to call gtk_widget_get_allocated_baseline()
to get it. to get it.
</para> </para>
<para>
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.
</para>
</section> </section>
<section> <section>
<title>Switch to GtkWidget's children APIs</title> <title>Switch to GtkWidget's children APIs</title>
<para> <para>
Instead of the GtkContainer subclass, in GTK 4, any widget can In GTK 4, any widget can have children (and GtkContainer is gone).
have children, and there is new API to navigate the widget tree: There is new API to navigate the widget tree, for use in widget
gtk_widget_get_first_child(), gtk_widget_get_last_child(), implementations: gtk_widget_get_first_child(), gtk_widget_get_last_child(),
gtk_widget_get_next_sibling(), gtk_widget_get_prev_sibling(). 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.
</para> </para>
</section> </section>
@ -757,18 +757,17 @@
</section> </section>
<section> <section>
<title>Don't use -gtk-outline-...-radius in your CSS</title> <title>Don't use -gtk-icon-theme in your CSS</title>
<para> <para>
These non-standard properties have been removed from GTK GTK now uses the current icon theme, without a way to change this.
CSS. Just use regular border radius.
</para> </para>
</section> </section>
<section> <section>
<title>Use gtk_widget_measure</title> <title>Don't use -gtk-outline-...-radius in your CSS</title>
<para> <para>
gtk_widget_measure() replaces the various gtk_widget_get_preferred_ functions These non-standard properties have been removed from GTK
for querying sizes. CSS. Just use regular border radius.
</para> </para>
</section> </section>
@ -809,6 +808,8 @@
The default value of #GtkWidget:visible in GTK 4 is %TRUE, so you no 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 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. 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.
</para> </para>
<para> <para>
A convenient way to remove unnecessary property assignments like this A convenient way to remove unnecessary property assignments like this
@ -817,7 +818,8 @@
</para> </para>
<para> <para>
The function gtk_widget_show_all(), the #GtkWidget:no-show-all property 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.
</para> </para>
</section> </section>
@ -848,11 +850,8 @@
<para> <para>
A number of #GdkPixbuf-based APIs have been removed. The available replacements A number of #GdkPixbuf-based APIs have been removed. The available replacements
are either using #GIcon, or the newly introduced #GdkTexture or #GdkPaintable are either using #GIcon, or the newly introduced #GdkTexture or #GdkPaintable
classes instead. classes instead. If you are dealing with pixbufs, you can use
</para> gdk_texture_new_for_pixbuf() to convert them to texture objects where needed.
<para>
If you are dealing with pixbufs, you can use gdk_texture_new_for_pixbuf()
to convert them to texture objects where needed.
</para> </para>
</section> </section>
@ -878,7 +877,9 @@
<title>Stop using GtkWidget::draw</title> <title>Stop using GtkWidget::draw</title>
<para> <para>
The #GtkWidget::draw signal has been removed. Widgets need to implement the 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().
</para> </para>
</section> </section>
@ -926,24 +927,15 @@
to override the icon size. to override the icon size.
</para> </para>
<para> <para>
The ::stock-size property of GtkCellRendererPixbuf has been renamed to The :stock-size property of GtkCellRendererPixbuf has been renamed to
#GtkCellRendererPixbuf:icon-size. #GtkCellRendererPixbuf:icon-size.
</para> </para>
</section> </section>
<section>
<title>Convert .ui files</title>
<para>
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.
</para>
</section>
<section> <section>
<title>Adapt to changes in the GtkAssistant API</title> <title>Adapt to changes in the GtkAssistant API</title>
<para> <para>
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. to pages. You can easily do that yourself.
</para> </para>
</section> </section>
@ -969,8 +961,8 @@
<section> <section>
<title>Adapt to changes in GtkOverlay API</title> <title>Adapt to changes in GtkOverlay API</title>
<para> <para>
The GtkOverlay::pass-through child property has been replaced by the The GtkOverlay :pass-through child property has been replaced by the
GtkWidget::can-target property. Note that they have the opposite sense: #GtkWidget:can-target property. Note that they have the opposite sense:
pass-through == !can-target. pass-through == !can-target.
</para> </para>
</section> </section>
@ -995,37 +987,15 @@
</para> </para>
</section> </section>
<section>
<title>Stop using child properties</title>
<para>
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.
</para>
</section>
<section>
<title>Stop using gtk_menu_set_display()</title>
<para>
This function has been removed. Menus should always be
attached to a widget and get their display that way.
</para>
</section>
<section> <section>
<title>Stop using gtk_window_activate_default()</title> <title>Stop using gtk_window_activate_default()</title>
<para> <para>
The handling of default widgets has been changed, and activating 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 gtk_widget_activate_default()
on the widget that caused the activation. on the widget that caused the activation. If you have a custom widget
</para> that wants to override the default handling, you can provide an
<para> implementation of the default.activate action in your widgets' action
If you have a custom widget that wants to override the default groups.
handling, you can provide an implementation of the default.activate
action in your widgets' action groups.
</para> </para>
</section> </section>
@ -1042,7 +1012,7 @@
<section> <section>
<title>Stop using the GtkWidget::display-changed signal</title> <title>Stop using the GtkWidget::display-changed signal</title>
<para> <para>
To track the current display, use the GtkWidget::root property To track the current display, use the #GtkWidget::root property
instead. instead.
</para> </para>
</section> </section>
@ -1097,29 +1067,6 @@
</para> </para>
</section> </section>
<section>
<title>The "iconified" window state has been renamed to "minimized"</title>
<para>
The <literal>GDK_SURFACE_STATE_ICONIFIED</literal> value of the
#GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED.
</para>
<para>
The #GdkSurface functions <function>gdk_surface_iconify()</function>
and <function>gdk_surface_deiconify()</function> have been renamed to
gdk_toplevel_minimize() and gdk_toplevel_present(), respectively.
</para>
<para>
The corresponding #GtkWindow functions <function>gtk_window_iconify()</function>
and <function>gtk_window_deiconify()</function> have been renamed
to gtk_window_minimize() and gtk_window_unminimize(), respectively.
</para>
<para>
The behavior of the minimization and unminimization operations have
not been changed, and they still require support from the underlying
windowing system.
</para>
</section>
<section> <section>
<title>GtkMenu, GtkMenuBar and GtkMenuItem are gone</title> <title>GtkMenu, GtkMenuBar and GtkMenuItem are gone</title>
<para> <para>
@ -1139,7 +1086,6 @@
complex layout in menu-like popups, consider directly using a complex layout in menu-like popups, consider directly using a
#GtkPopover instead. #GtkPopover instead.
</para> </para>
<para> <para>
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. and needs to be used with popovers in GTK 4.
@ -1150,10 +1096,8 @@
<title>GtkToolbar has been removed</title> <title>GtkToolbar has been removed</title>
<para> <para>
Toolbars were using outdated concepts such as requiring special toolitem Toolbars were using outdated concepts such as requiring special toolitem
widgets. widgets. Toolbars should be replaced by using a GtkBox with regular widgets
</para> instead and the "toolbar" style class.
<para>
Toolbars should be replaced by using a GtkBox with regular widgets instead.
</para> </para>
</section> </section>
@ -1177,46 +1121,36 @@
</section> </section>
<section> <section>
<title>Switch to the new DND api</title> <title>Switch to the new Drag-and-Drop api</title>
<para> <para>
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.
</para> </para>
<para> <para>
Instead of calling gtk_drag_source_set() and connecting to #GtkWidget signals, you create The destination-side Drag-and-Drop apis in GTK 4 have also been changed
a #GtkDragSource object, attach it to the widget with gtk_widget_add_controller(), and connect to use an event controller, #GtkDropTarget. Instead of calling
to #GtkDragSource signals. Instead of calling gtk_drag_begin() on a widget to start a drag gtk_drag_dest_set() and connecting to #GtkWidget signals, you create
manually, call gdk_drag_begin(). a #GtkDropTarget object, attach it to the widget with
</para> gtk_widget_add_controller(), and connect to #GtkDropTarget signals.
<para> The ::drag-motion signal has been renamed to #GtkDropTarget::accept, and
The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare signal, which instead of ::drag-data-received, you need to use async read methods on the
returns a #GdkContentProvider for the drag operation. #GdkDrop object, such as gdk_drop_read_async() or gdk_drop_read_value_async().
</para>
<para>
The destination-side DND apis in GTK 4 have also been changed to use and event controller,
#GtkDropTarget.
</para>
<para>
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.
</para>
<para>
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().
</para> </para>
</section> </section>
<section> <section>
<title>Adapt to GtkIconTheme API changes</title> <title>Adapt to GtkIconTheme API changes</title>
<para> <para>
gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable object now, instead
object now, instead of a #GtkIconInfo. It always returns of a #GtkIconInfo. It always returns a paintable in the requested size, and
a paintable in the requested size, and never fails. never fails. A number of no-longer-relevant lookup flags and API variants
</para> have been removed.
<para>
A number of no-longer-relevant lookup flags and API
variants have been removed.
</para> </para>
</section> </section>

109
docs/reference/gtk/question_index.xml
View File

@ -37,8 +37,10 @@ How do I get started with GTK?
<answer><para> <answer><para>
The GTK <ulink url="https://www.gtk.org">website</ulink> offers some The GTK <ulink url="https://www.gtk.org">website</ulink> offers some
<ulink url="https://www.gtk.org/documentation.php">tutorials</ulink> and other <ulink url="https://www.gtk.org/documentation.php">tutorials</ulink> and other
documentation (most of it about GTK 2.x, but mostly still applicable). documentation (most of it about GTK 2.x, but still somewhat applicable). This
More documentation ranging from whitepapers to online books can be found at reference manual also contains a introductory
<link linkend="gtk-getting-started">Getting Started</link> part.</para>
<para>More documentation ranging from whitepapers to online books can be found at
the <ulink url="https://developer.gnome.org">GNOME developer's site</ulink>. the <ulink url="https://developer.gnome.org">GNOME developer's site</ulink>.
After studying these materials you should be well prepared to come back to After studying these materials you should be well prepared to come back to
this reference manual for details. this reference manual for details.
@ -70,13 +72,9 @@ How do I port from one GTK version to another?
<para> <para>
See <xref linkend="migrating"/>. See <xref linkend="migrating"/>.
You may also find useful information in the documentation for You may also find useful information in the documentation for specific widgets
specific widgets and functions. and functions. If you have a question not covered in the manual, feel free to
</para> ask, and please <ulink
<para>
If you have a question not covered in the manual, feel free to
ask on the mailing lists and please <ulink
url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink> url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>
against the documentation. against the documentation.
</para> </para>
@ -108,6 +106,11 @@ undocumented exception to the rules, please
<ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>. <ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>.
</para> </para>
<para>
The transfer annotations for gobject-introspection that are part of the
documentation can provide useful hints for memory handling semantics as well.
</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -126,24 +129,23 @@ If <structname>GtkFoo</structname> isn't a toplevel window, then
foo = gtk_foo_new (); foo = gtk_foo_new ();
g_object_unref (foo); g_object_unref (foo);
</programlisting></informalexample> </programlisting></informalexample>
is a memory leak, because no one assumed the initial floating is a memory leak, because no one assumed the initial floating reference
reference. If you are using a widget and you aren't immediately (you will get a warning about this too). If you are using a widget and
packing it into a container, then you probably want standard you aren't immediately packing it into a container, then you probably
reference counting, not floating reference counting. want standard reference counting, not floating reference counting.
</para> </para>
<para> <para>
To get this, you must acquire a reference to the widget and drop the To get this, you must acquire a reference to the widget and drop the
floating reference (<quote>ref and sink</quote> in GTK parlance) after floating reference (<quote>ref and sink</quote> in GObject parlance) after
creating it: creating it:
<informalexample><programlisting> <informalexample><programlisting>
foo = gtk_foo_new (); foo = gtk_foo_new ();
g_object_ref_sink (foo); g_object_ref_sink (foo);
</programlisting></informalexample> </programlisting></informalexample>
When you immediately add a widget to a container, it takes care of When you immediately add a widget to a container, it takes care of assuming
assuming the initial floating reference and you don't have to worry the initial floating reference and you don't have to worry about reference
about reference counting at all ... just call gtk_container_remove() counting at all ... just remove the widget from the container to get rid of it.
to get rid of the widget.
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -156,9 +158,13 @@ How do I use GTK with threads?
<answer> <answer>
<para> <para>
This is covered in the <link linkend="gdk-Threads">GDK threads GTK requires that all GTK API calls are made from the same thread in which
documentation</link>. See also the <link linkend="glib-Threads">GThread</link> gtk_init() was called (the <quote>main thread</quote>).</para>
documentation for portable threading primitives.
<para>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.
</para> </para>
</answer> </answer>
@ -178,9 +184,9 @@ or Linux system with gettext installed, type <literal>info gettext</literal>
to read the documentation. to read the documentation.
</para> </para>
<para> <para>
The short checklist on how to use gettext is: call <literal>bindtextdomain(<!-- -->)</literal> so The short checklist on how to use gettext is: call bindtextdomain() so
gettext can find the files containing your translations, call textdomain() gettext can find the files containing your translations, call textdomain()
to set the default translation domain, call <literal>bind_textdomain_codeset(<!-- -->)</literal> to to set the default translation domain, call bind_textdomain_codeset() to
request that all translated strings are returned in UTF-8, then call 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. gettext() to look up each string to be translated in the default domain.
</para> </para>
@ -352,7 +358,7 @@ g_free (text);
</para> </para>
<para> <para>
If you are using gettext() to localize your application, you need to If you are using gettext() to localize your application, you need to
call <literal>bind_textdomain_codeset(<!-- -->)</literal> to ensure that translated strings are call bind_textdomain_codeset() to ensure that translated strings are
returned in UTF-8 encoding. returned in UTF-8 encoding.
</para> </para>
</answer> </answer>
@ -425,19 +431,9 @@ How do I load an image or animation from a file?
<para> <para>
To load an image file straight into a display widget, use To load an image file straight into a display widget, use
gtk_image_new_from_file() <footnote><para> If the file load fails, gtk_image_new_from_file(). To load an image for another purpose, use
gtk_image_new_from_file() will display no image graphic &mdash; to detect gdk_texture_new_from_file(). To load a video from a file, use
a failed load yourself, use gdk_pixbuf_new_from_file() directly, then gtk_media_file_new_for_file().
gtk_image_new_from_pixbuf().</para></footnote>.
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.
</para>
<para>
To load an image or animation file asynchronously (without blocking), use
#GdkPixbufLoader.
</para> </para>
</answer> </answer>
@ -450,7 +446,8 @@ How do I draw text ?
<answer> <answer>
<para> <para>
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().
<informalexample> <informalexample>
<programlisting> <programlisting>
layout = gtk_widget_create_pango_layout (widget, text); layout = gtk_widget_create_pango_layout (widget, text);
@ -468,6 +465,11 @@ See also the
<ulink url="https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html">Cairo Rendering</ulink> <ulink url="https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html">Cairo Rendering</ulink>
section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>. section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
</para> </para>
<para>
To draw a piece of text in a widget snapshot() implementation, use
gtk_snapshot_append_layout().
</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -513,10 +515,10 @@ macro ?
<answer> <answer>
<para> <para>
The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to The %GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and
<literal>gtk_blah_get_type(<!-- -->)</literal>, and the <literal>_get_type(<!-- -->)</literal> the _get_type(<!-- -->) functions are declared as %G_GNUC_CONST which allows
functions are declared as %G_GNUC_CONST which allows the compiler to optimize the compiler to optimize the call away if it appears that the value is not
the call away if it appears that the value is not being used. being used.
</para> </para>
<para> <para>
@ -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, 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. such as draw text or graphics over the top of the image.
</para> </para>
<para>
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:
<informalexample>
<programlisting>
mediafile = gtk_media_file_new_for_filename ("example.webm");
picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile));
</programlisting>
</informalexample>
</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -618,9 +632,7 @@ would use a combo box?
<answer> <answer>
<para> <para>
With GTK, a #GtkComboBox is the recommended widget to use for this use case. 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 If you need an editable text entry, use the #GtkComboBox:has-entry property.
on the current theme. If you need an editable text entry, use the
#GtkComboBox:has-entry property.
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -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 The background color of a widget is determined by the CSS style that applies
to it. To change that, you can set style classes on the widget, and provide to it. To change that, you can set style classes on the widget, and provide
custom CSS to change the appearance. Such CSS can be loaded with 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().
</para></answer> </para></answer>
</qandaentry> </qandaentry>
@ -912,8 +925,8 @@ How do I use cairo to draw in GTK applications ?
</para></question> </para></question>
<answer><para> <answer><para>
Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc to optain Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc
a cairo context and draw with that. to obtain a cairo context and draw with that.
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>

91
docs/reference/gtk/resources.xml
View File

@ -4,13 +4,13 @@
]> ]>
<refentry id="gtk-resources"> <refentry id="gtk-resources">
<refmeta> <refmeta>
<refentrytitle>Mailing lists and bug reports</refentrytitle> <refentrytitle>Contact information and bug reports</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>Mailing lists and bug reports</refmiscinfo> <refmiscinfo>Contact information and bug reports</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>Mailing lists and bug reports</refname> <refname>Contact information and bug reports</refname>
<refpurpose> <refpurpose>
Getting help with GTK Getting help with GTK
</refpurpose> </refpurpose>
@ -35,7 +35,7 @@ discussed, we'll add a note to that effect in the report.
</para> </para>
<para> <para>
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 not only for bugs. We track all GTK development in GitLab, to ensure
that nothing gets lost. that nothing gets lost.
</para> </para>
@ -61,83 +61,16 @@ for GTK, available on GitLab.
<para> <para>
If you want to discuss your approach before or after working on it, If you want to discuss your approach before or after working on it,
send and email to <ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink>. good ways to contact the GTK developers, apart from GitLab issues,
You should not send a patch to the mailing list, as it will inevitably are
get lost, or forgotten. Always open a merge request. <simplelist>
<member>the #gtk IRC channel on irc.gnome.org</member>
<member>the gtk tag on the <ulink url="https://discourse.gnome.org/tag/gtk">GNOME Discourse instance</ulink></member>
</simplelist>
You should not send patches by email, as they will inevitably get lost,
or forgotten. Always open a merge request.
</para> </para>
</refsect1> </refsect1>
<refsect1>
<title>Mailing lists</title>
<para>
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
<ulink url="https://mail.gnome.org">http://mail.gnome.org</ulink>.
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.
</para>
<para>
<variablelist>
<varlistentry>
<term><ulink url="mailto:gtk-list@gnome.org">gtk-list@gnome.org</ulink></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="mailto:gtk-app-devel-list@gnome.org">gtk-app-devel-list@gnome.org</ulink></term>
<listitem><para>
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. </para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink></term>
<listitem><para>
gtk-devel-list is for discussion of work on GTK itself, it is
<emphasis>not</emphasis> 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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="mailto:gtk-i18n-list@gnome.org">gtk-i18n-list@gnome.org</ulink></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="mailto:gtk-doc-list@gnome.org">gtk-doc-list@gnome.org</ulink></term>
<listitem><para>
gtk-doc-list is for discussion of the <application>gtk-doc</application>
documentation system (used to document GTK), and for work on the GTK
documentation.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry> </refentry>

19
gtk/gtkcssprovider.c
View File

@ -52,23 +52,24 @@
* GtkCssProvider is an object implementing the #GtkStyleProvider interface. * GtkCssProvider is an object implementing the #GtkStyleProvider interface.
* It is able to parse [CSS-like][css-overview] input in order to style widgets. * 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() * gtk_css_provider_load_from_file() or gtk_css_provider_load_from_resource()
* and adding the provider with gtk_style_context_add_provider() or * and adding the provider with gtk_style_context_add_provider() or
* gtk_style_context_add_provider_for_display(). * gtk_style_context_add_provider_for_display().
* In addition, certain files will be read when GTK+ is initialized. First, the * 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+ * file `$XDG_CONFIG_HOME/gtk-4.0/gtk.css` is loaded if it exists. Then, GTK
* loads the first existing file among * loads the first existing file among
* `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, * `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css`,
* `$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 * `$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 * `DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css`,
* the current theme (see the #GtkSettings:gtk-theme-name setting), * where `THEME` is the name of the current theme (see the #GtkSettings:gtk-theme-name
* VARIANT is the variant to load (see the #GtkSettings:gtk-application-prefer-dark-theme setting), `DATADIR` * setting), VARIANT is the variant to load (see the
* is the prefix configured when GTK+ was compiled (unless overridden by the * #GtkSettings:gtk-application-prefer-dark-theme setting), `DATADIR`
* `GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK+ version number. * is the prefix configured when GTK was compiled (unless overridden by the
* If no file is found for the current version, GTK+ tries older versions all 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. * way back to 4.0.
*/ */