XfwWorkspace: libxfce4windowing Reference Manual

## XfwWorkspace XfwWorkspace — A workspace that is part of a workspace group |

## Stability Level

Unstable, unless otherwise indicated

## Functions

const gchar * | xfw_workspace_get_id ()
const gchar * | xfw_workspace_get_name ()
XfwWorkspaceCapabilities | xfw_workspace_get_capabilities ()
XfwWorkspaceState | xfw_workspace_get_state ()
guint | xfw_workspace_get_number ()
XfwWorkspaceGroup * | xfw_workspace_get_workspace_group ()
gint | xfw_workspace_get_layout_row ()
gint | xfw_workspace_get_layout_column ()
XfwWorkspace * | xfw_workspace_get_neighbor ()
GdkRectangle * | xfw_workspace_get_geometry ()
gboolean | xfw_workspace_activate ()
gboolean | xfw_workspace_remove ()
gboolean | xfw_workspace_assign_to_workspace_group ()

## Properties

XfwWorkspaceCapabilities | capabilities | Read / Write / Construct
XfwWorkspaceGroup * | group | Read
char * | id | Read
int | layout-column | Read
int | layout-row | Read
char * | name | Read / Write / Construct
guint | number | Read / Write / Construct Only
XfwWorkspaceState | state | Read / Write / Construct

## Signals

void | capabilities-changed | Run Last
void | group-changed | Run Last
void | name-changed | Run Last
void | state-changed | Run Last

## Types and Values

| XfwWorkspace
enum | XfwWorkspaceCapabilities
enum | XfwWorkspaceState
typedef | XfwWorkspaceIface

## Object Hierarchy

        GFlags
        ├── XfwWorkspaceCapabilities
        ╰── XfwWorkspaceState
        GInterface
        ╰── XfwWorkspace

## Prerequisites

XfwWorkspace requires GObject.

## Includes

    #include <libxfce4windowing/libxfce4windowing.h>

## Description

XfwWorkspace represents a single workspace within a workspace group. A workspace is usually a collection of windows that are shown together on the desktop when that workspace is the active workspace.

An instance of XfwWorkspace can be used to obtain information about the workspace, such as its name, position in the group, and capabilities. The workspace can also be activated or removed.

Note that XfwWorkspace is actually an interface; when obtaining an instance, an instance of a windowing-environment-specific object that implements this interface will be returned.

## Functions

### xfw_workspace_get_id ()

    const gchar *
    xfw_workspace_get_id (XfwWorkspace *workspace);

Fetches this workspace's opaque ID.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

A UTF-8 formatted string, owned by `workspace` .

[not nullable][transfer none]

### xfw_workspace_get_name ()

    const gchar *
    xfw_workspace_get_name (XfwWorkspace *workspace);

Fetches this workspace's human-readable name.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

A UTF-8 formatted string, owned by `workspace` .

[not nullable][transfer none]

### xfw_workspace_get_capabilities ()

    XfwWorkspaceCapabilities
    xfw_workspace_get_capabilities (XfwWorkspace *workspace);

Fetches this workspace's capabilities bitfield.

The bitfield describes what operations are available on this workspace.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a XfwWorkspaceCapabilities bitfield.

### xfw_workspace_get_state ()

    XfwWorkspaceState
    xfw_workspace_get_state (XfwWorkspace *workspace);

Fetches this workspace's state bitfield.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a XfwWorkspaceState bitfield.

### xfw_workspace_get_number ()

    guint
    xfw_workspace_get_number (XfwWorkspace *workspace);

Fetches the ordinal number of this workspace.

The number can be used to order workspaces in a UI representation.

On X11, this number should be stable across runs of your application.

On Wayland, this number depends on the order in which the compositor advertises the workspaces. This order may be stable, but may not be.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a non-negative, 0-indexed integer.

### xfw_workspace_get_workspace_group ()

    XfwWorkspaceGroup *
    xfw_workspace_get_workspace_group (XfwWorkspace *workspace);

Fetches the group this workspace belongs to, if any.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a XfwWorkspaceGroup instance, owned by `workspace` , or `NULL` if the workspace is not a member of any groups.

[nullable][transfer none]

### xfw_workspace_get_layout_row ()

    gint
    xfw_workspace_get_layout_row (XfwWorkspace *workspace);

Fetches the row this workspace belongs to in the workspace's group.

This information can be used to lay out workspaces in a grid in a pager UI, for example.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a non-negative, 0-indexed integer.

### xfw_workspace_get_layout_column ()

    gint
    xfw_workspace_get_layout_column (XfwWorkspace *workspace);

Fetches the column this workspace belongs to in the workspace's group.

This information can be used to lay out workspaces in a grid in a pager UI, for example.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a non-negative, 0-indexed integer.

### xfw_workspace_get_neighbor ()

    XfwWorkspace *
    xfw_workspace_get_neighbor (XfwWorkspace *workspace,
                                XfwDirection direction);

Fetches the workspace that resides in `direction` from the `workspace` , if any. If workspace is on the edge of the layout, and `direction` points off the edge of the layout, will return `NULL`.

#### Parameters

workspace | an XfwWorkspace. |
direction | an XfwDirection. |

#### Returns

a XfwWorkspace, owned by the parent `group` , or `NULL` if no workspace exists in `direction` .

[nullable][transfer none]

### xfw_workspace_get_geometry ()

    GdkRectangle *
    xfw_workspace_get_geometry (XfwWorkspace *workspace);

Fetches the position and size of the workspace in screen coordinates.

The values in the returned GdkRectangle are owned by `workspace` and should not be modified.

#### Parameters

workspace | an XfwWorkspace. |

#### Returns

a GdkRectangle, owned by `workspace` .

[not nullable][transfer none]

### xfw_workspace_activate ()

    gboolean
    xfw_workspace_activate (XfwWorkspace *workspace,
                            GError **error);

Attempts to set `workspace` as the active workspace in its group.

On failure, `error` (if provided) will be set to a description of the error that occurred.

#### Parameters

workspace | an XfwWorkspace. |
error | a location to store a possible error. | [out callee-allocates]

#### Returns

`TRUE` if workspace activation succeeded, `FALSE` otherwise. If `FALSE`, and `error` is non-`NULL`, an error will be returned that must be freed using ``g_error_free()``.

### xfw_workspace_remove ()

    gboolean
    xfw_workspace_remove (XfwWorkspace *workspace,
                          GError **error);

Attempts to remove `workspace` from its group.

On failure, `error` (if provided) will be set to a description of the error that occurred.

#### Parameters

workspace | an XfwWorkspace. |
error | a location to store a possible error. | [out callee-allocates]

#### Returns

`TRUE` if workspace removal succeeded, `FALSE` otherwise. If `FALSE`, and `error` is non-`NULL`, an error will be returned that must be freed using ``g_error_free()``.

### xfw_workspace_assign_to_workspace_group ()

    gboolean
    xfw_workspace_assign_to_workspace_group
                                   (XfwWorkspace *workspace,
                                    XfwWorkspaceGroup *group,
                                    GError **error);

Attempts to assign `workspace` to `group` .

On failure, `error` (if provided) will be set to a description of the error that occurred.

#### Parameters

workspace | an XfwWorkspace. |
group | an XfwWorkspaceGroup. |
error | a location to store a possible error. | [out callee-allocates]

#### Returns

`TRUE` if workspace assignment succeeded, `FALSE` otherwise. If `FALSE`, and `error` is non-`NULL`, an error will be returned that must be freed using `g_error_free()`.

## Types and Values

### XfwWorkspace

    typedef struct _XfwWorkspace XfwWorkspace;

### enum XfwWorkspaceCapabilities

Flags enum representing a bitfield of actions that can be performed on this workspace.

#### Members

XFW_WORKSPACE_CAPABILITIES_NONE | workspace has no capabilities. |
XFW_WORKSPACE_CAPABILITIES_ACTIVATE | workspace can be activated. |
XFW_WORKSPACE_CAPABILITIES_DEACTIVATE | workspace can be deactivated. |
XFW_WORKSPACE_CAPABILITIES_REMOVE | workspace can be removed. |
XFW_WORKSPACE_CAPABILITIES_ASSIGN | workspace can be assigned to a group. |

### enum XfwWorkspaceState

Flags enum representing a bitfield that describes the workspace's state.

#### Members

XFW_WORKSPACE_STATE_NONE | workspace has no state information. |
XFW_WORKSPACE_STATE_ACTIVE | workspace is the active workspace in its group. |
XFW_WORKSPACE_STATE_URGENT | workspace contains a window that is requesting attention. |
XFW_WORKSPACE_STATE_HIDDEN | workspace should be hidden from pagers or other UI elements. |
XFW_WORKSPACE_STATE_VIRTUAL | workspace has a valid, visible viewport. |

### XfwWorkspaceIface

    typedef struct _XfwWorkspaceInterface XfwWorkspaceIface;

## Property Details

### The `“capabilities”` property

      “capabilities”             XfwWorkspaceCapabilities

The XfwWorkspaceCapabilities bitfield for this workspace.

Owner: XfwWorkspace

Flags: Read / Write / Construct

### The `“group”` property

      “group”                    XfwWorkspaceGroup *

The XfwWorkspaceGroup that this workspace is a member of, if any.

Owner: XfwWorkspace

Flags: Read

### The `“id”` property

      “id”                       char *

The opaque ID of this workspace.

Owner: XfwWorkspace

Flags: Read

Default value: ""

### The `“layout-column”` property

      “layout-column”            int

The y-coordinate of the workspace on a 2D grid.

Owner: XfwWorkspace

Flags: Read

Allowed values: >= -1

Default value: -1

### The `“layout-row”` property

      “layout-row”               int

The x-coordinate of the workspace on a 2D grid.

Owner: XfwWorkspace

Flags: Read

Allowed values: >= -1

Default value: -1

### The `“name”` property

      “name”                     char *

The human-readable name of this workspace.

Owner: XfwWorkspace

Flags: Read / Write / Construct

Default value: ""

### The `“number”` property

      “number”                   guint

The ordinal number of this workspace.

Owner: XfwWorkspace

Flags: Read / Write / Construct Only

Default value: 0

### The `“state”` property

      “state”                    XfwWorkspaceState

The XfwWorkspaceState bitfield for this workspace.

Owner: XfwWorkspace

Flags: Read / Write / Construct

## Signal Details

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

    void
    user_function (XfwWorkspace            *workspace,
                   XfwWorkspaceCapabilities changed_mask,
                   XfwWorkspaceCapabilities new_capabilities,
                   gpointer                 user_data)

Emitted when `workspace` 's capabilities change.

#### Parameters

workspace | the object which received the signal. |
changed_mask | a bitfield representing the capabilities that have changed. |
new_capabilities | a bitfield of the new capabilities. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (XfwWorkspace      *workspace,
                   XfwWorkspaceGroup *previous_group,
                   gpointer           user_data)

Emitted when `workspace` is assigned to an XfwWorkspaceGroup.

#### Parameters

workspace | the object which received the signal. |
previous_group | the group `workspace` was previously in, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (XfwWorkspace *workspace,
                   gpointer      user_data)

Emitted when `workspace` 's name changes.

#### Parameters

workspace | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (XfwWorkspace     *workspace,
                   XfwWorkspaceState changed_mask,
                   XfwWorkspaceState new_state,
                   gpointer          user_data)

Emitted when `workspace` 's state changes.

#### Parameters

workspace | the object which received the signal. |
changed_mask | a bitfield representing the state bits that have changed. |
new_state | a bitfield of the new state. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last