From e91907d427b6eb4ee659bbd57376cff769aca1ee Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 19 Apr 2020 16:26:25 -0400 Subject: [PATCH] Docs: Various tweaks Tweak the docs for library initialization, versioning and settings, and remove some outdated information. --- gtk/gtkmain.c | 41 ++++++++++++++++++++--------------------- gtk/gtksettings.c | 21 +++++++++++---------- gtk/gtkversion.h.in | 4 ++-- 3 files changed, 33 insertions(+), 33 deletions(-) diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c index cbb09c802c..7951dceaf5 100644 --- a/gtk/gtkmain.c +++ b/gtk/gtkmain.c @@ -24,29 +24,28 @@ /** * SECTION:gtkmain - * @Short_description: Library initialization, main event loop, and events - * @Title: Main loop and Events - * @See_also:See the GLib manual, especially #GMainLoop and signal-related + * @Short_description: Library initialization and main loop + * @Title: Initialization + * @See_also: See the GLib manual, especially #GMainLoop and signal-related * functions such as g_signal_connect() * - * Before using GTK, you need to initialize it; initialization connects to the - * window system display, and parses some standard command line arguments. The - * gtk_init() macro initializes GTK. gtk_init() exits the application if errors - * occur; to avoid this, use gtk_init_check(). gtk_init_check() allows you to - * recover from a failed GTK initialization - you might start up your - * application in text mode instead. + * Before using GTK, you need to initialize it using gtk_init(); this + * connects to the windowing system, sets up the locale and performs other + * initialization tasks. gtk_init() exits the application if errors occur; + * to avoid this, you can use gtk_init_check(), which allows you to recover + * from a failed GTK initialization - you might start up your application + * in text mode instead. * * Like all GUI toolkits, GTK uses an event-driven programming model. When the - * user is doing nothing, GTK sits in the “main loop” and - * waits for input. If the user performs some action - say, a mouse click - then - * the main loop “wakes up” and delivers an event to GTK. GTK forwards the - * event to one or more widgets. + * user is doing nothing, GTK sits in the “main loop” and waits for input. + * If the user performs some action - say, a mouse click - then the main loop + * “wakes up” and delivers an event to GTK. GTK forwards the event to one or + * more widgets. * - * When widgets receive an event, they frequently emit one or more - * “signals”. Signals notify your program that "something - * interesting happened" by invoking functions you’ve connected to the signal - * with g_signal_connect(). Functions connected to a signal are often termed - * “callbacks”. + * When widgets receive an event, they frequently emit one or more “signals”. + * Signals notify your program that "something interesting happened" by invoking + * functions you’ve connected to the signal with g_signal_connect(). Functions + * connected to a signal are often called “callbacks”. * * When your callbacks are invoked, you would typically take some action - for * example, when an Open button is clicked you might display a @@ -59,7 +58,7 @@ * int * main (int argc, char **argv) * { - * GtkWidget *mainwin; + * GtkWidget *window; * // Initialize i18n support with bindtextdomain(), etc. * * // ... @@ -68,14 +67,14 @@ * gtk_init (); * * // Create the main window - * mainwin = gtk_window_new (); + * window = gtk_window_new (); * * // Set up our GUI elements * * // ... * * // Show the application window - * gtk_widget_show (mainwin); + * gtk_widget_show (window); * * // Enter the main event loop, and wait for user interaction * while (!done) diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c index 6ce91b34b1..c6b9634213 100644 --- a/gtk/gtksettings.c +++ b/gtk/gtksettings.c @@ -74,14 +74,16 @@ * On the X window system, this sharing is realized by an * [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec) * manager that is usually part of the desktop environment, along with - * utilities that let the user change these settings. In the absence of - * an Xsettings manager, GTK reads default values for settings from - * `settings.ini` files in - * `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0` - * and `$XDG_CONFIG_HOME/gtk-4.0`. - * These files must be valid key files (see #GKeyFile), and have - * a section called Settings. Themes can also provide default values - * for settings by installing a `settings.ini` file + * utilities that let the user change these settings. + * + * On Wayland, the settings are obtained either via a settings portal, + * or by reading desktop settings from DConf. + * + * In the absence of these sharing mechanisms, GTK reads default values for + * settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0` + * and `$XDG_CONFIG_HOME/gtk-4.0`. These files must be valid key files (see + * #GKeyFile), and have a section called Settings. Themes can also provide + * default values for settings by installing a `settings.ini` file * next to their `gtk.css` file. * * Applications can override system-wide settings by setting the property @@ -91,8 +93,7 @@ * * There is one GtkSettings instance per display. It can be obtained with * gtk_settings_get_for_display(), but in many cases, it is more convenient - * to use gtk_widget_get_settings(). gtk_settings_get_default() returns the - * GtkSettings instance for the default display. + * to use gtk_widget_get_settings(). */ diff --git a/gtk/gtkversion.h.in b/gtk/gtkversion.h.in index b6b5337223..bccb24d144 100644 --- a/gtk/gtkversion.h.in +++ b/gtk/gtkversion.h.in @@ -31,10 +31,10 @@ /** * SECTION:gtkfeatures - * @Short_description: Variables and functions to check the GTK+ version + * @Short_description: Variables and functions to check the GTK version * @Title: Version Information * - * GTK+ provides version information, primarily useful in configure checks + * GTK provides version information, primarily useful in configure checks * for builds that have a configure script. Applications will not typically * use the features described here. */