diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml index fdd36a4444..d58a6cc31b 100644 --- a/docs/reference/gdk/gdk-docs.sgml +++ b/docs/reference/gdk/gdk-docs.sgml @@ -23,6 +23,7 @@ + diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt index 48fcd3c301..f06c7b8d83 100644 --- a/docs/reference/gdk/gdk3-sections.txt +++ b/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 GDK_DISPLAY @@ -1366,3 +1370,26 @@ GDK_GL_ERROR GDK_TYPE_GL_ERROR GDK_TYPE_GL_PROFILE + +
+gdkmonitor +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 + + +gdk_monitor_get_type +GdkMonitorClass +GDK_TYPE_MONITOR +GDK_MONITOR +GDK_IS_MONITOR +
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c index 01f4326e74..f4288aa1f3 100644 --- a/gdk/gdkdisplay.c +++ b/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) diff --git a/gdk/gdkmonitor.c b/gdk/gdkmonitor.c index fa92515144..deddb527ea 100644 --- a/gdk/gdkmonitor.c +++ b/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) { diff --git a/gdk/gdkmonitor.h b/gdk/gdkmonitor.h index 37f7d19935..82b2d18194 100644 --- a/gdk/gdkmonitor.h +++ b/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,