Common Desktop Environment: Programmer's Guide

6 Integrating with the
Workspace Manager

Contents of Chapter:
Communicating with the Workspace Manager
Placing an Application Window in Workspaces
To Place an Application Window in All Workspaces
To Place an Application Window in Specified Workspaces
Identifying Workspaces Containing the Application Windows
To Identify Workspaces That Contain the Application Window
Preventing Application Movement Among Workspaces
To Prevent Movement to Another Workspace
Monitoring Workspace Changes
To Monitor Workspace Switching
To Monitor Other Workspace Changes
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:

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 Chapter 4, "Integrating with Session Manager," for details on saving application-related information between sessions.

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:

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

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

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

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:

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

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 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

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

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.

Generated with CERN WebMaker