# Integrating with the Workspace Manager

The
Workspace Manager provides the means for an application to manage its windows within the desktop's multiple workspace environment. An application can perform four major tasks by communicating with the Workspace Manager:

- Place the application's windows in one or more workspaces

- Identify the workspaces in which the application's windows are located

- Prevent the application's windows from moving to another workspace

- Monitor changes to the workspaces, such as when a user switches from one workspace to another

Normally, Session Manager will get your application main window into the right workspace without your intervention. However, if your application has multiple top-level windows, you should use the Workspace Manager API to figure out where your windows are and save this data as part of your session state.

See PG.smgr.mkr.1 for details on saving application-related information between sessions.

PG.wsmgr.mkr.2
PG.wsmgr.mkr.3
PG.wsmgr.mkr.4
PG.wsmgr.mkr.5
PG.wsmgr.mkr.6

## Communicating with the
Workspace Manager

An application communicates with the Workspace Manager by using functions provided by the desktop. These functions allow you to quickly and easily perform a variety of tasks associated with workspace management. The following is a list of these functions:

- `DtWsmAddCurrentWorkspaceCallback`

- `DtWsmAddWorkspaceFunctions`

- `DtWsmAddWorkspaceModifiedCallback`

- `DtWsmFreeWorkspaceInfo`

- `DtWsmGetCurrentBackdropWindows`

- `DtWsmGetCurrentWorkspace`

- `DtWsmGetWorkspaceInfo`

- `DtWsmGetWorkspaceList`

- `DtWsmGetWorkspacesOccupied`

- `DtWsmOccupyAllWorkspaces`

- `DtWsmRemoveWorkspaceCallback`

- `DtWsmRemoveWorkspaceFunctions`

- `DtWsmSetCurrentWorkspace`

- `DtWsmSetWorkspacesOccupied`

Segments of code from two demo programs (`occupy.c` and `wsinfo.c`) illustrate the use of these functions. Listings for `occupy.c, wsinfo.c`, and makefiles for several brands of workstations are in the directory `/usr/dt/examples/dtwsm`. See the applicable man page for more information on each function.

## Placing an Application Window in
Workspaces

An application can place its windows in any or all of the existing workspaces. `DtWsmOccupyAllWorkspaces` places the windows in all currently defined workspaces, while `DtWsmSetWorkspacesOccupied` places the windows in all workspaces named in a list that is passed to the function.

### To Place an Application Window in All Workspaces

1. Use `
   DtWsmOccupyAllWorkspaces`.

   In `occupy.c`, the callback `allWsCB` for the Occupy All Workspaces push button calls this function.

       DtWsmOccupyAllWorkspaces (XtDisplay(toplevel),
                                 XtWindow(toplevel));

   where:

   - `XtDisplay(toplevel)` is the X display.

   - `XtWindow(toplevel)` is the window to be placed in all workspaces.

See the `DtWsmOccupyAllWorkspaces` man page for more information on this function.

### To Place an Application Window in Specified Workspaces

1. Use `
   DtWsmSetWorkspacesOccupied`.

   In `occupy.c`, the callback `setCB` for the Set Occupancy push button calls this function.

       DtWsmSetWorkSpacesOccupied (XtDisplay(toplevel),
                                   XtWindow(toplevel), paWsSet, numSet);

   where:

   - `XtDisplay(toplevel)` is the X display.

   - `XtWindow(toplevel)` is the window to be placed in the workspaces.

   - `paWsSet` is a pointer to a list of workspace names that have been converted to X atoms.

   - `numSet` is the number of workspaces in the list.

See the `DtWsmSetWorkspacesOccupied` man page for more information on this function.

## Identifying
Workspaces Containing the Application Windows

The function `DtWsmGetWorkspacesOccupied` returns a list of the workspaces in which a specified application window resides. In `occupy.c`, the procedure `ShowWorkspaceOccupancy` calls this function. Based on the results of this call, `ShowWorkspaceOccupancy` changes the appearance of the toggle buttons that represent the workspaces. A check mark appears on every toggle button in whose workspace the application window resides.

### To Identify Workspaces That Contain the Application Window

1. Use `
   DtWsmGetWorkspacesOccupied`.

    rval = DtWsmGetWorkspacesOccupied(XtDisplay(toplevel)
                 XtWindow(toplevel), &paWsIn, &numWsIn);

where:

- `XtDisplay(toplevel)` is the X display.

- `XtWindow(toplevel)` is the window to be searched for in the workspaces.

- `paWsIn` is the address of a pointer to a list of workspace names that have been converted to X atoms.

- `numWsIn` is the address of an integer into which the number of workspaces in the list is placed.

After this call, loops are set up to compare the list of workspaces (found in the procedure `SetUpWorkspaceButtons` by `DtWsmGetWorkspaceList`) with the list of workspaces in which the application window was found to reside. The toggle button resource `XmNset` is set to True for each toggle button that represents a workspace in which the application window resides.

## Preventing
Application Movement Among Workspaces

The function `
DtWsmRemoveWorkspaceFunctions` prevents an application from:

- Switching from one workspace to another

- Occupying all workspaces

- Being removed from the current workspace

`DtWsmRemoveWorkspaceFunctions` does this by making that portion of the desktop Workspace Manager (`dtwm`) window menu inactive. The application should call `DtWsmRemoveWorkspaceFunctions` before its top-level window is mapped because `dtwm` only checks workspace information at the time it manages the application's top-level window. If you need to call `DtWsmRemoveWorkspaceFunctions` after the application's top-level window is managed, then you must first call the Xlib function `XWithdrawWindow`, call `DtWsmRemoveWorkspaceFunctions,` and then call `XMapWindow` to remap the top-level window.

### To Prevent Movement to Another Workspace

1. Use `
   DtWsmRemoveWorkspaceFunctions`.

       DtWsmRemoveWorkspaceFunctions(XtDisplay(toplevel),
                                     XtWindow(toplevel));

   where:

   - `XtDisplay(toplevel)` is the X display.

   - `XtWindow(toplevel)` is the window for which workspace movement is to be prevented.

## Monitoring
Workspace Changes

You can monitor workspace changes by using either or both of the following functions:

- `
  DtWsmAddCurrentWorkspaceCallback`

- `
  DtWsmWorkspaceModifiedCallback`

`DtWsmAddCurrentWorkspaceCallback` registers an application callback to be called whenever the Workspace Manager is switched to a new workspace. See the `DtWsmAddCurrentWorkspaceCallback`(3) man page for more information.

`DtWsmWorkspaceModifiedCallback` registers an application callback to be called whenever a workspace is added, deleted, or changed. See the `DtWsmWorkspaceModifiedCallback`(3) man page for more information.

### To Monitor Workspace Switching

1. Use `
   DtWsmAddCurrentWorkspaceCallback`.

In the demo program `wsinfo.c`, this function is called after the top-level widget is realized.

    DtWsmAddCurrentWorkspaceCallback (toplevel, wschangecb, NULL);

where

- `toplevel` is the application's top level widget.

- `wschangecb` is the name of the function to be called.

- `NULL` is the parameter for client data to be passed to the callback. In this case, no data is passed.

### To Monitor Other Workspace Changes

1. Use `
   DtWsmWorkspaceModifiedCallback`.

       DtWsmWorkspaceModifiedCallback (toplevel, wschangecb, NULL);

   where:

   - `toplevel` is the application's top-level widget.

   - `wschangecb` is the name of the function to be called.

   - `NULL` is the parameter for client data to be passed to the callback. In this case, no data is passed.