MatewnckWorkspace

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

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libmatewnck/libmatewnck.h>

                        MatewnckWorkspace;
    MatewnckScreen *    matewnck_workspace_get_screen       (MatewnckWorkspace *space);
    int                 matewnck_workspace_get_number       (MatewnckWorkspace *space);
    const char *        matewnck_workspace_get_name         (MatewnckWorkspace *space);
    void                matewnck_workspace_change_name      (MatewnckWorkspace *space,
                                                             const char *name);
    int                 matewnck_workspace_get_width        (MatewnckWorkspace *space);
    int                 matewnck_workspace_get_height       (MatewnckWorkspace *space);
    int                 matewnck_workspace_get_viewport_x   (MatewnckWorkspace *space);
    int                 matewnck_workspace_get_viewport_y   (MatewnckWorkspace *space);
    gboolean            matewnck_workspace_is_virtual       (MatewnckWorkspace *space);
    int                 matewnck_workspace_get_layout_row   (MatewnckWorkspace *space);
    int                 matewnck_workspace_get_layout_column
                                                            (MatewnckWorkspace *space);
    MatewnckWorkspace * matewnck_workspace_get_neighbor     (MatewnckWorkspace *space,
                                                             MatewnckMotionDirection direction);
    void                matewnck_workspace_activate         (MatewnckWorkspace *space,
                                                             guint32 timestamp);

## Object Hierarchy

      GObject
       +----MatewnckWorkspace

## Signals

      "name-changed"                                   : Run Last

## Description

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

If the MatewnckWorkspace size is bigger that the MatewnckScreen 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. libmatewnck supports all situations, even multiple workspaces with viewports.

Workspaces are organized according to a layout set on the MatewnckScreen. See `matewnck_screen_try_set_workspace_layout()` and `matewnck_screen_release_workspace_layout()` for more information about the layout.

The MatewnckWorkspace objects are always owned by libmatewnck and must not be referenced or unreferenced.

## Details

### MatewnckWorkspace

    typedef struct _MatewnckWorkspace MatewnckWorkspace;

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

### matewnck_workspace_get_screen ()

    MatewnckScreen *    matewnck_workspace_get_screen       (MatewnckWorkspace *space);

Gets the MatewnckScreen `space` is on.

`space` : | a MatewnckWorkspace.
Returns : | the MatewnckScreen `space` is on. The returned MatewnckScreen is owned by libmatewnck and must not be referenced or unreferenced.

### matewnck_workspace_get_number ()

    int                 matewnck_workspace_get_number       (MatewnckWorkspace *space);

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

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

### matewnck_workspace_get_name ()

    const char *        matewnck_workspace_get_name         (MatewnckWorkspace *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 MatewnckWorkspace.
Returns : | the name of `space`.

### matewnck_workspace_change_name ()

    void                matewnck_workspace_change_name      (MatewnckWorkspace *space,
                                                             const char *name);

Changes the name of `space`.

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

Since 2.2

### matewnck_workspace_get_width ()

    int                 matewnck_workspace_get_width        (MatewnckWorkspace *space);

Gets the width of `space`.

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

Since 2.4

### matewnck_workspace_get_height ()

    int                 matewnck_workspace_get_height       (MatewnckWorkspace *space);

Gets the height of `space`.

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

Since 2.4

### matewnck_workspace_get_viewport_x ()

    int                 matewnck_workspace_get_viewport_x   (MatewnckWorkspace *space);

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

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

Since 2.4

### matewnck_workspace_get_viewport_y ()

    int                 matewnck_workspace_get_viewport_y   (MatewnckWorkspace *space);

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

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

Since 2.4

### matewnck_workspace_is_virtual ()

    gboolean            matewnck_workspace_is_virtual       (MatewnckWorkspace *space);

Gets whether `space` contains a viewport.

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

Since 2.4

### matewnck_workspace_get_layout_row ()

    int                 matewnck_workspace_get_layout_row   (MatewnckWorkspace *space);

Gets the row of `space` in the MatewnckWorkspace 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 MatewnckWorkspace.
Returns : | the row of `space` in the MatewnckWorkspace layout, or -1 on errors.

Since 2.20

### matewnck_workspace_get_layout_column ()

    int                 matewnck_workspace_get_layout_column
                                                            (MatewnckWorkspace *space);

Gets the column of `space` in the MatewnckWorkspace 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 MatewnckWorkspace.
Returns : | the column of `space` in the MatewnckWorkspace layout, or -1 on errors.

Since 2.20

### matewnck_workspace_get_neighbor ()

    MatewnckWorkspace * matewnck_workspace_get_neighbor     (MatewnckWorkspace *space,
                                                             MatewnckMotionDirection direction);

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

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

Since 2.20

### matewnck_workspace_activate ()

    void                matewnck_workspace_activate         (MatewnckWorkspace *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 MatewnckWorkspace.
`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                      (MatewnckWorkspace *space,
                                                            gpointer           user_data)      : Run Last

Emitted when the name of `space` changes.

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

## See Also

MatewnckScreen