[gtk/wip/chergert/macos-add-window-accessor] macos: add getter for NSWindow with macOS windowing

[Christian Hergert <chergert src gnome org>]

commit 99a40de8adebb809e8175a5c8b8a54fffcefbbff
Author: Christian Hergert <christian hergert me>
Date:   Tue Feb 22 10:21:46 2022 -0800

    macos: add getter for NSWindow with macOS windowing
    
    There may be various reasons that an application could need access to the
    underlying NSWindow that is being used to display the GdkMacosSurface
    contents. This provides a minimal API to do that without exposing our
    implementation details through public API.
    
    As our rendering system is likely to change over time, we very much want
    to keep GdkMacosView, GdkMacosLayer, GdkMacosTile, and GdkMacosWindow all
    private implementation details which are subject to change.
    
    As this is public API, we are a bit long-winded with the name so it is
    clear what is being accessed without polluting symbol names with things
    like "ns" as we used to.

 gdk/macos/gdkmacossurface.c | 26 ++++++++++++++++++++++++++
 gdk/macos/gdkmacossurface.h |  4 +++-
 2 files changed, 29 insertions(+), 1 deletion(-)
---
diff --git a/gdk/macos/gdkmacossurface.c b/gdk/macos/gdkmacossurface.c
index 0f9fd4d833..ff4dcbf218 100644
--- a/gdk/macos/gdkmacossurface.c
+++ b/gdk/macos/gdkmacossurface.c
@@ -528,6 +528,11 @@ gdk_macos_surface_class_init (GdkMacosSurfaceClass *klass)
   surface_class->set_input_region = gdk_macos_surface_set_input_region;
   surface_class->set_opaque_region = gdk_macos_surface_set_opaque_region;
 
+  /**
+   * GdkMacosSurface:native: (attributes org.gtk.Property.get=gdk_macos_surface_get_native_window)
+   *
+   * The "native" property contains the underlying NSWindow.
+   */
   properties [PROP_NATIVE] =
     g_param_spec_pointer ("native",
                           "Native",
@@ -688,6 +693,27 @@ _gdk_macos_surface_get_native (GdkMacosSurface *self)
   return (NSWindow *)self->window;
 }
 
+/**
+ * gdk_macos_surface_get_native_window: (attributes org.gtk.Method.get_property=native)
+ * @self: a #GdkMacosSurface
+ *
+ * Gets the underlying NSWindow used by the surface.
+ *
+ * The NSWindow's contentView is an implementation detail and may change
+ * between releases of GTK.
+ *
+ * Returns: (nullable): a #NSWindow or %NULL
+ *
+ * Since: 4.8
+ */
+gpointer
+gdk_macos_surface_get_native_window (GdkMacosSurface *self)
+{
+  g_return_val_if_fail (GDK_IS_MACOS_SURFACE (self), NULL);
+
+  return _gdk_macos_surface_get_native (self);
+}
+
 void
 _gdk_macos_surface_set_geometry_hints (GdkMacosSurface   *self,
                                        const GdkGeometry *geometry,
diff --git a/gdk/macos/gdkmacossurface.h b/gdk/macos/gdkmacossurface.h
index 470287202e..64ea4c733d 100644
--- a/gdk/macos/gdkmacossurface.h
+++ b/gdk/macos/gdkmacossurface.h
@@ -36,7 +36,9 @@ typedef struct _GdkMacosSurfaceClass GdkMacosSurfaceClass;
 #define GDK_IS_MACOS_SURFACE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), GDK_TYPE_MACOS_SURFACE))
 
 GDK_AVAILABLE_IN_ALL
-GType gdk_macos_surface_get_type (void);
+GType    gdk_macos_surface_get_type          (void);
+GDK_AVAILABLE_IN_4_8
+gpointer gdk_macos_surface_get_native_window (GdkMacosSurface *self);
 
 G_END_DECLS