Next: , Previous: GdkDisplayManager, Up: Top


5 GdkScreen

Object representing a physical screen

5.1 Overview

<gdk-screen> objects are the GDK representation of a physical screen. It is used throughout GDK and GTK+ 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 (gdk-screen-get-default-colormap), the screen width (gdk-screen-get-width), etc.

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

5.2 Usage

— Class: <gdk-screen>

Derives from <gobject>.

This class defines the following slots:

font-options
The default font options for the screen
resolution
The resolution for fonts on the screen
— Signal on <gdk-screen>: size-changed

The ::size_changed signal is emitted when the pixel width or height of a screen changes.

Since 2.2

— Signal on <gdk-screen>: composited-changed

The ::composited_changed signal is emitted when the composited status of the screen changes

Since 2.10

— Function: gdk-screen-get-default ⇒  (ret <gdk-screen>)

Gets the default screen for the default display. (See gdk-display-get-default).

ret
a <gdk-screen>, or ‘#f’ if there is no default display.

Since 2.2

— Function: gdk-screen-get-default-colormap (self <gdk-screen>) ⇒  (ret <gdk-colormap>)
— Method: get-default-colormap

Gets the default colormap for screen.

screen
a <gdk-screen>
ret
the default <gdk-colormap>.

Since 2.2

— Function: gdk-screen-set-default-colormap (self <gdk-screen>) (colormap <gdk-colormap>)
— Method: set-default-colormap

Sets the default colormap for screen.

screen
a <gdk-screen>
colormap
a <gdk-colormap>

Since 2.2

— Function: gdk-screen-get-system-colormap (self <gdk-screen>) ⇒  (ret <gdk-colormap>)
— Method: get-system-colormap

Gets the system's default colormap for screen

screen
a <gdk-screen>
ret
the default colormap for screen.

Since 2.2

— Function: gdk-screen-get-system-visual (self <gdk-screen>) ⇒  (ret <gdk-visual>)
— Method: get-system-visual

Get the system's default visual for screen. This is the visual for the root window of the display. The return value should not be freed.

screen
a <gdk-screen>.
ret
the system visual

Since 2.2

— Function: gdk-screen-get-rgb-colormap (self <gdk-screen>) ⇒  (ret <gdk-colormap>)
— Method: get-rgb-colormap

Gets the preferred colormap for rendering image data on 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.

screen
a <gdk-screen>.
ret
the preferred colormap

Since 2.2

— Function: gdk-screen-get-rgb-visual (self <gdk-screen>) ⇒  (ret <gdk-visual>)
— Method: get-rgb-visual

Gets a "preferred visual" chosen by GdkRGB for rendering image data on screen. In previous versions of GDK, this was the only visual GdkRGB could use for rendering. In current versions, it's simply the visual GdkRGB would have chosen as the optimal one in those previous versions. GdkRGB can now render to drawables with any visual.

screen
a <gdk-screen>
ret
The <gdk-visual> chosen by GdkRGB.

Since 2.2

— Function: gdk-screen-get-rgba-colormap (self <gdk-screen>) ⇒  (ret <gdk-colormap>)
— Method: get-rgba-colormap

Gets a colormap to use for creating windows or pixmaps with an alpha channel. The windowing system on which GTK+ is running may not support this capability, in which case ‘#f’ will be returned. Even if a non-‘#f’ value is returned, its 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.

screen
a <gdk-screen>.
ret
a colormap to use for windows with an alpha channel or ‘#f’ if the capability is not available.

Since 2.8

— Function: gdk-screen-get-rgba-visual (self <gdk-screen>) ⇒  (ret <gdk-visual>)
— Method: get-rgba-visual

Gets a visual to use for creating windows or pixmaps with an alpha channel. See the docs for gdk-screen-get-rgba-colormap for caveats.

screen
a <gdk-screen>
ret
a visual to use for windows with an alpha channel or ‘#f’ if the capability is not available.

Since 2.8

— Function: gdk-screen-is-composited (self <gdk-screen>) ⇒  (ret bool)
— Method: is-composited

Returns whether windows with an RGBA visual can reasonably be expected to have their alpha channel drawn correctly on the screen.

On X11 this function returns whether a compositing manager is compositing screen.

screen
a <gdk-screen>
ret
Whether windows with RGBA visuals can reasonably be expected to have their alpha channels drawn correctly on the screen.

Since 2.10

— Function: gdk-screen-get-root-window (self <gdk-screen>) ⇒  (ret <gdk-window>)
— Method: get-root-window

Gets the root window of screen.

screen
a <gdk-screen>
ret
the root window

Since 2.2

— Function: gdk-screen-get-display (self <gdk-screen>) ⇒  (ret <gdk-display>)
— Method: get-display

Gets the display to which the screen belongs.

screen
a <gdk-screen>
ret
the display to which screen belongs

Since 2.2

— Function: gdk-screen-get-number (self <gdk-screen>) ⇒  (ret int)
— Method: get-number

Gets the index of screen among the screens in the display to which it belongs. (See gdk-screen-get-display)

screen
a <gdk-screen>
ret
the index

Since 2.2

— Function: gdk-screen-get-width (self <gdk-screen>) ⇒  (ret int)
— Method: get-width

Gets the width of screen in pixels

screen
a <gdk-screen>
ret
the width of screen in pixels.

Since 2.2

— Function: gdk-screen-get-height (self <gdk-screen>) ⇒  (ret int)
— Method: get-height

Gets the height of screen in pixels

screen
a <gdk-screen>
ret
the height of screen in pixels.

Since 2.2

— Function: gdk-screen-get-width-mm (self <gdk-screen>) ⇒  (ret int)
— Method: get-width-mm

Gets the width of screen in millimeters. Note that on some X servers this value will not be correct.

screen
a <gdk-screen>
ret
the width of screen in millimeters.

Since 2.2

— Function: gdk-screen-get-height-mm (self <gdk-screen>) ⇒  (ret int)
— Method: get-height-mm

Returns the height of screen in millimeters. Note that on some X servers this value will not be correct.

screen
a <gdk-screen>
ret
the heigth of screen in millimeters.

Since 2.2

— Function: gdk-screen-list-visuals (self <gdk-screen>) ⇒  (ret glist-of)
— Method: list-visuals

Lists the available visuals for the specified screen. A 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.

Call g-list-free on the return value when you're finished with it.

screen
the relevant <gdk-screen>.
ret
a list of visuals; the list must be freed, but not its contents

Since 2.2

— Function: gdk-screen-get-toplevel-windows (self <gdk-screen>) ⇒  (ret glist-of)
— Method: get-toplevel-windows

Obtains a list of all toplevel windows known to GDK on the screen screen. A toplevel window is a child of the root window (see gdk-get-default-root-window).

The returned list should be freed with g-list-free, but its elements need not be freed.

screen
The <gdk-screen> where the toplevels are located.
ret
list of toplevel windows, free with g-list-free

Since 2.2

— Function: gdk-screen-make-display-name (self <gdk-screen>) ⇒  (ret mchars)
— Method: make-display-name

Determines the name to pass to gdk-display-open to get a <gdk-display> with this screen as the default screen.

screen
a <gdk-screen>
ret
a newly allocated string, free with g-free

Since 2.2

— Function: gdk-screen-get-n-monitors (self <gdk-screen>) ⇒  (ret int)
— Method: get-n-monitors

Returns the number of monitors which screen consists of.

screen
a <gdk-screen>.
ret
number of monitors which screen consists of.

Since 2.2

— Function: gdk-screen-get-monitor-geometry (self <gdk-screen>) (monitor_num int) (dest <gdk-rectangle>)
— Method: get-monitor-geometry

Retrieves the <gdk-rectangle> representing the size and position of the individual monitor within the entire screen area.

Note that the size of the entire screen area can be retrieved via gdk-screen-get-width and gdk-screen-get-height.

screen
a <gdk-screen>.
monitor-num
the monitor number.
dest
a <gdk-rectangle> to be filled with the monitor geometry

Since 2.2

— Function: gdk-screen-get-monitor-at-point (self <gdk-screen>) (int) (int) ⇒  (ret int)
— Method: get-monitor-at-point

Returns the monitor number in which the point (x,y) is located.

screen
a <gdk-screen>.
x
the x coordinate in the virtual screen.
y
the y coordinate in the virtual screen.
ret
the monitor number in which the point (x,y) lies, or a monitor close to (x,y) if the point is not in any monitor.

Since 2.2

— Function: gdk-screen-get-monitor-at-window (self <gdk-screen>) (window <gdk-window>) ⇒  (ret int)
— Method: get-monitor-at-window

Returns the number of the monitor in which the largest area of the bounding rectangle of window resides.

screen
a <gdk-screen>.
window
a <gdk-window>
ret
the monitor number in which most of window is located, or if window does not intersect any monitors, a monitor, close to window.

Since 2.2

— Function: gdk-screen-broadcast-client-message (self <gdk-screen>) (event <gdk-event>)
— Method: broadcast-client-message

On X11, sends an X ClientMessage event to all toplevel windows on 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.

screen
the <gdk-screen> where the event will be broadcasted.
event
the <gdk-event>.

Since 2.2

— Function: gdk-screen-get-setting (self <gdk-screen>) (name mchars) (value <gvalue>) ⇒  (ret bool)
— Method: get-setting

Retrieves a desktop-wide setting such as double-click time for the <gdk-screen>screen.

FIXME needs a list of valid settings here, or a link to more information.

screen
the <gdk-screen> where the setting is located
name
the name of the setting
value
location to store the value of the setting
ret
#t’ if the setting existed and a value was stored in value, ‘#f’ otherwise.

Since 2.2

— Function: gdk-screen-get-font-options (self <gdk-screen>) ⇒  (ret cairo-font-options-t)
— Method: get-font-options

Gets any options previously set with gdk-screen-set-font-options.

screen
a <gdk-screen>
ret
the current font options, or ‘#f’ if no default font options have been set.

Since 2.10

— Function: gdk-screen-set-font-options (self <gdk-screen>) (options cairo-font-options-t)
— Method: set-font-options

Sets the default font options for the screen. These options will be set on any <pango-context>'s newly created with gdk-pango-context-get-for-screen. Changing the default set of font options does not affect contexts that have already been created.

screen
a <gdk-screen>
options
a <cairo-font-options-t>, or ‘#f’ to unset any previously set default font options.

Since 2.10

— Function: gdk-screen-get-resolution (self <gdk-screen>) ⇒  (ret double)
— Method: get-resolution

Gets the resolution for font handling on the screen; see gdk-screen-set-resolution for full details.

screen
a <gdk-screen>
ret
the current resolution, or -1 if no resolution has been set.

Since 2.10

— Function: gdk-screen-set-resolution (self <gdk-screen>) (dpi double)
— Method: set-resolution

Sets the resolution for font handling on the screen. This is a scale factor between points specified in a <pango-font-description> and cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3).

screen
a <gdk-screen>
dpi
the resolution in "dots per inch". (Physical inches aren't actually involved; the terminology is conventional.)

Since 2.10

— Function: gdk-screen-get-active-window (self <gdk-screen>) ⇒  (ret <gdk-window>)
— Method: get-active-window

Returns the screen's currently active window.

On X11, this is done by inspecting the _NET_ACTIVE_WINDOW property on the root window, as described in the Extended Window Manager Hints. If there is no currently currently active window, or the window manager does not support the _NET_ACTIVE_WINDOW hint, this function returns ‘#f’.

On other platforms, this function may return ‘#f’, depending on whether it is implementable on that platform.

The returned window should be unrefed using g-object-unref when no longer needed.

screen
a <gdk-screen>
ret
the currently active window, or ‘#f’.

Since 2.10

— Function: gdk-screen-get-window-stack (self <gdk-screen>) ⇒  (ret glist-of)
— Method: get-window-stack

Returns a <g-list> of <gdk-window>s representing the current window stack.

On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING property on the root window, as described in the Extended Window Manager Hints. If the window manager does not support the _NET_CLIENT_LIST_STACKING hint, this function returns ‘#f’.

On other platforms, this function may return ‘#f’, depending on whether it is implementable on that platform.

The returned list is newly allocated and owns references to the windows it contains, so it should be freed using g-list-free and its windows unrefed using g-object-unref when no longer needed.

screen
a <gdk-screen>
ret
a list of <gdk-window>s for the current window stack, or ‘#f’.

Since 2.10

— Function: gdk-spawn-command-line-on-screen (screen <gdk-screen>) (command_line mchars) ⇒  (ret bool)

Like g-spawn-command-line-async, except the child process is spawned in such an environment that on calling gdk-display-open it would be returned a <gdk-display> with screen as the default screen.

This is useful for applications which wish to launch an application on a specific screen.

screen
a <gdk-screen>
command-line
a command line
error
return location for errors
ret
#t’ on success, ‘#f’ if error is set.

Since 2.4