Novell, Inc.       OpenDoc ToolSpace Design and API        03-20-95

Overview

The OpenDoc tool space management sub-system is a mechanism through
which a part can request and allocate space to be used for toolbars,
status bars, scrollbars, tool palettes, etc. 

Tool space is managed by one instance of a tool space class.  It
manages tool space for six different domains:

   DeskTop tool space   - tool space within the frame window 
                          (Windows MDI) or the desktop (Mac)

   Document tool space  - tool space within a document window

   Root tool space      - tool space within a document window owned 
                          by the root part

   PartFrame tool space - tool space around the edge of a frame's 
                          facet

   Status Tool          - tool space provided for status tool bar 
                          functions 

   Status Text          - tool space provided for status text 
                          display
   
Within each of these domains there are different positions for tool
space.  For example, within the document, DeskTop and Root tool
space domains there is left, top, right, bottom and float positions. 
Within the PartFrame, Status Tool and Status Text  domains there is
left, top, right and bottom positions.

The session object owns the tool space manager object.  The tool
space manager object keeps a list of all tool spaces it is
responsible for.  Tool spaces are implemented as an instance of a
tool space object class.  Each tool space object has an associated
window that is an instance of an ODWindow derived class
(ODToolWindow).  This window object handles messaging and updating. 

A part that needs tool space will obtain the tool space manager
object from the session object and request space from the tool space
manager object.  If the request succeeds, the part can ask for the
space to be created.  Once the tool space is created the requesting
part can use the tool space for toolbars, palettes, scroll bars,
etc.

Obtaining ToolSpace Manager Object

A part asks the session object for the toolSpace manager object via
the method call, GetToolSpaceManager().

ToolSpace Requesting

Requesting Part:
A part requests toolSpace for a particular toolSpace domain
(desktop, document, partFrame, etc.) through the toolSpace manager
object using an initialized ODToolSpaceRect via the method call,
RequestToolSpace(aToolSpaceDomain, partFrameShape, requestedSpace). 
The partFrameShape argument is used only for PartFrame tool space
requests. If the request is successful, the part asks the toolSpace
manager object to allocate the space requested via the method call,
CreateToolSpace(aToolSpaceDomain, requestingPart, requestedSpace,
partFrameShape).  The partFrameShape argument is used only for
PartFrame tool space creation. If the request fails, a part can get
the available space from the toolSpace manager via the method call,
GetAvailableSpace(aToolSpaceDomain).  GetAvailableSpace returns an
ODShape pointer that is set to the available space.  A part can use
this space to determine the best possible location for it's tool
space needs.  A part can always obtain floating tool space.

ToolSpace Manager:
The  toolSpace manager receives a request for tool space from a part
via the method call, RequestToolSpace(aToolSpaceDomain,
partFrameShape, requestedSpace). The toolSpace manager checks the
requested space against its list of existing toolSpace objects
within the given domain to see if the space is available. If the
space is available the toolSpace manager returns the value, kODTrue.
If the space is not available the toolSpace manager returns the
value, kODFalse.

ToolSpace Creation

Space is created by the toolSpace manager via a call to the method,
CreateToolSpace(aToolSpaceDomain, requestingPart, requestedSpace,
partFrameShape).  The partFrameShape argument is used only for
PartFrame toolSpace creation.  The requestedSpace argument is an
instance of an ODToolSpaceRect data type.  This data type is defined
as a struct with four ODCoordinate fields and one ODRect field
defining the desired left, top, right and  bottom widths and a
floating toolSpace rect within the specified domain.  A part should
set one or more of these fields to represent the space that it
desires within a toolSpace domain.  The space is interpreted as a 
relative value within the realm of the toolSpace domain.  For
example, the space for desktop toolSpace is relative to the outside
edge of the screen (Mac) or the frame window (Windows MDI).  The
space for document or root toolSpace is relative to the client area
of a document window.  The space for PartFrame toolSpace is relative
to outside edge of the partFrameShape argument. The toolSpace
manager checks to see if the space requested is available through
the method call, RequestToolSpace(aToolSpaceDomain, partFrameShape,
requestedSpace). If the space is available, the space is created. 
If the request is for document or root tool space, and the request
is for non-floating tool space, the toolSpace manager moves and
resizes the root facet to provide room for the requested space, adds
the space to its list of toolSpace objects and returns a valid
toolSpace object. If the space is not available, the toolSpace
manager returns kODNULL.

ToolSpace Updating

ToolSpace updating is handled by the toolSpace window via the normal
OpenDoc messaging protocol.  

ToolSpace Frames and Facets

A particular toolSpace window will create a root frame and facet
that will be assigned  to the requesting part.  The part can then
handle the frame and facet in the same manner as any other frame or
facet.  The only difference is the presentation type which is
defined as, kPresentationToolSpace.

ToolSpace Focus

Focus for a particular toolSpace domain is requested in the same
manner as menu focus, selection focus, etc.

ToolSpace Resizing

A toolSpace can be resized and/or moved via the method call,
SetToolSpaceSizePos(aToolSpaceObject, newLeft, newTop, newWidth,
newHeight, newPosition).

ToolSpace Moving

ToolSpace dragging is handled by the toolSpace manager via the
method call, TrackDrag(aToolSpaceObject, downPoint, finalPosition,
aFeedBackProc).  TrackDrag returns the position (left, top, right,
bottom, float) of the drop and sets finalPosition to the size and
location of  the drop.  The argument, aFeedBackProc, is optional and
can be set to a custom procedure to handle rendering of the space as
it is dragged.  Once TrackDrag has returned, a part can decide if it
wants to honor the drop and move the space via the method call,
SetToolSpaceSizePos(aToolSpaceObject, newLeft, newTop, newWidth,
newHeight, newPosition).
APIs:

ODWinSession:

ODToolSpaceManager* GetToolSpaceManager(void);

ODToolSpaceManager:

struct ODToolSpaceRect
{
    ODCoordinate    left;
    ODCoordinate    top;
    ODCoordinate    right;
    ODCoordinate    bottom;
    ODRect          floatRect;
                
    ODToolSpaceRect( )          { }
    ODToolSpaceRect( ODCoordinate l, ODCoordinate t,
           ODCoordinate r, ODCoordinate b, ODRect* aFloatRect )
           {left=l; top=t; right=r; bottom=b; floatRect =  
           *aFloatRect;}
    ODBoolean IsEmpty() const;
    void Set(ODCoordinate l, ODCoordinate t, ODCoordinate r, 
             ODCoordinate b, ODRect* aFloatRect);
    void Clear(void);
 };

typedef void (WINAPI *ToolDragFeedbackProc)(ODPlatformCanvas 
              aPltFrmCanvas, ODRgnHandle feedBackRgn, 
              ODBoolean erase);

#define kODTSNULL                     0x0000
#define kODTSLeft                     0x0001
#define kODTSTop                      0x0002
#define kODTSRight                    0x0004
#define kODTSBottom                   0x0008
#define kODTSFloat                    0x0010

enum ODToolSpaceDomain {
 kODNoDomain,
 kODDeskTop,
 kODDocument,
 kODRootPart,
 kODPartFrame,
 kODStatusTool,
 kODStatusText
};

typedef ODUShort ODToolSpacePos;

ODBoolean RequestToolSpace(ODToolSpaceDomain tsDomain, 
                           ODShape* partFrameShape, 
                           ODToolSpaceRect* requestedSpace);

ODToolSpaceObj* CreateToolSpace(ODToolSpaceDomain tsDomain, 
                                ODPart* requestingPart, 
                                ODToolSpaceRect* requestedSpace, 
                                ODShape* partFrameShape);

ODShape* GetExistingToolSpace(ODToolSpaceDomain tsDomain, 
                              ODBoolean includeFloat);

ODShape* GetAvailableSpace(ODToolSpaceDomain tsDomain);

void RemoveToolSpace(ODToolSpaceObj* aTSObj);

void DocWindowResized(ODPlatformWindow aDocumentWindow);

ODBoolean SetToolSpaceSizePos(ODToolSpaceObj aTSObj, 
                              ODCoordinate newLeft,
                              ODCoordinate newTop, 
                              ODCoordinate newWidth, 
                              ODCoordinate newHeight, 
                              ODToolSpacePos newPosition);

ODToolSpacePos TrackDrag(ODToolSpaceObj aTSObj, Point downPoint, 
                         ODToolSpacePos* finalPosition,        
                         ToolDragFeedbackProc aFeedBackProc);

ODRgnHandle GetHotZoneRgn(ODToolSpaceObj* aTSObj, 
                          ODToolSpacePos thePos);

