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