From 0b8a9503df598f2e825f065eb283c1acfbfc0c72 Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Mon, 29 Jul 2024 18:27:35 +0200 Subject: [PATCH] gtk: Add blurb for session management in GtkApplication docs --- gtk/gtkapplication.c | 52 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c index 94cff8f29a..eff7d5617d 100644 --- a/gtk/gtkapplication.c +++ b/gtk/gtkapplication.c @@ -106,6 +106,34 @@ * inform the user about the negative consequences of ending the * session while inhibitors are present. * + * ## Restoring window state + * + * In windowing environments that support it, `GtkApplication` supports + * restoring window state (this is up to the environment, but typically + * includes the position, size, and states such as maximized or fullscreen). + * + * In order to restore state from a previous execution, the application needs + * to specify a session identifier through [method@Gtk.Application.set_session_id] + * obtained from a previous session. In order to start a new session, %NULL + * should be used. + * + * The session will be registered during [signal@Gio.Application.startup], + * at which point [method@Gtk.Application.get_current_session_id] will return + * the session identifier for the current session. This is the session identifier + * that needs to be preserved for future runs. If the session is being restored + * from a prior run, this identifier will match the one given through + * [method@Gtk.Application.set_session_id], otherwise it will be a new identifier. + * + * Individual windows are identified through [method@Gtk.Window.set_session_id], + * so application toplevel windows can be matched with the previously saved + * session state. Windows that whose state was saved will be restored to their + * previous position when mapped. + * + * The window state is saved automatically in the background, thus no explicit + * save() call is necessary. Other state, such as the active tab in a notebook + * or scroll positions, is not preserved automatically and needs to be saved by + * the application, if that is desired. + * * ## See Also * * - [Using GtkApplication](https://developer.gnome.org/documentation/tutorials/application.html) @@ -650,6 +678,9 @@ gtk_application_class_init (GtkApplicationClass *class) * * The identifier of the session used to restore window state. * + * This property should be set to the ID of a previously saved session + * before ::startup (if available). + * * Since: 4.16 */ gtk_application_props[PROP_SESSION_ID] = @@ -1257,11 +1288,14 @@ gtk_application_set_screensaver_active (GtkApplication *application, * through [method@Gtk.Application.get_current_session_id]. * * This session identifier must be set before `GApplication::startup` happens, - * as it will be applied there. In the case %NULL was passed, or the request - * resulted in a new session being created from scratch, - * [method@Gtk.Application.get_current_session_id] may return a different - * identifier than the one passed here. - **/ + * as it will be applied there. + * + * In the case %NULL was passed, or the request resulted in a new session being + * created from scratch, [method@Gtk.Application.get_current_session_id] may + * return a different identifier than the one passed here. + * + * Since: 4.16 + */ void gtk_application_set_session_id (GtkApplication *application, const char *session_id) @@ -1286,7 +1320,9 @@ gtk_application_set_session_id (GtkApplication *application, * session management. * * Returns: (nullable): The session management ID - **/ + * + * Since: 4.16 + */ const char * gtk_application_get_session_id (GtkApplication *application) { @@ -1325,7 +1361,9 @@ gtk_application_get_session_id (GtkApplication *application) * Currently, session management is only supported in the Wayland backend. * * Returns: (nullable): The session identifier to preserve for future runs - **/ + * + * Since: 4.16 + */ const char * gtk_application_get_current_session_id (GtkApplication *application) {