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