[libwnck/wip/muktupavels/wnck-handle: 1/5] handle: make it public

[Alberts Muktupāvels <muktupavels src gnome org>]

commit aa8bc7f372e97de9e30efda35ac60b1a9ea1d943
Author: Alberts Muktupāvels <alberts muktupavels gmail com>
Date:   Mon Aug 19 16:12:32 2019 +0300

    handle: make it public

 libwnck/application.c         |  14 ++--
 libwnck/class-group.c         |  10 +--
 libwnck/libwnck.h             |   2 +
 libwnck/meson.build           |   1 +
 libwnck/pager.c               |  24 ++++++-
 libwnck/pager.h               |   2 +
 libwnck/private.h             |   2 -
 libwnck/screen.c              |  28 +++++---
 libwnck/screen.h              |   4 ++
 libwnck/selector.c            |  24 ++++++-
 libwnck/selector.h            |   8 ++-
 libwnck/tasklist.c            |  24 ++++++-
 libwnck/tasklist.h            |   2 +
 libwnck/util.c                |   6 +-
 libwnck/window.c              |  30 ++++----
 libwnck/wnck-handle-private.h |  28 +-------
 libwnck/wnck-handle.c         | 158 +++++++++++++++++++++++++++++++++++-------
 libwnck/wnck-handle.h         |  61 ++++++++++++++++
 libwnck/wnck-resource-usage.c |   2 +-
 libwnck/xutils.c              |  12 ++--
 20 files changed, 334 insertions(+), 108 deletions(-)
---
diff --git a/libwnck/application.c b/libwnck/application.c
index f67d8c4a..cbe6c4a9 100644
--- a/libwnck/application.c
+++ b/libwnck/application.c
@@ -191,7 +191,7 @@ wnck_application_finalize (GObject *object)
 WnckApplication*
 wnck_application_get (gulong xwindow)
 {
-  return _wnck_handle_get_application (_wnck_get_handle (), xwindow);
+  return wnck_handle_get_application (_wnck_get_handle (), xwindow);
 }
 
 /**
@@ -319,7 +319,7 @@ get_icons (WnckApplication *app)
   gsize normal_size;
   gsize mini_size;
 
-  handle = _wnck_screen_get_handle (app->priv->screen);
+  handle = wnck_screen_get_handle (app->priv->screen);
 
   icon = NULL;
   mini_icon = NULL;
@@ -505,8 +505,8 @@ _wnck_application_create (Window      xwindow,
   WnckApplication *application;
   Screen          *xscreen;
 
-  handle = _wnck_screen_get_handle (screen);
-  application = _wnck_handle_get_application (handle, xwindow);
+  handle = wnck_screen_get_handle (screen);
+  application = wnck_handle_get_application (handle, xwindow);
 
   g_return_val_if_fail (application == NULL, NULL);
 
@@ -554,15 +554,15 @@ _wnck_application_destroy (WnckApplication *application)
   WnckHandle *handle;
   Window xwindow = application->priv->xwindow;
 
-  handle = _wnck_screen_get_handle (application->priv->screen);
+  handle = wnck_screen_get_handle (application->priv->screen);
 
-  g_return_if_fail (_wnck_handle_get_application (handle, xwindow) == application);
+  g_return_if_fail (wnck_handle_get_application (handle, xwindow) == application);
 
   _wnck_handle_remove_application (handle, &xwindow);
 
   /* Removing from handle also removes the only ref WnckApplication had */
 
-  g_return_if_fail (_wnck_handle_get_application (handle, xwindow) == NULL);
+  g_return_if_fail (wnck_handle_get_application (handle, xwindow) == NULL);
 }
 
 static void
diff --git a/libwnck/class-group.c b/libwnck/class-group.c
index 202bef4f..46d1f241 100644
--- a/libwnck/class-group.c
+++ b/libwnck/class-group.c
@@ -202,7 +202,7 @@ wnck_class_group_finalize (GObject *object)
 WnckClassGroup *
 wnck_class_group_get (const char *id)
 {
-  return _wnck_handle_get_class_group (_wnck_get_handle (), id);
+  return wnck_handle_get_class_group (_wnck_get_handle (), id);
 }
 
 /**
@@ -224,8 +224,8 @@ _wnck_class_group_create (WnckScreen *screen,
   WnckHandle *handle;
   WnckClassGroup *class_group;
 
-  handle = _wnck_screen_get_handle (screen);
-  class_group = _wnck_handle_get_class_group (handle, res_class);
+  handle = wnck_screen_get_handle (screen);
+  class_group = wnck_handle_get_class_group (handle, res_class);
 
   g_return_val_if_fail (class_group == NULL, NULL);
 
@@ -256,7 +256,7 @@ _wnck_class_group_destroy (WnckClassGroup *class_group)
 
   g_return_if_fail (WNCK_IS_CLASS_GROUP (class_group));
 
-  handle = _wnck_screen_get_handle (class_group->priv->screen);
+  handle = wnck_screen_get_handle (class_group->priv->screen);
   _wnck_handle_remove_class_group (handle, class_group->priv->res_class);
 
   /* Removing from handle also removes the only ref WnckClassGroup had */
@@ -446,7 +446,7 @@ set_icon (WnckClassGroup *class_group)
     {
       WnckHandle *handle;
 
-      handle = _wnck_screen_get_handle (class_group->priv->screen);
+      handle = wnck_screen_get_handle (class_group->priv->screen);
 
       _wnck_get_fallback_icons (&icon,
                                 _wnck_handle_get_default_icon_size (handle),
diff --git a/libwnck/libwnck.h b/libwnck/libwnck.h
index 20f89f6f..7b1860a4 100644
--- a/libwnck/libwnck.h
+++ b/libwnck/libwnck.h
@@ -23,6 +23,8 @@
 
 #define __LIBWNCK_H_INSIDE__
 
+#include <libwnck/wnck-handle.h>
+
 #include <libwnck/window.h>
 #include <libwnck/application.h>
 #include <libwnck/class-group.h>
diff --git a/libwnck/meson.build b/libwnck/meson.build
index 9f714d0a..ddbff6ec 100644
--- a/libwnck/meson.build
+++ b/libwnck/meson.build
@@ -39,6 +39,7 @@ headers = [
   'util.h',
   'window.h',
   'window-action-menu.h',
+  'wnck-handle.h',
   'workspace.h',
 ]
 
diff --git a/libwnck/pager.c b/libwnck/pager.c
index 8561546c..3a97f63f 100644
--- a/libwnck/pager.c
+++ b/libwnck/pager.c
@@ -303,8 +303,8 @@ _wnck_pager_set_screen (WnckPager *pager)
   gdkscreen = gtk_widget_get_screen (GTK_WIDGET (pager));
   screen_number = gdk_x11_screen_get_screen_number (gdkscreen);
 
-  pager->priv->screen = _wnck_handle_get_screen (pager->priv->handle,
-                                                 screen_number);
+  pager->priv->screen = wnck_handle_get_screen (pager->priv->handle,
+                                                screen_number);
 
   if (!wnck_pager_set_layout_hint (pager))
     {
@@ -2207,6 +2207,26 @@ wnck_pager_new (void)
   return GTK_WIDGET (pager);
 }
 
+/**
+ * wnck_pager_new_with_handle:
+ * @handle: a #WnckHandle
+ *
+ * Creates a new #WnckPager. The #WnckPager will show the #WnckWorkspace of the
+ * #WnckScreen it is on.
+ *
+ * Returns: a newly created #WnckPager.
+ */
+GtkWidget *
+wnck_pager_new_with_handle (WnckHandle *handle)
+{
+  WnckPager *pager;
+
+  pager = g_object_new (WNCK_TYPE_PAGER, NULL);
+  pager->priv->handle = g_object_ref (handle);
+
+  return GTK_WIDGET (pager);
+}
+
 static gboolean
 wnck_pager_set_layout_hint (WnckPager *pager)
 {
diff --git a/libwnck/pager.h b/libwnck/pager.h
index c67f2fa3..db830ed2 100644
--- a/libwnck/pager.h
+++ b/libwnck/pager.h
@@ -104,6 +104,8 @@ GType      wnck_pager_get_type           (void) G_GNUC_CONST;
 
 GtkWidget* wnck_pager_new                (void);
 
+GtkWidget* wnck_pager_new_with_handle    (WnckHandle           *handle);
+
 gboolean   wnck_pager_set_orientation    (WnckPager            *pager,
                                           GtkOrientation        orientation);
 gboolean   wnck_pager_set_n_rows         (WnckPager            *pager,
diff --git a/libwnck/private.h b/libwnck/private.h
index bc83b65b..6f378d68 100644
--- a/libwnck/private.h
+++ b/libwnck/private.h
@@ -126,8 +126,6 @@ GdkScreen *_wnck_screen_get_gdk_screen (WnckScreen *screen);
 SnDisplay* _wnck_screen_get_sn_display (WnckScreen *screen);
 #endif
 
-WnckHandle    *_wnck_screen_get_handle          (WnckScreen    *screen);
-
 void           _wnck_pager_activate_workspace   (WnckWorkspace *wspace,
                                                  guint32        timestamp);
 int            _wnck_pager_get_n_workspaces     (WnckPager     *pager);
diff --git a/libwnck/screen.c b/libwnck/screen.c
index 26cc5af0..264f49e6 100644
--- a/libwnck/screen.c
+++ b/libwnck/screen.c
@@ -575,7 +575,7 @@ _wnck_screen_construct (WnckScreen *screen,
 WnckScreen*
 wnck_screen_get (int index)
 {
-  return _wnck_handle_get_screen (_wnck_get_handle (), index);
+  return wnck_handle_get_screen (_wnck_get_handle (), index);
 }
 
 /**
@@ -590,7 +590,7 @@ wnck_screen_get (int index)
 WnckScreen*
 wnck_screen_get_default (void)
 {
-  return _wnck_handle_get_default_screen (_wnck_get_handle ());
+  return wnck_handle_get_default_screen (_wnck_get_handle ());
 }
 
 /**
@@ -610,12 +610,20 @@ wnck_screen_get_default (void)
 WnckScreen*
 wnck_screen_get_for_root (gulong root_window_id)
 {
-  return _wnck_handle_get_screen_for_root (_wnck_get_handle (),
-                                           root_window_id);
+  return wnck_handle_get_screen_for_root (_wnck_get_handle (),
+                                          root_window_id);
 }
 
+/**
+ * wnck_screen_get_handle:
+ * @screen: a #WnckScreen.
+ *
+ * Gets the handle.
+ *
+ * Returns: (transfer none): a #WnckHandle, or %NULL.
+ */
 WnckHandle *
-_wnck_screen_get_handle (WnckScreen *screen)
+wnck_screen_get_handle (WnckScreen *screen)
 {
   g_return_val_if_fail (WNCK_IS_SCREEN (screen), NULL);
 
@@ -1405,7 +1413,7 @@ update_client_list (WnckScreen *screen)
     {
       WnckWindow *window;
 
-      window = _wnck_handle_get_window (screen->priv->handle, mapping[i]);
+      window = wnck_handle_get_window (screen->priv->handle, mapping[i]);
 
       if (window == NULL)
         {
@@ -1424,7 +1432,7 @@ update_client_list (WnckScreen *screen)
 
           leader = wnck_window_get_group_leader (window);
 
-          app = _wnck_handle_get_application (screen->priv->handle, leader);
+          app = wnck_handle_get_application (screen->priv->handle, leader);
           if (app == NULL)
             {
               app = _wnck_application_create (leader, screen);
@@ -1437,7 +1445,7 @@ update_client_list (WnckScreen *screen)
 
          res_class = wnck_window_get_class_group_name (window);
 
-         class_group = _wnck_handle_get_class_group (screen->priv->handle, res_class);
+         class_group = wnck_handle_get_class_group (screen->priv->handle, res_class);
          if (class_group == NULL)
            {
              class_group = _wnck_class_group_create (screen, res_class);
@@ -1501,7 +1509,7 @@ update_client_list (WnckScreen *screen)
     {
       WnckWindow *window;
 
-      window = _wnck_handle_get_window (screen->priv->handle, stack[i]);
+      window = wnck_handle_get_window (screen->priv->handle, stack[i]);
 
       g_assert (window != NULL);
 
@@ -1915,7 +1923,7 @@ update_active_window (WnckScreen *screen)
                     _wnck_atom_get ("_NET_ACTIVE_WINDOW"),
                     &xwindow);
 
-  window = _wnck_handle_get_window (screen->priv->handle, xwindow);
+  window = wnck_handle_get_window (screen->priv->handle, xwindow);
 
   if (window == screen->priv->active_window)
     return;
diff --git a/libwnck/screen.h b/libwnck/screen.h
index 3140ea51..153cf5fb 100644
--- a/libwnck/screen.h
+++ b/libwnck/screen.h
@@ -33,6 +33,7 @@ G_BEGIN_DECLS
 /* forward decls */
 typedef struct _WnckApplication WnckApplication;
 typedef struct _WnckClassGroup  WnckClassGroup;
+typedef struct _WnckHandle      WnckHandle;
 typedef struct _WnckWindow      WnckWindow;
 typedef struct _WnckWorkspace   WnckWorkspace;
 
@@ -196,6 +197,9 @@ GType wnck_screen_get_type (void) G_GNUC_CONST;
 WnckScreen*    wnck_screen_get_default              (void);
 WnckScreen*    wnck_screen_get                      (int         index);
 WnckScreen*    wnck_screen_get_for_root             (gulong      root_window_id);
+
+WnckHandle*    wnck_screen_get_handle               (WnckScreen *screen);
+
 int            wnck_screen_get_number               (WnckScreen *screen);
 WnckWorkspace* wnck_screen_get_workspace            (WnckScreen *screen,
                                                      int         workspace);
diff --git a/libwnck/selector.c b/libwnck/selector.c
index 482c614a..04ebfdbf 100644
--- a/libwnck/selector.c
+++ b/libwnck/selector.c
@@ -120,8 +120,8 @@ wnck_selector_get_screen (WnckSelector *selector)
 
   screen = gtk_widget_get_screen (GTK_WIDGET (selector));
 
-  return _wnck_handle_get_screen (selector->priv->handle,
-                                  gdk_x11_screen_get_screen_number (screen));
+  return wnck_handle_get_screen (selector->priv->handle,
+                                 gdk_x11_screen_get_screen_number (screen));
 }
 
 static GdkPixbuf *
@@ -1282,3 +1282,23 @@ wnck_selector_new (void)
 
   return GTK_WIDGET (selector);
 }
+
+/**
+ * wnck_selector_new_with_handle:
+ * @handle: a #WnckHandle
+ *
+ * Creates a new #WnckSelector. The #WnckSelector will list #WnckWindow of the
+ * #WnckScreen it is on.
+ *
+ * Returns: a newly created #WnckSelector.
+ */
+GtkWidget *
+wnck_selector_new_with_handle (WnckHandle *handle)
+{
+  WnckSelector *selector;
+
+  selector = g_object_new (WNCK_TYPE_SELECTOR, NULL);
+  selector->priv->handle = g_object_ref (handle);
+
+  return GTK_WIDGET (selector);
+}
diff --git a/libwnck/selector.h b/libwnck/selector.h
index 4783162b..bb6fceb9 100644
--- a/libwnck/selector.h
+++ b/libwnck/selector.h
@@ -27,6 +27,7 @@
 #define WNCK_SELECTOR_H
 
 #include <gtk/gtk.h>
+#include <libwnck/wnck-handle.h>
 
 G_BEGIN_DECLS
 #define WNCK_TYPE_SELECTOR              (wnck_selector_get_type ())
@@ -62,8 +63,11 @@ struct _WnckSelectorClass
   void (* pad4) (void);
 };
 
-GtkWidget *wnck_selector_new      (void);
-GType      wnck_selector_get_type (void) G_GNUC_CONST;
+GtkWidget *wnck_selector_new             (void);
+
+GtkWidget *wnck_selector_new_with_handle (WnckHandle *handle);
+
+GType      wnck_selector_get_type        (void) G_GNUC_CONST;
 
 G_END_DECLS
 
diff --git a/libwnck/tasklist.c b/libwnck/tasklist.c
index 78a73ff6..61b0e1ab 100644
--- a/libwnck/tasklist.c
+++ b/libwnck/tasklist.c
@@ -2163,8 +2163,8 @@ wnck_tasklist_realize (GtkWidget *widget)
   gdkscreen = gtk_widget_get_screen (widget);
   screen_number = gdk_x11_screen_get_screen_number (gdkscreen);
 
-  tasklist->priv->screen = _wnck_handle_get_screen (tasklist->priv->handle,
-                                                    screen_number);
+  tasklist->priv->screen = wnck_handle_get_screen (tasklist->priv->handle,
+                                                   screen_number);
 
   g_assert (tasklist->priv->screen != NULL);
 
@@ -2565,6 +2565,26 @@ wnck_tasklist_new (void)
   return GTK_WIDGET (tasklist);
 }
 
+/**
+ * wnck_tasklist_new_with_handle:
+ * @handle: a #WnckHandle
+ *
+ * Creates a new #WnckTasklist. The #WnckTasklist will list #WnckWindow of the
+ * #WnckScreen it is on.
+ *
+ * Returns: a newly created #WnckTasklist.
+ */
+GtkWidget *
+wnck_tasklist_new_with_handle (WnckHandle *handle)
+{
+  WnckTasklist *self;
+
+  self = g_object_new (WNCK_TYPE_TASKLIST, NULL);
+  self->priv->handle = g_object_ref (handle);
+
+  return GTK_WIDGET (self);
+}
+
 static void
 wnck_tasklist_free_tasks (WnckTasklist *tasklist)
 {
diff --git a/libwnck/tasklist.h b/libwnck/tasklist.h
index 0659f9d6..b308802b 100644
--- a/libwnck/tasklist.h
+++ b/libwnck/tasklist.h
@@ -89,6 +89,8 @@ GType wnck_tasklist_get_type (void) G_GNUC_CONST;
 
 GtkWidget *wnck_tasklist_new (void);
 
+GtkWidget *wnck_tasklist_new_with_handle (WnckHandle *handle);
+
 G_DEPRECATED
 const int *wnck_tasklist_get_size_hint_list (WnckTasklist  *tasklist,
                                              int           *n_elements);
diff --git a/libwnck/util.c b/libwnck/util.c
index b1023585..701878b4 100644
--- a/libwnck/util.c
+++ b/libwnck/util.c
@@ -158,7 +158,7 @@ _wnck_get_handle (void)
       if (client_type == 0)
         client_type = WNCK_CLIENT_TYPE_APPLICATION;
 
-      wnck_handle = _wnck_handle_new (client_type);
+      wnck_handle = wnck_handle_new (client_type);
     }
 
   return wnck_handle;
@@ -176,7 +176,7 @@ _wnck_get_handle (void)
 void
 wnck_set_default_icon_size (gsize size)
 {
-  _wnck_handle_set_default_icon_size (_wnck_get_handle (), size);
+  wnck_handle_set_default_icon_size (_wnck_get_handle(), size);
 }
 
 /**
@@ -195,7 +195,7 @@ wnck_set_default_mini_icon_size (gsize size)
   WnckScreen *screen;
   GList *l;
 
-  _wnck_handle_set_default_mini_icon_size (_wnck_get_handle (), size);
+  wnck_handle_set_default_mini_icon_size (_wnck_get_handle (), size);
 
   default_screen = DefaultScreen (_wnck_get_default_display ());
   screen = _wnck_handle_get_existing_screen (_wnck_get_handle (),
diff --git a/libwnck/window.c b/libwnck/window.c
index ec8768b6..475ddad5 100644
--- a/libwnck/window.c
+++ b/libwnck/window.c
@@ -448,7 +448,7 @@ wnck_window_finalize (GObject *object)
 WnckWindow*
 wnck_window_get (gulong xwindow)
 {
-  return _wnck_handle_get_window (_wnck_get_handle (), xwindow);
+  return wnck_handle_get_window (_wnck_get_handle (), xwindow);
 }
 
 /**
@@ -477,8 +477,8 @@ _wnck_window_create (Window      xwindow,
   WnckWindow *window;
   Screen     *xscreen;
 
-  handle = _wnck_screen_get_handle (screen);
-  window = _wnck_handle_get_window (handle, xwindow);
+  handle = wnck_screen_get_handle (screen);
+  window = wnck_handle_get_window (handle, xwindow);
 
   g_return_val_if_fail (window == NULL, NULL);
 
@@ -556,15 +556,15 @@ _wnck_window_destroy (WnckWindow *window)
 
   g_return_if_fail (WNCK_IS_WINDOW (window));
 
-  handle = _wnck_screen_get_handle (window->priv->screen);
+  handle = wnck_screen_get_handle (window->priv->screen);
 
-  g_return_if_fail (_wnck_handle_get_window (handle, xwindow) == window);
+  g_return_if_fail (wnck_handle_get_window (handle, xwindow) == window);
 
   _wnck_handle_remove_window (handle, &xwindow);
 
   /* Removing from handle also removes the only ref WnckWindow had */
 
-  g_return_if_fail (_wnck_handle_get_window (handle, xwindow) == NULL);
+  g_return_if_fail (wnck_handle_get_window (handle, xwindow) == NULL);
 }
 
 static Display *
@@ -744,9 +744,9 @@ wnck_window_get_transient (WnckWindow *window)
 
   g_return_val_if_fail (WNCK_IS_WINDOW (window), NULL);
 
-  handle = _wnck_screen_get_handle (window->priv->screen);
+  handle = wnck_screen_get_handle (window->priv->screen);
 
-  return _wnck_handle_get_window (handle, window->priv->transient_for);
+  return wnck_handle_get_window (handle, window->priv->transient_for);
 }
 
 /**
@@ -1170,8 +1170,8 @@ _wnck_window_get_startup_id (WnckWindow *window)
 
       /* Fall back to group leader property */
 
-      handle = _wnck_screen_get_handle (window->priv->screen);
-      app = _wnck_handle_get_application (handle, window->priv->group_leader);
+      handle = wnck_screen_get_handle (window->priv->screen);
+      app = wnck_handle_get_application (handle, window->priv->group_leader);
 
       if (app != NULL)
         return wnck_application_get_startup_id (app);
@@ -2115,7 +2115,7 @@ get_icons (WnckWindow *window)
   gsize normal_size;
   gsize mini_size;
 
-  handle = _wnck_screen_get_handle (window->priv->screen);
+  handle = wnck_screen_get_handle (window->priv->screen);
 
   icon = NULL;
   mini_icon = NULL;
@@ -2364,7 +2364,7 @@ wnck_window_set_geometry (WnckWindow               *window,
 
   g_return_if_fail (WNCK_IS_WINDOW (window));
 
-  handle = _wnck_screen_get_handle (window->priv->screen);
+  handle = wnck_screen_get_handle (window->priv->screen);
   source = _wnck_handle_get_client_type (handle);
 
   gravity_and_flags = gravity;
@@ -3102,9 +3102,9 @@ update_transient_for (WnckWindow *window)
 
       window->priv->transient_for = parent;
 
-      handle = _wnck_screen_get_handle (window->priv->screen);
-      screen = _wnck_handle_get_screen_for_root (handle,
-                                                 window->priv->transient_for);
+      handle = wnck_screen_get_handle (window->priv->screen);
+      screen = wnck_handle_get_screen_for_root (handle,
+                                                window->priv->transient_for);
 
       if (screen != NULL)
         window->priv->transient_for_root = TRUE;
diff --git a/libwnck/wnck-handle-private.h b/libwnck/wnck-handle-private.h
index 05ce22bd..cca13e17 100644
--- a/libwnck/wnck-handle-private.h
+++ b/libwnck/wnck-handle-private.h
@@ -20,34 +20,17 @@
 
 #include "class-group.h"
 #include "util.h"
+#include "wnck-handle.h"
 
 G_BEGIN_DECLS
 
-typedef struct _WnckHandle WnckHandle;
-
-WnckHandle      *_wnck_handle_new                        (WnckClientType  client_type);
-
 WnckClientType   _wnck_handle_get_client_type            (WnckHandle     *self);
 
-WnckScreen      *_wnck_handle_get_default_screen         (WnckHandle     *self);
-
-WnckScreen      *_wnck_handle_get_screen                 (WnckHandle     *self,
-                                                          int             index);
-
-WnckScreen      *_wnck_handle_get_screen_for_root        (WnckHandle     *self,
-                                                          gulong          root_window_id);
-
 WnckScreen      *_wnck_handle_get_existing_screen        (WnckHandle     *self,
                                                           int             number);
 
-void             _wnck_handle_set_default_icon_size      (WnckHandle     *self,
-                                                          gsize           icon_size);
-
 gsize            _wnck_handle_get_default_icon_size      (WnckHandle     *self);
 
-void             _wnck_handle_set_default_mini_icon_size (WnckHandle     *self,
-                                                          gsize           icon_size);
-
 gsize            _wnck_handle_get_default_mini_icon_size (WnckHandle     *self);
 
 void             _wnck_handle_insert_class_group         (WnckHandle      *self,
@@ -57,9 +40,6 @@ void             _wnck_handle_insert_class_group         (WnckHandle      *self,
 void             _wnck_handle_remove_class_group         (WnckHandle      *self,
                                                           const char      *id);
 
-WnckClassGroup  *_wnck_handle_get_class_group            (WnckHandle      *self,
-                                                          const char      *id);
-
 void             _wnck_handle_insert_application         (WnckHandle      *self,
                                                           gpointer         xwindow,
                                                           WnckApplication *app);
@@ -67,9 +47,6 @@ void             _wnck_handle_insert_application         (WnckHandle      *self,
 void             _wnck_handle_remove_application         (WnckHandle      *self,
                                                           gpointer         xwindow);
 
-WnckApplication *_wnck_handle_get_application            (WnckHandle      *self,
-                                                          gulong           xwindow);
-
 void             _wnck_handle_insert_window              (WnckHandle      *self,
                                                           gpointer         xwindow,
                                                           WnckWindow      *window);
@@ -77,9 +54,6 @@ void             _wnck_handle_insert_window              (WnckHandle      *self,
 void             _wnck_handle_remove_window              (WnckHandle      *self,
                                                           gpointer         xwindow);
 
-WnckWindow      *_wnck_handle_get_window                 (WnckHandle      *self,
-                                                          gulong           xwindow);
-
 G_END_DECLS
 
 #endif
diff --git a/libwnck/wnck-handle.c b/libwnck/wnck-handle.c
index 157aabea..5c2ba806 100644
--- a/libwnck/wnck-handle.c
+++ b/libwnck/wnck-handle.c
@@ -19,6 +19,13 @@
  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION: wnck-handle
+ * @short_description: an object representing a handle.
+ *
+ * This is the main entry point into the libwnck library.
+ */
+
 #include "config.h"
 #include "wnck-handle-private.h"
 
@@ -28,9 +35,6 @@
 #include "wnck-enum-types.h"
 #include "xutils.h"
 
-#define WNCK_TYPE_HANDLE (wnck_handle_get_type ())
-G_DECLARE_FINAL_TYPE (WnckHandle, wnck_handle, WNCK, HANDLE, GObject)
-
 struct _WnckHandle
 {
   GObject          parent;
@@ -80,7 +84,7 @@ filter_func (GdkXEvent *gdkxevent,
       {
         WnckScreen *screen;
 
-        screen = _wnck_handle_get_screen_for_root (self, xevent->xany.window);
+        screen = wnck_handle_get_screen_for_root (self, xevent->xany.window);
 
         if (screen != NULL)
           {
@@ -91,8 +95,8 @@ filter_func (GdkXEvent *gdkxevent,
             WnckWindow *window;
             WnckApplication *app;
 
-            window = wnck_window_get (xevent->xany.window);
-            app = wnck_application_get (xevent->xany.window);
+            window = wnck_handle_get_window (self, xevent->xany.window);
+            app = wnck_handle_get_application (self, xevent->xany.window);
 
             if (app)
               _wnck_application_process_property_notify (app, xevent);
@@ -107,7 +111,7 @@ filter_func (GdkXEvent *gdkxevent,
       {
         WnckWindow *window;
 
-        window = wnck_window_get (xevent->xconfigure.window);
+        window = wnck_handle_get_window (self, xevent->xconfigure.window);
 
         if (window)
           _wnck_window_process_configure_notify (window, xevent);
@@ -305,8 +309,16 @@ wnck_handle_init (WnckHandle *self)
   gdk_window_add_filter (NULL, filter_func, self);
 }
 
+/**
+ * wnck_handle_new:
+ * @client_type: a role for the client
+ *
+ * Creates a new #WnckHandle object with a given @client_type.
+ *
+ * Returns: (transfer full): newly created #WnckHandle.
+ */
 WnckHandle *
-_wnck_handle_new (WnckClientType client_type)
+wnck_handle_new (WnckClientType client_type)
 {
   return g_object_new (WNCK_TYPE_HANDLE,
                        "client-type", client_type,
@@ -319,8 +331,18 @@ _wnck_handle_get_client_type (WnckHandle *self)
   return self->client_type;
 }
 
+/**
+ * wnck_handle_get_default_screen:
+ * @self: a #WnckHandle
+ *
+ * Gets the default #WnckScreen on the default display.
+ *
+ * Returns: (transfer none) (nullable): the default #WnckScreen. The
+ * returned #WnckScreen is owned by #WnckHandle and must not be referenced
+ * or unreferenced. This can return %NULL if not on X11.
+ */
 WnckScreen *
-_wnck_handle_get_default_screen (WnckHandle *self)
+wnck_handle_get_default_screen (WnckHandle *self)
 {
   Display *display;
 
@@ -330,12 +352,23 @@ _wnck_handle_get_default_screen (WnckHandle *self)
   if (display == NULL)
     return NULL;
 
-  return _wnck_handle_get_screen (self, DefaultScreen (display));
+  return wnck_handle_get_screen (self, DefaultScreen (display));
 }
 
+/**
+ * wnck_handle_get_screen:
+ * @self: a #WnckHandle
+ * @index: screen number, starting from 0.
+ *
+ * Gets the #WnckScreen for a given screen on the default display.
+ *
+ * Returns: (transfer none): the #WnckScreen for screen @index, or %NULL
+ * if no such screen exists. The returned #WnckScreen is owned by #WnckHandle
+ * and must not be referenced or unreferenced.
+ */
 WnckScreen *
-_wnck_handle_get_screen (WnckHandle *self,
-                         int         index)
+wnck_handle_get_screen (WnckHandle *self,
+                        int         index)
 {
   Display *display;
 
@@ -360,9 +393,24 @@ _wnck_handle_get_screen (WnckHandle *self,
   return self->screens[index];
 }
 
+/**
+ * wnck_handle_get_screen_for_root:
+ * @self: a #WnckHandle
+ * @root_window_id: an X window ID.
+ *
+ * Gets the #WnckScreen for the root window at @root_window_id, or
+ * %NULL if no #WnckScreen exists for this root window.
+ *
+ * This function does not work if wnck_handle_get_screen() was not called
+ * for the sought #WnckScreen before, and returns %NULL.
+ *
+ * Returns: (transfer none): the #WnckScreen for the root window at
+ * @root_window_id, or %NULL. The returned #WnckScreen is owned by
+ * #WnckHandle and must not be referenced or unreferenced.
+ */
 WnckScreen *
-_wnck_handle_get_screen_for_root (WnckHandle *self,
-                                  gulong      root_window_id)
+wnck_handle_get_screen_for_root (WnckHandle *self,
+                                 gulong      root_window_id)
 {
   Display *display;
   int i;
@@ -407,29 +455,53 @@ _wnck_handle_get_existing_screen (WnckHandle *self,
   return NULL;
 }
 
+/**
+ * wnck_handle_set_default_icon_size:
+ * @self: a #WnckHandle
+ * @icon_size: the default size for windows and application standard icons.
+ *
+ * The default main icon size is %WNCK_DEFAULT_ICON_SIZE. This function allows
+ * to change this value.
+ */
 void
-_wnck_handle_set_default_icon_size (WnckHandle *self,
-                                    gsize       icon_size)
+wnck_handle_set_default_icon_size (WnckHandle *self,
+                                   gsize       icon_size)
 {
+  g_return_if_fail (WNCK_IS_HANDLE (self));
+
   self->default_icon_size = icon_size;
 }
 
 gsize
 _wnck_handle_get_default_icon_size (WnckHandle *self)
 {
+  g_return_val_if_fail (WNCK_IS_HANDLE (self), WNCK_DEFAULT_ICON_SIZE);
+
   return self->default_icon_size;
 }
 
+/**
+ * wnck_handle_set_default_mini_icon_size:
+ * @self: a #WnckHandle
+ * @icon_size: the default size for windows and application mini icons.
+ *
+ * The default main icon size is %WNCK_DEFAULT_MINI_ICON_SIZE. This function
+ * allows to change this value.
+ */
 void
-_wnck_handle_set_default_mini_icon_size (WnckHandle *self,
-                                         gsize       icon_size)
+wnck_handle_set_default_mini_icon_size (WnckHandle *self,
+                                        gsize       icon_size)
 {
+  g_return_if_fail (WNCK_IS_HANDLE (self));
+
   self->default_mini_icon_size = icon_size;
 }
 
 gsize
 _wnck_handle_get_default_mini_icon_size (WnckHandle *self)
 {
+  g_return_val_if_fail (WNCK_IS_HANDLE (self), WNCK_DEFAULT_MINI_ICON_SIZE);
+
   return self->default_mini_icon_size;
 }
 
@@ -451,9 +523,21 @@ _wnck_handle_remove_class_group (WnckHandle *self,
   g_hash_table_remove (self->class_group_hash, id);
 }
 
+/**
+ * wnck_handle_get_class_group:
+ * @self: a #WnckHandle
+ * @id: identifier name of the sought resource class.
+ *
+ * Gets the #WnckClassGroup corresponding to @id.
+ *
+ * Returns: (transfer none): the #WnckClassGroup corresponding to
+ * @id, or %NULL if there is no #WnckClassGroup with the specified
+ * @id. The returned #WnckClassGroup is owned by libwnck and must not be
+ * referenced or unreferenced.
+ */
 WnckClassGroup *
-_wnck_handle_get_class_group (WnckHandle *self,
-                              const char *id)
+wnck_handle_get_class_group (WnckHandle *self,
+                             const char *id)
 {
   g_return_val_if_fail (WNCK_IS_HANDLE (self), NULL);
 
@@ -475,9 +559,23 @@ _wnck_handle_remove_application (WnckHandle *self,
   g_hash_table_remove (self->app_hash, xwindow);
 }
 
+
+/**
+ * wnck_handle_get_application:
+ * @self: a #WnckHandle
+ * @xwindow: the X window ID of a group leader.
+ *
+ * Gets the #WnckApplication corresponding to the group leader with @xwindow
+ * as X window ID.
+ *
+ * Returns: (transfer none): the #WnckApplication corresponding to
+ * @xwindow, or %NULL if there no such #WnckApplication could be found. The
+ * returned #WnckApplication is owned by libwnck and must not be referenced or
+ * unreferenced.
+ */
 WnckApplication *
-_wnck_handle_get_application (WnckHandle *self,
-                              gulong      xwindow)
+wnck_handle_get_application (WnckHandle *self,
+                             gulong      xwindow)
 {
   g_return_val_if_fail (WNCK_IS_HANDLE (self), NULL);
 
@@ -499,9 +597,21 @@ _wnck_handle_remove_window (WnckHandle *self,
   g_hash_table_remove (self->window_hash, xwindow);
 }
 
+/**
+ * wnck_handle_get_window:
+ * @self: a #WnckHandle
+ * @xwindow: an X window ID.
+ *
+ * Gets a preexisting #WnckWindow for the X window @xwindow. This will not
+ * create a #WnckWindow if none exists. The function is robust against bogus
+ * window IDs.
+ *
+ * Returns: (transfer none): the #WnckWindow for @xwindow. The returned
+ * #WnckWindow is owned by libwnck and must not be referenced or unreferenced.
+ */
 WnckWindow *
-_wnck_handle_get_window (WnckHandle *self,
-                         gulong      xwindow)
+wnck_handle_get_window (WnckHandle *self,
+                        gulong      xwindow)
 {
   g_return_val_if_fail (WNCK_IS_HANDLE (self), NULL);
 
diff --git a/libwnck/wnck-handle.h b/libwnck/wnck-handle.h
new file mode 100644
index 00000000..b58a47f0
--- /dev/null
+++ b/libwnck/wnck-handle.h
@@ -0,0 +1,61 @@
+/*
+ * Copyright (C) 2021 Alberts Muktupāvels
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#if !defined (__LIBWNCK_H_INSIDE__) && !defined (WNCK_COMPILATION)
+#error "Only <libwnck/libwnck.h> can be included directly."
+#endif
+
+#ifndef WNCK_HANDLE_H
+#define WNCK_HANDLE_H
+
+#include <glib-object.h>
+#include <libwnck/screen.h>
+#include <libwnck/util.h>
+
+G_BEGIN_DECLS
+
+#define WNCK_TYPE_HANDLE (wnck_handle_get_type ())
+G_DECLARE_FINAL_TYPE (WnckHandle, wnck_handle, WNCK, HANDLE, GObject)
+
+WnckHandle      *wnck_handle_new                        (WnckClientType     client_type);
+
+WnckScreen      *wnck_handle_get_default_screen         (WnckHandle        *self);
+
+WnckScreen      *wnck_handle_get_screen                 (WnckHandle        *self,
+                                                         int                index);
+
+WnckScreen      *wnck_handle_get_screen_for_root        (WnckHandle        *self,
+                                                         gulong             root_window_id);
+
+void             wnck_handle_set_default_icon_size      (WnckHandle        *self,
+                                                         gsize              icon_size);
+
+void             wnck_handle_set_default_mini_icon_size (WnckHandle        *self,
+                                                         gsize              icon_size);
+
+WnckClassGroup  *wnck_handle_get_class_group            (WnckHandle        *self,
+                                                         const char        *id);
+
+WnckApplication *wnck_handle_get_application            (WnckHandle        *self,
+                                                         gulong             xwindow);
+
+WnckWindow      *wnck_handle_get_window                 (WnckHandle        *self,
+                                                         gulong             xwindow);
+
+G_END_DECLS
+
+#endif
diff --git a/libwnck/wnck-resource-usage.c b/libwnck/wnck-resource-usage.c
index 1bb5f4ed..a845d82b 100644
--- a/libwnck/wnck-resource-usage.c
+++ b/libwnck/wnck-resource-usage.c
@@ -395,7 +395,7 @@ wnck_pid_read_resource_usage_no_cache (GdkDisplay        *gdisplay,
       GList *windows;
       GList *tmp;
 
-      screen = _wnck_handle_get_screen (_wnck_get_handle (), i);
+      screen = wnck_handle_get_screen (_wnck_get_handle (), i);
 
       g_assert (screen != NULL);
 
diff --git a/libwnck/xutils.c b/libwnck/xutils.c
index e95abef8..f2a2d3c3 100644
--- a/libwnck/xutils.c
+++ b/libwnck/xutils.c
@@ -786,7 +786,7 @@ _wnck_close (WnckScreen *screen,
   Window root;
   XEvent xev;
 
-  handle = _wnck_screen_get_handle (screen);
+  handle = wnck_screen_get_handle (screen);
   xscreen = _wnck_screen_get_xscreen (screen);
   display = DisplayOfScreen (xscreen);
   root = RootWindowOfScreen (xscreen);
@@ -835,7 +835,7 @@ _wnck_keyboard_move (WnckScreen *screen,
   Window root;
   XEvent xev;
 
-  handle = _wnck_screen_get_handle (screen);
+  handle = wnck_screen_get_handle (screen);
   xscreen = _wnck_screen_get_xscreen (screen);
   display = DisplayOfScreen (xscreen);
   root = RootWindowOfScreen (xscreen);
@@ -872,7 +872,7 @@ _wnck_keyboard_size (WnckScreen *screen,
   Window root;
   XEvent xev;
 
-  handle = _wnck_screen_get_handle (screen);
+  handle = wnck_screen_get_handle (screen);
   xscreen = _wnck_screen_get_xscreen (screen);
   display = DisplayOfScreen (xscreen);
   root = RootWindowOfScreen (xscreen);
@@ -916,7 +916,7 @@ _wnck_change_state (WnckScreen *screen,
 #define _NET_WM_STATE_ADD           1    /* add/set property */
 #define _NET_WM_STATE_TOGGLE        2    /* toggle property  */
 
-  handle = _wnck_screen_get_handle (screen);
+  handle = wnck_screen_get_handle (screen);
   xscreen = _wnck_screen_get_xscreen (screen);
   display = DisplayOfScreen (xscreen);
   root = RootWindowOfScreen (xscreen);
@@ -954,7 +954,7 @@ _wnck_change_workspace (WnckScreen *screen,
   Window root;
   XEvent xev;
 
-  handle = _wnck_screen_get_handle (screen);
+  handle = wnck_screen_get_handle (screen);
   xscreen = _wnck_screen_get_xscreen (screen);
   display = DisplayOfScreen (xscreen);
   root = RootWindowOfScreen (xscreen);
@@ -996,7 +996,7 @@ _wnck_activate (WnckScreen *screen,
     g_warning ("Received a timestamp of 0; window activation may not "
                "function properly.\n");
 
-  handle = _wnck_screen_get_handle (screen);
+  handle = wnck_screen_get_handle (screen);
   xscreen = _wnck_screen_get_xscreen (screen);
   display = DisplayOfScreen (xscreen);
   root = RootWindowOfScreen (xscreen);