DtWsmGetWorkspaceInfo(library call)									       DtWsmGetWorkspaceInfo(library call)

NAME

       DtWsmGetWorkspaceInfo -- get detailed workspace information

SYNOPSIS

       #include <Dt/Wsm.h>
       int 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  (con-
					     verted 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  man-
					     agement  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, dtwm(1),
					     is  running.  The	title is
					     different	   from      the
					     workspace	   name.     The
					     workspace name,  when  con-
					     verted  from  an X atom, is
					     used as the identifier  for
					     a	  workspace    in    the
					     workspace manager	function
					     calls.  The  CDE  workspace
					     manager, dtwm(1). also uses
					     the  workspace  name  as  a
					     resource  name;  thus,  the
					     characters    used   in   a
					     workspace	   name      are
					     restricted  to  the charac-
					     ters  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, dtwm(1).
       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

       Dt/Wsm.h - DtWsm(5),  dtwm(1), DtWsmGetWorkspaceList(3), DtWsmFreeWorkspaceInfo(3).

													       DtWsmGetWorkspaceInfo(library call)