AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests 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
GTK consists of widgets. This is implemented in C using
<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
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 <varname>org.gtk.example</varname> is used. For
choosing an identifier for your application, see
<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.
</para>
@ -112,14 +112,14 @@
<ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html">
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>
<para>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
<para>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 <varname>status</varname>. Afterwards, the
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
<firstterm>events</firstterm>. These are typically input events caused by
@ -204,7 +204,7 @@
<ulink url="https://wiki.gnome.org/HowDoI/Buttons">here</ulink>.
</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
application.</para>
</section>
@ -213,9 +213,8 @@
<title>Packing</title>
<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,
it becomes important to control how each widget is positioned and sized.
This is where packing comes in.</para>
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.</para>
<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
@ -245,16 +244,60 @@
</para>
</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>
<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
cumbersome, and making changes becomes next to impossible.</para>
<para>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.</para>
XML format that can be parsed by the GtkBuilder class.</para>
<example>
<title>Packing buttons with GtkBuilder</title>
@ -333,8 +376,8 @@
application menus, settings, GtkHeaderBar, GtkStack, GtkSearchBar,
GtkListBox, and more.</para>
<para>The full, buildable sources for these examples can be found
in the examples/ directory of the GTK source distribution, or
<para>The full, buildable sources for these examples can be found in the
<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.
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
@ -887,10 +930,7 @@ example_app_window_init (ExampleAppWindow *win)
<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
look at the code to add the gears menu.</para>
<para>As expected by now, the gears menu is specified in a GtkBuilder
ui file.</para>
look at the code to add a checkbutton for the new feature to the menu.</para>
<informalexample>
<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>
<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>

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

@ -80,38 +80,52 @@
<para>
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.
</para>
<para>
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
<literal>gdk_window_set_visual (gdk_screen_get_rgba_visual ())</literal>
after creating your window.
</para>
<para>
GTK 4 also removes the GDK_WA_WMCLASS flag. If you need this
X11-specific functionality, use XSetClassHint() directly.
</para>
</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>
<title>Stop using non-RGBA visuals</title>
<para>
GTK 4 always uses RGBA visuals for its windows; you should make
sure that your code works with that.
</para>
<para>
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.
</para>
</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>
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.
</para>
<para>
@ -152,8 +166,9 @@
<section>
<title>Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()</title>
<para>
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).
</para>
</section>
@ -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().
</para>
</section>
@ -180,12 +195,11 @@
<section>
<title>Set a proper application ID</title>
<para>
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.
</para>
<para>
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>
<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,
using GMainContext APIs.
</para>
<para>
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().
</para>
</section>
<section>
<title>Reduce the use of gtk_widget_destroy()</title>
<para>
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().
</para>
@ -226,8 +238,8 @@
<section>
<title>Reduce the use of generic container APIs</title>
<para>
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.
</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>
<title>Stop using GdkScreen</title>
<para>
@ -269,9 +270,8 @@
<title>Stop using the root window</title>
<para>
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.
</para>
</section>
@ -297,113 +297,80 @@
GdkWindow has been renamed to GdkSurface.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
gdk_window_reparent() is no longer available.
</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>
<title>Adapt to GdkEvent API changes</title>
<para>
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.
</para>
<para>
GdkEvent is now a strictly read-only type, and you
can no longer change any of its fields, or construct new
events.
</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.
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.
</para>
</section>
<section>
<title>Stop using grabs</title>
<para>
GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() apis.
</para>
<para>
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.
</para>
<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().
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.
</para>
</section>
@ -418,13 +385,13 @@
</para>
<para>
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().
</para>
</section>
<section>
<title>Adapt to GdkKeymap API changes</title>
<para>
@ -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
<literal>gdk_seat_get_keyboard (gdk_display_get_default_seat (display))</literal>.
</para>
<para>
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).
</para>
<para>
@ -454,21 +420,6 @@
</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 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>
<title>Adapt to changes in keyboard modifier handling</title>
<para>
@ -501,6 +452,39 @@
</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>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>
<title>Focus handling changes</title>
<para>
@ -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.
</para>
<para>
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.
</para>
<para>
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.
</para>
</section>
@ -541,8 +523,8 @@
<section>
<title>Adapt to GtkBox API changes</title>
<para>
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.
</para>
</section>
@ -550,8 +532,8 @@
<title>Adapt to GtkHeaderBar and GtkActionBar API changes</title>
<para>
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.
</para>
<para>
The ::pack-type child properties of GtkHeaderBar and GtkActionBar have
@ -586,8 +568,11 @@
<para>
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
<tag class="starttag">child</tag> still works.
The affected classes are:
</para>
<simplelist>
<member>GtkAspectFrame</member>
@ -605,19 +590,30 @@
<member>GtkWindow (and subclasses)</member>
</simplelist>
<para>
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 <tag class="starttag">child</tag> 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.
</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>
</section>
<section>
<title>Adapt to GtkContainer removal</title>
<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,
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
<tag class="starttag">child</tag> still works.
The affected classes are:
</para>
<simplelist>
<member>GtkActionBar</member>
@ -637,11 +633,22 @@
<member>GtkTreeView</member>
</simplelist>
<para>
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
<tag class="starttag">child</tag> 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.
</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>
</section>
@ -677,22 +684,10 @@
<section>
<title>Adapt to GtkCssProvider API changes</title>
<para>
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.
</para>
<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.
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().
</para>
</section>
@ -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.
</para>
</section>
<section>
<title>Adapt to GtkWidget's size allocation changes</title>
<para>
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.
</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>
<title>Switch to GtkWidget's children APIs</title>
<para>
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.
</para>
</section>
@ -757,18 +757,17 @@
</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>
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.
</para>
</section>
<section>
<title>Use gtk_widget_measure</title>
<title>Don't use -gtk-outline-...-radius in your CSS</title>
<para>
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.
</para>
</section>
@ -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.
</para>
<para>
A convenient way to remove unnecessary property assignments like this
@ -817,7 +818,8 @@
</para>
<para>
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>
</section>
@ -848,11 +850,8 @@
<para>
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.
</para>
<para>
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.
</para>
</section>
@ -878,7 +877,9 @@
<title>Stop using GtkWidget::draw</title>
<para>
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>
</section>
@ -926,24 +927,15 @@
to override the icon size.
</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.
</para>
</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>
<title>Adapt to changes in the GtkAssistant API</title>
<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.
</para>
</section>
@ -969,8 +961,8 @@
<section>
<title>Adapt to changes in GtkOverlay API</title>
<para>
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.
</para>
</section>
@ -995,37 +987,15 @@
</para>
</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>
<title>Stop using gtk_window_activate_default()</title>
<para>
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.
</para>
<para>
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.
</para>
</section>
@ -1042,7 +1012,7 @@
<section>
<title>Stop using the GtkWidget::display-changed signal</title>
<para>
To track the current display, use the GtkWidget::root property
To track the current display, use the #GtkWidget::root property
instead.
</para>
</section>
@ -1097,29 +1067,6 @@
</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 #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>
<title>GtkMenu, GtkMenuBar and GtkMenuItem are gone</title>
<para>
@ -1139,7 +1086,6 @@
complex layout in menu-like popups, consider directly using a
#GtkPopover instead.
</para>
<para>
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 @@
<title>GtkToolbar has been removed</title>
<para>
Toolbars were using outdated concepts such as requiring special toolitem
widgets.
</para>
<para>
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.
</para>
</section>
@ -1177,46 +1121,36 @@
</section>
<section>
<title>Switch to the new DND api</title>
<title>Switch to the new Drag-and-Drop api</title>
<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>
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().
</para>
<para>
The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare signal, which
returns a #GdkContentProvider for the drag operation.
</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().
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().
</para>
</section>
<section>
<title>Adapt to GtkIconTheme API changes</title>
<para>
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.
</para>
<para>
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.
</para>
</section>

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

@ -37,8 +37,10 @@ How do I get started with GTK?
<answer><para>
The GTK <ulink url="https://www.gtk.org">website</ulink> offers some
<ulink url="https://www.gtk.org/documentation.php">tutorials</ulink> 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
<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>.
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?
<para>
See <xref linkend="migrating"/>.
You may also find useful information in the documentation for
specific widgets and functions.
</para>
<para>
If you have a question not covered in the manual, feel free to
ask on the mailing lists and please <ulink
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, and please <ulink
url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file a bug report</ulink>
against the documentation.
</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>.
</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>
</qandaentry>
@ -126,24 +129,23 @@ If <structname>GtkFoo</structname> isn't a toplevel window, then
foo = gtk_foo_new ();
g_object_unref (foo);
</programlisting></informalexample>
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.
</para>
<para>
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:
<informalexample><programlisting>
foo = gtk_foo_new ();
g_object_ref_sink (foo);
</programlisting></informalexample>
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.
</para>
</answer>
</qandaentry>
@ -156,9 +158,13 @@ How do I use GTK with threads?
<answer>
<para>
This is covered in the <link linkend="gdk-Threads">GDK threads
documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
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 <quote>main thread</quote>).</para>
<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>
</answer>
@ -178,9 +184,9 @@ or Linux system with gettext installed, type <literal>info gettext</literal>
to read the documentation.
</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()
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
gettext() to look up each string to be translated in the default domain.
</para>
@ -352,7 +358,7 @@ g_free (text);
</para>
<para>
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.
</para>
</answer>
@ -425,19 +431,9 @@ How do I load an image or animation from a file?
<para>
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() will display no image graphic &mdash; to detect
a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
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.
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().
</para>
</answer>
@ -450,7 +446,8 @@ How do I draw text ?
<answer>
<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>
<programlisting>
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>
section of <ulink url="https://developer.gnome.org/pango/stable/">Pango manual</ulink>.
</para>
<para>
To draw a piece of text in a widget snapshot() implementation, use
gtk_snapshot_append_layout().
</para>
</answer>
</qandaentry>
@ -513,10 +515,10 @@ macro ?
<answer>
<para>
The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
<literal>gtk_blah_get_type(<!-- -->)</literal>, and the <literal>_get_type(<!-- -->)</literal>
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.
</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,
such as draw text or graphics over the top of the image.
</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>
</qandaentry>
@ -618,9 +632,7 @@ would use a combo box?
<answer>
<para>
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.
</para>
</answer>
</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
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().
</para></answer>
</qandaentry>
@ -912,8 +925,8 @@ How do I use cairo to draw in GTK applications ?
</para></question>
<answer><para>
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.
</para>
</answer>
</qandaentry>

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

@ -4,13 +4,13 @@
]>
<refentry id="gtk-resources">
<refmeta>
<refentrytitle>Mailing lists and bug reports</refentrytitle>
<refentrytitle>Contact information and bug reports</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
<refmiscinfo>Contact information and bug reports</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Mailing lists and bug reports</refname>
<refname>Contact information and bug reports</refname>
<refpurpose>
Getting help with GTK
</refpurpose>
@ -35,7 +35,7 @@ discussed, we'll add a note to that effect in the report.
</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
that nothing gets lost.
</para>
@ -61,83 +61,16 @@ for GTK, available on GitLab.
<para>
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>.
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
<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>
</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>

19
gtk/gtkcssprovider.c
View File

@ -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.
*/