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

• "Communicating with the Workspace Manager"

• "Placing an Application Window in Workspaces"

• "Identifying Workspaces Containing the Application Windows"

• "Preventing Application Movement Among Workspaces"

• "Monitoring Workspace Changes"

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

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:

• 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

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

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.