home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 July: Mac OS SDK / Dev.CD Jul 96 SDK / Dev.CD Jul 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc Source Code / Utilities / Interfaces / DocUtils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-04-22  |  17.9 KB  |  403 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        DocUtils.h
  3.  
  4.     Contains:    interface for useful high level UI oriented document utilities
  5.  
  6.     Owned by:    Tantek Çelik
  7.  
  8.     Copyright:    © 1995 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Notes:
  11.  
  12.     These functions are a collection of utilities which are used by the OpenDoc Shell
  13.     and other subsystems to manipulate user documents.
  14.     
  15.     They will also be useful to part editors which manipulate documents directly,
  16.     e.g. if a part editor wants to open another document in its process,
  17.     or create a new document from part/document stationery.
  18.     
  19.     The functions also help container part editors implement the "Insert…" Document
  20.     menu item.
  21.     
  22.     To Do:
  23.     
  24.         Reorder functions hilevel first, lowlevel last.
  25.         Move NewDocument from Shell to here.
  26.  
  27. */
  28.  
  29. #ifndef _DOCUTILS_
  30. #define _DOCUTILS_
  31.  
  32. // for ODFileRefNum
  33. #ifndef _PLFMFILE_
  34. #include "PlfmFile.h"
  35. #endif
  36.  
  37. #ifndef SOM_ODWindow_xh
  38. #include "Window.xh"
  39. #endif
  40.  
  41. //==============================================================================
  42. // Classes used by this interface
  43. //==============================================================================
  44.  
  45. class Environment;
  46. class ODSession;
  47.  
  48. class ODPart;
  49.  
  50. class ODStorageUnit;
  51. class ODDraft;
  52. class ODDocument;
  53. class ODContainer;
  54. class PlatformFile;
  55.  
  56. //==============================================================================
  57. // MACROS
  58. //==============================================================================
  59.  
  60. #define RETURN_IF_NULL(x,y)    if (!(x)) return y;
  61. #define HAS_WRITE_ACCESS(x) ((x) >= kODDPSharedWrite)
  62.  
  63. extern "C" {
  64.  
  65. //==============================================================================
  66. // Opening an file/container/document/draft
  67. //==============================================================================
  68.  
  69. //------------------------------------------------------------------------------
  70. // ODAcquireCtrDocTopDraft
  71. //    Given a PlatformFile object, get the container, document and top draft (readonly)
  72. //  reget the draft if you need more permissions.
  73. //------------------------------------------------------------------------------
  74.  
  75. void ODAcquireCtrDocTopDraft(Environment* ev, ODSession* session, PlatformFile* file, 
  76.         ODContainer** container, ODDocument** document, ODDraft** draft);
  77.  
  78. //------------------------------------------------------------------------------
  79. // ODGetFirstOpenDocument
  80. //    A pointer to the first document in the collection of open documents is returned.
  81. //    If the collection is empty, then kODNULL is returned.
  82. //    It is the caller's responsibility to Acquire the returned document it she wishes to 
  83. //    hold onto it.
  84. //------------------------------------------------------------------------------
  85.  
  86. ODDocument*    ODGetFirstOpenDocument(Environment* ev, ODSession* session);
  87.                 
  88. //------------------------------------------------------------------------------
  89. // ODGetNthOpenDocument
  90. //    A pointer to the nth document in the collection of open documents is returned.
  91. //    If the collection is empty, then kODNULL is returned.
  92. //    It is the caller's responsibility to Acquire the returned document it she wishes to 
  93. //    hold onto it.
  94. //------------------------------------------------------------------------------
  95.  
  96. ODDocument*    ODGetNthOpenDocument(Environment* ev, ODSession* session, ODULong n);
  97.                 
  98. //------------------------------------------------------------------------------
  99. // ODGetOpenDocumentFromRefNum
  100. //    Given a refnum, if it refers to a document open in this process, then a pointer to
  101. //    the respective ODDocument object is returned, else kODNULL is returned.
  102. //    It is the caller's responsibility to Acquire the returned document it she wishes to 
  103. //    hold onto it.
  104. //------------------------------------------------------------------------------
  105.  
  106. ODDocument*    ODGetOpenDocumentFromRefNum(Environment* ev, ODSession* session,
  107.                 ODFileRefNum refnum);
  108.                 
  109. //------------------------------------------------------------------------------
  110. // ODGetTempDraftFromOpenDocument
  111. //    Given a pointer to an already open ODDocument which has a tempdraft with rw perms,
  112. //    a pointer to that tempdraft is returned.  
  113. //    If there no tempdraft is found then kODNULL is returned.
  114. //    It is the caller's responsibility to Acquire the returned tempdraft it she wishes to 
  115. //    hold onto it.
  116. //------------------------------------------------------------------------------
  117.                 
  118. ODDraft*    ODGetTempDraftFromOpenDocument(Environment* ev, ODSession* session,
  119.                 ODDocument* document);
  120.  
  121. //------------------------------------------------------------------------------
  122. // ODTempDraftCreated
  123. //    This method updates the appropriate internal namespaces to note that a 
  124. //    tempdraft has been created and opened on the document passed in.
  125. //  The caller is responsible for properly refcounting the tempdraft.
  126. //------------------------------------------------------------------------------
  127.                 
  128. void    ODTempDraftCreated(Environment* ev, ODSession* session, 
  129.             ODDocument* document, ODDraft* tempDraft);
  130.  
  131. //------------------------------------------------------------------------------
  132. // ODDocumentOpened
  133. //    This method updates the appropriate internal namespaces to note that an ODDocument
  134. //    has been opened with the given file refnum.  If a tempdraft was created and opened
  135. //    with rw perms, then that should also be passed in, else pass in kODNULL.
  136. //    This method bumps the refcount of document and its container in order to keep a valid
  137. //    reference to it.  The caller is responsible for properly refcounting the tempdraft.
  138. //    This function calls ODTempDraftCreated as part of its implementation;
  139. //    no need to also call ODTempDraftCreated if you call this function.
  140. //------------------------------------------------------------------------------
  141.                 
  142. void        ODDocumentOpened(Environment* ev, ODSession* session,
  143.                 ODFileRefNum refnum, ODDocument* document, ODDraft* tempDraft);
  144.                 
  145. //------------------------------------------------------------------------------
  146. // ODDocumentClosed
  147. //    This method updates the appropriate internal namespaces to note that an ODDocument
  148. //    has been closed with the given file refnum.
  149. //    This method simply removes the appropriate entries from the namespaces;
  150. //    The document is released, as is its container.
  151. //    It is up to the caller to make sure that the tempdraft if any
  152. //    is released.
  153. //------------------------------------------------------------------------------
  154.                 
  155. void        ODDocumentClosed(Environment* ev, ODSession* session,
  156.                 ODDocument* document);
  157.  
  158. //==============================================================================
  159. // Document Properties
  160. //==============================================================================
  161.  
  162. //------------------------------------------------------------------------------
  163. // ODResetDateModByInfo
  164. //  Use this call when creating a new draft, either a new docuemnt from stationery,
  165. //    or a new saved draft.
  166. //  If it's a new document, then after calling SetBaseDraftFromForeignDraft on the new document,
  167. //  you need to reset the creation date, modification date, modification by (username) info
  168. //  since the person who created the new document may not necessarily be the same person
  169. //  who created the stationery.
  170. //------------------------------------------------------------------------------
  171.  
  172. void ODResetDateModByInfo(Environment* ev, ODStorageUnit* su);
  173.  
  174. //------------------------------------------------------------------------------
  175. // ODGetDocumentFileName
  176. //    Use this call to retrieve the name of the file of the document.
  177. //    fileName is presumed to be preallocated array of 256 characters.
  178. //    Maximum length of fileName filled in is 255 characters (256th reserved for
  179. //  terminating null).
  180. //------------------------------------------------------------------------------
  181.  
  182. void ODGetDocumentFileName(Environment* ev, ODDocument* document, char* fileName);
  183.  
  184. //==============================================================================
  185. // Root Part/StorageUnit/Draft
  186. //==============================================================================
  187.  
  188. //------------------------------------------------------------------------------
  189. // ODAcquireRootPartOfDraft
  190. //  Given a draft object, get the root part
  191. //------------------------------------------------------------------------------
  192.  
  193. ODPart* ODAcquireRootPartOfDraft(Environment* ev, ODDraft* draft);
  194.  
  195. //------------------------------------------------------------------------------
  196. // ODAcquireRootPartSUOfDraft
  197. //  Given a draft object, get the root part's storageUnit without getting the part
  198. //------------------------------------------------------------------------------
  199.  
  200. ODStorageUnit* ODAcquireRootPartSUOfDraft(Environment* ev, ODDraft* draft);
  201.  
  202. //------------------------------------------------------------------------------
  203. // ODSetRootPartOfDraft
  204. //  Given a draft object and the storageUnit of a part, set that part to be
  205. //  the root part of the draft.
  206. //  Preconditions:
  207. //        Write permissions on the draft.
  208. //        No current root part in the draft*.
  209. //
  210. // *Calling this function when there already is a root part, not represented by the
  211. // rootPartSU passed in, will cause data loss in the document.
  212. //------------------------------------------------------------------------------
  213.  
  214. void ODSetRootPartSUOfDraft(Environment* ev, ODDraft* draft, ODStorageUnit* rootPartSU);
  215.  
  216. //------------------------------------------------------------------------------
  217. // ODGetDraftOfWindow
  218. //  Given a window object, get the root part's storageUnit's draft
  219. //------------------------------------------------------------------------------
  220.  
  221. ODDraft* ODGetDraftOfWindow(Environment* ev, ODWindow* window);
  222.  
  223.  
  224. //==============================================================================
  225. // Cursor Utils
  226. //==============================================================================
  227.  
  228. void WatchCursor();
  229.  
  230. void ArrowCursor();
  231.  
  232. //==============================================================================
  233. // Active/Changed Utils
  234. //==============================================================================
  235.  
  236. ODWindow*    ODAcquireActiveWindow(Environment* ev, ODSession* session);
  237. ODDraft*    ODGetActiveDraft(Environment* ev, ODSession* session);
  238. ODDocument*    ODGetActiveDocument(Environment* ev, ODSession* session);
  239.  
  240. ODBoolean    ODDocumentHasChanges(Environment* ev, ODSession* session,
  241.                 ODDocument* document);
  242. ODBoolean    ODDocumentHasWriteAccess(Environment* ev, ODSession* session,
  243.                 ODDocument* document);
  244. ODBoolean    ODDraftHasWriteAccess(Environment* ev, ODDraft* draft);
  245.  
  246. //==============================================================================
  247. // User level document operations
  248. //==============================================================================
  249.  
  250. //------------------------------------------------------------------------------
  251. // ODNewDocument
  252. //  Given a valid container, this function turns it into a valid New OpenDoc document
  253. //    By creating a root part with the editor and/or kind passed inCreates a new document
  254. //    It is the caller's responsibility to make sure that the container can be written to.
  255. //------------------------------------------------------------------------------
  256.  
  257. void ODNewDocument(Environment* ev, ODContainer* container,
  258.                             ODType        rootPartKind,
  259.                             ODEditor    rootPartEditor);
  260.  
  261. //------------------------------------------------------------------------------
  262. // ODIsUnsavedNewDocument
  263. //  Returns whether or not the document has been saved since it was created.
  264. //------------------------------------------------------------------------------
  265.  
  266. ODBoolean ODIsUnsavedNewDocument(Environment* ev, ODSession* session, ODDocument* document);
  267.  
  268. //------------------------------------------------------------------------------
  269. // ODSetIsUnsavedNewDocument
  270. //  Sets the fact that the document has not been saved since it was created.
  271. //------------------------------------------------------------------------------
  272.  
  273. void ODSetIsUnsavedNewDocument(Environment* ev, ODDraft* draft);
  274.  
  275. //------------------------------------------------------------------------------
  276. // ODOpenFileDocument
  277. //    Opens the document specified in the passed in file.
  278. //    If write permissions are requested (and possible), then a tempdraft is created,
  279. //    otherwise the document is opened readonly.
  280. //    This method calls ODDocumentOpened appropriately.
  281. //  The "current" draft is returned, all ready to be sent into an ODOpenDraft call
  282. //    Note that if a tempdraft was created, that is what is returned as the "current" draft.
  283. //    The draft returned is a refcounted reference that the caller owns.
  284. //------------------------------------------------------------------------------
  285.  
  286. ODDraft* ODOpenFileDocument(Environment* ev, ODSession* session, PlatformFile* file,
  287.             ODDraftPermissions permissions);
  288.  
  289. //------------------------------------------------------------------------------
  290. // ODOpenDraft
  291. //    Notifies all appropriate objects that this draft is opening.
  292. //    The draft's document must have already been opened with ODOpenDocument.
  293. //  E.g. the LinkManager, Undo, Clipboard, WindowState (opens windows on that draft) etc.
  294. //  The draft is not acquired, nor is it added to the tempdrafts collection. 
  295. //------------------------------------------------------------------------------
  296.  
  297. void ODOpenDraft(Environment* ev, ODSession* session, ODDraft* draft);
  298.  
  299. //------------------------------------------------------------------------------
  300. // ODCloseDraft
  301. //    Notifies all appropriate objects that this draft is closing.
  302. //  E.g. the LinkManager, Undo, Clipboard, WindowState (closes windows on that draft) etc.
  303. //  The draft is not released, nor is it removed from the tempdrafts collection. 
  304. //------------------------------------------------------------------------------
  305.  
  306. void ODCloseDraft(Environment* ev, ODSession* session, ODDraft* draft);
  307.  
  308. //------------------------------------------------------------------------------
  309. // ODCloseDocument
  310. //    Closes the document and any associated windows etc.
  311. //    Caller is responsible for saving changes, prompting the user etc. BEFORE calling.
  312. //    Document is released.
  313. //    It is removed from the list of open documents, and if it has a tempdraft,
  314. //    that too is removed from the tempdrafts collection.
  315. //    Removes any tempdraft and any changes therein which implicitly releases the tempdraft.
  316. //    If there are no more open windows once the document is closed,
  317. //    then kODTrue is returned.
  318. //------------------------------------------------------------------------------
  319.  
  320. ODBoolean ODCloseDocument(Environment* ev, ODSession* session, ODDocument* document);
  321.  
  322. //------------------------------------------------------------------------------
  323. // ODReleaseCloseWindow
  324. //    Releases the window and
  325. //    Closes the window and any dependent windows.
  326. //    All child windows are dependent on the root windows of their draft.
  327. //    All windows of a saved draft of a document are dependent on the root windows 
  328. //    of the "current/top/temp" draft of the document.
  329. //    If the last window of a document is closed, then ODCloseDocument is called.
  330. //    If there are no more open windows once the window is closed,
  331. //    then kODTrue is returned.
  332. //    This function MUST consume the window reference passed in because:
  333. //    1. The Windowstate hangs onto a reference to every window
  334. //    2. The window's frame hangs onto a reference to the window
  335. //    2. The window passed in is AT LEAST the third reference to that window
  336. //    3. If the window is that last root window of the draft,
  337. //       then the window MUST be fully released by this function so that
  338. //       the draft, document and container can be properly released by ODCloseDocument
  339. //       which as noted above, is called by this function.
  340. //------------------------------------------------------------------------------
  341.  
  342. ODBoolean ODReleaseCloseWindow(Environment* ev, ODSession* session, ODWindow* window);
  343.  
  344. //------------------------------------------------------------------------------
  345. // ODDeleteDocument
  346. //    Saves & closes the document and moves it to the trash.
  347. //    If there are no more open windows once the document is closed,
  348. //    then kODTrue is returned.
  349. //------------------------------------------------------------------------------
  350.  
  351. ODBoolean ODDeleteDocument(Environment* ev, ODSession* session, ODDocument* document);
  352.  
  353. //------------------------------------------------------------------------------
  354. // ODSaveDocument
  355. //    Saves the document if there is an associated tempdraft.  Otherwise does nothing.
  356. //------------------------------------------------------------------------------
  357.  
  358. void ODSaveDocument(Environment* ev, ODSession* session, ODDocument* document);
  359.  
  360. //------------------------------------------------------------------------------
  361. // ODSaveACopyOfDraft
  362. //    Saves a copy of the draft.
  363. //    Note: destinationFile must be Specified but should not Exist.
  364. //------------------------------------------------------------------------------
  365.  
  366. void ODSaveACopyOfDraft(Environment* ev, ODSession* session, ODDraft* draft, 
  367.                         PlatformFile* destinationFile);
  368.  
  369. //------------------------------------------------------------------------------
  370. // ODRevertDocument
  371. //    Reverts the document if there is an associated tempdraft.  Otherwise does nothing.
  372. //  Note: it is advised that you get a confirmation from the user BEFORE
  373. //    calling this function.
  374. //------------------------------------------------------------------------------
  375.  
  376. void ODRevertDocument(Environment* ev, ODSession* session, ODDocument* document);
  377.  
  378. //------------------------------------------------------------------------------
  379. // ODDocumentInfo
  380. //    Displays the document info dialog.
  381. //------------------------------------------------------------------------------
  382.  
  383. void ODDocumentInfo(Environment* ev, ODSession* session);
  384.  
  385. //------------------------------------------------------------------------------
  386. // ODIsTempDocument
  387. //  Returns whether or not the document is a temp document.
  388. //------------------------------------------------------------------------------
  389.  
  390. ODBoolean ODIsTempDocument(Environment* ev, ODSession* session, ODDocument* document);
  391.  
  392. //------------------------------------------------------------------------------
  393. // ODSetIsTempDocument
  394. //  Sets whether the document is a temp document or not.
  395. //------------------------------------------------------------------------------
  396.  
  397. void ODSetIsTempDocument(Environment* ev, ODDraft* draft, ODBoolean isTemp);
  398.  
  399. }    // End of extern "C" {
  400.  
  401. #endif
  402. // _DOCUTILS_
  403.