Pileus Git - ~andy/gtk/blob - gdk/gdkscreen.c

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