home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Sample Code / CALib & You… / Source / CALib / Interfaces / CPlusPlus / CALib.h < prev   
Encoding:
C/C++ Source or Header  |  1995-12-07  |  16.9 KB  |  477 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        CALib.h
  3.  
  4.     Contains:    Container Application Library header (public)
  5.  
  6.     Written by:    Tantek Çelik, Jens Alfke, Joshua Susser, Steve Foley, Rick Badertscher
  7.  
  8.     Copyright:    © 1994 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <16>     5/12/95    RB        Removing CAOffsetFrame()
  13.          <15>     4/23/95    RB        Added GetFocusOwner() routine.
  14.                                      Added CAFrameRefValid(), CAFrameRefCopy(), CAFrameRefEqual()
  15.  
  16.         <14>      4/19/95    RB        Layout API Renovation
  17.         <13>      4/7/95    SJF        Changes to the DnD API
  18.         <12>      4/7/95    SJF        final cleanup
  19.          <11>     4/05/95    SJF        Strip out definition of data types to CA_Defs.h
  20.          <10>     4/02/95    RB        Integrating changes for b1c14 build
  21.          <9>     4/01/95    RB        Added CAActivateWindowHandler callback to
  22.                                      allow CA to respond when the ODWindowState
  23.                                      activates/deactivates windows.
  24.          <8>     3/27/95    RB        Modified CALib type definitions to
  25.                                      more readable form.
  26.          <7>     3/16/95    RB        Added some comments on the CADoc API
  27.          <6>     3/15/95    SJF        Modify Drag & Drop API
  28.          <4+>     2/28/95    SJF        merge in changes from RickB
  29.          <4>     2/13/95    SJF        Interim checkin to update project database
  30.          <3>    12/19/94    SJF        Clean up API to meet actual CA needs
  31.          <2>    10/30/94    SV        SOMverted
  32.          <1>     4/20/94    jpa        Added error reporting calls.
  33.          <0>     4/19/94    JA        Got it to compile!
  34.          <-1>     3/25/94    JBS        layout, menu & UI fixes
  35.          <-2>     3/21/94    TÇ        use pascal calling conventions, reconcile
  36.                                     CALength into CASize, length as out
  37.                                     parameter in CASaveDocument
  38.          <-3>     3/18/94    JBS        imaging changes, remove XMP-types, install
  39.                                     callbacks
  40.          <-4>     3/17/94    T        first checked in
  41.     To Do:
  42.         - Implement
  43. */
  44.  
  45. #ifndef _CALIB_
  46. #define _CALIB_
  47.  
  48. #ifndef __DRAG__
  49. #include <Drag.h>            // For DragTrackingHandler type, etc.
  50. #endif
  51.  
  52. #ifndef __EDITIONS__
  53. #include <Editions.h>        // For SectionHandle type, etc.
  54. #endif
  55.  
  56. #ifndef _CADEFS_
  57. #include "CADefs.h"
  58. #endif
  59.  
  60.  
  61.  
  62. //=========================================================================
  63. // CALib Public API
  64. //=========================================================================
  65.  
  66. #ifdef __cplusplus
  67. extern "C" {
  68. #endif
  69.  
  70.  
  71. //=========================================================================
  72. // Error reporting
  73. //=========================================================================
  74.  
  75. pascal    OSErr        CAError( void );
  76.  
  77. pascal    CAErrorProc    CASetErrorProc( CAErrorProc proc );
  78.  
  79. //=========================================================================
  80. // Session
  81. //=========================================================================
  82.  
  83. pascal    void    CAInit( void );
  84. pascal    void    CAShutdown( void );
  85.  
  86. //=========================================================================
  87. // Document API
  88. //=========================================================================
  89. //
  90. //    A CA can opt to use one of 2 storage models for CADocuments, 
  91. //
  92. //    Using the Native storage model, CALib writes the ODContainer containing
  93. //  the Proxy part storage into the data fork of the document file.  To save
  94. //    a document, the CA provides a file and an offset to write the ODContainer.
  95. //
  96. //    Using the OpenDoc model, the Application document stream as well as the
  97. //  proxy part ODContainer are stored in a single OpenDoc container file.
  98. //  The CAStream API allows the App to read/write to the embedded document
  99. //  stream.
  100. //
  101. //-------------------------------------------------------------------------
  102.  
  103. //-------------------------------------------------------------------------
  104. // CACreateDocument() : Returns a reference to an empty document.  The
  105. // document may be used as either OpenDoc or Native, the type is
  106. // bound at CASaveDocument() time.
  107. //
  108. // For each CADocument, CALib maintains a temporary container.  The temp container
  109. // may be file or memory based, specified by containerType.
  110. //-------------------------------------------------------------------------
  111. pascal    CADocumentRef    CACreateDocument(        FSSpecPtr             docSpec,
  112.                                                 Handle                docHandle);
  113.  
  114. //-------------------------------------------------------------------------
  115. // CAOpenDocument() : Use offset & length to specify the size and location
  116. // of an embedded OpenDoc Container, for Native storage model.
  117. // For the OpenDoc storage model set offset & length to 0, this indicates
  118. // that the file specified by docSpec is a single OpenDoc container.
  119. //
  120. // A CA may open a CADocument from docHandle.  The CADocument must have
  121. //     been previously saved to memory via CASaveDocument.  offset & length
  122. //  specify the container length and location within docHandle.
  123. //
  124. // For each CADocument, CALib maintains a temporary container.  The temp container
  125. // may be file or memory based, specified by containerType.
  126. //-------------------------------------------------------------------------
  127.  
  128. pascal    CADocumentRef    CAOpenDocument(            FSSpecPtr            docSpec,
  129.                                                 Handle                docHandle,
  130.                                                 CAOffset            offset,
  131.                                                 CASize                length);                                    
  132.  
  133. //-------------------------------------------------------------------------
  134. // CASaveDocument() : For the Native storage model use offset to
  135. //    specify where to write the ODContainer in your file.
  136. //  For the OpenDoc storage model CASaveDocument writes out the entire
  137. //    ODContainer as the file, including the document stream.
  138. //
  139. // A CA may alternatively pass a non-NULL handle in docHandle
  140. //    to save the document to memory.  docHandle must be a non-NULL
  141. //    handle and is realloced internally.  If offset is non-zero, CASaveDocument
  142. //  will preserve the original contents of docHandle's memory.
  143. //-------------------------------------------------------------------------
  144.  
  145. pascal    void             CASaveDocument(            CADocumentRef    document,
  146.                                                 FSSpecPtr        newFile,
  147.                                                 Handle*            docHandle,
  148.                                                 CAOffset        offset,
  149.                                                 CASize*            length);
  150.                                                 
  151. pascal    void             CACloseDocument(        CADocumentRef );
  152.  
  153. pascal    Boolean            CAHasDocumentChanged(    CADocumentRef );
  154.  
  155. pascal    void            CASetDocumentKind(        CADocumentRef document, CAISOStr kind );
  156.  
  157. // CAGetDocumentKind() - The CA should dispose of the result with DisposePtr()
  158.  
  159. pascal    CAISOStr        CAGetDocumentKind(        CADocumentRef document);
  160.  
  161.  
  162. // Multiple Document Kind Support
  163.  
  164. // CAUseKind() - if kind is NULL then index is used.  if there is no such kind
  165. // (the ISOStr passed in doesn't exist, or the index is out of range) then
  166. // FALSE is returned, else TRUE is returned
  167.  
  168. pascal Boolean            CAUseKind(                CADocumentRef document, CAISOStr kind, short index);
  169. pascal CAISOStr            CACurrentKind(            CADocumentRef document);
  170. pascal void                CAAddKind(                CADocumentRef document, CAISOStr kind);
  171. pascal void                CARemoveKind(            CADocumentRef document, CAISOStr kind);
  172. pascal CAISOStr            CAGetNthKind(            CADocumentRef document, short index);
  173. pascal short            CAGetKindCount(            CADocumentRef document);
  174.  
  175.  
  176. //=========================================================================
  177. // Stream
  178. //=========================================================================
  179. // The Stream API is used by a CA implementing the OpenDoc storage model.
  180. //-------------------------------------------------------------------------
  181.  
  182.  
  183. pascal    void    CARead(            CADocumentRef, char* buffer, CASize* length );
  184. pascal    void    CAWrite(        CADocumentRef, char* buffer, CASize* length );
  185. pascal    CASize    CAGetSize(        CADocumentRef);
  186. pascal    CASize    CAGetOffset(    CADocumentRef);
  187. pascal    void    CASetOffset(    CADocumentRef, CASize offset );
  188. pascal    void    CAInsert(        CADocumentRef, char* buffer, CASize* length );
  189. pascal    void    CADelete(        CADocumentRef, char* buffer, CASize* length );
  190.  
  191.  
  192. //=========================================================================
  193. // Data Interchange
  194. //=========================================================================
  195.  
  196. pascal    CACloneKey    CABeginClone(        CADocumentRef    sourceDocument,
  197.                                         CADocumentRef    destDocument,
  198.                                         CACloneKind        cloneKind );
  199.                                         
  200. pascal    void        CAEndClone(            CADocumentRef    sourceDocument,
  201.                                         CADocumentRef    destDocument,
  202.                                         CACloneKey        clonekey );
  203.  
  204. pascal    CAFrameRef    CACloneFrameRef(     CAFrameRef        sourceFrameRef,    
  205.                                         // can be NULL if only one frame in source document
  206.                                         CADocumentRef    sourceDocument,
  207.                                         CADocumentRef    destDocument,
  208.                                         Boolean            isRootFrameRef,
  209.                                         CACloneKey        cloneKey);
  210.  
  211. // when copying a bunch of data from one document to another,
  212. // BeginClone, then Clone the FrameRefs, the stream out native content using
  213. // the newly returned FrameRefs, then EndClone
  214. // if none of the Cloned FrameRefs had isRootFrameRef set to true, then EndClone
  215. // sets the native content as the root.
  216.  
  217. //=========================================================================
  218. // Clipboard
  219. //=========================================================================
  220.  
  221. pascal    CADocumentRef    CAGetClipboardDocument( void );    
  222. pascal    void            CAExportClipboard(        void);
  223.  
  224. // to paste from the clipboard, 
  225. //    CloneFrameRef(clipbdFrameRef,clipbdDocument,destDocument)
  226. // clipbdFrameRef is cloned from the clipboard to destDocument, and its 
  227. // CAFrameRef within the context of destDocument is returned
  228.  
  229. // to copy to the clipboard, 
  230. //    CloneFrameRef(sourceFrameRef,sourceDocument,clipbdDocument)
  231. // sourceFrameRef is cloned from sourceDocument to the clipboard, and its
  232. // CAFrameRef within the context of the clipboard is returned
  233.  
  234. // Use Stream API to write native contents to the ClipDocument
  235.  
  236. //=========================================================================
  237. // Drag and Drop
  238. //=========================================================================
  239.  
  240. pascal    CADocumentRef    CAGetDragDropDocument(    ItemReference    item );
  241.  
  242. pascal    CADropResult    CAStartDrag(            CADocumentRef    document,
  243.                                                 EventRecord*    event,
  244.                                                 RgnHandle        dragRgn);
  245.  
  246. pascal    void            CASetDataSendProc(        CADocumentRef    document,
  247.                                                 DragSendDataUPP sendProc,
  248.                                                 void*            refCon);
  249.  
  250. // for backward compatibilty with Apps which already support Drag Manager
  251.  
  252. pascal    OSErr    CAInstallTrackingHandler(    DragTrackingHandler    trackingHandler,
  253.                                             WindowPtr            window,
  254.                                              void*                handlerRefCon );
  255.                                               
  256. pascal    OSErr    CAInstallReceiveHandler(    DragReceiveHandler    receiveHandler,
  257.                                             WindowPtr            window,
  258.                                             void*                handlerRefCon );
  259.                                             
  260. pascal OSErr     CARemoveTrackingHandler(     DragTrackingHandler trackingHandler,
  261.                                             WindowPtr            theWindow);
  262.  
  263. pascal OSErr     CARemoveReceiveHandler(     DragReceiveHandler    receiveHandler,
  264.                                             WindowPtr            theWindow);
  265.                                  
  266. //=========================================================================
  267. //    Window Management
  268. //=========================================================================
  269.  
  270. pascal    Boolean            CAIsPartWindow(    WindowPtr );
  271.  
  272. pascal    WindowPtr        CAGetFrontDocWindow( void );
  273. pascal    WindowPtr        CAGetFrontFloatingWindow( void );
  274. pascal    void            CASelectWindow(    WindowPtr );
  275.  
  276. pascal    void            CARegisterRootWindow(        WindowPtr,
  277.                                                     CADocumentRef);
  278.  
  279. pascal    void            CARegisterFloatingWindow(    WindowPtr);
  280.  
  281.                                                     
  282. pascal    void            CAUnregisterWindow(            WindowPtr );
  283.  
  284. //=========================================================================
  285. //    Window Management Callbacks (Optional)
  286. //=========================================================================
  287.  
  288.  
  289. // CAWindowActivateHandler - Called when a window is activated, deactivated
  290. //    by the ODWindowState.  OD does not generate activate events. 
  291. pascal    OSErr        CAInstallWindowActivateHandler (CAWindowActivateHandler,
  292.                                                     CADocumentRef);
  293.  
  294.                                          
  295. pascal    OSErr        CAInstallFloatingWindowHandlers (    CASelectWindowHandler    handler1,
  296.                                                         CAFrontWindowHandler    handler2,
  297.                                                         CAIsFloaterHandler        handler3);
  298.  
  299. //=========================================================================
  300. // Focus Arbitration
  301. //=========================================================================
  302.  
  303.  
  304. pascal    Boolean        CARequestStandardFocusSet(        WindowPtr window );
  305. pascal    Boolean        CARequestModalFocus(            WindowPtr window );
  306.  
  307. pascal    void        CARelinquishStandardFocusSet(     WindowPtr window );
  308. pascal    void        CARelinquishModalFocus(            WindowPtr window );
  309.  
  310. // callbacks
  311. pascal    void        CAInstallFocusNotification(     CAFocusAcquiredProc    focusAquiredProc,
  312.                                                     CAFocusLostProc      focusLostProc,
  313.                                                     CADocumentRef        document );
  314.  
  315.  
  316.  
  317. //=========================================================================
  318. // Layout
  319. //=========================================================================
  320. //
  321. // A frame which is visible has a CAVisFrame associated with it.
  322. //
  323.  
  324. // Embedded Frame callbacks
  325.  
  326. pascal    void        CAInstallFrameShapeRequestHandler (    CAFrameShapeRequestHandler handler,
  327.                                                         CADocumentRef    document);
  328.                                                     
  329.  
  330. // Frame manipulation
  331. //
  332. // The transform associated with a frame represents the scrolled position
  333. // of it's contents.
  334. //
  335. // CASetFrameRgn() & CASetFrameTransform() consume RgnHandle & CATransform
  336. //   respectively
  337.  
  338. pascal    CAFrameRef    CAGetRootFrameRef(        CADocumentRef    document);
  339.  
  340. pascal    void        CARemoveFrameRef(        CADocumentRef    document,
  341.                                             CAFrameRef        frame );
  342.  
  343. pascal    RgnHandle    CAGetFrameRgn(            CADocumentRef    document,
  344.                                             CAFrameRef        frame );
  345.                                             
  346. pascal    void        CASetFrameRgn(            CADocumentRef    document,
  347.                                             CAFrameRef        frame,
  348.                                             RgnHandle        frameRgn );
  349.                                             
  350. pascal    RgnHandle    CAGetUsedRgn(            CADocumentRef    document,
  351.                                             CAFrameRef        frame );
  352.  
  353. pascal    void        CAGetFrameTransform(    CADocumentRef    document,
  354.                                             CAFrameRef        frameRef,
  355.                                             CATransform*    transform );
  356.                                             
  357. pascal    void        CASetFrameTransform(    CADocumentRef    document,
  358.                                              CAFrameRef        frameRef,
  359.                                             CATransform*    transform );
  360.  
  361. pascal    Boolean        CAGetFrozen(            CADocumentRef    document,
  362.                                             CAFrameRef        frame );
  363.                                             
  364. pascal    void        CASetFrozen(            CADocumentRef    document,
  365.                                             CAFrameRef        frame,
  366.                                             Boolean            isFrozen );
  367.  
  368. pascal Boolean        CAActiveBorderContainsPoint(    Point mouse);
  369.  
  370. // VisFrame manipulation
  371. //  The transform of a CAVisFrame defines the VisFrames position
  372. //  within it's containing frame.  Location.
  373.  
  374.  
  375. pascal    CAVisFrame    CAGetVisFrame(            CADocumentRef    document,
  376.                                             CAFrameRef        frame );
  377.                                             
  378. pascal    CAVisFrame    CAMakeVisFrame(            CADocumentRef    document,
  379.                                             CAFrameRef        frame,
  380.                                             RgnHandle        clipRgn,
  381.                                             CATransform*    xform,
  382.                                             GrafPtr            port );
  383.                                     
  384. pascal    void        CARemoveVisFrame(        CAVisFrame        visFrame );
  385.  
  386. pascal    void        CAAdjustVisFrame(        CAVisFrame        visFrame,
  387.                                             RgnHandle        clipRgn,
  388.                                             CATransform*    xform );
  389.                                             
  390. pascal    void        CAGetVisFrameTransform(    CADocumentRef    document,
  391.                                             CAFrameRef        frameRef,
  392.                                             CATransform*    xform );
  393.  
  394.                                     
  395. pascal    Boolean        CAGetSelected(            CAVisFrame visFrame );
  396. pascal    void        CASetSelected(            CAVisFrame visFrame, Boolean isSelected );
  397.  
  398. pascal    CAHighlight    CAGetHighlight(            CAVisFrame visFrame );
  399. pascal    void        CASetHighlight(            CAVisFrame visFrame, CAHighlight highlight );
  400.                                     
  401.  
  402. // Transform utilities
  403.  
  404. pascal void            CAMoveTransformBy(        CATransform* transform, Point offset );
  405. pascal void            CAMoveTransformTo(        CATransform* transform, Point origin );
  406.  
  407. // Other transform utility routines
  408.  
  409.  
  410. //=========================================================================
  411. // Imaging
  412. //=========================================================================
  413.  
  414. pascal    GrafPtr        CAGetCanvas(        CAVisFrame visFrame, CAGraphicsSystem graphicsSystem );
  415. pascal    void        CADrawFrame(        CAVisFrame visFrame, RgnHandle invalidRgn );
  416. pascal    void        CADrawActiveBorder(    void);
  417.  
  418. // callbacks
  419. pascal    void        CAInstallCanvasNotification(    CACanvasUpdatedProc    proc,
  420.                                                      CADocumentRef        document);
  421.  
  422. pascal    void        CACanvasUpdated(    GrafPtr port );
  423.  
  424. //-------------------------------------------------------------------------
  425. // Menu
  426. //-------------------------------------------------------------------------
  427.  
  428. pascal    void        CASetBaseMenuBar(        Handle menuBar );
  429. pascal    void        CAAdjustMenus(            void );
  430. pascal    void        CARegisterCommand(        CACommandID command,
  431.                                             CAMenuID menu,
  432.                                             CAMenuItemID menuItem );
  433.                                             
  434. pascal    Boolean        CADispatchMenuEvent(    EventRecord* event, long menuSelection );
  435.  
  436. //-------------------------------------------------------------------------
  437. // UI Events
  438. //-------------------------------------------------------------------------
  439.  
  440. pascal    Boolean        CADispatchEvent( EventRecord* event, CAEventInfo* eventInfo );
  441.  
  442. pascal    RgnHandle    CAGetMouseRegion( void );
  443. pascal    long        CAGetSleepTime( void );
  444.  
  445. // callbacks
  446. pascal    void        CAInstallBorderAdjuster(CADocumentRef,
  447.                                             CAAdjustBorderProc);
  448.  
  449. pascal    void        CAAdjustActiveBorder( CADocumentRef document, CAFrameRef frame, RgnHandle border );
  450.  
  451.  
  452. //-------------------------------------------------------------------------
  453. // Undo
  454. //-------------------------------------------------------------------------
  455.  
  456. pascal    void        CAClearUndo( void );
  457.  
  458. //-------------------------------------------------------------------------
  459. // Proxy Root Part
  460. //-------------------------------------------------------------------------
  461.  
  462. pascal Boolean        CAShowPartFrameInfo( CADocumentRef, CAVisFrame visFrame);
  463.  
  464. pascal void            CAViewFrameInWindow (CADocumentRef, CAFrameRef);
  465.  
  466. // Does this really belong here?
  467. // I think the Proxy Root Part is invisible to the Container Application.
  468. // -Tantek
  469.  
  470.  
  471. #ifdef __cplusplus
  472. }
  473. #endif
  474.  
  475.  
  476.  
  477. #endif // _CALIB_