WnckScreen: Libwnck Reference Manual

## WnckScreen WnckScreen — an object representing a screen. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

WnckScreen * | wnck_screen_get_default ()
WnckScreen * | wnck_screen_get ()
WnckScreen * | wnck_screen_get_for_root ()
int | wnck_screen_get_number ()
int | wnck_screen_get_width ()
int | wnck_screen_get_height ()
void | wnck_screen_force_update ()
const char * | wnck_screen_get_window_manager_name ()
gboolean | wnck_screen_net_wm_supports ()
WnckWindow * | wnck_screen_get_active_window ()
WnckWindow * | wnck_screen_get_previously_active_window ()
GList * | wnck_screen_get_windows ()
GList * | wnck_screen_get_windows_stacked ()
WnckWorkspace * | wnck_screen_get_active_workspace ()
GList * | wnck_screen_get_workspaces ()
WnckWorkspace * | wnck_screen_get_workspace ()
int | wnck_screen_get_workspace_count ()
void | wnck_screen_change_workspace_count ()
int | wnck_screen_try_set_workspace_layout ()
void | wnck_screen_release_workspace_layout ()
void | wnck_screen_calc_workspace_layout ()
void | wnck_screen_free_workspace_layout ()
void | wnck_screen_move_viewport ()
gulong | wnck_screen_get_background_pixmap ()
gboolean | wnck_screen_get_showing_desktop ()
void | wnck_screen_toggle_showing_desktop ()

## Signals

void | active-window-changed | Run Last
void | active-workspace-changed | Run Last
void | application-closed | Run Last
void | application-opened | Run Last
void | background-changed | Run Last
void | class-group-closed | Run Last
void | class-group-opened | Run Last
void | showing-desktop-changed | Run Last
void | viewports-changed | Run Last
void | window-closed | Run Last
void | window-manager-changed | Run Last
void | window-opened | Run Last
void | window-stacking-changed | Run Last
void | workspace-created | Run Last
void | workspace-destroyed | Run Last

## Types and Values

struct | WnckScreen
struct | WnckWorkspaceLayout

## Object Hierarchy

        GObject
        ╰── WnckScreen

## Includes

    #include <libwnck/libwnck.h>

## Description

The WnckScreen represents a physical screen. A screen may consist of multiple monitors which are merged to form a large screen area. The WnckScreen is at the bottom of the libwnck stack of objects: WnckWorkspace objects exist a WnckScreen and WnckWindow objects are displayed on a WnckWorkspace.

The WnckScreen corresponds to the notion of

`GdkScreen` in GDK.

The WnckScreen objects are always owned by libwnck and must not be referenced or unreferenced.

## Functions

### wnck_screen_get_default ()

    WnckScreen *
    wnck_screen_get_default (void);

Gets the default WnckScreen on the default display.

#### Returns

the default WnckScreen. The returned WnckScreen is owned by libwnck and must not be referenced or unreferenced. This can return `NULL` if not on X11.

[transfer none][nullable]

### wnck_screen_get ()

    WnckScreen *
    wnck_screen_get (int index);

Gets the WnckScreen for a given screen on the default display.

#### Parameters

index | screen number, starting from 0. |

#### Returns

the WnckScreen for screen `index` , or `NULL` if no such screen exists. The returned WnckScreen is owned by libwnck and must not be referenced or unreferenced.

[transfer none]

### wnck_screen_get_for_root ()

    WnckScreen *
    wnck_screen_get_for_root (gulong root_window_id);

Gets the WnckScreen for the root window at `root_window_id` , or `NULL` if no WnckScreen exists for this root window.

This function does not work if `wnck_screen_get()` was not called for the sought WnckScreen before, and returns `NULL`.

#### Parameters

root_window_id | an X window ID. |

#### Returns

the WnckScreen for the root window at `root_window_id` , or `NULL`. The returned WnckScreen is owned by libwnck and must not be referenced or unreferenced.

[transfer none]

### wnck_screen_get_number ()

    int
    wnck_screen_get_number (WnckScreen *screen);

Gets the index of `screen` on the display to which it belongs. The first WnckScreen has an index of 0.

#### Parameters

screen | a WnckScreen. |

#### Returns

the index of `space` on `screen` , or -1 on errors.

Since: 2.20

### wnck_screen_get_width ()

    int
    wnck_screen_get_width (WnckScreen *screen);

Gets the width of `screen` .

#### Parameters

screen | a WnckScreen. |

#### Returns

the width of `screen` .

### wnck_screen_get_height ()

    int
    wnck_screen_get_height (WnckScreen *screen);

Gets the height of `screen` .

#### Parameters

screen | a WnckScreen. |

#### Returns

the height of `screen` .

### wnck_screen_force_update ()

    void
    wnck_screen_force_update (WnckScreen *screen);

Synchronously and immediately updates the list of WnckWindow on `screen` . This bypasses the standard update mechanism, where the list of WnckWindow is updated in the idle loop.

This is usually a bad idea for both performance and correctness reasons (to get things right, you need to write model-view code that tracks changes, not get a static list of open windows). However, this function can be useful for small applications that just do something and then exit.

#### Parameters

screen | a WnckScreen. |

### wnck_screen_get_window_manager_name ()

    const char *
    wnck_screen_get_window_manager_name (WnckScreen *screen);

Gets the name of the window manager.

#### Parameters

screen | a WnckScreen. |

#### Returns

the name of the window manager, or `NULL` if the window manager does not comply with the EWMH specification.

Since: 2.20

### wnck_screen_net_wm_supports ()

    gboolean
    wnck_screen_net_wm_supports (WnckScreen *screen,
                                 const char *atom);

Gets whether the window manager for `screen` supports a certain hint from the Extended Window Manager Hints specification (EWMH).

When using this function, keep in mind that the window manager can change over time; so you should not use this function in a way that impacts persistent application state. A common bug is that your application can start up before the window manager does when the user logs in, and before the window manager starts `wnck_screen_net_wm_supports()` will return `FALSE` for every property.

See also `gdk_x11_screen_supports_net_wm_hint()` in GDK.

#### Parameters

screen | a WnckScreen. |
atom | a property atom. |

#### Returns

`TRUE` if the window manager for `screen` supports the `atom` hint, `FALSE` otherwise.

### wnck_screen_get_active_window ()

    WnckWindow *
    wnck_screen_get_active_window (WnckScreen *screen);

Gets the active WnckWindow on `screen` . May return `NULL` sometimes, since not all window managers guarantee that a window is always active.

#### Parameters

screen | a WnckScreen. |

#### Returns

the active WnckWindow on `screen` , or `NULL`. The returned WnckWindow is owned by libwnck and must not be referenced or unreferenced.

[transfer none]

### wnck_screen_get_previously_active_window ()

    WnckWindow *
    wnck_screen_get_previously_active_window
                                   (WnckScreen *screen);

Gets the previously active WnckWindow on `screen` . May return `NULL` sometimes, since not all window managers guarantee that a window is always active.

#### Parameters

screen | a WnckScreen. |

#### Returns

the previously active WnckWindow on `screen` , or `NULL`. The returned WnckWindow is owned by libwnck and must not be referenced or unreferenced.

[transfer none]

Since: 2.8

### wnck_screen_get_windows ()

    GList *
    wnck_screen_get_windows (WnckScreen *screen);

Gets the list of WnckWindow on `screen` . The list is not in a defined order, but should be "stable" (windows should not be reordered in it). However, the stability of the list is established by the window manager, so don't blame libwnck if it breaks down.

#### Parameters

screen | a WnckScreen. |

#### Returns

the list of WnckWindow on `screen` , or `NULL` if there is no window on `screen` . The list should not be modified nor freed, as it is owned by `screen` .

[element-type WnckWindow][transfer none]

### wnck_screen_get_windows_stacked ()

    GList *
    wnck_screen_get_windows_stacked (WnckScreen *screen);

Gets the list of WnckWindow on `screen` in bottom-to-top order.

#### Parameters

screen | a WnckScreen. |

#### Returns

the list of WnckWindow in stacking order on `screen` , or `NULL` if there is no window on `screen` . The list should not be modified nor freed, as it is owned by `screen` .

[element-type WnckWindow][transfer none]

### wnck_screen_get_active_workspace ()

    WnckWorkspace *
    wnck_screen_get_active_workspace (WnckScreen *screen);

Gets the active WnckWorkspace on `screen` . May return `NULL` sometimes, if libwnck is in a weird state due to the asynchronous nature of the interaction with the window manager.

#### Parameters

screen | a WnckScreen. |

#### Returns

the active WnckWorkspace on `screen` , or `NULL`. The returned WnckWorkspace is owned by libwnck and must not be referenced or unreferenced.

[transfer none]

### wnck_screen_get_workspaces ()

    GList *
    wnck_screen_get_workspaces (WnckScreen *screen);

Gets the list of WnckWorkspace on `screen` . The list is ordered: the first element in the list is the first WnckWorkspace, etc..

#### Parameters

screen | a WnckScreen. |

#### Returns

the list of WnckWorkspace on `screen` . The list should not be modified nor freed, as it is owned by `screen` .

[element-type WnckWorkspace][transfer none]

Since: 2.20

### wnck_screen_get_workspace ()

    WnckWorkspace *
    wnck_screen_get_workspace (WnckScreen *screen,
                               int workspace);

Gets the WnckWorkspace numbered `workspace` on `screen` .

#### Parameters

screen | a WnckScreen. |
workspace | a workspace index, starting from 0. |

#### Returns

the WnckWorkspace numbered `workspace` on `screen` , or `NULL` if no such workspace exists. The returned WnckWorkspace is owned by libwnck and must not be referenced or unreferenced.

[transfer none]

### wnck_screen_get_workspace_count ()

    int
    wnck_screen_get_workspace_count (WnckScreen *screen);

Gets the number of WnckWorkspace on `screen` .

#### Parameters

screen | a WnckScreen. |

#### Returns

the number of WnckWorkspace on `screen` .

### wnck_screen_change_workspace_count ()

    void
    wnck_screen_change_workspace_count (WnckScreen *screen,
                                        int count);

Asks the window manager to change the number of WnckWorkspace on `screen` .

#### Parameters

screen | a WnckScreen. |
count | the number of WnckWorkspace to request. |

Since: 2.2

### wnck_screen_try_set_workspace_layout ()

    int
    wnck_screen_try_set_workspace_layout (WnckScreen *screen,
                                          int current_token,
                                          int rows,
                                          int columns);

Tries to modify the layout of WnckWorkspace on `screen` . To do this, tries to acquire ownership of the layout. If the current process is the owner of the layout, `current_token` is used to determine if the caller is the owner (there might be more than one part of the same process trying to set the layout). Since no more than one application should set this property of `screen` at a time, setting the layout is not guaranteed to work.

If `rows` is 0, the actual number of rows will be determined based on `columns` and the number of WnckWorkspace. If `columns` is 0, the actual number of columns will be determined based on `rows` and the number of WnckWorkspace. `rows` and `columns` must not be 0 at the same time.

You have to release the ownership of the layout with `wnck_screen_release_workspace_layout()` when you do not need it anymore.

#### Parameters

screen | a WnckScreen. |
current_token | a token. Use 0 if you do not called `wnck_screen_try_set_workspace_layout()` before, or if you did not keep the old token. |
rows | the number of rows to use for the WnckWorkspace layout. |
columns | the number of columns to use for the WnckWorkspace layout. |

#### Returns

a token to use for future calls to `wnck_screen_try_set_workspace_layout()` and to `wnck_screen_release_workspace_layout()`, or 0 if the layout could not be set.

### wnck_screen_release_workspace_layout ()

    void
    wnck_screen_release_workspace_layout (WnckScreen *screen,
                                          int current_token);

Releases the ownership of the layout of WnckWorkspace on `screen` . `current_token` is used to verify that the caller is the owner of the layout. If the verification fails, nothing happens.

#### Parameters

screen | a WnckScreen. |
current_token | the token obtained through `wnck_screen_try_set_workspace_layout()`. |

### wnck_screen_calc_workspace_layout ()

    void
    wnck_screen_calc_workspace_layout (WnckScreen *screen,
                                       int num_workspaces,
                                       int space_index,
                                       WnckWorkspaceLayout *layout);

`wnck_screen_calc_workspace_layout` has been deprecated since version 2.20 and should not be used in newly-written code.

Calculates the layout of WnckWorkspace, with additional information like the row and column of the WnckWorkspace with index `space_index` .

#### Parameters

screen | a WnckScreen. |
num_workspaces | the number of WnckWorkspace on `screen` , or -1 to let `wnck_screen_calc_workspace_layout()` find this number. |
space_index | the index of a WnckWorkspace. |
layout | return location for the layout of WnckWorkspace with additional information. |

Since: 2.12

### wnck_screen_free_workspace_layout ()

    void
    wnck_screen_free_workspace_layout (WnckWorkspaceLayout *layout);

`wnck_screen_free_workspace_layout` has been deprecated since version 2.20 and should not be used in newly-written code.

Frees the content of `layout` . This does not free `layout` itself, so you might want to free `layout` yourself after calling this.

#### Parameters

layout | a WnckWorkspaceLayout. |

Since: 2.12

### wnck_screen_move_viewport ()

    void
    wnck_screen_move_viewport (WnckScreen *screen,
                               int x,
                               int y);

Asks the window manager to move the viewport of the current WnckWorkspace on `screen` .

#### Parameters

screen | a WnckScreen. |
x | X offset in pixels of viewport. |
y | Y offset in pixels of viewport. |

Since: 2.4

### wnck_screen_get_background_pixmap ()

    gulong
    wnck_screen_get_background_pixmap (WnckScreen *screen);

Gets the X window ID of the background pixmap of `screen` .

#### Parameters

screen | a WnckScreen. |

#### Returns

the X window ID of the background pixmap of `screen` .

### wnck_screen_get_showing_desktop ()

    gboolean
    wnck_screen_get_showing_desktop (WnckScreen *screen);

Gets whether `screen` is in the "showing the desktop" mode. This mode is changed when a “showing-desktop-changed” signal gets emitted.

#### Parameters

screen | a WnckScreen. |

#### Returns

`TRUE` if `window` is fullscreen, `FALSE` otherwise.

Since: 2.2

### wnck_screen_toggle_showing_desktop ()

    void
    wnck_screen_toggle_showing_desktop (WnckScreen *screen,
                                        gboolean show);

Asks the window manager to set the "showing the desktop" mode on `screen` according to `show` .

#### Parameters

screen | a WnckScreen. |
show | whether to activate the "showing the desktop" mode on `screen` . |

Since: 2.2

## Types and Values

### struct WnckScreen

    struct WnckScreen;

The WnckScreen struct contains only private fields and should not be directly accessed.

### struct WnckWorkspaceLayout

    struct WnckWorkspaceLayout {
      int rows;
      int cols;
      int *grid;
      int grid_area;
      int current_row;
      int current_col;
    };

`WnckWorkspaceLayout` has been deprecated since version 2.20 and should not be used in newly-written code.

The WnckWorkspaceLayout struct contains information about the layout of WnckWorkspace on a WnckScreen, and the exact position of a specific WnckWorkspace.

#### Members

int `rows`; | number of rows in the layout grid. |
int `cols`; | number of columns in the layout grid. |
int *`grid`; | array of size `grid_area` containing the index (starting from 0) of the WnckWorkspace for each position in the layout grid, or -1 if the position does not correspond to any WnckWorkspace. |
int `grid_area`; | size of the grid containing all WnckWorkspace. This can be bigger than the number of WnckWorkspace because the grid might not be filled. |
int `current_row`; | row of the specific WnckWorkspace, starting from 0. |
int `current_col`; | column of the specific WnckWorkspace, starting from 0. |

Since: 2.12

## Signal Details

### The `“active-window-changed”` signal

    void
    user_function (WnckScreen *screen,
                   WnckWindow *previously_active_window,
                   gpointer    user_data)

Emitted when the active window on `screen` has changed.

#### Parameters

screen | the WnckScreen which emitted the signal. |
previously_active_window | the previously active WnckWindow before this change. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“active-workspace-changed”` signal

    void
    user_function (WnckScreen    *screen,
                   WnckWorkspace *previously_active_space,
                   gpointer       user_data)

Emitted when the active workspace on `screen` has changed.

#### Parameters

screen | the WnckScreen which emitted the signal. |
previously_active_space | the previously active WnckWorkspace before this change. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“application-closed”` signal

    void
    user_function (WnckScreen      *screen,
                   WnckApplication *app,
                   gpointer         user_data)

Emitted when a WnckApplication is closed on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
app | the closed WnckApplication. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“application-opened”` signal

    void
    user_function (WnckScreen      *screen,
                   WnckApplication *app,
                   gpointer         user_data)

Emitted when a new WnckApplication is opened on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
app | the opened WnckApplication. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“background-changed”` signal

    void
    user_function (WnckScreen *screen,
                   gpointer    user_data)

Emitted when the background on the root window of `screen` has changed.

#### Parameters

screen | the WnckScreen which emitted the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“class-group-closed”` signal

    void
    user_function (WnckScreen     *screen,
                   WnckClassGroup *class_group,
                   gpointer        user_data)

Emitted when a WnckClassGroup is closed on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
class_group | the closed WnckClassGroup. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.20

### The `“class-group-opened”` signal

    void
    user_function (WnckScreen     *screen,
                   WnckClassGroup *class_group,
                   gpointer        user_data)

Emitted when a new WnckClassGroup is opened on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
class_group | the opened WnckClassGroup. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.20

### The `“showing-desktop-changed”` signal

    void
    user_function (WnckScreen *screen,
                   gpointer    user_data)

Emitted when "showing the desktop" mode of `screen` is toggled.

#### Parameters

screen | the WnckScreen which emitted the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.20

### The `“viewports-changed”` signal

    void
    user_function (WnckScreen *screen,
                   gpointer    user_data)

Emitted when a viewport position has changed in a WnckWorkspace of `screen` or when a WnckWorkspace of `screen` gets or loses its viewport.

#### Parameters

screen | the WnckScreen which emitted the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.20

### The `“window-closed”` signal

    void
    user_function (WnckScreen *screen,
                   WnckWindow *window,
                   gpointer    user_data)

Emitted when a WnckWindow is closed on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
window | the closed WnckWindow. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-manager-changed”` signal

    void
    user_function (WnckScreen *screen,
                   gpointer    user_data)

Emitted when the window manager on `screen` has changed.

#### Parameters

screen | the WnckScreen which emitted the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.20

### The `“window-opened”` signal

    void
    user_function (WnckScreen *screen,
                   WnckWindow *window,
                   gpointer    user_data)

Emitted when a new WnckWindow is opened on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
window | the opened WnckWindow. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“window-stacking-changed”` signal

    void
    user_function (WnckScreen *screen,
                   gpointer    user_data)

Emitted when the stacking order of WnckWindow on `screen` has changed.

#### Parameters

screen | the WnckScreen which emitted the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“workspace-created”` signal

    void
    user_function (WnckScreen    *screen,
                   WnckWorkspace *space,
                   gpointer       user_data)

Emitted when a WnckWorkspace is created on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
space | the workspace that has been created. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“workspace-destroyed”` signal

    void
    user_function (WnckScreen    *screen,
                   WnckWorkspace *space,
                   gpointer       user_data)

Emitted when a WnckWorkspace is destroyed on `screen` .

#### Parameters

screen | the WnckScreen which emitted the signal. |
space | the workspace that has been destroyed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

WnckWindow, WnckWorkspace