Workspaces

A workspace in the context of the window manager is that what holds (or owns) a set of clients.

By default there are 9 workspaces available represented by the numbers 1 through 9.

The workspace area, i.e. where the clients are drawn, is restricted to a monitor. This is in contrast to most desktop environments where the workspace typically span across all monitors.

Workspaces can be moved freely across monitors unless they are pinned to a specific monitor.

More than one workspace can be viewed simultaneously on a single monitor, in which case the workspace area will be divided evenly between the visible workspaces.

Configuration

Workspaces are defined in the wsrules array in config.h.

static const WorkspaceRule wsrules[] = {
   /*                                                                     ------------------------------- schemes ------------------------------- ------ icons ------
      name,  monitor,  pinned,  layout,  mfact,  nmaster,  nstack,  gaps, default,          visible,          selected,         occupied,         def,   vac,  occ,  */
   {  "1",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "1",   "",   "[1]", },
   {  "2",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "2",   "",   "[2]", },
   {  "3",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "3",   "",   "[3]", },
   {  "4",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "4",   "",   "[4]", },
   {  "5",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "5",   "",   "[5]", },
   {  "6",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "6",   "",   "[6]", },
   {  "7",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "7",   "",   "[7]", },
   {  "8",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "8",   "",   "[8]", },
   {  "9",   -1,       0,       0,       -1,    -1,       -1,      -1,    SchemeWsNorm,     SchemeWsVisible,  SchemeWsSel,      SchemeWsOcc,      "9",   "",   "[9]", },
};

These rules define the workspaces that are available, which monitor they are initially assigned to and whether the workspace is pinned to that monitor.

Additionally the rules specify the icons used for the workspace as well as the initial layout.

The name of the workspace is used as a reference for internal configuration as well as for external commands. Optionally workspace names can also be shown in the bar if the AltWorkspaceIcons functionality is enabled.

The monitor index indicates which monitor the workspace is to start on by default. Workspaces where the monitor index is set to -1 will be distributed evenly across the available monitors. Refer to the Monitor page for details on multi-monitor setup.

The pinned option indicates whether or not the workspace is also pinned to the monitor it is assigned to. A pinned workspace can not be moved between monitors when activated or enabled.

The layout index indicates which layout the workspace is to start with by default. The index comes from the layouts array in config.h. Refer to the Layout page for more details on layouts.

The mfact value indicates the master / stack factor that the workspace is to start with by default. This is what controls the size of the master area compared to the stack area in most, but not all, layouts. If this is set to -1 then it will default to whatever the global setting is set to in config.h.

The nmaster value indicates the number of clients that should be placed in the master area for master and stack layouts. If this is set to -1 then it will default to whatever the global setting is set to in config.h.

The nstack value indicates the number of clients that should be placed in the stack area for dual stack layouts. If this is set to -1 then it will default to whatever the global setting is set to in config.h.

The gaps value indicates whether or not gaps are enabled for the workspace. If this is set to -1 then it will default to whatever the global enablegaps setting is set to in config.h.

For information on workspace colour schemes, represented by the next four fields of each workspace rule, refer to the Workspace bar module.

For information on workspace icons, represented by the last three fields of each workspace rule, refer to the Workspace bar module.

Keybindings

Refer to the WSKEYS macro in config.h for instructions on how to add keybindings for additional workspaces.

Refer to the Workspace module for instructions for how to change button bindings to handle clicks on workspace icons in the bar.

Monitor distribution

This section documents some special features when it comes to how workspaces are distributed across the available monitors in a multi-monitor setup.

To give a more complete picture the examples provided here assumes a three monitor setup with indices of 0, 1 and 2.

Scenario 1) - Startup

Workspaces are created based on the workspace rules listed earlier. If the monitor attribute matches the index of an existing monitor then the workspace will be assigned to that monitor.

Example cases:

• -1 - the workspace will be distributed evenly
• 2 - the workspace will be assigned to the monitor with index 2
• 3 - the workspace will be distributed evenly as no monitor with index 3 exists

It should be noted that the pinned attribute is only taken into account if the workspace is directly assigned to a monitor via workspace rules.

Once all the workspaces have been created the remaining workspaces that have not yet been assigned to a monitor will be evenly distributed. How many workspaces that have already been assigned to a monitor via workspace rules do not influence the distribution of the remaining workspaces.

The remaining workspaces are distributed to each monitor in order, i.e. monitor 0 will get the first workspace, monitor 1 will get the next, monitor 2 will get the one after that, then it goes back to 0.

If all nine workspaces are distributed this way then you will end up with:

• monitor 0 having workspaces 1, 4 and 7
• monitor 1 having workspaces 2, 5 and 8
• monitor 2 having workspaces 3, 6 and 9

Scenario 2) - Removing monitor 2 (hotplugging)

If a monitor is removed or deactivated via xrandr then all workspaces that were assigned to monitor 2 will be moved to monitor 0 and marked as not being shown / active.

The rationale behind this is that:

• monitor 0 and monitor 1 should already have workspaces that are shown and
• dumping all the workspaces that were on monitor 2 on monitor 0 seems more intuitive than evenly distributing the workspaces across the remaining monitors

If any of the workspaces being moved were pinned to monitor 2 then those workspaces will lose their pinned status. The rationale here is that the workspace was pinned specifically to workspace 2 and not to the monitor it is being moved to.

---

It is worth noting that dusk does not auto-detect an HDMI cable being inserted for example so simply removing a display cable would not trigger the above scenario. Run in the new xrandr configuration for the above to come into effect.

If you are looking for auto-detection of display changes then refer to autorandr or look up guides for setting up udev rules to do this.

---

Scenario 3) - Adding monitor 2 again (hotplugging)

If a monitor is added or activated via xrandr then workspaces will be subject to redistribution across the available monitors.

The redistribution is subject to the following rules:

• if the workspace rule for the workspace had a monitor attribute that matches that of the new monitor then that workspace will be assigned to that monitor
  • if the workspace rule also had a pinned attribute then the workspace will be pinned to the new monitor
• the remaining workspaces will be redistributed evenly across the available monitors
  • if a workspace is pinned then it will lose that attribute

The distribution of the remaining workspaces happens as outlined in scenario 1.

Scenario 4) - Restarting

When doing a live restart of dusk the workspaces will remain associated with the same monitors that they were assigned to before the restart took place.

Functions

Here is a list of functions relating to workspaces.

Function	Description
enablews	Enables or disables a workspace by right-clicking the workspace icon on the bar
enablewsbyindex	Enables the nth workspace on the current monitor in addition to the current workspace
enablewsbyname	Enables the workspace with a given name in addition to the current workspace
comboviewwsbyindex	Changes the view to one or more workspace with a given index on the current monitor
comboviewwsbyname	Changes the view to one or more workspace with a given name
movews	Move a client window to another workspace by clicking on the workspace icon on the bar
movewsdir	Move a client to the workspace on the immediate left or right of the active workspace
movetowsbyindex	Moves the currently active window to the workspace with a given name
movetowsbyname	Moves the currently active window to the workspace with a given name
movealltowsbyindex	Moves all windows on the current workspace to the nth workspace on the current monitor
movealltowsbyname	Moves all windows on the current workspace to a workspace with a given name
moveallfromwsbyindex	Moves all windows from the nth workspace on the current monitor to the current workspace
moveallfromwsbyname	Moves all windows from a workspace with a given name to the current workspace
sendtowsbyindex	Moves the currently active window to the workspace with a given name while inverting ViewOnWs functionality
sendtowsbyname	Moves the currently active window to the nth workspace on the current monitor while inverting ViewOnWs functionality
swapws	Swaps all clients on the current workspace with all clients on another workspace by clicking on the workspace icon on the bar
swapwsbyindex	Swaps all clients on the current workspace with all clients on the nth workspace on the current monitor
swapwsbyname	Swaps all clients on the current workspace with all clients on the workspace with a given name
togglepinnedws	Used to pin or unpin the current workspace to / from the current monitor
togglews	Toggle to the previously viewed workspace on the current monitor
viewallwsonmon	View all workspaces assigned to the current monitor
viewalloccwsonmon	View all workspaces assigned to the current monitor that have clients
viewselws	Change the view to only show the workspace of the selected client
viewws	View a workspace by left-clicking on the workspace icon on the bar
viewwsbyindex	Changes the view to the the nth workspace on the current monitor
viewwsbyname	Changes the view to the the workspace with a given name
viewwsdir	View the workspace on the immediate left or right of the active workspace

Functionality

Here is a list of functionality that are related to workspaces.

Functionality	Description
ViewOnWs	Follow a window to the workspace it is being moved to
GreedyMonitor	Disables swap of workspaces between monitors

Flags

Here is a list of flags that are related to workspaces.

Flag	Description
SwitchWorkspace	Automatically moves you to the workspace of the newly opened application
EnableWorkspace	Enables the workspace of the newly opened application in addition to your existing viewed workspaces
RevertWorkspace	If SwitchWorkspace or EnableWorkspace, closing that window reverts the view back to what it was previously

---

Back to Features.