368 lines
15 KiB
Plaintext
368 lines
15 KiB
Plaintext
<!-- $XConsortium: ch06.sgm /main/7 1996/10/30 15:04:48 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<Chapter Id="PG.wsmgr.div.1">
|
|
<Title Id="PG.wsmgr.mkr.1">Integrating with the Workspace Manager</Title>
|
|
<Para>The<IndexTerm>
|
|
<Primary>Workspace Manager</Primary>
|
|
<Secondary>integrating with</Secondary>
|
|
</IndexTerm>
|
|
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:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Place the application's windows in one or more workspaces</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Identify the workspaces in which the application's windows are located</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Prevent the application's windows from moving to another workspace</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Monitor changes to the workspaces, such as when a user switches from one
|
|
workspace to another</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para>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.</Para>
|
|
<Para>See
|
|
<!--Original XRef content: 'Chapter 4, &xd2;Integrating with Session Manager'--><XRef Role="ChapNumAndTitle" Linkend="PG.smgr.mkr.1"> for details on saving
|
|
application-related information between sessions.</Para>
|
|
<InformalTable Id="PG.wsmgr.itbl.1" Frame="All">
|
|
<TGroup Cols="1">
|
|
<ColSpec Colname="1" Colwidth="4.0 in">
|
|
<TBody>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Communicating with the Workspace Manager64'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.2"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Placing an Application Window in Workspaces64'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.3"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Identifying Workspaces Containing the Application Windows65'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.4"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Preventing Application Movement Among Workspaces66'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.5"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Monitoring Workspace Changes67'--><XRef Role="JumpText" Linkend="PG.wsmgr.mkr.6"></Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</InformalTable>
|
|
<Sect1 Id="PG.wsmgr.div.2">
|
|
<Title Id="PG.wsmgr.mkr.2">Communicating with the<IndexTerm>
|
|
<Primary>Workspace Manager</Primary>
|
|
<Secondary>communicating with</Secondary>
|
|
</IndexTerm> Workspace Manager</Title>
|
|
<Para>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:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para><Command>DtWsmAddCurrentWorkspaceCallback</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmAddWorkspaceFunctions</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmAddWorkspaceModifiedCallback</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmFreeWorkspaceInfo</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmGetCurrentBackdropWindows</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmGetCurrentWorkspace</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmGetWorkspaceInfo</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmGetWorkspaceList</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmGetWorkspacesOccupied</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmOccupyAllWorkspaces</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmRemoveWorkspaceCallback</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmRemoveWorkspaceFunctions</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmSetCurrentWorkspace</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>DtWsmSetWorkspacesOccupied</Command></Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para>Segments of code from two demo programs (<Filename>occupy.c</Filename> and <Filename>wsinfo.c</Filename>)
|
|
illustrate the use of these functions. Listings for <Command>occupy.c, wsinfo.c</Command>, and
|
|
makefiles for several brands of workstations are in the directory
|
|
<Filename>/usr/dt/examples/dtwsm</Filename>. See the applicable man page for more
|
|
information on each function.</Para>
|
|
</Sect1>
|
|
<Sect1 Id="PG.wsmgr.div.3">
|
|
<Title Id="PG.wsmgr.mkr.3">Placing an Application Window in<IndexTerm>
|
|
<Primary>workspace</Primary>
|
|
<Secondary>placing application window in</Secondary>
|
|
</IndexTerm> Workspaces</Title>
|
|
<Para>An application can place its windows in any or all of the existing workspaces.
|
|
<Command>DtWsmOccupyAllWorkspaces</Command> places the windows in all currently defined
|
|
workspaces, while <Command>DtWsmSetWorkspacesOccupied</Command> places the windows in
|
|
all workspaces named in a list that is passed to the function.</Para>
|
|
<Sect2 Id="PG.wsmgr.div.4" Role="Procedure">
|
|
<Title>To Place an Application Window in All Workspaces</Title>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Use <Command><IndexTerm>
|
|
<Primary>DtWsmOccupyAllWorkspaces</Primary>
|
|
</IndexTerm>DtWsmOccupyAllWorkspaces</Command>.</Para>
|
|
<Para>In <Filename>occupy.c</Filename>, the callback <Command>allWsCB</Command> for the Occupy All Workspaces push
|
|
button calls this function.</Para>
|
|
<ProgramListing>DtWsmOccupyAllWorkspaces (XtDisplay(toplevel),
|
|
XtWindow(toplevel));</ProgramListing>
|
|
<Para>where:</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Filename>XtWindow(toplevel)</Filename> is the window to be placed in all workspaces.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<Para>See the <Command>DtWsmOccupyAllWorkspaces</Command> man page for more information on this
|
|
function.</Para>
|
|
</Sect2>
|
|
<Sect2 Id="PG.wsmgr.div.5" Role="Procedure">
|
|
<Title>To Place an Application Window in Specified Workspaces</Title>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Use <Command><IndexTerm>
|
|
<Primary>DtWsmSetWorkspacesOccupied</Primary>
|
|
</IndexTerm>DtWsmSetWorkspacesOccupied</Command>.</Para>
|
|
<Para>In <Filename>occupy.c</Filename>, the callback <Command>setCB</Command> for the Set Occupancy push button calls
|
|
this function.</Para>
|
|
<ProgramListing>DtWsmSetWorkSpacesOccupied (XtDisplay(toplevel),
|
|
XtWindow(toplevel), paWsSet, numSet);</ProgramListing>
|
|
<Para>where:</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Filename>XtWindow(toplevel)</Filename> is the window to be placed in the workspaces.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>paWsSet</Command> is a pointer to a list of workspace names that have been
|
|
converted to X atoms.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>numSet</Command> is the number of workspaces in the list.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<Para>See the <Command>DtWsmSetWorkspacesOccupied</Command> man page for more information on
|
|
this function.</Para>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.wsmgr.div.6">
|
|
<Title Id="PG.wsmgr.mkr.4">Identifying<IndexTerm>
|
|
<Primary>workspace</Primary>
|
|
<Secondary>identifying</Secondary>
|
|
</IndexTerm> Workspaces Containing the Application Windows</Title>
|
|
<Para>The function <Command>DtWsmGetWorkspacesOccupied</Command> returns a list of the
|
|
workspaces in which a specified application window resides. In <Filename>occupy.c</Filename>, the
|
|
procedure <Command>ShowWorkspaceOccupancy</Command> calls this function. Based on the results
|
|
of this call, <Command>ShowWorkspaceOccupancy</Command> 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.</Para>
|
|
<Sect2 Id="PG.wsmgr.div.7" Role="Procedure">
|
|
<Title>To Identify Workspaces That Contain the Application Window</Title>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Use <Command><IndexTerm>
|
|
<Primary>DtWsmGetWorkspacesOccupied</Primary>
|
|
</IndexTerm>DtWsmGetWorkspacesOccupied</Command>.</Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<ProgramListing>rval = DtWsmGetWorkspacesOccupied(XtDisplay(toplevel)
|
|
XtWindow(toplevel), &paWsIn, &numWsIn);</ProgramListing>
|
|
<Para>where:</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Filename>XtWindow(toplevel)</Filename> is the window to be searched for in the
|
|
workspaces.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>paWsIn</Command> is the address of a pointer to a list of workspace names that have
|
|
been converted to X atoms.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>numWsIn</Command> is the address of an integer into which the number of
|
|
workspaces in the list is placed.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para>After this call, loops are set up to compare the list of workspaces (found in the
|
|
procedure <Command>SetUpWorkspaceButtons</Command> by <Command>DtWsmGetWorkspaceList</Command>) with
|
|
the list of workspaces in which the application window was found to reside.
|
|
The toggle button resource <Command>XmNset</Command> is set to True for each toggle button that
|
|
represents a workspace in which the application window resides.</Para>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.wsmgr.div.8">
|
|
<Title Id="PG.wsmgr.mkr.5">Preventing<IndexTerm>
|
|
<Primary>workspace</Primary>
|
|
<Secondary>preventing application movement</Secondary>
|
|
</IndexTerm> Application Movement Among Workspaces</Title>
|
|
<Para>The function <Command><IndexTerm>
|
|
<Primary>DtWsmRemoveWorkspaceFunctions</Primary>
|
|
</IndexTerm>DtWsmRemoveWorkspaceFunctions</Command> prevents an application
|
|
from:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Switching from one workspace to another</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Occupying all workspaces</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Being removed from the current workspace</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para><Command>DtWsmRemoveWorkspaceFunctions</Command> does this by making that portion of the
|
|
desktop Workspace Manager (<Command>dtwm</Command>) window menu inactive. The application
|
|
should call <Command>DtWsmRemoveWorkspaceFunctions</Command> before its top-level window
|
|
is mapped because <Command>dtwm</Command> only checks workspace information at the time it
|
|
manages the application's top-level window. If you need to call
|
|
<Command>DtWsmRemoveWorkspaceFunctions</Command> after the application's top-level window
|
|
is managed, then you must first call the Xlib function <Command>XWithdrawWindow</Command>, call
|
|
<Filename>DtWsmRemoveWorkspaceFunctions,</Filename> and then call <Command>XMapWindow</Command> to remap
|
|
the top-level window.</Para>
|
|
<Sect2 Id="PG.wsmgr.div.9" Role="Procedure">
|
|
<Title>To Prevent Movement to Another Workspace</Title>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Use <Command><IndexTerm>
|
|
<Primary>DtWsmRemoveWorkspaceFunctions</Primary>
|
|
</IndexTerm>DtWsmRemoveWorkspaceFunctions</Command>.</Para>
|
|
<ProgramListing>DtWsmRemoveWorkspaceFunctions(XtDisplay(toplevel),
|
|
XtWindow(toplevel));</ProgramListing>
|
|
<Para>where:</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Filename>XtDisplay(toplevel)</Filename> is the X display.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Filename>XtWindow(toplevel)</Filename> is the window for which workspace movement is
|
|
to be prevented.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</ListItem>
|
|
</OrderedList>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.wsmgr.div.10">
|
|
<Title Id="PG.wsmgr.mkr.6">Monitoring<IndexTerm>
|
|
<Primary>workspace</Primary>
|
|
<Secondary>monitoring changes</Secondary>
|
|
</IndexTerm> Workspace Changes</Title>
|
|
<Para>You can monitor workspace changes by using either or both of the following
|
|
functions:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para><Command><IndexTerm>
|
|
<Primary>DtWsmAddCurrentWorkspceCallback</Primary>
|
|
</IndexTerm>DtWsmAddCurrentWorkspaceCallback</Command></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command><IndexTerm>
|
|
<Primary>DtWsmWorkspaceModifiedCallback</Primary>
|
|
</IndexTerm>DtWsmWorkspaceModifiedCallback</Command></Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para><Command>DtWsmAddCurrentWorkspaceCallback</Command> registers an application callback to
|
|
be called whenever the Workspace Manager is switched to a new workspace.
|
|
See the <Filename>DtWsmAddCurrentWorkspaceCallback</Filename>(3) man page for more
|
|
information.</Para>
|
|
<Para><Command>DtWsmWorkspaceModifiedCallback</Command> registers an application callback to be
|
|
called whenever a workspace is added, deleted, or changed. See the
|
|
<Filename>DtWsmWorkspaceModifiedCallback</Filename>(3) man page for more information.</Para>
|
|
<Sect2 Id="PG.wsmgr.div.11" Role="Procedure">
|
|
<Title>To Monitor Workspace Switching</Title>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Use <Command><IndexTerm>
|
|
<Primary>DtWsmAddCurrentWorkspaceCallback</Primary>
|
|
</IndexTerm>DtWsmAddCurrentWorkspaceCallback</Command>.</Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<Para>In the demo program <Filename>wsinfo.c</Filename>, this function is called after the top-level
|
|
widget is realized.</Para>
|
|
<ProgramListing>DtWsmAddCurrentWorkspaceCallback (toplevel, wschangecb, NULL);</ProgramListing>
|
|
<Para>where</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Command>toplevel</Command> is the application's top level widget.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>wschangecb</Command> is the name of the function to be called.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>NULL</Command> is the parameter for client data to be passed to the callback. In this
|
|
case, no data is passed.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect2>
|
|
<Sect2 Id="PG.wsmgr.div.12" Role="Procedure">
|
|
<Title>To Monitor Other Workspace Changes</Title>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Use <Command><IndexTerm>
|
|
<Primary>DtWsmWorkspaceModifiedCallback</Primary>
|
|
</IndexTerm>DtWsmWorkspaceModifiedCallback</Command>.</Para>
|
|
<ProgramListing>DtWsmWorkspaceModifiedCallback (toplevel, wschangecb, NULL);</ProgramListing>
|
|
<Para>where:</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Command>toplevel</Command> is the application's top-level widget.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>wschangecb</Command> is the name of the function to be called.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>NULL</Command> is the parameter for client data to be passed to the callback. In this
|
|
case, no data is passed.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</ListItem>
|
|
</OrderedList>
|
|
</Sect2>
|
|
</Sect1>
|
|
</Chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->
|