WnckWorkspace

## WnckWorkspace WnckWorkspace — an object representing a workspace. |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libwnck/libwnck.h>

                        WnckWorkspace;
    WnckScreen *        wnck_workspace_get_screen           (WnckWorkspace *space);
    int                 wnck_workspace_get_number           (WnckWorkspace *space);
    const char *        wnck_workspace_get_name             (WnckWorkspace *space);
    void                wnck_workspace_change_name          (WnckWorkspace *space,
                                                             const char *name);
    int                 wnck_workspace_get_width            (WnckWorkspace *space);
    int                 wnck_workspace_get_height           (WnckWorkspace *space);
    int                 wnck_workspace_get_viewport_x       (WnckWorkspace *space);
    int                 wnck_workspace_get_viewport_y       (WnckWorkspace *space);
    gboolean            wnck_workspace_is_virtual           (WnckWorkspace *space);
    int                 wnck_workspace_get_layout_row       (WnckWorkspace *space);
    int                 wnck_workspace_get_layout_column    (WnckWorkspace *space);
    enum                WnckMotionDirection;
    WnckWorkspace *     wnck_workspace_get_neighbor         (WnckWorkspace *space,
                                                             WnckMotionDirection direction);
    void                wnck_workspace_activate             (WnckWorkspace *space,
                                                             guint32 timestamp);

## Object Hierarchy

      GObject
       +----WnckWorkspace

## Signals

      "name-changed"                                   : Run Last

## Description

The WnckWorkspace represents what is called virtual desktops in the EWMH. A workspace is a virtualization of a WnckScreen: only one workspace can be shown on a WnckScreen at a time. It makes it possible, for example, to put windows on different workspaces to organize them.

If the WnckWorkspace size is bigger that the WnckScreen size, the workspace contains a viewport. Viewports are defined in the large desktops section of the EWMH. The notion of workspaces and viewports are quite similar, and generally both are not used at the same time: there are generally either multiple workspaces with no viewport, or one workspace with a viewport. libwnck supports all situations, even multiple workspaces with viewports.

Workspaces are organized according to a layout set on the WnckScreen. See `wnck_screen_try_set_workspace_layout()` and `wnck_screen_release_workspace_layout()` for more information about the layout.

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

## Details

### WnckWorkspace

    typedef struct _WnckWorkspace WnckWorkspace;

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

### wnck_workspace_get_screen ()

    WnckScreen *        wnck_workspace_get_screen           (WnckWorkspace *space);

Gets the WnckScreen `space` is on.

`space` : | a WnckWorkspace.
Returns : | the WnckScreen `space` is on. The returned WnckScreen is owned by libwnck and must not be referenced or unreferenced. [transfer none]

### wnck_workspace_get_number ()

    int                 wnck_workspace_get_number           (WnckWorkspace *space);

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

`space` : | a WnckWorkspace.
Returns : | the index of `space` on its WnckScreen, or -1 on errors.

### wnck_workspace_get_name ()

    const char *        wnck_workspace_get_name             (WnckWorkspace *space);

Gets the human-readable name that should be used to refer to `space`. If the user has not set a special name, a fallback like "Workspace 3" will be used.

`space` : | a WnckWorkspace.
Returns : | the name of `space`.

### wnck_workspace_change_name ()

    void                wnck_workspace_change_name          (WnckWorkspace *space,
                                                             const char *name);

Changes the name of `space`.

`space` : | a WnckWorkspace.
`name` : | new name for `space`.

Since 2.2

### wnck_workspace_get_width ()

    int                 wnck_workspace_get_width            (WnckWorkspace *space);

Gets the width of `space`.

`space` : | a WnckWorkspace.
Returns : | the width of `space`.

Since 2.4

### wnck_workspace_get_height ()

    int                 wnck_workspace_get_height           (WnckWorkspace *space);

Gets the height of `space`.

`space` : | a WnckWorkspace.
Returns : | the height of `space`.

Since 2.4

### wnck_workspace_get_viewport_x ()

    int                 wnck_workspace_get_viewport_x       (WnckWorkspace *space);

Gets the X coordinate of the viewport in `space`.

`space` : | a WnckWorkspace.
Returns : | the X coordinate of the viewport in `space`, or 0 if `space` does not contain a viewport.

Since 2.4

### wnck_workspace_get_viewport_y ()

    int                 wnck_workspace_get_viewport_y       (WnckWorkspace *space);

Gets the Y coordinate of the viewport in `space`.

`space` : | a WnckWorkspace.
Returns : | the Y coordinate of the viewport in `space`, or 0 if `space` does not contain a viewport.

Since 2.4

### wnck_workspace_is_virtual ()

    gboolean            wnck_workspace_is_virtual           (WnckWorkspace *space);

Gets whether `space` contains a viewport.

`space` : | a WnckWorkspace.
Returns : | `TRUE` if `space` contains a viewport, `FALSE` otherwise.

Since 2.4

### wnck_workspace_get_layout_row ()

    int                 wnck_workspace_get_layout_row       (WnckWorkspace *space);

Gets the row of `space` in the WnckWorkspace layout. The first row has an index of 0 and is always the top row, regardless of the starting corner set for the layout.

`space` : | a WnckWorkspace.
Returns : | the row of `space` in the WnckWorkspace layout, or -1 on errors.

Since 2.20

### wnck_workspace_get_layout_column ()

    int                 wnck_workspace_get_layout_column    (WnckWorkspace *space);

Gets the column of `space` in the WnckWorkspace layout. The first column has an index of 0 and is always the left column, regardless of the starting corner set for the layout and regardless of the default direction of the environment (i.e., in both Left-To-Right and Right-To-Left environments).

`space` : | a WnckWorkspace.
Returns : | the column of `space` in the WnckWorkspace layout, or -1 on errors.

Since 2.20

### enum WnckMotionDirection

    typedef enum {
      WNCK_MOTION_UP = -1,
      WNCK_MOTION_DOWN = -2,
      WNCK_MOTION_LEFT = -3,
      WNCK_MOTION_RIGHT = -4
    } WnckMotionDirection;

Type defining a direction in which to search a neighbor WnckWorkspace.

`WNCK_MOTION_UP` | search a neighbor WnckWorkspace above another WnckWorkspace.
`WNCK_MOTION_DOWN` | search a neighbor WnckWorkspace below another WnckWorkspace.
`WNCK_MOTION_LEFT` | search a neighbor WnckWorkspace at the left of another WnckWorkspace.
`WNCK_MOTION_RIGHT` | search a neighbor WnckWorkspace at the right of another WnckWorkspace.

Since 2.14

### wnck_workspace_get_neighbor ()

    WnckWorkspace *     wnck_workspace_get_neighbor         (WnckWorkspace *space,
                                                             WnckMotionDirection direction);

Gets the neighbor WnckWorkspace of `space` in the `direction` direction.

`space` : | a WnckWorkspace.
`direction` : | direction in which to search the neighbor.
Returns : | the neighbor WnckWorkspace of `space` in the `direction` direction, or `NULL` if no such neighbor WnckWorkspace exists. The returned WnckWorkspace is owned by libwnck and must not be referenced or unreferenced. [transfer none]

Since 2.20

### wnck_workspace_activate ()

    void                wnck_workspace_activate             (WnckWorkspace *space,
                                                             guint32 timestamp);

Asks the window manager to make `space` the active workspace. The window manager may decide to refuse the request (to not steal the focus if there is a more recent user activity, for example).

This function existed before 2.10, but the `timestamp` argument was missing in earlier versions.

`space` : | a WnckWorkspace.
`timestamp` : | the X server timestamp of the user interaction event that caused this call to occur.

Since 2.10

## Signal Details

### The `"name-changed"` signal

    void                user_function                      (WnckWorkspace *space,
                                                            gpointer       user_data)      : Run Last

Emitted when the name of `space` changes.

`space` : | the WnckWorkspace which emitted the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

WnckScreen