From: Marco Melorio <marco.melorio@protonmail.com>
Date: Sun, 8 Jan 2023 21:37:42 +0000 (+0100)
Subject: docs: Improve gtk_window_present description
X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~8^2~82^2
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=c775262e9dce8a8cc61f1c3dca5a0366da90690f;p=gtk4.git

docs: Improve gtk_window_present description

Move most of the documentation from gtk_window_present_with_time and
also reword it a bit to make it more understandable.
---

diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 909154c231..88cc0b71ab 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -5206,9 +5206,12 @@ _gtk_window_unset_focus_and_default (GtkWindow *window,
  *
  * Presents a window to the user.
  *
- * This function should not be used as when it is called,
- * it is too late to gather a valid timestamp to allow focus
- * stealing prevention to work correctly.
+ * This may mean raising the window in the stacking order,
+ * unminimizing it, moving it to the current desktop and/or
+ * giving it the keyboard focus (possibly dependent on the user’s
+ * platform, window manager and preferences).
+ *
+ * If @window is hidden, this function also makes it visible.
  */
 void
 gtk_window_present (GtkWindow *window)
@@ -5222,23 +5225,10 @@ gtk_window_present (GtkWindow *window)
  * @timestamp: the timestamp of the user interaction (typically a
  *   button or key press event) which triggered this call
  *
- * Presents a window to the user.
- *
- * This may mean raising the window in the stacking order,
- * unminimizing it, moving it to the current desktop, and/or
- * giving it the keyboard focus, possibly dependent on the user’s
- * platform, window manager, and preferences.
- *
- * If @window is hidden, this function calls [method@Gtk.Widget.show]
- * as well.
+ * Presents a window to the user in response to an user interaction.
  *
- * This function should be used when the user tries to open a window
- * that’s already open. Say for example the preferences dialog is
- * currently open, and the user chooses Preferences from the menu
- * a second time; use [method@Gtk.Window.present] to move the
- * already-open dialog where the user can see it.
+ * See [method@Gtk.Window.present] for more details.
  *
- * Presents a window to the user in response to a user interaction.
  * The timestamp should be gathered when the window was requested
  * to be shown (when clicking a link for example), rather than once
  * the window is ready to be shown.