5 files changed, 74 insertions, 38 deletions

diff --git a/gdk/win32/gdkdisplay-win32.c b/gdk/win32/gdkdisplay-win32.c
index a544bf3827..3028045746 100644
--- a/gdk/win32/gdkdisplay-win32.c
+++ b/gdk/win32/gdkdisplay-win32.c
@@ -51,8 +51,8 @@ static int debug_indent = 0;
 /**
  * gdk_win32_display_add_filter:
  * @display: a `GdkWin32Display`
- * @function: filter callback
- * @data: data to pass to filter callback
+ * @function: (scope notified): filter callback
+ * @data: (closure): data to pass to filter callback
  *
  * Adds an event filter to @window, allowing you to intercept messages
  * before they reach GDK. This is a low-level operation and makes it
@@ -136,8 +136,8 @@ _gdk_win32_message_filter_unref (GdkWin32Display       *display,
 /**
  * gdk_win32_display_remove_filter:
  * @display: A `GdkWin32Display`
- * @function: previously-added filter function
- * @data: user data for previously-added filter function
+ * @function: (scope notified): previously-added filter function
+ * @data: (closure): user data for previously-added filter function
  *
  * Remove a filter previously added with gdk_win32_display_add_filter().
  */
diff --git a/gdk/win32/gdksurface-win32.c b/gdk/win32/gdksurface-win32.c
index a94e43b68d..4dc6f38fdd 100644
--- a/gdk/win32/gdksurface-win32.c
+++ b/gdk/win32/gdksurface-win32.c
@@ -1310,19 +1310,27 @@ gdk_win32_surface_raise (GdkSurface *window)
     }
 }
 
+/**
+ * gdk_win32_surface_set_urgency_hint:
+ * @surface: (type GdkWin32Surface): a native `GdkSurface`.
+ * @urgent: if %TRUE, flashes both the window and the taskbar button
+ *          continuously.
+ *
+ * Flashes the specified @surface.
+ */
 void
-gdk_win32_surface_set_urgency_hint (GdkSurface *window,
+gdk_win32_surface_set_urgency_hint (GdkSurface *surface,
                                     gboolean    urgent)
 {
   FLASHWINFO flashwinfo;
 
-  g_return_if_fail (GDK_IS_SURFACE (window));
+  g_return_if_fail (GDK_IS_WIN32_SURFACE (surface));
 
-  if (GDK_SURFACE_DESTROYED (window))
+  if (GDK_SURFACE_DESTROYED (surface))
     return;
 
   flashwinfo.cbSize = sizeof (flashwinfo);
-  flashwinfo.hwnd = GDK_SURFACE_HWND (window);
+  flashwinfo.hwnd = GDK_SURFACE_HWND (surface);
   if (urgent)
     flashwinfo.dwFlags = FLASHW_ALL | FLASHW_TIMER;
   else
@@ -4238,6 +4246,13 @@ gdk_win32_surface_focus (GdkSurface *window,
   SetFocus (GDK_SURFACE_HWND (window));
 }
 
+/**
+ * gdk_win32_surface_lookup_for_display:
+ * @display: a %GdkDisplay
+ * @anid: a HWND window handle
+ *
+ * Returns: (nullable): the %GdkSurface associated with the given @anid, or %NULL.
+ */
 GdkSurface *
 gdk_win32_surface_lookup_for_display (GdkDisplay *display,
                                      HWND        anid)
@@ -4247,10 +4262,18 @@ gdk_win32_surface_lookup_for_display (GdkDisplay *display,
   return (GdkSurface*) gdk_win32_handle_table_lookup (anid);
 }
 
+/**
+ * gdk_win32_surface_is_win32:
+ * @surface: a `GdkSurface`
+ *
+ * Returns: %TRUE if the @surface is a win32 implemented surface.
+ *
+ * Deprecated: 4.8: Use `GDK_IS_WIN32_SURFACE` instead.
+ */
 gboolean
-gdk_win32_surface_is_win32 (GdkSurface *window)
+gdk_win32_surface_is_win32 (GdkSurface *surface)
 {
-  return GDK_IS_WIN32_SURFACE (window);
+  return GDK_IS_WIN32_SURFACE (surface);
 }
 
 static gboolean
@@ -4284,11 +4307,19 @@ gdk_win32_surface_show_window_menu (GdkSurface *surface,
   return TRUE;
 }
 
+/**
+ * gdk_win32_surface_get_impl_hwnd:
+ * @surface: a `GdkSurface`
+ *
+ * Returns: the associated @surface HWND handle.
+ *
+ * Deprecated: 4.8: Use gdk_win32_surface_get_handle() instead.
+ */
 HWND
-gdk_win32_surface_get_impl_hwnd (GdkSurface *window)
+gdk_win32_surface_get_impl_hwnd (GdkSurface *surface)
 {
-  if (GDK_IS_WIN32_SURFACE (window))
-    return GDK_SURFACE_HWND (window);
+  if (GDK_IS_WIN32_SURFACE (surface))
+    return GDK_SURFACE_HWND (surface);
   return NULL;
 }
 
@@ -4618,16 +4649,20 @@ gdk_win32_surface_class_init (GdkWin32SurfaceClass *klass)
   impl_class->compute_size = _gdk_win32_surface_compute_size;
 }
 
-HGDIOBJ
-gdk_win32_surface_get_handle (GdkSurface *window)
+/**
+ * gdk_win32_surface_get_handle:
+ * @surface: (type GdkWin32Surface): a native `GdkSurface`.
+ *
+ * Returns the HWND handle belonging to @surface.
+ *
+ * Returns: the associated HWND handle.
+ */
+HWND
+gdk_win32_surface_get_handle (GdkSurface *surface)
 {
-  if (!GDK_IS_WIN32_SURFACE (window))
-    {
-      g_warning (G_STRLOC " window is not a native Win32 window");
-      return NULL;
-    }
+  g_return_val_if_fail (GDK_IS_WIN32_SURFACE (surface), NULL);
 
-  return GDK_SURFACE_HWND (window);
+  return GDK_SURFACE_HWND (surface);
 }
 
 #define LAST_PROP 1
diff --git a/gdk/win32/gdkwin32misc.h b/gdk/win32/gdkwin32misc.h
index 3582e81572..990b8d0156 100644
--- a/gdk/win32/gdkwin32misc.h
+++ b/gdk/win32/gdkwin32misc.h
@@ -68,18 +68,17 @@ G_BEGIN_DECLS
 #define XBUTTON2 2
 #endif
 
-/* Return true if the GdkSurface is a win32 implemented window */
-GDK_AVAILABLE_IN_ALL
-gboolean      gdk_win32_surface_is_win32 (GdkSurface *window);
-GDK_AVAILABLE_IN_ALL
-HWND          gdk_win32_surface_get_impl_hwnd (GdkSurface *window);
+GDK_DEPRECATED_IN_4_8_FOR(GDK_IS_WIN32_SURFACE)
+gboolean      gdk_win32_surface_is_win32 (GdkSurface *surface);
+GDK_DEPRECATED_IN_4_8_FOR(gdk_win32_surface_get_handle)
+HWND          gdk_win32_surface_get_impl_hwnd (GdkSurface *surface);
 
 /* Return the Gdk* for a particular HANDLE */
 GDK_AVAILABLE_IN_ALL
 gpointer      gdk_win32_handle_table_lookup (HWND handle);
 /* Translate from window to Windows handle */
 GDK_AVAILABLE_IN_ALL
-HGDIOBJ       gdk_win32_surface_get_handle (GdkSurface *window);
+HWND          gdk_win32_surface_get_handle (GdkSurface *surface);
 
 GDK_AVAILABLE_IN_ALL
 GdkSurface *   gdk_win32_surface_lookup_for_display (GdkDisplay *display,
diff --git a/gtk/gtkimcontextime.c b/gtk/gtkimcontextime.c
index adb122f2c6..e341925733 100644
--- a/gtk/gtkimcontextime.c
+++ b/gtk/gtkimcontextime.c
@@ -256,7 +256,7 @@ gtk_im_context_ime_set_client_widget (GtkIMContext *context,
 
   if (surface != NULL)
     {
-      HWND hwnd = gdk_win32_surface_get_impl_hwnd (surface);
+      HWND hwnd = gdk_win32_surface_get_handle (surface);
       HIMC himc = ImmGetContext (hwnd);
       if (himc)
         {
@@ -418,7 +418,7 @@ gtk_im_context_ime_reset (GtkIMContext *context)
   if (!context_ime->client_surface)
     return;
 
-  hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+  hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return;
@@ -453,7 +453,7 @@ get_utf8_preedit_string (GtkIMContextIME *context_ime,
 
   if (!context_ime->client_surface)
     return g_strdup ("");
-  hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+  hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return g_strdup ("");
@@ -512,7 +512,7 @@ get_pango_attr_list (GtkIMContextIME *context_ime, const char *utf8str)
 
   if (!context_ime->client_surface)
     return attrs;
-  hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+  hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return attrs;
@@ -655,7 +655,7 @@ gtk_im_context_ime_focus_in (GtkIMContext *context)
       return;
     }
 
-  hwnd = gdk_win32_surface_get_impl_hwnd (toplevel);
+  hwnd = gdk_win32_surface_get_handle (toplevel);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return;
@@ -741,6 +741,9 @@ gtk_im_context_ime_focus_out (GtkIMContext *context)
 
       case GTK_WIN32_IME_FOCUS_BEHAVIOR_FOLLOW:
         break;
+
+      default:
+        g_assert_not_reached ();
     }
 
   /* remove event filter */
@@ -780,7 +783,7 @@ gtk_im_context_ime_set_cursor_location (GtkIMContext *context,
   if (!context_ime->client_surface)
     return;
 
-  hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+  hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return;
@@ -811,7 +814,7 @@ gtk_im_context_ime_set_use_preedit (GtkIMContext *context,
       HWND hwnd;
       HIMC himc;
 
-      hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+      hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
       himc = ImmGetContext (hwnd);
       if (!himc)
         return;
@@ -844,7 +847,7 @@ gtk_im_context_ime_set_preedit_font (GtkIMContext *context)
   if (!(context_ime->client_widget && context_ime->client_surface))
     return;
 
-  hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+  hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return;
@@ -955,10 +958,10 @@ gtk_im_context_ime_message_filter (GdkWin32Display *display,
     return retval;
 
   toplevel = context_ime->client_surface;
-  if (gdk_win32_surface_get_impl_hwnd (toplevel) != msg->hwnd)
+  if (gdk_win32_surface_get_handle (toplevel) != msg->hwnd)
     return retval;
 
-  hwnd = gdk_win32_surface_get_impl_hwnd (context_ime->client_surface);
+  hwnd = gdk_win32_surface_get_handle (context_ime->client_surface);
   himc = ImmGetContext (hwnd);
   if (!himc)
     return retval;
diff --git a/tests/dummy-headers/windows.h b/tests/dummy-headers/windows.h
index fefe9e8fa2..1b1d700fc3 100644
--- a/tests/dummy-headers/windows.h
+++ b/tests/dummy-headers/windows.h
@@ -1,6 +1,5 @@
 /* Dummy header for the Win32 backend. */
 
 typedef void *HDC;
-typedef void *HGDIOBJ;
 typedef void *HICON;
 typedef void *HWND;