GNOME.org
 

[gtkmm] Gdk: Add [Drag,Popup,Toplevel]SurfaceImpl

commit fdb96fffb9c986c3f598312ecb403678e0788a30
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Tue Aug 11 16:05:36 2020 +0200

    Gdk: Add [Drag,Popup,Toplevel]SurfaceImpl
    
    [Drag,Popup,Toplevel]SurfaceImpl don't correspond to C classes. They can
    wrap any C object that derives from GdkSurface and implements
    GdkDragSurface, GdkPopup and GdkToplevel, respectively. Such C classes
    in GTK are not public. They can't be wrapped in the usual way.
    
    Surface_Class::wrap_new() can wrap a C object in a Surface, DragSurfaceImpl,
    PopupSurfaceImpl or ToplevelSurfaceImpl depending on which interface,
    if any, the C object implements.
    
    This is similar to DeviceWithPad.

 gdk/gdkmm.h                      |  3 ++
 gdk/gdkmm/dragsurfaceimpl.cc     | 41 ++++++++++++++++++++++++++
 gdk/gdkmm/dragsurfaceimpl.h      | 63 ++++++++++++++++++++++++++++++++++++++++
 gdk/gdkmm/filelist.am            |  6 ++++
 gdk/gdkmm/meson.build            |  3 ++
 gdk/gdkmm/popupsurfaceimpl.cc    | 41 ++++++++++++++++++++++++++
 gdk/gdkmm/popupsurfaceimpl.h     | 63 ++++++++++++++++++++++++++++++++++++++++
 gdk/gdkmm/toplevelsurfaceimpl.cc | 41 ++++++++++++++++++++++++++
 gdk/gdkmm/toplevelsurfaceimpl.h  | 63 ++++++++++++++++++++++++++++++++++++++++
 gdk/src/drag.hg                  | 22 ++++++++++++--
 gdk/src/surface.ccg              | 18 ++++++++++++
 gdk/src/surface.hg               | 46 +++++++++++++++++++++++++----
 12 files changed, 402 insertions(+), 8 deletions(-)
---
diff --git a/gdk/gdkmm.h b/gdk/gdkmm.h
index dede906c..01ce3a4b 100644
--- a/gdk/gdkmm.h
+++ b/gdk/gdkmm.h
@@ -32,6 +32,7 @@
 #include <gdkmm/display.h>
 #include <gdkmm/displaymanager.h>
 #include <gdkmm/dragsurface.h>
+#include <gdkmm/dragsurfaceimpl.h>
 #include <gdkmm/drop.h>
 #include <gdkmm/event.h>
 #include <gdkmm/frameclock.h>
@@ -45,12 +46,14 @@
 #include <gdkmm/pixbufformat.h>
 #include <gdkmm/pixbufloader.h>
 #include <gdkmm/popup.h>
+#include <gdkmm/popupsurfaceimpl.h>
 #include <gdkmm/rectangle.h>
 #include <gdkmm/seat.h>
 #include <gdkmm/snapshot.h>
 #include <gdkmm/surface.h>
 #include <gdkmm/texture.h>
 #include <gdkmm/toplevel.h>
+#include <gdkmm/toplevelsurfaceimpl.h>
 #include <gdkmm/types.h>
 
 #endif /* _GDKMM_GDKMM_H_ */
diff --git a/gdk/gdkmm/dragsurfaceimpl.cc b/gdk/gdkmm/dragsurfaceimpl.cc
new file mode 100644
index 00000000..ae844df0
--- /dev/null
+++ b/gdk/gdkmm/dragsurfaceimpl.cc
@@ -0,0 +1,41 @@
+/* Copyright (C) 2020 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <gdkmm/dragsurfaceimpl.h>
+#include <utility> // std::move()
+
+namespace Gdk
+{
+DragSurfaceImpl::DragSurfaceImpl(GdkSurface* castitem)
+: Glib::ObjectBase(nullptr), Surface(castitem)
+{}
+
+DragSurfaceImpl::DragSurfaceImpl(DragSurfaceImpl&& src) noexcept
+: DragSurface(std::move(src)),
+  Surface(std::move(src))
+{}
+
+DragSurfaceImpl& DragSurfaceImpl::operator=(DragSurfaceImpl&& src) noexcept
+{
+  DragSurface::operator=(std::move(src));
+  Surface::operator=(std::move(src));
+  return *this;
+}
+
+DragSurfaceImpl::~DragSurfaceImpl() noexcept
+{}
+
+} // namespace Gdk
diff --git a/gdk/gdkmm/dragsurfaceimpl.h b/gdk/gdkmm/dragsurfaceimpl.h
new file mode 100644
index 00000000..04c7f9f4
--- /dev/null
+++ b/gdk/gdkmm/dragsurfaceimpl.h
@@ -0,0 +1,63 @@
+#ifndef _GDKMM_DRAGSURFACEIMPL_H
+#define _GDKMM_DRAGSURFACEIMPL_H
+
+/* Copyright (C) 2020 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <gdkmmconfig.h>
+#include <gdkmm/dragsurface.h>
+#include <gdkmm/surface.h>
+
+namespace Gdk
+{
+
+/** %Gdk::DragSurfaceImpl is a Gdk::Surface that implements the Gdk::DragSurface interface.
+ *
+ * The GdkDragSurface interface can be implemented by C classes that
+ * derive from GdkSurface. No public GTK class implements GdkDragSurface.
+ * Some GTK functions, such as gdk_drag_get_drag_surface(), return an object
+ * of a class which is derived from GdkSurface and implements GdkDragSurface.
+ * Since that C class is not public, it's not wrapped in a C++ class.
+ * A C object of such a class can be wrapped in a %Gdk::DragSurfaceImpl object.
+ * %Gdk::DragSurfaceImpl does not directly correspond to any GTK class.
+ *
+ * This class is intended only for wrapping C objects returned from GTK functions.
+ *
+ * @see Gdk::Drag::get_drag_surface()
+ * @newin{3,98}
+ */
+class GDKMM_API DragSurfaceImpl : public DragSurface, public Surface
+{
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+protected:
+  explicit DragSurfaceImpl(GdkSurface* castitem);
+  friend class Surface_Class;
+
+  // noncopyable
+  DragSurfaceImpl(const DragSurfaceImpl&) = delete;
+  DragSurfaceImpl& operator=(const DragSurfaceImpl&) = delete;
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
+public:
+  DragSurfaceImpl(DragSurfaceImpl&& src) noexcept;
+  DragSurfaceImpl& operator=(DragSurfaceImpl&& src) noexcept;
+
+  ~DragSurfaceImpl() noexcept override;
+};
+
+} // namespace Gdk
+
+#endif /* _GDKMM_DRAGSURFACEIMPL_H */
diff --git a/gdk/gdkmm/filelist.am b/gdk/gdkmm/filelist.am
index 5ae0d78b..675668d6 100644
--- a/gdk/gdkmm/filelist.am
+++ b/gdk/gdkmm/filelist.am
@@ -6,13 +6,19 @@ gdkmm_files_built_h  = $(gdkmm_files_used_hg:.hg=.h)
 gdkmm_files_extra_cc = \
   cairoutils.cc \
   devicewithpad.cc \
+  dragsurfaceimpl.cc \
   general.cc \
+  popupsurfaceimpl.cc \
+  toplevelsurfaceimpl.cc \
   value_cairo.cc
 
 gdkmm_files_extra_h  = \
   cairoutils.h \
   devicewithpad.h \
+  dragsurfaceimpl.h \
   general.h \
+  popupsurfaceimpl.h \
+  toplevelsurfaceimpl.h \
   value_cairo.h \
   wrap_init.h
 
diff --git a/gdk/gdkmm/meson.build b/gdk/gdkmm/meson.build
index 47ba652a..ec4950ee 100644
--- a/gdk/gdkmm/meson.build
+++ b/gdk/gdkmm/meson.build
@@ -79,7 +79,10 @@ gdkmm_deprecated_hg_ccg_basenames = []
 gdkmm_extra_any_h_cc_basenames = [
   'cairoutils',
   'devicewithpad',
+  'dragsurfaceimpl',
   'general',
+  'popupsurfaceimpl',
+  'toplevelsurfaceimpl',
   'value_cairo',
 ]
 
diff --git a/gdk/gdkmm/popupsurfaceimpl.cc b/gdk/gdkmm/popupsurfaceimpl.cc
new file mode 100644
index 00000000..73f5a9be
--- /dev/null
+++ b/gdk/gdkmm/popupsurfaceimpl.cc
@@ -0,0 +1,41 @@
+/* Copyright (C) 2020 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <gdkmm/popupsurfaceimpl.h>
+#include <utility> // std::move()
+
+namespace Gdk
+{
+PopupSurfaceImpl::PopupSurfaceImpl(GdkSurface* castitem)
+: Glib::ObjectBase(nullptr), Surface(castitem)
+{}
+
+PopupSurfaceImpl::PopupSurfaceImpl(PopupSurfaceImpl&& src) noexcept
+: Popup(std::move(src)),
+  Surface(std::move(src))
+{}
+
+PopupSurfaceImpl& PopupSurfaceImpl::operator=(PopupSurfaceImpl&& src) noexcept
+{
+  Popup::operator=(std::move(src));
+  Surface::operator=(std::move(src));
+  return *this;
+}
+
+PopupSurfaceImpl::~PopupSurfaceImpl() noexcept
+{}
+
+} // namespace Gdk
diff --git a/gdk/gdkmm/popupsurfaceimpl.h b/gdk/gdkmm/popupsurfaceimpl.h
new file mode 100644
index 00000000..ac5f70cb
--- /dev/null
+++ b/gdk/gdkmm/popupsurfaceimpl.h
@@ -0,0 +1,63 @@
+#ifndef _GDKMM_POPUPSURFACEIMPL_H
+#define _GDKMM_POPUPSURFACEIMPL_H
+
+/* Copyright (C) 2020 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <gdkmmconfig.h>
+#include <gdkmm/popup.h>
+#include <gdkmm/surface.h>
+
+namespace Gdk
+{
+
+/** %Gdk::PopupSurfaceImpl is a Gdk::Surface that implements the Gdk::Popup interface.
+ *
+ * The GdkPopup interface can be implemented by C classes that
+ * derive from GdkSurface. No public GTK class implements GdkPopup.
+ * Some GTK functions, such as gdk_surface_new_popup(), return an object
+ * of a class which is derived from GdkSurface and implements GdkPopup.
+ * Since that C class is not public, it's not wrapped in a C++ class.
+ * A C object of such a class can be wrapped in a %Gdk::PopupSurfaceImpl object.
+ * %Gdk::PopupSurfaceImpl does not directly correspond to any GTK class.
+ *
+ * This class is intended only for wrapping C objects returned from GTK functions.
+ *
+ * @see Gdk::Surface::create_popup()
+ * @newin{3,98}
+ */
+class GDKMM_API PopupSurfaceImpl : public Popup, public Surface
+{
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+protected:
+  explicit PopupSurfaceImpl(GdkSurface* castitem);
+  friend class Surface_Class;
+
+  // noncopyable
+  PopupSurfaceImpl(const PopupSurfaceImpl&) = delete;
+  PopupSurfaceImpl& operator=(const PopupSurfaceImpl&) = delete;
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
+public:
+  PopupSurfaceImpl(PopupSurfaceImpl&& src) noexcept;
+  PopupSurfaceImpl& operator=(PopupSurfaceImpl&& src) noexcept;
+
+  ~PopupSurfaceImpl() noexcept override;
+};
+
+} // namespace Gdk
+
+#endif /* _GDKMM_POPUPSURFACEIMPL_H */
diff --git a/gdk/gdkmm/toplevelsurfaceimpl.cc b/gdk/gdkmm/toplevelsurfaceimpl.cc
new file mode 100644
index 00000000..b4567526
--- /dev/null
+++ b/gdk/gdkmm/toplevelsurfaceimpl.cc
@@ -0,0 +1,41 @@
+/* Copyright (C) 2020 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <gdkmm/toplevelsurfaceimpl.h>
+#include <utility> // std::move()
+
+namespace Gdk
+{
+ToplevelSurfaceImpl::ToplevelSurfaceImpl(GdkSurface* castitem)
+: Glib::ObjectBase(nullptr), Surface(castitem)
+{}
+
+ToplevelSurfaceImpl::ToplevelSurfaceImpl(ToplevelSurfaceImpl&& src) noexcept
+: Toplevel(std::move(src)),
+  Surface(std::move(src))
+{}
+
+ToplevelSurfaceImpl& ToplevelSurfaceImpl::operator=(ToplevelSurfaceImpl&& src) noexcept
+{
+  Toplevel::operator=(std::move(src));
+  Surface::operator=(std::move(src));
+  return *this;
+}
+
+ToplevelSurfaceImpl::~ToplevelSurfaceImpl() noexcept
+{}
+
+} // namespace Gdk
diff --git a/gdk/gdkmm/toplevelsurfaceimpl.h b/gdk/gdkmm/toplevelsurfaceimpl.h
new file mode 100644
index 00000000..c2353129
--- /dev/null
+++ b/gdk/gdkmm/toplevelsurfaceimpl.h
@@ -0,0 +1,63 @@
+#ifndef _GDKMM_TOPLEVELSURFACEIMPL_H
+#define _GDKMM_TOPLEVELSURFACEIMPL_H
+
+/* Copyright (C) 2020 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <gdkmmconfig.h>
+#include <gdkmm/toplevel.h>
+#include <gdkmm/surface.h>
+
+namespace Gdk
+{
+
+/** %Gdk::ToplevelSurfaceImpl is a Gdk::Surface that implements the Gdk::Toplevel interface.
+ *
+ * The GdkToplevel interface can be implemented by C classes that
+ * derive from GdkSurface. No public GTK class implements GdkToplevel.
+ * Some GTK functions, such as gdk_surface_new_toplevel(), return an object
+ * of a class which is derived from GdkSurface and implements GdkToplevel.
+ * Since that C class is not public, it's not wrapped in a C++ class.
+ * A C object of such a class can be wrapped in a %Gdk::ToplevelSurfaceImpl object.
+ * %Gdk::ToplevelSurfaceImpl does not directly correspond to any GTK class.
+ *
+ * This class is intended only for wrapping C objects returned from GTK functions.
+ *
+ * @see Gdk::Surface::create_toplevel()
+ * @newin{3,98}
+ */
+class GDKMM_API ToplevelSurfaceImpl : public Toplevel, public Surface
+{
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+protected:
+  explicit ToplevelSurfaceImpl(GdkSurface* castitem);
+  friend class Surface_Class;
+
+  // noncopyable
+  ToplevelSurfaceImpl(const ToplevelSurfaceImpl&) = delete;
+  ToplevelSurfaceImpl& operator=(const ToplevelSurfaceImpl&) = delete;
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
+public:
+  ToplevelSurfaceImpl(ToplevelSurfaceImpl&& src) noexcept;
+  ToplevelSurfaceImpl& operator=(ToplevelSurfaceImpl&& src) noexcept;
+
+  ~ToplevelSurfaceImpl() noexcept override;
+};
+
+} // namespace Gdk
+
+#endif /* _GDKMM_TOPLEVELSURFACEIMPL_H */
diff --git a/gdk/src/drag.hg b/gdk/src/drag.hg
index 51e62815..3d549274 100644
--- a/gdk/src/drag.hg
+++ b/gdk/src/drag.hg
@@ -60,8 +60,26 @@ public:
 
   _WRAP_METHOD(void drag_drop_done(bool success), gdk_drag_drop_done)
 
-  // No unconst version of get_drag_surface(). The surface is owned by the Drag, and shall not be changed by 
the caller.
-  _WRAP_METHOD(Glib::RefPtr<const Surface> get_drag_surface() const, gdk_drag_get_drag_surface, refreturn)
+  /** Returns the surface on which the drag icon should be rendered
+   * during the drag operation. Note that the surface may not be
+   * available until the drag operation has begun. GDK will move
+   * the surface in accordance with the ongoing drag operation.
+   * The surface will be destroyed when the drag operation is over.
+   *
+   * The returned surface is usually a subclass of Gdk::Surface that implements
+   * the Gdk::DragSurface interface. To use drag surface API, do something like
+   * @code
+   * auto surface = drag->get_drag_surface();
+   * auto drag_surface = std::dynamic_pointer_cast<Gdk::DragSurfaceImpl>(surface);
+   * if (drag_surface)
+   *   drag_surface->do_something();
+   * @endcode
+   * 
+   * @return The drag surface, or an empty RefPtr.
+   */
+  _WRAP_METHOD(Glib::RefPtr<Surface> get_drag_surface(), gdk_drag_get_drag_surface, refreturn)
+  /// See the non-const version.
+  _WRAP_METHOD(Glib::RefPtr<const Surface> get_drag_surface() const, gdk_drag_get_drag_surface, refreturn, 
constversion)
 
   _WRAP_METHOD(void set_hotspot(int hot_x, int hot_y), gdk_drag_set_hotspot)
 
diff --git a/gdk/src/surface.ccg b/gdk/src/surface.ccg
index 207c8fb6..f40a1b28 100644
--- a/gdk/src/surface.ccg
+++ b/gdk/src/surface.ccg
@@ -25,6 +25,9 @@
 #include <gdkmm/glcontext.h>
 #include <gdkmm/frameclock.h>
 #include <gdkmm/monitor.h>
+#include <gdkmm/dragsurfaceimpl.h>
+#include <gdkmm/popupsurfaceimpl.h>
+#include <gdkmm/toplevelsurfaceimpl.h>
 
 using State = Gdk::Surface::State;
 using CairoRegion = cairo_region_t;
@@ -32,6 +35,21 @@ using CairoRegion = cairo_region_t;
 namespace Gdk
 {
 
+// Custom wrap_new() because we want to create
+// a DragSurfaceImpl if the underlying C class implements the GdkDragSurface interface,
+// a PopupSurfaceImpl if the underlying C class implements the GdkPopup interface,
+// a ToplevelSurfaceImpl if the underlying C class implements the GdkToplevel interface.
+Glib::ObjectBase* Surface_Class::wrap_new(GObject* object)
+{
+  if (GDK_IS_DRAG_SURFACE(object))
+     return new DragSurfaceImpl((GdkSurface*)object);
+  if (GDK_IS_POPUP(object))
+     return new PopupSurfaceImpl((GdkSurface*)object);
+  if (GDK_IS_TOPLEVEL(object))
+     return new ToplevelSurfaceImpl((GdkSurface*)object);
+  return new Surface((GdkSurface*)object);
+}
+
 void Surface::set_cursor()
 {
   gdk_surface_set_cursor(gobj(), nullptr);
diff --git a/gdk/src/surface.hg b/gdk/src/surface.hg
index d1756f61..fc4cfc62 100644
--- a/gdk/src/surface.hg
+++ b/gdk/src/surface.hg
@@ -47,15 +47,17 @@ class GDKMM_API GLContext;
 class GDKMM_API FrameClock;
 class GDKMM_API Monitor;
 
-/** A Gdk::Surface is a rectangular region on the screen. It's a low-level object, used to implement 
high-level objects such
- * as Gtk::Widget and Gtk::Window on the GTK+ level. A Gtk::Window is a toplevel window, the thing a user 
might think of as
- * a "window" with a titlebar and so on; a Gtk::Window may contain many Gdk::Surfaces. For example, each 
Gtk::Button has a
- * Gdk::Surface associated with it.
+/** Onscreen display areas in the target window system.
+ *
+ * A %Gdk::Surface is a (usually) rectangular region on the screen.
+ * It's a low-level object, used to implement high-level objects such
+ * as Gtk::Window on the GTK level.
  */
 class GDKMM_API Surface : public Glib::Object
 {
   _CLASS_GOBJECT(Surface, GdkSurface, GDK_SURFACE, Glib::Object, GObject, , , GDKMM_API)
   _STRUCT_NOT_HIDDEN
+  _CUSTOM_WRAP_NEW
   _IGNORE(gdk_surface_destroy, gdk_surface_is_destroyed)
 
 public:
@@ -63,9 +65,41 @@ public:
 
   // _WRAP_CREATE() would not be very useful here.
   // The gdk_surface_new_*() functions do more than call g_object_new().
-  // And we can't make one hand-coded constructor for each gdk_surface_new_*()
-  // function, because some of them have identical prototypes.
+
+  /** Creates a new toplevel surface.
+   *
+   * The created surface is usually a subclass of Gdk::Surface that implements
+   * the Gdk::Toplevel interface. To use toplevel API, do something like
+   * @code
+   * auto surface = Gdk::Surface::create_toplevel(display);
+   * auto toplevel = std::dynamic_pointer_cast<Gdk::ToplevelSurfaceImpl>(surface);
+   * if (toplevel)
+   *   toplevel->do_something();
+   * @endcode
+   * 
+   * @param display The display to create the surface on.
+   * @return The new %Gdk::Surface.
+   */
   _WRAP_METHOD(static Glib::RefPtr<Surface> create_toplevel(const Glib::RefPtr<Display>& display), 
gdk_surface_new_toplevel)
+
+  /** Create a new popup surface.
+   * 
+   * The surface will be attached to @a parent and can be positioned
+   * relative to it using Gdk::Popup::present().
+   *
+   * The created surface is usually a subclass of Gdk::Surface that implements
+   * the Gdk::Popup interface. To use popup API, do something like
+   * @code
+   * auto surface = Gdk::Surface::create_popup(parent, autohide);
+   * auto popup = std::dynamic_pointer_cast<Gdk::PopupSurfaceImpl>(surface);
+   * if (popup)
+   *   popup->do_something();
+   * @endcode
+   * 
+   * @param parent The parent surface to attach the surface to.
+   * @param autohide Whether to hide the surface on outside clicks.
+   * @return A new %Gdk::Surface.
+   */
   _WRAP_METHOD(static Glib::RefPtr<Surface> create_popup(
     const Glib::RefPtr<Surface>& parent, bool autohide), gdk_surface_new_popup)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]