1/*
2 * gdkscreen.c
3 *
4 * Copyright 2001 Sun Microsystems Inc.
5 *
6 * Erwann Chenede <erwann.chenede@sun.com>
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
17 *
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22#include "config.h"
23
24#include "gdkinternals.h"
25#include "gdkscreenprivate.h"
26#include "gdkrectangle.h"
27#include "gdkwindow.h"
28#include "gdkintl.h"
29
30
31/**
32 * SECTION:gdkscreen
33 * @Short_description: Object representing a physical screen
34 * @Title: GdkScreen
35 *
36 * #GdkScreen objects are the GDK representation of the screen on
37 * which windows can be displayed and on which the pointer moves.
38 * X originally identified screens with physical screens, but
39 * nowadays it is more common to have a single #GdkScreen which
40 * combines several physical monitors (see gdk_screen_get_n_monitors()).
41 *
42 * GdkScreen is used throughout GDK and GTK+ to specify which screen
43 * the top level windows are to be displayed on. it is also used to
44 * query the screen specification and default settings such as
45 * the default visual (gdk_screen_get_system_visual()), the dimensions
46 * of the physical monitors (gdk_screen_get_monitor_geometry()), etc.
47 */
48
49
50static void gdk_screen_finalize (GObject *object);
51static void gdk_screen_set_property (GObject *object,
52 guint prop_id,
53 const GValue *value,
54 GParamSpec *pspec);
55static void gdk_screen_get_property (GObject *object,
56 guint prop_id,
57 GValue *value,
58 GParamSpec *pspec);
59
60enum
61{
62 PROP_0,
63 PROP_FONT_OPTIONS,
64 PROP_RESOLUTION
65};
66
67enum
68{
69 SIZE_CHANGED,
70 COMPOSITED_CHANGED,
71 MONITORS_CHANGED,
72 LAST_SIGNAL
73};
74
75static guint signals[LAST_SIGNAL] = { 0 };
76
77G_DEFINE_TYPE (GdkScreen, gdk_screen, G_TYPE_OBJECT)
78
79static void
80gdk_screen_class_init (GdkScreenClass *klass)
81{
82 GObjectClass *object_class = G_OBJECT_CLASS (klass);
83
84 object_class->finalize = gdk_screen_finalize;
85 object_class->set_property = gdk_screen_set_property;
86 object_class->get_property = gdk_screen_get_property;
87
88 g_object_class_install_property (object_class,
89 PROP_FONT_OPTIONS,
90 g_param_spec_pointer ("font-options",
91 P_("Font options"),
92 P_("The default font options for the screen"),
93 G_PARAM_READWRITE|G_PARAM_STATIC_NAME|
94 G_PARAM_STATIC_NICK|G_PARAM_STATIC_BLURB));
95
96 g_object_class_install_property (object_class,
97 PROP_RESOLUTION,
98 g_param_spec_double ("resolution",
99 P_("Font resolution"),
100 P_("The resolution for fonts on the screen"),
101 -1.0,
102 10000.0,
103 -1.0,
104 G_PARAM_READWRITE|G_PARAM_STATIC_NAME|
105 G_PARAM_STATIC_NICK|G_PARAM_STATIC_BLURB));
106
107 /**
108 * GdkScreen::size-changed:
109 * @screen: the object on which the signal is emitted
110 *
111 * The ::size-changed signal is emitted when the pixel width or
112 * height of a screen changes.
113 *
114 * Since: 2.2
115 */
116 signals[SIZE_CHANGED] =
117 g_signal_new (g_intern_static_string ("size-changed"),
118 G_OBJECT_CLASS_TYPE (klass),
119 G_SIGNAL_RUN_LAST,
120 G_STRUCT_OFFSET (GdkScreenClass, size_changed),
121 NULL, NULL,
122 g_cclosure_marshal_VOID__VOID,
123 G_TYPE_NONE,
124 0);
125
126 /**
127 * GdkScreen::composited-changed:
128 * @screen: the object on which the signal is emitted
129 *
130 * The ::composited-changed signal is emitted when the composited
131 * status of the screen changes
132 *
133 * Since: 2.10
134 */
135 signals[COMPOSITED_CHANGED] =
136 g_signal_new (g_intern_static_string ("composited-changed"),
137 G_OBJECT_CLASS_TYPE (klass),
138 G_SIGNAL_RUN_LAST,
139 G_STRUCT_OFFSET (GdkScreenClass, composited_changed),
140 NULL, NULL,
141 g_cclosure_marshal_VOID__VOID,
142 G_TYPE_NONE,
143 0);
144
145 /**
146 * GdkScreen::monitors-changed:
147 * @screen: the object on which the signal is emitted
148 *
149 * The ::monitors-changed signal is emitted when the number, size
150 * or position of the monitors attached to the screen change.
151 *
152 * Only for X11 and OS X for now. A future implementation for Win32
153 * may be a possibility.
154 *
155 * Since: 2.14
156 */
157 signals[MONITORS_CHANGED] =
158 g_signal_new (g_intern_static_string ("monitors-changed"),
159 G_OBJECT_CLASS_TYPE (klass),
160 G_SIGNAL_RUN_LAST,
161 G_STRUCT_OFFSET (GdkScreenClass, monitors_changed),
162 NULL, NULL,
163 g_cclosure_marshal_VOID__VOID,
164 G_TYPE_NONE,
165 0);
166}
167
168static void
169gdk_screen_init (GdkScreen *screen)
170{
171 screen->resolution = -1.;
172}
173
174static void
175gdk_screen_finalize (GObject *object)
176{
177 GdkScreen *screen = GDK_SCREEN (object);
178
179 if (screen->font_options)
180 cairo_font_options_destroy (screen->font_options);
181
182 G_OBJECT_CLASS (gdk_screen_parent_class)->finalize (object);
183}
184
185void
186_gdk_screen_close (GdkScreen *screen)
187{
188 g_return_if_fail (GDK_IS_SCREEN (screen));
189
190 if (!screen->closed)
191 {
192 screen->closed = TRUE;
193 g_object_run_dispose (G_OBJECT (screen));
194 }
195}
196
197static int
198get_monitor_num (GdkMonitor *monitor)
199{
200 GdkDisplay *display;
201 int n_monitors, i;
202
203 display = gdk_monitor_get_display (monitor);
204 n_monitors = gdk_display_get_n_monitors (display);
205 for (i = 0; i < n_monitors; i++)
206 {
207 if (gdk_display_get_monitor (display, i) == monitor)
208 return i;
209 }
210 return -1;
211}
212
213/**
214 * gdk_screen_get_monitor_at_point:
215 * @screen: a #GdkScreen.
216 * @x: the x coordinate in the virtual screen.
217 * @y: the y coordinate in the virtual screen.
218 *
219 * Returns the monitor number in which the point (@x,@y) is located.
220 *
221 * Returns: the monitor number in which the point (@x,@y) lies, or
222 * a monitor close to (@x,@y) if the point is not in any monitor.
223 *
224 * Since: 2.2
225 **/
226gint
227gdk_screen_get_monitor_at_point (GdkScreen *screen,
228 gint x,
229 gint y)
230{
231 GdkDisplay *display;
232 GdkMonitor *monitor;
233
234 g_return_val_if_fail (GDK_IS_SCREEN (screen), -1);
235
236 display = gdk_screen_get_display (screen);
237 monitor = gdk_display_get_monitor_at_point (display, x, y);
238 return get_monitor_num (monitor);
239}
240
241/**
242 * gdk_screen_get_monitor_at_window:
243 * @screen: a #GdkScreen.
244 * @window: a #GdkWindow
245 *
246 * Returns the number of the monitor in which the largest area of the
247 * bounding rectangle of @window resides.
248 *
249 * Returns: the monitor number in which most of @window is located,
250 * or if @window does not intersect any monitors, a monitor,
251 * close to @window.
252 *
253 * Since: 2.2
254 **/
255gint
256gdk_screen_get_monitor_at_window (GdkScreen *screen,
257 GdkWindow *window)
258{
259 GdkDisplay *display;
260 GdkMonitor *monitor;
261
262 g_return_val_if_fail (GDK_IS_SCREEN (screen), -1);
263 g_return_val_if_fail (GDK_IS_WINDOW (window), -1);
264
265 display = gdk_screen_get_display (screen);
266 monitor = gdk_display_get_monitor_at_window (display, window);
267 return get_monitor_num (monitor);
268}
269
270/**
271 * gdk_screen_width:
272 *
273 * Gets the width of the default screen in pixels. The returned
274 * size is in ”application pixels”, not in ”device pixels” (see
275 * gdk_screen_get_monitor_scale_factor()).
276 *
277 * Returns: the width of the default screen in pixels.
278 **/
279gint
280gdk_screen_width (void)
281{
282 return gdk_screen_get_width (gdk_screen_get_default ());
283}
284
285/**
286 * gdk_screen_height:
287 *
288 * Gets the height of the default screen in pixels. The returned
289 * size is in ”application pixels”, not in ”device pixels” (see
290 * gdk_screen_get_monitor_scale_factor()).
291 *
292 * Returns: the height of the default screen in pixels.
293 **/
294gint
295gdk_screen_height (void)
296{
297 return gdk_screen_get_height (gdk_screen_get_default ());
298}
299
300/**
301 * gdk_screen_width_mm:
302 *
303 * Returns the width of the default screen in millimeters.
304 * Note that on many X servers this value will not be correct.
305 *
306 * Returns: the width of the default screen in millimeters,
307 * though it is not always correct.
308 **/
309gint
310gdk_screen_width_mm (void)
311{
312 return gdk_screen_get_width_mm (gdk_screen_get_default ());
313}
314
315/**
316 * gdk_screen_height_mm:
317 *
318 * Returns the height of the default screen in millimeters.
319 * Note that on many X servers this value will not be correct.
320 *
321 * Returns: the height of the default screen in millimeters,
322 * though it is not always correct.
323 **/
324gint
325gdk_screen_height_mm (void)
326{
327 return gdk_screen_get_height_mm (gdk_screen_get_default ());
328}
329
330/**
331 * gdk_screen_set_font_options:
332 * @screen: a #GdkScreen
333 * @options: (allow-none): a #cairo_font_options_t, or %NULL to unset any
334 * previously set default font options.
335 *
336 * Sets the default font options for the screen. These
337 * options will be set on any #PangoContext’s newly created
338 * with gdk_pango_context_get_for_screen(). Changing the
339 * default set of font options does not affect contexts that
340 * have already been created.
341 *
342 * Since: 2.10
343 **/
344void
345gdk_screen_set_font_options (GdkScreen *screen,
346 const cairo_font_options_t *options)
347{
348 g_return_if_fail (GDK_IS_SCREEN (screen));
349
350 if (screen->font_options != options)
351 {
352 if (screen->font_options)
353 cairo_font_options_destroy (screen->font_options);
354
355 if (options)
356 screen->font_options = cairo_font_options_copy (options);
357 else
358 screen->font_options = NULL;
359
360 g_object_notify (G_OBJECT (screen), "font-options");
361 }
362}
363
364/**
365 * gdk_screen_get_font_options:
366 * @screen: a #GdkScreen
367 *
368 * Gets any options previously set with gdk_screen_set_font_options().
369 *
370 * Returns: (nullable): the current font options, or %NULL if no
371 * default font options have been set.
372 *
373 * Since: 2.10
374 **/
375const cairo_font_options_t *
376gdk_screen_get_font_options (GdkScreen *screen)
377{
378 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
379
380 return screen->font_options;
381}
382
383/**
384 * gdk_screen_set_resolution:
385 * @screen: a #GdkScreen
386 * @dpi: the resolution in “dots per inch”. (Physical inches aren’t actually
387 * involved; the terminology is conventional.)
388
389 * Sets the resolution for font handling on the screen. This is a
390 * scale factor between points specified in a #PangoFontDescription
391 * and cairo units. The default value is 96, meaning that a 10 point
392 * font will be 13 units high. (10 * 96. / 72. = 13.3).
393 *
394 * Since: 2.10
395 **/
396void
397gdk_screen_set_resolution (GdkScreen *screen,
398 gdouble dpi)
399{
400 g_return_if_fail (GDK_IS_SCREEN (screen));
401
402 if (dpi < 0)
403 dpi = -1.0;
404
405 screen->resolution_set = TRUE;
406
407 if (screen->resolution != dpi)
408 {
409 screen->resolution = dpi;
410
411 g_object_notify (G_OBJECT (screen), "resolution");
412 }
413}
414
415/* Just like gdk_screen_set_resolution(), but doesn't change
416 * screen->resolution. This is us to allow us to distinguish
417 * resolution changes that the backend picks up from resolution
418 * changes made through the public API - perhaps using
419 * g_object_set(<GtkSetting>, "gtk-xft-dpi", ...);
420 */
421void
422_gdk_screen_set_resolution (GdkScreen *screen,
423 gdouble dpi)
424{
425 g_return_if_fail (GDK_IS_SCREEN (screen));
426
427 if (dpi < 0)
428 dpi = -1.0;
429
430 if (screen->resolution != dpi)
431 {
432 screen->resolution = dpi;
433
434 g_object_notify (G_OBJECT (screen), "resolution");
435 }
436}
437
438/**
439 * gdk_screen_get_resolution:
440 * @screen: a #GdkScreen
441 *
442 * Gets the resolution for font handling on the screen; see
443 * gdk_screen_set_resolution() for full details.
444 *
445 * Returns: the current resolution, or -1 if no resolution
446 * has been set.
447 *
448 * Since: 2.10
449 **/
450gdouble
451gdk_screen_get_resolution (GdkScreen *screen)
452{
453 g_return_val_if_fail (GDK_IS_SCREEN (screen), -1.0);
454
455 return screen->resolution;
456}
457
458static void
459gdk_screen_get_property (GObject *object,
460 guint prop_id,
461 GValue *value,
462 GParamSpec *pspec)
463{
464 GdkScreen *screen = GDK_SCREEN (object);
465
466 switch (prop_id)
467 {
468 case PROP_FONT_OPTIONS:
469 g_value_set_pointer (value, (gpointer) gdk_screen_get_font_options (screen));
470 break;
471 case PROP_RESOLUTION:
472 g_value_set_double (value, gdk_screen_get_resolution (screen));
473 break;
474 default:
475 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
476 break;
477 }
478}
479
480static void
481gdk_screen_set_property (GObject *object,
482 guint prop_id,
483 const GValue *value,
484 GParamSpec *pspec)
485{
486 GdkScreen *screen = GDK_SCREEN (object);
487
488 switch (prop_id)
489 {
490 case PROP_FONT_OPTIONS:
491 gdk_screen_set_font_options (screen, g_value_get_pointer (value));
492 break;
493 case PROP_RESOLUTION:
494 gdk_screen_set_resolution (screen, g_value_get_double (value));
495 break;
496 default:
497 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
498 break;
499 }
500}
501
502/**
503 * gdk_screen_get_display:
504 * @screen: a #GdkScreen
505 *
506 * Gets the display to which the @screen belongs.
507 *
508 * Returns: (transfer none): the display to which @screen belongs
509 *
510 * Since: 2.2
511 **/
512GdkDisplay *
513gdk_screen_get_display (GdkScreen *screen)
514{
515 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
516
517 return GDK_SCREEN_GET_CLASS (screen)->get_display (screen);
518}
519
520
521/**
522 * gdk_screen_get_width:
523 * @screen: a #GdkScreen
524 *
525 * Gets the width of @screen in pixels. The returned size is in
526 * ”application pixels”, not in ”device pixels” (see
527 * gdk_screen_get_monitor_scale_factor()).
528 *
529 * Returns: the width of @screen in pixels.
530 *
531 * Since: 2.2
532 **/
533gint
534gdk_screen_get_width (GdkScreen *screen)
535{
536 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
537
538 return GDK_SCREEN_GET_CLASS (screen)->get_width (screen);
539}
540
541/**
542 * gdk_screen_get_height:
543 * @screen: a #GdkScreen
544 *
545 * Gets the height of @screen in pixels. The returned size is in
546 * ”application pixels”, not in ”device pixels” (see
547 * gdk_screen_get_monitor_scale_factor()).
548 *
549 * Returns: the height of @screen in pixels.
550 *
551 * Since: 2.2
552 **/
553gint
554gdk_screen_get_height (GdkScreen *screen)
555{
556 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
557
558 return GDK_SCREEN_GET_CLASS (screen)->get_height (screen);
559}
560
561/**
562 * gdk_screen_get_width_mm:
563 * @screen: a #GdkScreen
564 *
565 * Gets the width of @screen in millimeters.
566 *
567 * Note that this value is somewhat ill-defined when the screen
568 * has multiple monitors of different resolution. It is recommended
569 * to use the monitor dimensions instead.
570 *
571 * Returns: the width of @screen in millimeters.
572 *
573 * Since: 2.2
574 **/
575gint
576gdk_screen_get_width_mm (GdkScreen *screen)
577{
578 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
579
580 return GDK_SCREEN_GET_CLASS (screen)->get_width_mm (screen);
581}
582
583/**
584 * gdk_screen_get_height_mm:
585 * @screen: a #GdkScreen
586 *
587 * Returns the height of @screen in millimeters.
588 *
589 * Note that this value is somewhat ill-defined when the screen
590 * has multiple monitors of different resolution. It is recommended
591 * to use the monitor dimensions instead.
592 *
593 * Returns: the heigth of @screen in millimeters.
594 *
595 * Since: 2.2
596 **/
597gint
598gdk_screen_get_height_mm (GdkScreen *screen)
599{
600 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
601
602 return GDK_SCREEN_GET_CLASS (screen)->get_height_mm (screen);
603}
604
605/**
606 * gdk_screen_get_number:
607 * @screen: a #GdkScreen
608 *
609 * Gets the index of @screen among the screens in the display
610 * to which it belongs. (See gdk_screen_get_display())
611 *
612 * Returns: the index
613 *
614 * Since: 2.2
615 **/
616gint
617gdk_screen_get_number (GdkScreen *screen)
618{
619 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
620
621 return GDK_SCREEN_GET_CLASS (screen)->get_number (screen);
622}
623
624/**
625 * gdk_screen_get_root_window:
626 * @screen: a #GdkScreen
627 *
628 * Gets the root window of @screen.
629 *
630 * Returns: (transfer none): the root window
631 *
632 * Since: 2.2
633 **/
634GdkWindow *
635gdk_screen_get_root_window (GdkScreen *screen)
636{
637 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
638
639 return GDK_SCREEN_GET_CLASS (screen)->get_root_window (screen);
640}
641
642static GdkMonitor *
643get_monitor (GdkScreen *screen,
644 gint n)
645{
646 GdkDisplay *display;
647
648 display = gdk_screen_get_display (screen);
649 return gdk_display_get_monitor (display, n);
650}
651
652/**
653 * gdk_screen_get_n_monitors:
654 * @screen: a #GdkScreen
655 *
656 * Returns the number of monitors which @screen consists of.
657 *
658 * Returns: number of monitors which @screen consists of
659 *
660 * Since: 2.2
661 */
662gint
663gdk_screen_get_n_monitors (GdkScreen *screen)
664{
665 GdkDisplay *display;
666
667 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
668
669 display = gdk_screen_get_display (screen);
670 return gdk_display_get_n_monitors (display);
671}
672
673/**
674 * gdk_screen_get_primary_monitor:
675 * @screen: a #GdkScreen.
676 *
677 * Gets the primary monitor for @screen. The primary monitor
678 * is considered the monitor where the “main desktop” lives.
679 * While normal application windows typically allow the window
680 * manager to place the windows, specialized desktop applications
681 * such as panels should place themselves on the primary monitor.
682 *
683 * If no primary monitor is configured by the user, the return value
684 * will be 0, defaulting to the first monitor.
685 *
686 * Returns: An integer index for the primary monitor, or 0 if none is configured.
687 *
688 * Since: 2.20
689 */
690gint
691gdk_screen_get_primary_monitor (GdkScreen *screen)
692{
693 GdkDisplay *display;
694 GdkMonitor *primary;
695
696 g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
697
698 display = gdk_screen_get_display (screen);
699 primary = gdk_display_get_primary_monitor (display);
700 if (primary)
701 return get_monitor_num (primary);
702
703 return 0;
704}
705
706/**
707 * gdk_screen_get_monitor_width_mm:
708 * @screen: a #GdkScreen
709 * @monitor_num: number of the monitor, between 0 and gdk_screen_get_n_monitors (screen)
710 *
711 * Gets the width in millimeters of the specified monitor, if available.
712 *
713 * Returns: the width of the monitor, or -1 if not available
714 *
715 * Since: 2.14
716 */
717gint
718gdk_screen_get_monitor_width_mm (GdkScreen *screen,
719 gint monitor_num)
720{
721 GdkMonitor *monitor;
722
723 g_return_val_if_fail (GDK_IS_SCREEN (screen), -1);
724
725 monitor = get_monitor (screen, monitor_num);
726
727 g_return_val_if_fail (monitor != NULL, -1);
728
729 return gdk_monitor_get_width_mm (monitor);
730}
731
732/**
733 * gdk_screen_get_monitor_height_mm:
734 * @screen: a #GdkScreen
735 * @monitor_num: number of the monitor, between 0 and gdk_screen_get_n_monitors (screen)
736 *
737 * Gets the height in millimeters of the specified monitor.
738 *
739 * Returns: the height of the monitor, or -1 if not available
740 *
741 * Since: 2.14
742 */
743gint
744gdk_screen_get_monitor_height_mm (GdkScreen *screen,
745 gint monitor_num)
746{
747 GdkMonitor *monitor;
748
749 g_return_val_if_fail (GDK_IS_SCREEN (screen), -1);
750
751 monitor = get_monitor (screen, monitor_num);
752
753 g_return_val_if_fail (monitor != NULL, -1);
754
755 return gdk_monitor_get_height_mm (monitor);
756}
757
758/**
759 * gdk_screen_get_monitor_plug_name:
760 * @screen: a #GdkScreen
761 * @monitor_num: number of the monitor, between 0 and gdk_screen_get_n_monitors (screen)
762 *
763 * Returns the output name of the specified monitor.
764 * Usually something like VGA, DVI, or TV, not the actual
765 * product name of the display device.
766 *
767 * Returns: (nullable): a newly-allocated string containing the name
768 * of the monitor, or %NULL if the name cannot be determined
769 *
770 * Since: 2.14
771 */
772gchar *
773gdk_screen_get_monitor_plug_name (GdkScreen *screen,
774 gint monitor_num)
775{
776 GdkMonitor *monitor;
777
778 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
779
780 monitor = get_monitor (screen, monitor_num);
781
782 g_return_val_if_fail (monitor != NULL, NULL);
783
784 return g_strdup (gdk_monitor_get_model (monitor));
785}
786
787/**
788 * gdk_screen_get_monitor_geometry:
789 * @screen: a #GdkScreen
790 * @monitor_num: the monitor number
791 * @dest: (out) (allow-none): a #GdkRectangle to be filled with
792 * the monitor geometry
793 *
794 * Retrieves the #GdkRectangle representing the size and position of
795 * the individual monitor within the entire screen area. The returned
796 * geometry is in ”application pixels”, not in ”device pixels” (see
797 * gdk_screen_get_monitor_scale_factor()).
798 *
799 * Monitor numbers start at 0. To obtain the number of monitors of
800 * @screen, use gdk_screen_get_n_monitors().
801 *
802 * Note that the size of the entire screen area can be retrieved via
803 * gdk_screen_get_width() and gdk_screen_get_height().
804 *
805 * Since: 2.2
806 */
807void
808gdk_screen_get_monitor_geometry (GdkScreen *screen,
809 gint monitor_num,
810 GdkRectangle *dest)
811{
812 GdkMonitor *monitor;
813
814 g_return_if_fail (GDK_IS_SCREEN (screen));
815
816 monitor = get_monitor (screen, monitor_num);
817
818 g_return_if_fail (monitor != NULL);
819
820 gdk_monitor_get_geometry (monitor, dest);
821}
822
823/**
824 * gdk_screen_get_monitor_workarea:
825 * @screen: a #GdkScreen
826 * @monitor_num: the monitor number
827 * @dest: (out) (allow-none): a #GdkRectangle to be filled with
828 * the monitor workarea
829 *
830 * Retrieves the #GdkRectangle representing the size and position of
831 * the “work area” on a monitor within the entire screen area. The returned
832 * geometry is in ”application pixels”, not in ”device pixels” (see
833 * gdk_screen_get_monitor_scale_factor()).
834 *
835 * The work area should be considered when positioning menus and
836 * similar popups, to avoid placing them below panels, docks or other
837 * desktop components.
838 *
839 * Note that not all backends may have a concept of workarea. This
840 * function will return the monitor geometry if a workarea is not
841 * available, or does not apply.
842 *
843 * Monitor numbers start at 0. To obtain the number of monitors of
844 * @screen, use gdk_screen_get_n_monitors().
845 *
846 * Since: 3.4
847 */
848void
849gdk_screen_get_monitor_workarea (GdkScreen *screen,
850 gint monitor_num,
851 GdkRectangle *dest)
852{
853 GdkMonitor *monitor;
854
855 g_return_if_fail (GDK_IS_SCREEN (screen));
856
857 monitor = get_monitor (screen, monitor_num);
858
859 g_return_if_fail (monitor != NULL);
860
861 /* FIXME */
862 gdk_monitor_get_geometry (monitor, dest);
863}
864
865/**
866 * gdk_screen_list_visuals:
867 * @screen: the relevant #GdkScreen.
868 *
869 * Lists the available visuals for the specified @screen.
870 * A visual describes a hardware image data format.
871 * For example, a visual might support 24-bit color, or 8-bit color,
872 * and might expect pixels to be in a certain format.
873 *
874 * Call g_list_free() on the return value when you’re finished with it.
875 *
876 * Returns: (transfer container) (element-type GdkVisual):
877 * a list of visuals; the list must be freed, but not its contents
878 *
879 * Since: 2.2
880 **/
881GList *
882gdk_screen_list_visuals (GdkScreen *screen)
883{
884 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
885
886 return GDK_SCREEN_GET_CLASS (screen)->list_visuals (screen);
887}
888
889/**
890 * gdk_screen_get_system_visual:
891 * @screen: a #GdkScreen.
892 *
893 * Get the system’s default visual for @screen.
894 * This is the visual for the root window of the display.
895 * The return value should not be freed.
896 *
897 * Returns: (transfer none): the system visual
898 *
899 * Since: 2.2
900 **/
901GdkVisual *
902gdk_screen_get_system_visual (GdkScreen * screen)
903{
904 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
905
906 return GDK_SCREEN_GET_CLASS (screen)->get_system_visual (screen);
907}
908
909/**
910 * gdk_screen_get_rgba_visual:
911 * @screen: a #GdkScreen
912 *
913 * Gets a visual to use for creating windows with an alpha channel.
914 * The windowing system on which GTK+ is running
915 * may not support this capability, in which case %NULL will
916 * be returned. Even if a non-%NULL value is returned, its
917 * possible that the window’s alpha channel won’t be honored
918 * when displaying the window on the screen: in particular, for
919 * X an appropriate windowing manager and compositing manager
920 * must be running to provide appropriate display.
921 *
922 * This functionality is not implemented in the Windows backend.
923 *
924 * For setting an overall opacity for a top-level window, see
925 * gdk_window_set_opacity().
926 *
927 * Returns: (nullable) (transfer none): a visual to use for windows
928 * with an alpha channel or %NULL if the capability is not
929 * available.
930 *
931 * Since: 2.8
932 **/
933GdkVisual *
934gdk_screen_get_rgba_visual (GdkScreen *screen)
935{
936 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
937
938 return GDK_SCREEN_GET_CLASS (screen)->get_rgba_visual (screen);
939}
940
941/**
942 * gdk_screen_is_composited:
943 * @screen: a #GdkScreen
944 *
945 * Returns whether windows with an RGBA visual can reasonably
946 * be expected to have their alpha channel drawn correctly on
947 * the screen.
948 *
949 * On X11 this function returns whether a compositing manager is
950 * compositing @screen.
951 *
952 * Returns: Whether windows with RGBA visuals can reasonably be
953 * expected to have their alpha channels drawn correctly on the screen.
954 *
955 * Since: 2.10
956 **/
957gboolean
958gdk_screen_is_composited (GdkScreen *screen)
959{
960 g_return_val_if_fail (GDK_IS_SCREEN (screen), FALSE);
961
962 return GDK_SCREEN_GET_CLASS (screen)->is_composited (screen);
963}
964
965/**
966 * gdk_screen_make_display_name:
967 * @screen: a #GdkScreen
968 *
969 * Determines the name to pass to gdk_display_open() to get
970 * a #GdkDisplay with this screen as the default screen.
971 *
972 * Returns: a newly allocated string, free with g_free()
973 *
974 * Since: 2.2
975 **/
976gchar *
977gdk_screen_make_display_name (GdkScreen *screen)
978{
979 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
980
981 return GDK_SCREEN_GET_CLASS (screen)->make_display_name (screen);
982}
983
984/**
985 * gdk_screen_get_active_window:
986 * @screen: a #GdkScreen
987 *
988 * Returns the screen’s currently active window.
989 *
990 * On X11, this is done by inspecting the _NET_ACTIVE_WINDOW property
991 * on the root window, as described in the
992 * [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec).
993 * If there is no currently currently active
994 * window, or the window manager does not support the
995 * _NET_ACTIVE_WINDOW hint, this function returns %NULL.
996 *
997 * On other platforms, this function may return %NULL, depending on whether
998 * it is implementable on that platform.
999 *
1000 * The returned window should be unrefed using g_object_unref() when
1001 * no longer needed.
1002 *
1003 * Returns: (nullable) (transfer full): the currently active window,
1004 * or %NULL.
1005 *
1006 * Since: 2.10
1007 **/
1008GdkWindow *
1009gdk_screen_get_active_window (GdkScreen *screen)
1010{
1011 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
1012
1013 return GDK_SCREEN_GET_CLASS (screen)->get_active_window (screen);
1014}
1015
1016/**
1017 * gdk_screen_get_window_stack:
1018 * @screen: a #GdkScreen
1019 *
1020 * Returns a #GList of #GdkWindows representing the current
1021 * window stack.
1022 *
1023 * On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING
1024 * property on the root window, as described in the
1025 * [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec).
1026 * If the window manager does not support the
1027 * _NET_CLIENT_LIST_STACKING hint, this function returns %NULL.
1028 *
1029 * On other platforms, this function may return %NULL, depending on whether
1030 * it is implementable on that platform.
1031 *
1032 * The returned list is newly allocated and owns references to the
1033 * windows it contains, so it should be freed using g_list_free() and
1034 * its windows unrefed using g_object_unref() when no longer needed.
1035 *
1036 * Returns: (nullable) (transfer full) (element-type GdkWindow): a
1037 * list of #GdkWindows for the current window stack, or %NULL.
1038 *
1039 * Since: 2.10
1040 **/
1041GList *
1042gdk_screen_get_window_stack (GdkScreen *screen)
1043{
1044 g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
1045
1046 return GDK_SCREEN_GET_CLASS (screen)->get_window_stack (screen);
1047}
1048
1049/**
1050 * gdk_screen_get_setting:
1051 * @screen: the #GdkScreen where the setting is located
1052 * @name: the name of the setting
1053 * @value: location to store the value of the setting
1054 *
1055 * Retrieves a desktop-wide setting such as double-click time
1056 * for the #GdkScreen @screen.
1057 *
1058 * FIXME needs a list of valid settings here, or a link to
1059 * more information.
1060 *
1061 * Returns: %TRUE if the setting existed and a value was stored
1062 * in @value, %FALSE otherwise.
1063 *
1064 * Since: 2.2
1065 **/
1066gboolean
1067gdk_screen_get_setting (GdkScreen *screen,
1068 const gchar *name,
1069 GValue *value)
1070{
1071 g_return_val_if_fail (GDK_IS_SCREEN (screen), FALSE);
1072 g_return_val_if_fail (name != NULL, FALSE);
1073 g_return_val_if_fail (value != NULL, FALSE);
1074
1075 return GDK_SCREEN_GET_CLASS (screen)->get_setting (screen, name, value);
1076}
1077
1078/**
1079 * gdk_screen_get_monitor_scale_factor:
1080 * @screen: screen to get scale factor for
1081 * @monitor_num: number of the monitor, between 0 and gdk_screen_get_n_monitors (screen)
1082 *
1083 * Returns the internal scale factor that maps from monitor coordinates
1084 * to the actual device pixels. On traditional systems this is 1, but
1085 * on very high density outputs this can be a higher value (often 2).
1086 *
1087 * This can be used if you want to create pixel based data for a
1088 * particular monitor, but most of the time you’re drawing to a window
1089 * where it is better to use gdk_window_get_scale_factor() instead.
1090 *
1091 * Since: 3.10
1092 * Returns: the scale factor
1093 */
1094gint
1095gdk_screen_get_monitor_scale_factor (GdkScreen *screen,
1096 gint monitor_num)
1097{
1098 GdkScreenClass *screen_class;
1099
1100 g_return_val_if_fail (GDK_IS_SCREEN (screen), 1);
1101 g_return_val_if_fail (monitor_num >= 0, 1);
1102 g_return_val_if_fail (monitor_num < gdk_screen_get_n_monitors (screen), 1);
1103
1104 screen_class = GDK_SCREEN_GET_CLASS (screen);
1105
1106 if (screen_class->get_monitor_scale_factor)
1107 return screen_class->get_monitor_scale_factor (screen, monitor_num);
1108
1109 return 1;
1110}
1111