The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/source/bento/headers/frame.h

C/C++ Source or Header | 1994-03-02 | 15.3 KB | 435 lines

/*
    File:        XMPFrame.h

    Contains:    Definition of class XMPFrame

    Written by:    Joshua Susser & Sepp Friedrich

    Copyright:    ⌐ 1993 by Apple Computer, Inc., all rights reserved.

    Change History (most recent first):

        <29>     2/14/94    JBS        RADAR bug# 1143608 - remove SetRoot(),
                                    SetOverlaid(), fUsesCachedImage & accessors
        <28>      2/2/94    RR        Added isRoot to InitFrame
        <27>      2/2/94    NP        Added methods and XMPLinkStatus type for
                                    new linking protocol APIs.
        <26>     1/27/94    VL        Added CloneTo.
        <25>     1/15/94    VL        Added fGettingPart to prevent recursive
                                    GetPart.
        <24>     1/13/94    JBS        add fIsSubframe, IsSubframe(),
                                    SetSubframe()
        <23>     1/11/94    Té        Init... changes
        <22>    12/21/93    JBS        InitFrame with viewType & presentation
        <21>    12/15/93    JBS        remove fActiveShape, fWindow
        <20>    12/14/93    Té        InitFrame changes
        <19>    11/19/93    PH        Add virtual keyword and fix for ASLM
        <18>    11/18/93    JBS        add fWindow and accessors
        <17>    11/16/93    JBS        remove fHighlight, add fViewType and
                                    get/set
        <16>    11/12/93    JBS        use Facets
        <15>    10/12/93    PH        Remove DragDrop.h
        <14>     9/30/93    PH        Support new Drag and Drop protocol
        <13>     9/29/93    Té        with RCR, added Close()
        <12>     9/29/93    VL        Added InitializePersistent.
        <11>     9/21/93    PH        Remove De/RegisterDroppableFrame
        <10>     9/17/93    JBS        added fIsDroppable & fIsDragging &
                                    get/setters
         <9>      9/3/93    JBS        removed fWindow, fCanvas; added fLayout
         <8>     8/10/93    PH        Add release
         <7>      8/9/93    NP        Added class id string.
         <6>      8/6/93    JBS        add fHighlight and related methods
         <5>      7/8/93    JBS        replaced with prototype version

        <45>     5/13/93    JBS        add ChangeActiveShape()
        <44>      5/7/93    JBS        namesmith
        <43>     4/29/93    JBS        8.3 file names
        <42>     4/28/93    JBS        8.3 file names
        <39>     4/19/93    NP        NameSmithing.
        <38>     4/19/93    NP        NameSmithing.
        <37>     4/19/93    NP        Namesmithing.
        <36>      4/1/93    SF        privatized constructor/destructor/initialize
        <35>      4/1/93    SF        Updated "Theory of Operation"
        <34>     3/30/93    SF        Correct constructor/Internalize usage and removal of Restore
        <33>     3/29/93    SF        new GetAggregateClipShape().
        <32>     3/29/93    JBS        add IntersectClipShape()
        <31>     3/23/93    SF        subclass of XMPObject
        <30>     3/22/93    SF        Creation broke up into XMPFrame(), Initialize / Restore
        <29>     3/19/93    SF        Changed ChangedFrameShape to ChangeFrameShape ChangedUsedShape
                                    to ChangeUseShape; ChangeFrameShape returns void now.
        <28>     3/18/93    SF        Changed names: NotifyReshape->ChangedUsedShape;
                                    Reshape->ChangedFrameShape; Added: RequestFrameShape
        <27>     3/11/93    SF        Removed fCachedPresentation, XMPImage, fInvalidShape, and
                                    Get/SetCachedRepresentation
        <26>     3/11/93    SF        Reshape returns a Shape
        <25>     3/10/93    SF        don't know any more
        <24>      3/2/93    SF        Removed 2 creation function; made remaining creators temporarly
                                    public for Window.cp and ContainingPartRCR.cp
        <23>      3/2/93    SF        update with March 1 API documentation
        <22>     2/26/93    TIé        remove partInfo from XMPFrame constructor
        <21>     2/25/93    VL        XMPFrame::DragLeave takes the mouse position now.
        <20>      2/9/93    SF        Added creation: XMPFrame(XMPStorageUnit* su); changed
                                    GetFrameID() to GetID();
        <19>      2/3/93    SF        Fixed comments.
        <17>      2/3/93    SF        Added "Theory of Operation"
        <16>      2/2/93    SF        remove XMPDisplayFramesIterator()
        <15>      2/2/93    SF        Added protected GetStorageUnit() and GetFrameID(); removed class
                                    XMPEmbeddedFrameIterator;
        <14>      2/1/93    RCR        Merge with prototype shell
        <13>     1/29/93    SF        Changed fInvalid to fCachedTransfomValid + extended usage text
                                    for InvalidateCachedTransform();
        <12>     1/28/93    SF        Changed "...FrameIterator" to "...FramesIterator"
        <11>     1/27/93    SF        Adopt to Richard's JediShell: temporary create
        <10>     1/27/93    SF        return value of Purge: XMPSize; cached transform is now the
                                    composite transform of contained frames with the contained
                                    frame's Inner and this frame's External transfom.
         <9>     1/26/93    VL        Changed __XXXX__ to _XXXX_.
         <8>     1/21/93    SF        Added comments about what to change
         <7>     1/20/93    SF        Added Internalize/Externalize, simple Draw(),
                                     fFrozen, fDisplayMyImage ("as is" and don't
                                    call partHandler). creation/destruction
                                    became protected. friend class XMPDraft.
                                    StorageUnit added to creation parameters.
         <6>     1/16/93    SF        Added creation parameters. Removed get/set
                                     for embedded frames.
                                    Added size parameter for purging. Updated
                                    XMPEmbeddedFrameIterator class.
         <5>     1/12/93    SF        Added class XMPEmbeddedFrameIterator and
                                    creator function in XMPFrame.
         <4>     1/11/93    SF        Moved XMPXform to platform types.
         <3>     1/10/93    SF        Cosmetics
         <2>      1/7/93    SF        Changed headers, names ...
         <1>    12/22/92    SF        first checked in
*/

#ifndef _FRAME_
#define _FRAME_

#ifndef _PSTOBJ_
#include "PstObj.h"    // base class
#endif

#ifndef _XMPTYPES_
#include "XMPTypes.h"
#endif

#ifndef _DRAFT_
#include "Draft.h"    // For XMPDraftKey
#endif

//==============================================================================
// Theory of Operation
//==============================================================================
/*
If an XMPPart╒s contents needs to become visible, it provides to the embedding
XMPPart an XMPFrame with a desired frameShape and an XMPCanvas,  in which╒
coordinate space the frameShape is defined, and an XMPWindow, in which
eventually the XMPPart╒s contents will be rendered.

The embedding XMPPart╒s Part Handler then reshapes the XMPFrame╒s bounding
FrameShape and also sets the ClipShape to be used for clipping drawings or
cached images rendered within the XMPFrame.  It also decides about proper
alignment within its own space and, therefore, sets the XMPFrame╒s External
Transform (c.f. below) accordingly.

The Part Handler having created an XMPFrame object adds it to the XMPWindow╒s
list of visible XMPFrames.

Invalidation concerns two cases:  an XMPFrame╒s XMPTransfom or a (partial) area
of the XMPFrame can be affected as described below.

First, an XMPFrame╒s position and shape within its containing Root XMPFrame
(which is equal to the XMPWindow╒s frame) is determined by its Aggregate
Transfoms, which consists of the Frame╒s External and Internal Transform
pre-composed with the containing Frame╒s Aggregate Transforms.  For
mapping a point given in Window coordinates to a frame╒s local space, XMPFrame
transforms it by using its Aggregate Internal Transform. Similarly, for
representing an XMPShape object, given in a containing Frame╒s coordinate
space, into this Frame╒s coordinate space, the given shape becomes transformed
by applying this Frame╒s External Transform. For this release, it is required
that the local coordinate spaces have the same metric as the Root Frame╒s
canvas. In other words, the Frames╒ associated XMPCanvas objects must have the
same type as the Root Frame╒s XMPCanvas object.  Independently, a part handler
can come up with its own private canvases and mappings to the XMPCanvas object
given to its XMPFrame object.

Whenever a Part Handler for a containing XMPPart changes a contained XMPFrame╒s
External Transform (e.g. moving the XMPFrame to a new position) or the
XMPFrame╒s own Part Handler changes the Internal Transform (e.g. scrolling the
visible XMPPart  contents within the XMPFrame), the XMPFrame╒s Aggregate
Transforms are invalidated or get updated.

Furthermore, to assist a containing Part Handler in finding a fine-tuned
layout between adjacent contained Frames, the UsedShape, set by its Part, may
be used by the embedding Part.  It describes the XMPShape of an XMPFrame which
is used by its actual contents, versus the FrameShape, that reflects rather the
required XMPShape as defined by the contained Part Handler.

ActiveShape, also set by this XMPFrame╒s XMPPart╒s Part Hanlder, defines the
area within the UsedShape which reacts to mouse clicks which it receives when
the Frame is not set to Frozen.

All Shapes are given in their Frame╒s local coordinate space.
*/


//==============================================================================
// Types
//==============================================================================

enum XMPLinkStatus
{
    kXMPInLinkDestination,
    kXMPInLinkSource,
    kXMPNotInLink
};

//==============================================================================
// Classes defined in this interface
//==============================================================================

class XMPFrame;
class XMPFrameFacetIterator;

//==============================================================================
// Classes used by this interface
//==============================================================================

class OrderedCollection;
class OrderedCollectionIterator;
class XMPCanvas;
class XMPDraft;
class XMPFacet;
class XMPPart;
class XMPPersistentObject;
class XMPShape;
class XMPStorageUnit;
class XMPTransform;
class XMPDragItemIterator;
class XMPWindow;

struct XMPPoint;

//==============================================================================
// XMPFrame
//==============================================================================

#define kXMPFrameID "appl:xmpframe$class,1.0.0"

class XMPFrame : public XMPPersistentObject
{
    friend class XMPDraft;
    friend class XMPFrameFacetIterator;

public:

// getters/setters:

    XMPVMethod XMPFrame*    GetContainingFrame();
    XMPVMethod void         SetContainingFrame(XMPFrame* frame);

    XMPVMethod XMPULong        GetFrameGroup();
    XMPVMethod void            SetFrameGroup(XMPULong groupID);

    XMPVMethod XMPBoolean    IsRoot();

    XMPVMethod XMPBoolean    IsSubframe();
    XMPVMethod void            SetSubframe(XMPBoolean isSubframe);

    XMPVMethod XMPBoolean    IsOverlaid();

    XMPVMethod XMPBoolean    IsFrozen();
    XMPVMethod void            SetFrozen(XMPBoolean isFrozen);

    XMPVMethod XMPBoolean    DoesPropagateEvents();
    XMPVMethod void            SetPropagateEvents(XMPBoolean doesPropagateEvents);


// part

    XMPVMethod XMPPart* GetPart();

    XMPVMethod void ChangePart(XMPPart* part);
        // change the part this frame views

    XMPVMethod XMPInfoType    GetPartInfo();
    XMPVMethod void            SetPartInfo(XMPInfoType partInfo);

    XMPVMethod XMPTypeToken GetViewType();
    XMPVMethod void            SetViewType(XMPTypeToken viewType);
        // should be called only by my part
    XMPVMethod void            ChangeViewType(XMPTypeToken viewType);
        // called by container, etc. to request part to change type

    XMPVMethod XMPTypeToken GetPresentation();
    XMPVMethod void            SetPresentation(XMPTypeToken presentation);
        // should be called only by my part
    XMPVMethod void            ChangePresentation(XMPTypeToken presentation);
        // called by container, etc. to request part to change presentation kind

// facets

    XMPVMethod void FacetAdded(XMPFacet* facet);

    XMPVMethod void FacetRemoved(XMPFacet* facet);

    XMPVMethod XMPFrameFacetIterator* CreateFacetIterator();

// shapes:

    // frame shape

    XMPVMethod XMPShape* GetFrameShape();

    XMPVMethod void ChangeFrameShape(XMPShape* shape);
        // Containing Part picks a new Frame Shape for this embedded frame.

    XMPVMethod XMPShape* RequestFrameShape(XMPShape* shape);
        // Embedded Part asks to change the Frame Shape for this frame.

    // used shape

    XMPVMethod XMPShape* GetUsedShape();

    XMPVMethod void ChangeUsedShape(XMPShape* shape);
        // Embedded Part changes the Used Shape of this frame.

// transformations:

    XMPVMethod XMPTransform* GetInternalTransform();

    XMPVMethod void ChangeInternalTransform(XMPTransform* transform);
        // change internalTransform to new value, notify facets of change

// drag&drop:

    XMPVMethod XMPBoolean    IsDroppable();
    XMPVMethod void            SetDroppable(XMPBoolean isDroppable);

    XMPVMethod XMPBoolean    IsDragging();
    XMPVMethod void            SetDragging(XMPBoolean isDragging);

// linking:

    XMPVMethod void                ContentChanged(XMPChangeID change);
    XMPVMethod void                ChangeLinkStatus(XMPLinkStatus status);
    XMPVMethod XMPLinkStatus    GetLinkStatus();

// invalidation/draw:

    XMPVMethod void Invalidate(XMPShape* invalidShape);
        // invalidate the area in all my facets

    XMPVMethod void Validate(XMPShape* validShape);
        // validate the area in all my facets

    XMPVMethod void InvalidateActiveBorder();
        // invalidate the active border on all my facets

    XMPVMethod void DrawActiveBorder();
        // draw the active border on all my facets

// memory management:

    XMPVMethod XMPSize Purge(XMPSize numBytes);        // override
        //    gets rid of any unnecessary memory by purging memory blocks
        //    or flushing structures out to disk.

    XMPVMethod XMPStorageUnit*    CloneTo(XMPDraftKey key, XMPDraft* destDraft);

    XMPVMethod void Externalize();                    // override

// ref counting

    XMPVMethod void Release();                        // override

    XMPVMethod void Close();

        // tell the frame to release references

    XMPVMethod void Remove();

        // tell the frame to release references and remove from Draft

protected:    // only to be called by XMPDraft

    XMPFrame();
    XMPVMethod ~XMPFrame();

    XMPNVMethod void    InitFrame(
                XMPStorageUnit*    storageUnit,
                XMPFrame*         containingFrame,
                XMPShape*         frameShape,
                XMPPart*         part,
                XMPTypeToken    viewType,
                XMPTypeToken    presentation,
                XMPULong         frameGroup,
                XMPBoolean        isRoot,
                XMPBoolean         isOverlaid);

    XMPNVMethod void    InitFrameFromStorage(XMPStorageUnit*    storageUnit);

protected:    // only to be called by XMPFrameFacetIterator

    XMPVMethod OrderedCollection* GetFacets();

protected:

    void    CommonInitFrame();

    XMPFrame*            fContainingFrame;    // parent in frame hierarchy
    OrderedCollection*    fFacets;            // list of current facets

    XMPShape*        fFrameShape;            // basic shape of frame
    XMPShape*        fUsedShape;                // region to wrap around

    XMPTransform*    fInternalTransform;        // viewing transform

    XMPPart*        fPart;                    // part the frame is displaying
    XMPInfoType        fPartInfo;                // data type of part
    XMPTypeToken    fViewType;                // type of view of part (icon, etc.)
    XMPTypeToken    fPresentation;            // kind of frame (content, palette, etc.)

    XMPULong        fFrameGroup;            // ID of group this frame is in

    XMPBoolean        fIsRoot;                // is this a window's root frame?
    XMPBoolean        fIsSubframe;            // is this subframe of conglomerate frame?
    XMPBoolean        fIsOverlaid;            // is this an overlaid frame?
    XMPBoolean        fIsFrozen;                // mouse events go to my containing frame
    XMPBoolean        fIsDroppable;            // accepts drag/drop events
    XMPBoolean        fIsDragging;            // is being dragged
    XMPBoolean        fDoesPropagateEvents;    // frame can't handle delegated events

    XMPBoolean        fGettingPart;            // Semaphore to ensure that GetPart is not called recursively.
};

//==============================================================================
// XMPFrameFacetIterator
//==============================================================================

#define kXMPFrameFacetIteratorID "appl:xmpframefacetiterator$class,1.0.0"

class XMPFrameFacetIterator
{

public:

    XMPFrameFacetIterator(XMPFrame* frame);

    virtual ~XMPFrameFacetIterator();

    XMPVMethod XMPFacet* First();
        // Returns the first visible facet

    XMPVMethod XMPFacet* Next();
        // Returns the next visible facet

    XMPVMethod XMPBoolean IsNotComplete();
        // Returns TRUE as long as there are more facets

    XMPFrame*                    fFrame;
    OrderedCollectionIterator*    fIter;
};

#endif // _XMPFRAME_