Merge branch 'wip/hadess/window-present-docs' into 'master'

gtk_window_present() docs

See merge request GNOME/gtk!609

17 files changed, 87 insertions, 27 deletions

diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index 8a1f66f0bc..7d6e951769 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -4098,7 +4098,7 @@ gdk_surface_create_similar_surface (GdkSurface *     surface,
  * @surface: a #GdkSurface
  * @timestamp: timestamp of the event triggering the surface focus
  *
- * Sets keyboard focus to @surface. In most cases, gtk_window_present()
+ * Sets keyboard focus to @surface. In most cases, gtk_window_present_with_time()
  * should be used on a #GtkWindow, rather than calling this function.
  *
  **/
@@ -4491,7 +4491,7 @@ gdk_surface_iconify (GdkSurface *surface)
  * Attempt to deiconify (unminimize) @surface. On X11 the window manager may
  * choose to ignore the request to deiconify. When using GTK,
  * use gtk_window_deiconify() instead of the #GdkSurface variant. Or better yet,
- * you probably want to use gtk_window_present(), which raises the surface, focuses it,
+ * you probably want to use gtk_window_present_with_time(), which raises the surface, focuses it,
  * unminimizes it, and puts it on the current desktop.
  *
  **/
diff --git a/gdk/gdkversionmacros.h.in b/gdk/gdkversionmacros.h.in
index 5b413f1704..8565011197 100644
--- a/gdk/gdkversionmacros.h.in
+++ b/gdk/gdkversionmacros.h.in
@@ -54,6 +54,7 @@
 
 #define GDK_VERSION_3_92        (G_ENCODE_VERSION (3, 92))
 #define GDK_VERSION_3_94        (G_ENCODE_VERSION (3, 94))
+
 /**
  * GDK_VERSION_4_0:
  *
@@ -137,6 +138,13 @@
 # define GDK_AVAILABLE_IN_4_0                _GDK_EXTERN
 #endif
 
+#if GDK_VERSION_MIN_REQUIRED >= GDK_VERSION_3_92
+# define GDK_DEPRECATED_IN_4_0                GDK_DEPRECATED
+# define GDK_DEPRECATED_IN_4_0_FOR(f)         GDK_DEPRECATED_FOR(f)
+#else
+# define GDK_DEPRECATED_IN_4_0                _GDK_EXTERN
+# define GDK_DEPRECATED_IN_4_0_FOR(f)         _GDK_EXTERN
+#endif
 
 #endif  /* __GDK_VERSION_MACROS_H__ */
 
diff --git a/gtk/a11y/gtkiconviewaccessible.c b/gtk/a11y/gtkiconviewaccessible.c
index 1cebf28df6..5eab1dbdf8 100644
--- a/gtk/a11y/gtkiconviewaccessible.c
+++ b/gtk/a11y/gtkiconviewaccessible.c
@@ -626,7 +626,11 @@ gtk_icon_view_item_accessible_grab_focus (AtkComponent *component)
   _gtk_icon_view_set_cursor_item (GTK_ICON_VIEW (item->widget), item->item, NULL);
   toplevel = gtk_widget_get_toplevel (GTK_WIDGET (item->widget));
   if (gtk_widget_is_toplevel (toplevel))
-    gtk_window_present (GTK_WINDOW (toplevel));
+    {
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+      gtk_window_present (GTK_WINDOW (toplevel));
+      G_GNUC_END_IGNORE_DEPRECATIONS
+    }
 
   return TRUE;
 }
diff --git a/gtk/a11y/gtktreeviewaccessible.c b/gtk/a11y/gtktreeviewaccessible.c
index 6a27578540..79008638e4 100644
--- a/gtk/a11y/gtktreeviewaccessible.c
+++ b/gtk/a11y/gtktreeviewaccessible.c
@@ -1179,7 +1179,11 @@ gtk_tree_view_accessible_grab_cell_focus (GtkCellAccessibleParent *parent,
                                           gdk_x11_get_server_time (gtk_widget_get_surface (widget)));
           else
 #endif
-            gtk_window_present (GTK_WINDOW (toplevel));
+            {
+              G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+              gtk_window_present (GTK_WINDOW (toplevel));
+              G_GNUC_END_IGNORE_DEPRECATIONS
+            }
         }
 
       return TRUE;
diff --git a/gtk/a11y/gtkwidgetaccessible.c b/gtk/a11y/gtkwidgetaccessible.c
index 69a205f508..ebdee94276 100644
--- a/gtk/a11y/gtkwidgetaccessible.c
+++ b/gtk/a11y/gtkwidgetaccessible.c
@@ -608,9 +608,12 @@ gtk_widget_accessible_grab_focus (AtkComponent *component)
       gtk_window_present_with_time (GTK_WINDOW (toplevel),
       gdk_x11_get_server_time (gtk_widget_get_surface (widget)));
 #else
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
       gtk_window_present (GTK_WINDOW (toplevel));
+      G_GNUC_END_IGNORE_DEPRECATIONS
 #endif
     }
+
   return TRUE;
 }
 
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index ab344cc71b..1105a966e9 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -1002,7 +1002,9 @@ gtk_about_dialog_activate_link (GtkAboutDialog *about,
       g_signal_connect (dialog, "response",
                         G_CALLBACK (gtk_widget_destroy), NULL);
 
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
       gtk_window_present (GTK_WINDOW (dialog));
+      G_GNUC_END_IGNORE_DEPRECATIONS
     }
 
   return TRUE;
@@ -2409,7 +2411,9 @@ gtk_show_about_dialog (GtkWindow   *parent,
 
     }
 
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (dialog));
+  G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 /**
diff --git a/gtk/gtkcolorbutton.c b/gtk/gtkcolorbutton.c
index 7b764d9957..0c8abded61 100644
--- a/gtk/gtkcolorbutton.c
+++ b/gtk/gtkcolorbutton.c
@@ -555,7 +555,9 @@ gtk_color_button_clicked (GtkButton *b,
 
   gtk_color_chooser_set_rgba (GTK_COLOR_CHOOSER (priv->cs_dialog), &priv->rgba);
 
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (priv->cs_dialog));
+  G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 static void
diff --git a/gtk/gtkfilechooserbutton.c b/gtk/gtkfilechooserbutton.c
index 3d41a1f233..f7d4e3d49a 100644
--- a/gtk/gtkfilechooserbutton.c
+++ b/gtk/gtkfilechooserbutton.c
@@ -2705,7 +2705,11 @@ open_dialog (GtkFileChooserButton *button)
 
   gtk_widget_set_sensitive (priv->combo_box, FALSE);
   if (priv->dialog)
-    gtk_window_present (GTK_WINDOW (priv->dialog));
+    {
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+      gtk_window_present (GTK_WINDOW (priv->dialog));
+      G_GNUC_END_IGNORE_DEPRECATIONS
+    }
   else
     gtk_native_dialog_show (GTK_NATIVE_DIALOG (priv->native));
 }
diff --git a/gtk/gtkfilechoosernative.c b/gtk/gtkfilechoosernative.c
index b6c65b449b..aec8cb9df9 100644
--- a/gtk/gtkfilechoosernative.c
+++ b/gtk/gtkfilechoosernative.c
@@ -623,7 +623,9 @@ show_dialog (GtkFileChooserNative *self)
                     G_CALLBACK (dialog_update_preview_cb),
                     self);
 
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (self->dialog));
+  G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 static void
diff --git a/gtk/gtkfontbutton.c b/gtk/gtkfontbutton.c
index 4617ed12d3..3d87ffb103 100644
--- a/gtk/gtkfontbutton.c
+++ b/gtk/gtkfontbutton.c
@@ -995,7 +995,9 @@ gtk_font_button_clicked (GtkButton *button,
       gtk_font_chooser_set_font_desc (font_dialog, priv->font_desc);
     }
 
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (priv->font_dialog));
+  G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 
diff --git a/gtk/gtkpagesetupunixdialog.c b/gtk/gtkpagesetupunixdialog.c
index 5bcd37a6bb..5549fe71c4 100644
--- a/gtk/gtkpagesetupunixdialog.c
+++ b/gtk/gtkpagesetupunixdialog.c
@@ -787,7 +787,9 @@ paper_size_changed (GtkComboBox            *combo_box,
           /* And show the custom paper dialog */
           custom_paper_dialog = _gtk_custom_paper_unix_dialog_new (GTK_WINDOW (dialog), NULL);
           g_signal_connect (custom_paper_dialog, "response", G_CALLBACK (custom_paper_dialog_response_cb), dialog);
+          G_GNUC_BEGIN_IGNORE_DEPRECATIONS
           gtk_window_present (GTK_WINDOW (custom_paper_dialog));
+          G_GNUC_END_IGNORE_DEPRECATIONS
 
           return;
         }
diff --git a/gtk/gtkprinteroptionwidget.c b/gtk/gtkprinteroptionwidget.c
index a81168247b..6ca97ce35f 100644
--- a/gtk/gtkprinteroptionwidget.c
+++ b/gtk/gtkprinteroptionwidget.c
@@ -573,7 +573,9 @@ filesave_choose_cb (GtkWidget              *button,
   g_signal_connect (dialog, "response",
                     G_CALLBACK (dialog_response_callback), widget);
   gtk_window_set_modal (GTK_WINDOW (dialog), TRUE);
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (dialog));
+  G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 static gchar *
diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c
index 85cc171805..8e15763b67 100644
--- a/gtk/gtkprintoperation-unix.c
+++ b/gtk/gtkprintoperation-unix.c
@@ -729,8 +729,10 @@ gtk_print_operation_unix_run_dialog_async (GtkPrintOperation          *op,
 
       g_signal_connect (pd, "response", 
 			G_CALLBACK (handle_print_response), rdata);
-      
+
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
       gtk_window_present (GTK_WINDOW (pd));
+      G_GNUC_END_IGNORE_DEPRECATIONS
     }
   else
     {
@@ -1025,8 +1027,10 @@ gtk_print_run_page_setup_dialog_async (GtkWindow            *parent,
 
   g_signal_connect (dialog, "response",
 		    G_CALLBACK (handle_page_setup_response), rdata);
- 
+
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (dialog));
+  G_GNUC_END_IGNORE_DEPRECATIONS
  }
 
 struct _PrinterFinder 
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index c18d3d2d78..3c6b01937c 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -2852,7 +2852,9 @@ handle_progress_response (GtkWidget *dialog,
 static gboolean
 show_progress_timeout (PrintPagesData *data)
 {
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   gtk_window_present (GTK_WINDOW (data->progress));
+  G_GNUC_END_IGNORE_DEPRECATIONS
 
   data->op->priv->show_progress_timeout_id = 0;
 
diff --git a/gtk/gtkprintunixdialog.c b/gtk/gtkprintunixdialog.c
index 7dc8c37202..9b36ce9dd1 100644
--- a/gtk/gtkprintunixdialog.c
+++ b/gtk/gtkprintunixdialog.c
@@ -3312,7 +3312,9 @@ paper_size_changed (GtkComboBox        *combo_box,
           /* And show the custom paper dialog */
           custom_paper_dialog = _gtk_custom_paper_unix_dialog_new (GTK_WINDOW (dialog), _("Manage Custom Sizes"));
           g_signal_connect (custom_paper_dialog, "response", G_CALLBACK (custom_paper_dialog_response_cb), dialog);
+          G_GNUC_BEGIN_IGNORE_DEPRECATIONS
           gtk_window_present (GTK_WINDOW (custom_paper_dialog));
+          G_GNUC_END_IGNORE_DEPRECATIONS
 
           return;
         }
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 719967cd64..c5b55ffd71 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -8736,23 +8736,11 @@ gtk_window_snapshot (GtkWidget   *widget,
  * gtk_window_present:
  * @window: a #GtkWindow
  *
- * Presents a window to the user. This may mean raising the window
- * in the stacking order, deiconifying 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.
+ * 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.
  *
- * If @window is hidden, this function calls gtk_widget_show()
- * as well.
- * 
- * 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 gtk_window_present() to move the already-open dialog
- * where the user can see it.
- *
- * If you are calling this function in response to a user interaction,
- * it is preferable to use gtk_window_present_with_time().
- * 
+ * Deprecated: 4.0: Use gtk_window_present_with_time() instead.
  **/
 void
 gtk_window_present (GtkWindow *window)
@@ -8766,9 +8754,24 @@ 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 in response to a user interaction.
- * If you need to present a window without a timestamp, use 
- * gtk_window_present(). See gtk_window_present() for details. 
+ * Presents a window to the user. This may mean raising the window
+ * in the stacking order, deiconifying 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 gtk_widget_show()
+ * as well.
+ *
+ * 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 gtk_window_present() to move the already-open dialog
+ * where the user can see it.
+ *
+ * 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.
  **/
 void
 gtk_window_present_with_time (GtkWindow *window,
@@ -8777,6 +8780,7 @@ gtk_window_present_with_time (GtkWindow *window,
   GtkWindowPrivate *priv = gtk_window_get_instance_private (window);
   GtkWidget *widget;
   GdkSurface *surface;
+  static gsize warned_current_time = FALSE;
 
   g_return_if_fail (GTK_IS_WINDOW (window));
 
@@ -8793,6 +8797,15 @@ gtk_window_present_with_time (GtkWindow *window,
       /* Translate a timestamp of GDK_CURRENT_TIME appropriately */
       if (timestamp == GDK_CURRENT_TIME)
         {
+	  if (g_once_init_enter (&warned_current_time))
+	    {
+	      gboolean warned = TRUE;
+	      g_warning ("gtk_window_present_with_time() should not be called with 0, or "
+			 "GDK_CURRENT_TIME as a timestamp, the timestamp should instead be "
+			 "gathered at the time the user initiated the request for the window "
+			 "to be shown");
+	      g_once_init_leave (&warned_current_time, warned);
+	    }
 #ifdef GDK_WINDOWING_X11
 	  if (GDK_IS_X11_SURFACE(surface))
 	    {
@@ -10402,7 +10415,9 @@ gtk_window_set_debugging (gboolean enable,
 
   if (enable)
     {
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS
       gtk_window_present (GTK_WINDOW (inspector_window));
+      G_GNUC_END_IGNORE_DEPRECATIONS
       if (dialog)
         gtk_widget_show (dialog);
 
diff --git a/gtk/gtkwindow.h b/gtk/gtkwindow.h
index fb30ab99b8..c21d5261c4 100644
--- a/gtk/gtkwindow.h
+++ b/gtk/gtkwindow.h
@@ -324,7 +324,7 @@ GDK_AVAILABLE_IN_ALL
 gboolean gtk_window_propagate_key_event   (GtkWindow        *window,
 					   GdkEventKey      *event);
 
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_4_0_FOR(gtk_window_present_with_time)
 void     gtk_window_present            (GtkWindow *window);
 GDK_AVAILABLE_IN_ALL
 void     gtk_window_present_with_time  (GtkWindow *window,