XfwWorkspaceGroup: libxfce4windowing Reference Manual

## XfwWorkspaceGroup XfwWorkspaceGroup — A group of workspaces |

## Stability Level

Unstable, unless otherwise indicated

## Functions

XfwWorkspaceGroupCapabilities | xfw_workspace_group_get_capabilities ()
guint | xfw_workspace_group_get_workspace_count ()
GList * | xfw_workspace_group_list_workspaces ()
XfwWorkspace * | xfw_workspace_group_get_active_workspace ()
GList * | xfw_workspace_group_get_monitors ()
XfwWorkspaceManager * | xfw_workspace_group_get_workspace_manager ()
gboolean | xfw_workspace_group_create_workspace ()
gboolean | xfw_workspace_group_move_viewport ()
gboolean | xfw_workspace_group_set_layout ()

## Properties

XfwWorkspace * | active-workspace | Read
gpointer | monitors | Read
XfwScreen * | screen | Read / Write / Construct Only
XfwWorkspaceManager * | workspace-manager | Read / Write / Construct Only
gpointer | workspaces | Read

## Signals

void | active-workspace-changed | Run Last
void | capabilities-changed | Run Last
void | monitor-added | Run Last
void | monitor-removed | Run Last
void | monitors-changed | Run Last
void | viewports-changed | Run Last
void | workspace-added | Run Last
void | workspace-removed | Run Last

## Types and Values

| XfwWorkspaceGroup
enum | XfwWorkspaceGroupCapabilities
typedef | XfwWorkspaceGroupIface

## Object Hierarchy

        GFlags
        ╰── XfwWorkspaceGroupCapabilities
        GInterface
        ╰── XfwWorkspaceGroup

## Prerequisites

XfwWorkspaceGroup requires GObject.

## Includes

    #include <libxfce4windowing/libxfce4windowing.h>

## Description

Workspaces may be arranged in groups, and groups may be present on different monitors. The XfwWorkspaceGroup can create and enumerate workspaces, as well as provide notifications when workspaces are created and destroyed.

Each workspace group may have an active workspace.

Workspace groups are displayed on a list of zero or more monitors, and have viewport coordinates.

Note that XfwWorkspaceGroup 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_group_get_capabilities ()

    XfwWorkspaceGroupCapabilities
    xfw_workspace_group_get_capabilities (XfwWorkspaceGroup *group);

Returns a bitfield describing operations allowed on this `group` .

#### Parameters

group | an XfwWorkspaceGroup. |

#### Returns

an XfwWorkspaceGroupCapabilities bitfield.

### xfw_workspace_group_get_workspace_count ()

    guint
    xfw_workspace_group_get_workspace_count
                                   (XfwWorkspaceGroup *group);

Fetches the number of workspaces in `group` .

#### Parameters

group | an XfwWorkspaceGroup. |

#### Returns

an unsigned integer describing the number of workspaces.

### xfw_workspace_group_list_workspaces ()

    GList *
    xfw_workspace_group_list_workspaces (XfwWorkspaceGroup *group);

Lists the workspaces in `group` .

#### Parameters

group | an XfwWorkspaceGroup. |

#### Returns

the list of XfwWorkspace in `group` , or `NULL` if there are no workspaces. The list and its contents are owned by `group` .

[nullable][element-type XfwWorkspace][transfer none]

### xfw_workspace_group_get_active_workspace ()

    XfwWorkspace *
    xfw_workspace_group_get_active_workspace
                                   (XfwWorkspaceGroup *group);

Gets the active workspace on `group` , if there is one.

#### Parameters

group | an XfwWorkspaceGroup. |

#### Returns

an XfwWorkspace, or `NULL` if there is no active workspace.

[nullable][transfer none]

### xfw_workspace_group_get_monitors ()

    GList *
    xfw_workspace_group_get_monitors (XfwWorkspaceGroup *group);

Lists the physical monitors that this workspace group displays on.

#### Parameters

group | an XfwWorkspaceGroup. |

#### Returns

A list of XfwMonitor, or `NULL` if `group` is not displayed on any monitors. The list and its contents are owned by `group` .

[nullable][element-type XfwMonitor][transfer none]

### xfw_workspace_group_get_workspace_manager ()

    XfwWorkspaceManager *
    xfw_workspace_group_get_workspace_manager
                                   (XfwWorkspaceGroup *group);

Fetches the XfwWorkspaceManager instance that owns `group` .

#### Parameters

group | an XfwWorkspaceGroup. |

#### Returns

a XfwWorkspaceManager, owned by `group` .

[not nullable][transfer none]

### xfw_workspace_group_create_workspace ()

    gboolean
    xfw_workspace_group_create_workspace (XfwWorkspaceGroup *group,
                                          const gchar *name,
                                          GError **error);

Attempts to create a new workspace on `group` . Typically, the new workspace will be appended to the existing list of workspaces.

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

#### Parameters

group | an XfwWorkspaceGroup. |
name | a name for the new workspace. |
error | a location to store a possible error. | [out callee-allocates]

#### Returns

`TRUE` if workspace creation 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_group_move_viewport ()

    gboolean
    xfw_workspace_group_move_viewport (XfwWorkspaceGroup *group,
                                       gint x,
                                       gint y,
                                       GError **error);

Moves the workspace group to a new location, and possibly a new monitor.

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

#### Parameters

group | an XfwWorkspaceGroup. |
x | a coordinate in the horizontal direction. |
y | a coordinate in the vertical direction. |
error | a location to store a possible error. | [out callee-allocates]

#### Returns

`TRUE` if moving the workspace group 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_group_set_layout ()

    gboolean
    xfw_workspace_group_set_layout (XfwWorkspaceGroup *group,
                                    gint rows,
                                    gint columns,
                                    GError **error);

Sets the layout of `group` to `rows` by `columns` .

Note that this will not change the number of workspaces if the new layout implies a larger number of workspaces than currently exists.

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

#### Parameters

group | an XfwWorkspaceGroup. |
rows | the new numbers of rows. |
columns | the new number of columns. |
error | a location to store a possible error. | [out callee-allocates]

#### Returns

`TRUE` if changing the layout of `group` succeede, `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

### XfwWorkspaceGroup

    typedef struct _XfwWorkspaceGroup XfwWorkspaceGroup;

### enum XfwWorkspaceGroupCapabilities

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

#### Members

XFW_WORKSPACE_GROUP_CAPABILITIES_NONE | group has no capabilities. |
XFW_WORKSPACE_GROUP_CAPABILITIES_CREATE_WORKSPACE | new workspaces can be created in this group. |
XFW_WORKSPACE_GROUP_CAPABILITIES_MOVE_VIEWPORT | the viewport coordinates for this group can be changed. |
XFW_WORKSPACE_GROUP_CAPABILITIES_SET_LAYOUT | the number of rows and columns for this group can be changed. |

### XfwWorkspaceGroupIface

    typedef struct _XfwWorkspaceGroupInterface XfwWorkspaceGroupIface;

## Property Details

### The `“active-workspace”` property

      “active-workspace”         XfwWorkspace *

The active XfwWorkspace on this XfwWorkspaceGroup, or `NULL`.

Owner: XfwWorkspaceGroup

Flags: Read

### The `“monitors”` property

      “monitors”                 gpointer

The list of XfwMonitor this XfwWorkspaceGroup is displayed on.

[type GList(XfwMonitor)]

Owner: XfwWorkspaceGroup

Flags: Read

### The `“screen”` property

      “screen”                   XfwScreen *

The XfwScreen that owns this XfwWorkspaceGroup.

Owner: XfwWorkspaceGroup

Flags: Read / Write / Construct Only

### The `“workspace-manager”` property

      “workspace-manager”        XfwWorkspaceManager *

The XfwWorkspaceManager instance that manages this XfwWorkspaceGroup.

Owner: XfwWorkspaceGroup

Flags: Read / Write / Construct Only

### The `“workspaces”` property

      “workspaces”               gpointer

The list of XfwWorkspace in this XfwWorkspaceGroup.

[type GList(XfwWorkspace)]

Owner: XfwWorkspaceGroup

Flags: Read

## Signal Details

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

    void
    user_function (XfwWorkspaceGroup *group,
                   XfwWorkspace      *previously_active_workspace,
                   gpointer           user_data)

Emitted when the active workspace of `group` changes.

#### Parameters

group | the object which received the signal. |
previously_active_workspace | the previously active XfwWorkspace, or `NULL`. | [nullable]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (XfwWorkspaceGroup            *group,
                   XfwWorkspaceGroupCapabilities changed_mask,
                   XfwWorkspaceGroupCapabilities new_capabilities,
                   gpointer                      user_data)

Emitted when capabilities have changed on `group` .

#### Parameters

group | 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 `“monitor-added”` signal

    void
    user_function (XfwWorkspaceGroup *group,
                   XfwMonitor        *monitor,
                   gpointer           user_data)

Emitted when `group` is added to a new monitor.

#### Parameters

group | the object which received the signal. |
monitor | a XfwMonitor. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“monitor-removed”` signal

    void
    user_function (XfwWorkspaceGroup *group,
                   XfwMonitor        *monitor,
                   gpointer           user_data)

Emitted when `group` is removed from a monitor.

#### Parameters

group | the object which received the signal. |
monitor | a XfwMonitor. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (XfwWorkspaceGroup *group,
                   gpointer           user_data)

Emitted when `group` moves to a new set of monitors.

#### Parameters

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

Flags: Run Last

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

    void
    user_function (XfwWorkspaceGroup *group,
                   gpointer           user_data)

Emitted when `group` 's viewport coordinates have changed.

#### Parameters

group | the object which recieved the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

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

Emitted when `workspace` joins `group` .

#### Parameters

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

Flags: Run Last

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

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

Emitted when `workspace` leaves `group` .

#### Parameters

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

Flags: Run Last