DtWsmGetWorkspaceInfo(3)

NAME
DtWsmGetWorkspaceInfo - get detailed workspace information

SYNOPSIS
#include <Dt/Wsm.h>

Status DtWsmGetWorkspaceInfo(Display *display,
	Window root,
	Atom aWorkspace,
	DtWsmWorkspaceInfo **ppWsInfo);

DESCRIPTION
The DtWsmGetWorkspaceInfo() function works with the CDE workspace manager, dtwm(1), and returns detailed information on a specific workspace.

The display argument is the X display.

The root argument is the root window of the screen of interest.

The aWorkspace argument is the workspace name (converted to an X atom).

The *ppWsInfo argument is the address of a variable to receive the returned pointer to the workspace information data.

The DtWsmWorkspaceInfo structure contains at least the following members:
Atom | workspace | The workspace name (converted to an X atom).
unsigned long | bg | The pixel ID used for the background color of the backdrop.
unsigned long | fg | The pixel ID used for the foreground color of the backdrop.
Atom | backdropName | The backdrop file name (converted to an X atom). The file must be in either X Bitmap file format (with extension .bm) or X Pixmap file format (with extension .pm). The workspace management services look for the file along the same path used for searching icons. The directory /usr/dt/backdrops is the default directory if the file cannot be found along the icon search path.
int | colorSetId | The colorset number used for this workspace, which affects the backdrop color and the button color for this workspace on the front panel.
char | *pchTitle | The title displayed in the button for this workspace on the front panel. This string is interpreted in the locale in which the CDE workspace manager, is running. The title is different from the workspace name. The workspace name, when converted from an X atom, is used as the identifier for a workspace in the workspace manager function calls. The CDE workspace manager, also uses the workspace name as a resource name; thus, the characters used in a workspace name are restricted to the characters in the X Portable Character Set. The workspace name for a workspace created from the front panel is generated automatically by the CDE workspace manager,
Window | *backdropWindows | A pointer to an array of windows that make up the backdrop.
int | numBackdropWindows | The number of elements in the backdropWindows array.

RETURN VALUE
Upon successful completion, the DtWsmGetWorkspaceInfo() function returns Success and the workspace manager returns in *ppWsInfo a pointer to a DtWsmInfo structure that contains information about the workspace aWorkspace; otherwise, it returns a value not equal to Success.

APPLICATION USAGE
If the DtWsmGetWorkspaceInfo() function is not successful, failure may be due to a memory allocation error or failure to find the correct workspace information (that is, the CDE workspace manager, dtwm(1), is not running). The application must use the DtWsmFreeWorkspaceInfo(3) function to free the data returned in *ppWsInfo. The *backdropWindows pointer may be useful for applications that are interested in some events on the root window. Since the backdrop covers the root window, the backdrop catches the button events before they reach the root.

SEE ALSO
DtWsm(5), dtwm(1), DtWsmGetWorkspaceList(3), DtWsmFreeWorkspaceInfo(3).