Add docs

docs/reference/gdk/gdk-docs.sgml

@@ -23,6 +23,7 @@
     <xi:include href="xml/gdkdisplay.xml" />
     <xi:include href="xml/gdkscreen.xml" />
     <xi:include href="xml/gdkseat.xml" />
+    <xi:include href="xml/gdkmonitor.xml" />
     <xi:include href="xml/gdkdevicemanager.xml" />
     <xi:include href="xml/gdkdevice.xml" />
     <xi:include href="xml/regions.xml" />

docs/reference/gdk/gdk3-sections.txt

@@ -158,6 +158,10 @@ gdk_display_get_app_launch_context
 gdk_display_notify_startup_complete
 gdk_display_get_default_seat
 gdk_display_list_seats
+gdk_display_get_monitors
+gdk_display_get_primary_monitor
+gdk_display_get_monitor_at_point
+gdk_display_get_monitor_at_window
 
 <SUBSECTION Standard>
 GDK_DISPLAY
@@ -1366,3 +1370,26 @@ GDK_GL_ERROR
 GDK_TYPE_GL_ERROR
 GDK_TYPE_GL_PROFILE
 </SECTION>
+
+<SECTION>
+<FILE>gdkmonitor</FILE>
+GdkMonitor
+gdk_monitor_get_display
+gdk_monitor_get_geometry
+gdk_monitor_get_workarea
+gdk_monitor_get_width_mm
+gdk_monitor_get_height_mm
+gdk_monitor_get_manufacturer
+gdk_monitor_get_model
+gdk_monitor_get_scale_factor
+gdk_monitor_get_refresh_rate
+gdk_monitor_get_subpixel_layout
+gdk_monitor_is_primary
+
+<SUBSECTION Standard>
+gdk_monitor_get_type
+GdkMonitorClass
+GDK_TYPE_MONITOR
+GDK_MONITOR
+GDK_IS_MONITOR
+</SECTION>

gdk/gdkdisplay.c

@@ -230,6 +230,16 @@ gdk_display_class_init (GdkDisplayClass *class)
                   g_cclosure_marshal_VOID__OBJECT,
 		  G_TYPE_NONE, 1, GDK_TYPE_SEAT);
 
+  /**
+   * GdkDisplay::monitor-added:
+   * @display: the objedct on which the signal is emitted
+   * @monitor: the monitor that was just added
+   *
+   * The ::monitor-added signal is emitted whenever a monitor is
+   * added.
+   *
+   * Since: 3.22
+   */
   signals[MONITOR_ADDED] =
     g_signal_new (g_intern_static_string ("monitor-added"),
 		  G_OBJECT_CLASS_TYPE (object_class),
@@ -237,6 +247,17 @@ gdk_display_class_init (GdkDisplayClass *class)
 		  0, NULL, NULL,
                   g_cclosure_marshal_VOID__OBJECT,
 		  G_TYPE_NONE, 1, GDK_TYPE_MONITOR);
+
+  /**
+   * GdkDisplay::monitor-removed:
+   * @display: the object on which the signal is emitted
+   * @monitor: the monitor that was just removed
+   *
+   * The ::monitor-removed signal is emitted whenever a monitor is
+   * removed.
+   *
+   * Since: 3.22
+   */
   signals[MONITOR_REMOVED] =
     g_signal_new (g_intern_static_string ("monitor-removed"),
 		  G_OBJECT_CLASS_TYPE (object_class),
@@ -2482,6 +2503,19 @@ gdk_display_list_seats (GdkDisplay *display)
   return g_list_copy (display->seats);
 }
 
+/**
+ * gdk_display_get_monitors:
+ * @display: a #GdkDisplay
+ * @n_monitors: (out): Return location for the length of the returned array
+ *
+ * Gets the monitors associated with this display. The array will only be
+ * valid until the next emission of the #GdkDisplay::monitor-added or
+ * #GdkDisplay::monitor-removed signal.
+ *
+ * Returns: (transfer none) (element-type GdkMonitor): an array of #GdkMonitor
+ *     objects
+ * Since: 3.22
+ */
 GdkMonitor **
 gdk_display_get_monitors (GdkDisplay *display,
                           gint       *n_monitors)
@@ -2491,6 +2525,21 @@ gdk_display_get_monitors (GdkDisplay *display,
   return GDK_DISPLAY_GET_CLASS (display)->get_monitors (display, n_monitors);
 }
 
+/**
+ * gdk_display_get_primary_monitor:
+ * @display: a #GdkDisplay
+ *
+ * Gets the primary monitor for the display.
+ *
+ * The primary monitor is considered the monitor where the “main desktop”
+ * lives. While normal application windows typically allow the window
+ * manager to place the windows, specialized desktop applications
+ * such as panels should place themselves on the primary monitor.
+ *
+ * Returns: (transfer none): the primary monitor, or %NULL if no primary
+ *     monitor is configured by the user
+ * Since: 3.22
+ */
 GdkMonitor *
 gdk_display_get_primary_monitor (GdkDisplay *display)
 {
@@ -2502,6 +2551,18 @@ gdk_display_get_primary_monitor (GdkDisplay *display)
   return NULL;
 }
 
+/**
+ * gdk_display_get_monitor_at_point:
+ * @display: a #GdkDisplay
+ * @x: the x coordinate of the point
+ * @y: the y coordinate of the point
+ *
+ * Gets the monitor in which the point (@x, @y) is located,
+ * or a nearby monitor if the point is not in any monitor.
+ *
+ * Returns: (transfer none): the monitor containing the point
+ * Since: 3.22
+ */
 GdkMonitor *
 gdk_display_get_monitor_at_point (GdkDisplay *display,
                                   int         x,
@@ -2550,6 +2611,18 @@ gdk_display_get_monitor_at_point (GdkDisplay *display,
   return nearest;
 }
 
+/**
+ * gdk_display_get_monitor_at_window:
+ * @display: a #GdkDisplay
+ * @window: a #GdkWindow
+ *
+ * Gets the monitor in which the largest area of @window
+ * resides, or a monitor close to @window if it is outside
+ * of all monitors.
+ *
+ * Returns: (transfer none): the monitor with the largest overlap with @window
+ * Since: 3.22
+ */
 GdkMonitor *
 gdk_display_get_monitor_at_window (GdkDisplay *display,
                                    GdkWindow  *window)

gdk/gdkmonitor.c

@@ -25,6 +25,21 @@
 #include "gdkdisplay.h"
 #include "gdkenumtypes.h"
 
+/**
+ * SECTION:gdkmonitor
+ * @Title: GdkMonitor
+ * @Short_description: Object representing an output
+ *
+ * GdkMonitor objects represent the individual outputs that are
+ * associated with a #GdkDisplay. GdkDisplay has APIs to enumerate
+ * monitors with gdk_display_get_monitors() and to find particular
+ * monitors with gdk_display_get_primary_monitor() or
+ * gdk_display_get_monitor_at_window().
+ *
+ * GdkMonitor was introduced in GTK+ 3.22 and supersedes earlier
+ * APIs in GdkScreen to obtain monitor-related information.
+ */
+
 /*
  * TODO:
  * - monitor type (laptop, projector, ...)
@@ -225,6 +240,15 @@ gdk_monitor_class_init (GdkMonitorClass *class)
   g_object_class_install_properties (object_class, LAST_PROP, props);
 }
 
+/**
+ * gdk_monitor_get_display:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the display that this monitor belongs to.
+ *
+ * Returns: (transfer none): the display
+ * Since: 3.22
+ */
 GdkDisplay *
 gdk_monitor_get_display (GdkMonitor *monitor)
 {
@@ -233,6 +257,17 @@ gdk_monitor_get_display (GdkMonitor *monitor)
   return monitor->display;
 }
 
+/**
+ * gdk_monitor_get_geometry:
+ * @monitor: a #GdkMonitor
+ * @geometry: (out): a #GdkRectangle to be filled wiht the monitor geometry
+ *
+ * Retrieves the size and position of an individual monitor within the
+ * display coordinate space. The returned geometry is in  ”application pixels”,
+ * not in ”device pixels” (see gdk_monitor_get_scale_factor()).
+ *
+ * Since: 3.22
+ */
 void
 gdk_monitor_get_geometry (GdkMonitor   *monitor,
                           GdkRectangle *geometry)
@@ -243,6 +278,27 @@ gdk_monitor_get_geometry (GdkMonitor   *monitor,
   *geometry = monitor->geometry;
 }
 
+/**
+ * gdk_monitor_get_workarea:
+ * @monitor: a #GdkMonitor
+ * @workarea: (out): a #GdkRectangle to be filled with
+ *     the monitor workarea
+ *
+ * Retrieves the size and position of the “work area” on a monitor
+ * within the display coordinate space. The returned geometry is in
+ * ”application pixels”, not in ”device pixels” (see
+ * gdk_monitor_get_scale_factor()).
+ *
+ * The work area should be considered when positioning menus and
+ * similar popups, to avoid placing them below panels, docks or other
+ * desktop components.
+ *
+ * Note that not all backends may have a concept of workarea. This
+ * function will return the monitor geometry if a workarea is not
+ * available, or does not apply.
+ *
+ * Since: 3.22
+ */
 void
 gdk_monitor_get_workarea (GdkMonitor   *monitor,
                           GdkRectangle *workarea)
@@ -256,6 +312,16 @@ gdk_monitor_get_workarea (GdkMonitor   *monitor,
     *workarea = monitor->geometry;
 }
 
+/**
+ * gdk_monitor_get_width_mm:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the width in millimeters of the monitor.
+ *
+ * Returns: the physical width of the monitor
+ *
+ * Since: 3.22
+ */
 int
 gdk_monitor_get_width_mm (GdkMonitor *monitor)
 {
@@ -264,6 +330,15 @@ gdk_monitor_get_width_mm (GdkMonitor *monitor)
   return monitor->width_mm;
 }
 
+/**
+ * gdk_monitor_get_height_mm:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the height in millimeters of the monitor.
+ *
+ * Returns: the physical height of the monitor
+ * Since: 3.22
+ */
 int
 gdk_monitor_get_height_mm (GdkMonitor *monitor)
 {
@@ -272,6 +347,14 @@ gdk_monitor_get_height_mm (GdkMonitor *monitor)
   return monitor->height_mm;
 }
 
+/**
+ * gdk_monitor_get_manufacturer:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the name of the monitor's manufacturer, if available.
+ *
+ * Returns: (transfer none) (nullable): the name of the manufacturer, or %NULL
+ */
 const char *
 gdk_monitor_get_manufacturer (GdkMonitor *monitor)
 {
@@ -280,6 +363,14 @@ gdk_monitor_get_manufacturer (GdkMonitor *monitor)
   return monitor->manufacturer;
 }
 
+/**
+ * gdk_monitor_get_model:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the a string identifying the monitor model, if available.
+ *
+ * Returns: (transfer none) (nullable): the monitor model, or %NULL
+ */
 const char *
 gdk_monitor_get_model (GdkMonitor *monitor)
 {
@@ -288,6 +379,21 @@ gdk_monitor_get_model (GdkMonitor *monitor)
   return monitor->model;
 }
 
+/**
+ * gdk_monitor_get_scale_factor:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the internal scale factor that maps from monitor coordinates
+ * to the actual device pixels. On traditional systems this is 1, but
+ * on very high density outputs this can be a higher value (often 2).
+ *
+ * This can be used if you want to create pixel based data for a
+ * particular monitor, but most of the time you’re drawing to a window
+ * where it is better to use gdk_window_get_scale_factor() instead.
+ *
+ * Returns: the scale factor
+ * Since: 3.22
+ */
 int
 gdk_monitor_get_scale_factor (GdkMonitor *monitor)
 {
@@ -296,6 +402,18 @@ gdk_monitor_get_scale_factor (GdkMonitor *monitor)
   return monitor->scale_factor;
 }
 
+/**
+ * gdk_monitor_get_refresh_rate:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets the refresh rate of the monitor, if available.
+ *
+ * The value is in milli-Hertz, so a refresh rate of 60Hz
+ * is returned as 60000.
+ *
+ * Returns: the refresh rate in milli-Hertz, or 0
+ * Since: 3.22
+ */
 int
 gdk_monitor_get_refresh_rate (GdkMonitor *monitor)
 {
@@ -304,6 +422,16 @@ gdk_monitor_get_refresh_rate (GdkMonitor *monitor)
   return monitor->refresh_rate;
 }
 
+/**
+ * gdk_monitor_get_subpixel_layout:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets information about the layout of red, green and blue
+ * primaries for each pixel in this monitor, if available.
+ *
+ * Returns: the subpixel layout
+ * Since: 3.22
+ */
 GdkSubpixelLayout
 gdk_monitor_get_subpixel_layout (GdkMonitor *monitor)
 {
@@ -312,6 +440,16 @@ gdk_monitor_get_subpixel_layout (GdkMonitor *monitor)
   return monitor->subpixel_layout;
 }
 
+/**
+ * gdk_monitor_is_primary:
+ * @monitor: a #GdkMonitor
+ *
+ * Gets whether this monitor should be considered primary
+ * (see gdk_display_get_primary_monitor()).
+ *
+ * Returns: %TRUE if @monitor is primary
+ * Since: 3.22
+ */
 gboolean
 gdk_monitor_is_primary (GdkMonitor *monitor)
 {

gdk/gdkmonitor.h

@@ -39,6 +39,20 @@ G_BEGIN_DECLS
 typedef struct _GdkMonitor      GdkMonitor;
 typedef struct _GdkMonitorClass GdkMonitorClass;
 
+/**
+ * GdkSubpixelLayout:
+ * @GDK_SUBPIXEL_LAYOUT_UNKNOWN: The layout is not known
+ * @GDK_SUBPIXEL_LAYOUT_NONE: Not organized in this way
+ * @GDK_SUBPIXEL_LAYOUT_HORIZONTAL_RGB: The layout is horizontal, the order is RGB
+ * @GDK_SUBPIXEL_LAYOUT_HORIZONTAL_BGR: The layout is horizontal, the order is BGR
+ * @GDK_SUBPIXEL_LAYOUT_VERTICAL_RGB: The layout is vertical, the order is RGB
+ * @GDK_SUBPIXEL_LAYOUT_VERTICAL_BGR: The layout is vertical, the order is BGR
+ *
+ * This enumeration describes how the red, green and blue components
+ * of physical pixels on an output device are laid out.
+ *
+ * Since: 3.22
+ */
 typedef enum {
   GDK_SUBPIXEL_LAYOUT_UNKNOWN,
   GDK_SUBPIXEL_LAYOUT_NONE,