gtk.gdk.Screen
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.Screen

gtk.gdk.Screen — an object representing a physical screen

## Synopsis

    class gtk.gdk.Screen(gobject.GObject):
        def get_default_colormap()
        def set_default_colormap(colormap)
        def get_system_colormap()
        def get_system_visual()
        def get_rgb_colormap()
        def get_rgb_visual()
        def get_root_window()
        def get_display()
        def get_number()
        def get_width()
        def get_height()
        def get_width_mm()
        def get_height_mm()
        def list_visuals()
        def get_toplevel_windows()
        def make_display_name()
        def get_n_monitors()
        def get_monitor_geometry(monitor_num)
        def get_monitor_at_point(x, y)
        def get_monitor_at_window(window)
        def broadcast_client_message(event)
        def get_setting(name)
        def get_rgba_colormap()
        def get_rgba_visual()
        def get_monitor_height_mm(monitor_num)
        def get_monitor_width_mm(monitor_num)
        def get_monitor_plug_name(monitor_num)

    Functions

        def gtk.gdk.screen_width()
        def gtk.gdk.screen_height()
        def gtk.gdk.screen_width_mm()
        def gtk.gdk.screen_height_mm()
        def gtk.gdk.screen_get_default()

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.Screen

## Signal Prototypes

"size-changed" | `def callback(`screen`, `user_param1`, `...`)`

"monitors-changed" | `def callback(`screen`, `user_param1`, `...`)`

## Description

### Note

This object is available in PyGTK 2.2 and above.

`gtk.gdk.Screen` objects are the `PyGTK` representation of a physical screen. It is used throughout `PyGTK` to specify which screen the top level windows are to be displayed on. It is also used to query the screen specification and default settings such as the default colormap (the `get_default_colormap`() method), the screen width (the `get_width`() method), etc.

### Note

a screen may consist of multiple monitors that are merged to form a large screen area.

## Methods

### gtk.gdk.Screen.get_default_colormap

        def get_default_colormap()

Returns : | the default `gtk.gdk.Colormap`.

### Note

This method is available in PyGTK 2.2 and above.

The `get_default_colormap`() method returns the default `gtk.gdk.Colormap` for the screen.

### gtk.gdk.Screen.set_default_colormap

        def set_default_colormap(colormap)

`colormap` : | a `gtk.gdk.Colormap`

### Note

This method is available in PyGTK 2.2 and above.

The `set_default_colormap`() method sets the `gtk.gdk.Colormap` specified by `colormap` as the default colormap for the screen.

### gtk.gdk.Screen.get_system_colormap

        def get_system_colormap()

Returns : | the default colormap for the screen. Since: 2.2

### Note

This method is available in PyGTK 2.2 and above.

The `get_system_colormap`() method returns the system's default colormap for the screen

### gtk.gdk.Screen.get_system_visual

        def get_system_visual()

Returns : | the system `gtk.gdk.Visual`

### Note

This method is available in PyGTK 2.2 and above.

The `get_system_visual`() method returns the system's default `gtk.gdk.Visual` for the screen. This is the visual for the root window of the display.

### gtk.gdk.Screen.get_rgb_colormap

        def get_rgb_colormap()

Returns : | a `gtk.gdk.Colormap`

### Note

This method is available in PyGTK 2.2 and above.

The `get_rgb_colormap`() method returns the preferred colormap for rendering image data on the screen. Not a very useful function; historically, `GDK` could only render RGB image data to one colormap and visual, but in the current version it can render to any colormap and visual. So there's no need to call this function.

### gtk.gdk.Screen.get_rgb_visual

        def get_rgb_visual()

Returns : | a `gtk.gdk.Visual`

### Note

This method is available in PyGTK 2.2 and above.

The `get_rgb_visual`() method returns a "preferred visual" chosen for rendering `RGB` image data on the screen.

### gtk.gdk.Screen.get_root_window

        def get_root_window()

Returns : | the root `gtk.gdk.Window`

### Note

This method is available in PyGTK 2.2 and above.

The `get_root_window`() method returns the root `gtk.gdk.Window` of the screen.

### gtk.gdk.Screen.get_display

        def get_display()

Returns : | the display that the screen belongs to

### Note

This method is available in PyGTK 2.2 and above.

The `get_display`() method returns the `gtk.gdk.Display` that the screen belongs to.

### gtk.gdk.Screen.get_number

        def get_number()

Returns : | the index

### Note

This method is available in PyGTK 2.2 and above.

The `get_number`() method returns the index of the screen among the screens in its display. (See the `get_display()` method)

### gtk.gdk.Screen.get_width

        def get_width()

Returns : | the width of the screen in pixels.

### Note

This method is available in PyGTK 2.2 and above.

The `get_width`() method returns the width of the screen in pixels

### gtk.gdk.Screen.get_height

        def get_height()

Returns : | the height of the screen in pixels.

### Note

This method is available in PyGTK 2.2 and above.

The `get_height`() method returns the height of the screen in pixels

### gtk.gdk.Screen.get_width_mm

        def get_width_mm()

Returns : | the width of the screen in millimeters.

### Note

This method is available in PyGTK 2.2 and above.

The `get_width_mm`() method returns the width of the screen in millimeters. Note that on some X servers this value will not be correct.

### gtk.gdk.Screen.get_height_mm

        def get_height_mm()

Returns : | the height of the screen in pixels. Since: 2.2

### Note

This method is available in PyGTK 2.2 and above.

The `get_height_mm`() method returns the height of the screen in millimeters. Note that on some X servers this value will not be correct.

### gtk.gdk.Screen.list_visuals

        def list_visuals()

Returns : | a list of `gtk.gdk.Visual`

### Note

This method is available in PyGTK 2.2 and above.

The `list_visuals`() method returns a list of the available visuals for the screen. A `gtk.gdk.Visual` describes a hardware image data format. For example, a visual might support 24-bit color, or 8-bit color, and might expect pixels to be in a certain format.

### gtk.gdk.Screen.get_toplevel_windows

        def get_toplevel_windows()

Returns : | a list of the toplevel `gtk.gdk.Window` objects

### Note

This method is available in PyGTK 2.2 and above.

The `get_toplevel_windows`() method returns a list of all toplevel `gtk.gdk.Window` objects known to `PyGTK` on the screen. A toplevel window is a child of the root window (see the `gtk.gdk.get_default_root_window`() function).

### gtk.gdk.Screen.make_display_name

        def make_display_name()

Returns : | a generated nae

### Note

This method is available in PyGTK 2.2 and above.

The `make_display_name`() method determines the name to pass to `gtk.gdk.Display()` to get a `gtk.gdk.Display` with this screen as the default screen.

### gtk.gdk.Screen.get_n_monitors

        def get_n_monitors()

Returns : | the number of monitors that the screen consists of.

### Note

This method is available in PyGTK 2.2 and above.

The `get_n_monitors`() method returns the number of monitors that the screen consists of.

### gtk.gdk.Screen.get_monitor_geometry

        def get_monitor_geometry(monitor_num)

`monitor_num` : | the monitor number.
Returns : | a `gtk.gdk.Rectangle` containing the monitor geometry

### Note

This method is available in PyGTK 2.2 and above.

The `get_monitor_geometry`() method returns a `gtk.gdk.Rectangle` representing the size and position of the individual monitor within the the entire screen area.

Note that the size of the entire screen area can be retrieved via the `get_width()` and `get_height()`. methods.

### gtk.gdk.Screen.get_monitor_at_point

        def get_monitor_at_point(x, y)

`x` : | an x coordinate in the virtual screen.
`y` : | a y coordinate in the virtual screen.
Returns : | the number of the monitor that the point (`x`,`y`) lies in, or a monitor close to (`x`,`y`) if the point is not in any monitor.

### Note

This method is available in PyGTK 2.2 and above.

The `get_monitor_at_point`() method returns the number of the monitor in which the point (`x`,`y`) is located or the closest monitor if not in a monitor.

### gtk.gdk.Screen.get_monitor_at_window

        def get_monitor_at_window(window)

`window` : | a `gtk.gdk.Window`
Returns : | the number of the monitor that most of `window` is located. Since: 2.2

### Note

This method is available in PyGTK 2.2 and above.

The `get_monitor_at_window`() method returns the number of the monitor that most of the `gtk.gdk.Window` specified by `window` is in. If `window` does not intersect any monitors, the closest monitor to the main bounding rectangle of `window` is returned.

### gtk.gdk.Screen.broadcast_client_message

        def broadcast_client_message(event)

`event` : | the `gtk.gdk.Event`.

### Note

This method is available in PyGTK 2.2 and above.

The `broadcast_client_message`() method sends a message to all top level windows. On X11, sends an X ClientMessage event to all toplevel windows on the screen.

Toplevel windows are determined by checking for the `WM_STATE` property, as described in the Inter-Client Communication Conventions Manual (ICCCM). If no windows are found with the `WM_STATE` property set, the message is sent to all children of the root window.

On Windows, broadcasts a message registered with the name `GDK_WIN32_CLIENT_MESSAGE` to all top-level windows. The amount of data is limited to one long, i.e. four bytes.

### gtk.gdk.Screen.get_setting

        def get_setting(name)

`name` : | the name of the setting
Returns : | the value of `setting`

### Note

This method is available in PyGTK 2.2 and above.

The `get_setting`() method returns the value of the desktop-wide setting (specified by `setting`) such as double-click time for the screen.

### gtk.gdk.Screen.get_rgba_colormap

        def get_rgba_colormap()

Returns : | a `gtk.gdk.Colormap` for use with windows with an alpha channel or `None` if the capability is not available.

### Note

This method is available in PyGTK 2.10 and above.

The `get_rgba_colormap`() method returns a colormap to use for creating windows or pixmaps with an alpha channel. The windowing system on which PyGTK is running may not support this capability, in which case `None` will be returned. Even if a non-`None` value is returned, it's possible that the window's alpha channel won't be honored when displaying the window on the screen: in particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display.

### gtk.gdk.Screen.get_rgba_visual

        def get_rgba_visual()

Returns : | a `gtk.gdk.Visual` to use for windows with an alpha channel or `None` if the capability is not available.

### Note

This method is available in PyGTK 2.10 and above.

The `get_rgba_visual`() method returns a visual to use for creating windows or pixmaps with an alpha channel. See the `get_rgba_colormap`() method for caveats.

### gtk.gdk.Screen.get_monitor_height_mm

        def get_monitor_height_mm(monitor_num)

`monitor_num` : | Number of the monitor.
Returns : | The height of the monitor, or -1 if not available.

### Note

This method is available in PyGTK 2.14 and above.

The `get_monitor_height_mm`() method gets the height in millimeters of the specified monitor.

### gtk.gdk.Screen.get_monitor_width_mm

        def get_monitor_width_mm(monitor_num)

`monitor_num` : | Number of the monitor.
Returns : | The width of the monitor, or -1 if not available.

### Note

This method is available in PyGTK 2.14 and above.

The `get_monitor_width_mm`() method gets the width in millimeters of the specified monitor.

### gtk.gdk.Screen.get_monitor_plug_name

        def get_monitor_plug_name(monitor_num)

`monitor_num` : | Number of the monitor.
Returns : | A newly-allocated string containing the name of the monitor, or `None` if the name cannot be determined.

### Note

This method is available in PyGTK 2.14 and above.

The `get_monitor_plug_name`() method returns the output name of the specified monitor. Usually something like VGA, DVI, or TV, not the actual product name of the display device.

## Functions

### gtk.gdk.screen_width

        def gtk.gdk.screen_width()

Returns : | the width of the default screen in pixels.

The `gtk.gdk.screen_width`() function returns the width of the default screen in pixels.

### gtk.gdk.screen_height

        def gtk.gdk.screen_height()

Returns : | the height of the default screen in pixels.

The `gtk.gdk.screen_height`() function returns the height of the default screen in pixels.

### gtk.gdk.screen_width_mm

        def gtk.gdk.screen_width_mm()

Returns : | the width of the default screen in millimeters, though it is not always correct.

The `gtk.gdk.screen_width_mm`() function returns the width of the default screen in millimeters. Note that on many X servers this value will not be correct.

### gtk.gdk.screen_height_mm

        def gtk.gdk.screen_height_mm()

Returns : | the height of the default screen in millimeters, though it is not always correct.

The `gtk.gdk.screen_height_mm`() function returns the height of the default screen in millimeters. Note that on many X servers this value will not be correct.

### gtk.gdk.screen_get_default

        def gtk.gdk.screen_get_default()

Returns : | a `gtk.gdk.Screen`, or `None` if there is no default display.

### Note

This function is available in PyGTK 2.2 and above.

The `gtk.gdk.screen_get_default`() function returns the default `gtk.gdk.Screen` for the default `gtk.gdk.Display`. (See the `gtk.gdk.display_get_default`() function).

## Signals

### The "size-changed" gtk.gdk.Screen Signal

        def callback(screen, user_param1, ...)

`screen` : | the screen that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "size-changed" signal is emitted when the pixel width or height of a screen changes.

### The "monitor-changed" gtk.gdk.Screen Signal

        def callback(screen, user_param1, ...)

`screen` : | the screen that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "monitor-changed" signal is emitted when the number, size or position of the monitors attached to the screen change.

Only for X for now. Future implementations for Win32 and OS X may be a possibility.

Prev | Up | Next
gtk.gdk.Region | Home | gtk.gdk.Visual