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,
                                          dtwm(1), 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, dtwm(1).
                                          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, 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
          DtWsm(5), dtwm(1), DtWsmGetWorkspaceList(3),
          DtWsmFreeWorkspaceInfo(3).