Programming Reference: DocumentManager

# Programming Reference

## DocumentManager

Class Definition File | DocMgr.idl
Class C++ Binding | DocMgr.xh

Class Hierarchy

    SOMObject
      somf_MLinkable
        DocumentManager

Description | An object of the DocumentManager class manages the run time existence of an OpenDoc document. It provides the interfaces for creating, opening, saving, and closing documents. Drafts may be created, opened, closed, or deleted. DocumentManager objects are used by the shell. Each time the shell needs to create or open a document, it creates a DocumentManager object.

Methods

The methods defined by the DocumentManager class include:

- CloseDocument
- CloseDraft
- CloseWindow
- CreateDocumentAsStationery
- CreateDocumentInFile
- CreateDocumentInMemory
- CreateDraft
- DeleteDraft
- DeleteDraftList
- GetFileName
- GetDocument
- GetDraft
- GetDraftList
- GetLatestCreatedDraft
- GetOleWrapper (Windows)
- GetPartKindName
- HasWriteAccess
- Initialize
- InternalizeHistory
- OpenDocumentFromFile
- OpenDocumentFromMemory
- OpenDraft
- Revert
- SaveACopyAs
- SaveDocument
- SaveDraft
- SetFileName
- SetOleWrapper (Windows)
- SetPartKindName

Overridden Methods | There are no methods overridden by the DocumentManager class.

### CloseDocument

This method closes the current document.

Signature

    void CloseDocument (ODULong saveOption)

Parameters

saveOption (ODULong) - input

  A flag indicating whether to save or remove unsaved changes made in the current document. This parameter can be one of the following:

  kODCommandSaveChanges | Save any unsaved changes made in the current document.
  kODCommandDiscardChanges | Remove any unsaved changes made in the current document.

Returns

None.

Remarks

This method closes down the document belonging to this DocumentManager. If the saveOption parameter is set to kODCommandSaveChanges, the document is saved before bringing down the document. All opened windows belonging to this DocumentManager are closed. The container and document objects belonging to this DocumentManager that are acquired when the document is created are closed.

This method removes the OLE wrapper associated with this DocumentManager for the Windows platform.

Related Methods

- ApplicationShell::DocumentClose
- DocumentManager::CloseWindow
- DocumentManager::CreateDocumentInFile
- DocumentManager::CreateDocumentInMemory
- DocumentManager::OpenDocumentFromFile
- DocumentManager::OpenDocumentFromMemory
- DocumentManager::SaveDocument
- OpenDocShell::HandleCloseEvent

### CloseDraft

This method closes the specified draft and its windows.

Signature

    void CloseDraft (ODULong *draft)

Parameters

draft (ODULong *) - input

  A reference to the opened draft object.

Returns

None.

Remarks

This method clears the redo and undo stack, closes all the opened windows belonging to this draft object, and notifies data transfer services objects that this draft is closed. This method will not decrement the reference count of the opened draft acquired by the caller before calling the DocumentManager's OpenDraft method.

Related Methods

- DocumentManager::OpenDraft
- ODClipboard::DraftClosing
- ODDragAndDrop::DraftClosing
- ODLinkManager::DraftClosing
- ODWindowState::CloseWindows

### CloseWindow

This method closes the window object corresponding to the specified platform-specific window if the window object belongs to the DocumentManager.

Signature

    ODBoolean CloseWindow (ODPlatformWindow platWindow,
                           ODBoolean confirm)

Parameters

platWindow (ODPlatformWindow) - input

  A platform-specific window.

confirm (ODBoolean) - input

  A flag indicating whether to confirm the closing of the window object. If the specified platform-specific window corresponds to the root window containing the most recent draft of the current document, do not close the window object if this parameter is set to kODTrue. Otherwise, close the window.

  This parameter is ignored if the window object is a non-root window or a root window not belonging to the most recent draft.

Returns

rv (ODBoolean) - returns

  If confirm is set to kODFalse:

  kODTrue | The window corresponding to the platform-specific window is closed.
  kODFalse | The window corresponding to the platform-specific window is not closed.

  If confirm is set to kODTrue:

  kODTrue | The window corresponding to the platform-specific window is not closed if this window is a root window containing the most recent draft of the document.
  kODFalse | The window corresponding to the platform-specific window is closed if the window belongs to this DocumentManager.

Remarks

This method closes the OpenDoc window corresponding to the platform-specific window if the OpenDoc window is a non-root window and belongs to this DocumentManager. If the OpenDoc window is a root window containing a previous draft version of the document, it closes the draft and its OpenDoc window. If the OpenDoc window is a root window containing the most recent draft of the document and confirm is set to kODTrue, it returns to the caller and does not close the draft and its window. Otherwise, it closes the draft and its window.

This method is called by the ApplicationShell and DocumentManager.

Exception Handling

kODErrClosingNonODWindow | Window to be closed does not belong to OpenDoc.
kODErrNoDraftInWindow | Window to be closed contains no draft.

Related Methods

- DocumentManager::CloseDraft
- ODWindow::CloseAndRemove
- ODWindow::IsRootWindow
- ODWindowState::IsODWindow
- ODWindowState::GetRootWindowCount
- OpenDocShell::HandleCloseEvent

### CreateDocumentAsStationery

This method creates a document in a new file container and marks it as stationery.

Signature

    void CreateDocumentAsStationery (ODType kindName,
                                     char *filename)

Parameters

kindName (ODTupe) - input

  The root part kind.

filename (char *) - input

  The file name where the new document is created.

Returns

None.

Remarks

This method creates and initializes a document in a new file container. The document is marked as a stationery document. This document has an initial draft with the specified part kind as its root part. This method will not open the root part of the newly created stationery document.

This method is called by the Application Shell to create a new stationery document without opening it.

Related Methods

- ApplicationShell::OpenDocument

### CreateDocumentInFile

This method creates a document in a new file container and opens this document.

Signature

    void CreateDocumentInFile (ODType kindName,
                               char *filename)

Parameters

kindName (ODType) - input

  The root part kind.

filename (char *) - input

  The file name where the new document is created and saved.

Returns

None.

Remarks

This method creates and initializes a document in a new file container. The document has an initial draft with the specified part kind as its root part. After the initial draft is created, shell plug-ins installed in the system are executed. After all shell plug-ins have executed, the root part of the document opens its document window.

After executing this method, a document file with the specified filename is created. This method first tries to create the document file in the current directory. If it fails, then it tries to create the document file in the directory set in the ODTMP environment variable. If ODTMP is not set, this method returns an exception to the caller.

This method initializes the reference count of the newly created file container, document, and draft. The container and document objects are released in the DocumentManager's CloseDocument method. The draft object is released in the DocumentManager's CloseDocument method or in the DocumentManager's CreateDraft method when a new draft is created.

Related Methods

- ApplicationShell::OpenDocument
- DocumentManager::CloseDocument
- DocumentManager::CreateDraft

### CreateDocumentInMemory

This method creates a document in a new memory container and opens this document.

Signature

    void CreateDocumentInMemory (ODType kindName)

Parameters

kindName (ODType) - input

  The root part kind.

Returns

None.

Remarks

This method creates and initializes a document in a new memory container. The document has an initial draft with the specified part kind as its root part. After the initial draft is created, shell plug-ins installed in the system are executed. After all shell plug-ins have executed, the root part of the document opens its document window.

This method initializes the reference count of the newly created file container, document, and draft. The container and document objects are released in the DocumentManager's CloseDocument method. The draft object is released in the DocumentManager's CloseDocument method or in the DocumentManager's CreateDraft method when a new draft is created.

Exception Handling

kODErrOpeningMemContainer | Error allocating document memory container.

Related Methods

- DocumentManager::CloseDocument
- DocumentManager::CreateDraft

### CreateDraft

This method saves the current state of the document in a new draft.

Signature

    void CreateDraft (ODULong draftNum,
                      ODIText *modUser,
                      ODIText *comment)

Parameters

draftNum (ODULong) - input

  The number for the draft.

modUser (ODIText *) - input

  The name of the user who created the draft or kODNULL if not specified.

comment (ODIText *) - input

  User-created comments on the draft or kODNULL if not specified.

Returns

None.

Remarks

This method saves the current state of the document to the most recent draft, closes the most recent draft, creates a new most recent draft for editing, and opens the new most recent draft. After calling this method, the document has been saved.

This method increments the reference count of the newly created draft. The newly created draft's Release method is called when another new draft is created or when the document is closed in the DocumentManager's CloseDocument method.

This method is called by the create draft dialog.

Related Methods

- ApplicationShell::DocumentDraftHistory
- DocumentManager::CloseDocument
- DocumentManager::CloseDraft
- DocumentManager::OpenDraft
- DocumentManager::SaveDocument
- ODDocument::CreateDraft

### DeleteDraft

This method deletes the specified draft from the current document.

Signature

    ODBoolean DeleteDraft (DraftInfoRec *record)

Parameters

record (DraftInfoRec) - input

  The draft entry containing the specified information about the draft.

Returns

kODTrue indicates the draft was deleted successfully; otherwise, kODFalse.

Remarks

This method can be called only if the draft is not open and has a reference count of one. This method closes the draft, deletes the draft from the current document, and removes the draft entry from the draft history list.

This method is called by the draft history dialog.

Related Methods

- ApplicationShell::DocumentDraftHistory
- DocumentManager::DeleteDraftList
- DocumentManager::GetDraftList
- DocumentManager::InternalizeHistory
- DocumentManager::OpenDraft

### DeleteDraftList

This method deletes the draft history list.

Signature

    void DeleteDraftList ()

Parameters

None.

Returns

None.

Remarks

This method releases the draft acquired for each draft entry and deletes all the draft entries in the draft history list. After executing this method, the draft history list is empty.

This method is called by the draft history dialog.

Related Methods

- ApplicationShell::DocumentDraftHistory
- DocumentManager::GetDraftList
- DocumentManager::InternalizeHistory

### GetFileName

This method returns the file name associated with the file container where the current document resides on the disk.

Signature

    char *GetFileName ()

Parameters

None.

Returns

rv (char *) - returns

  The name of the document file where the current document resides physically on the disk if the current container is not a file container; otherwise, returns kODNULL.

Remarks

This method returns the name of the document file corresponding to the current document if the current document is a file container. If the current document is not a file container, this method returns kODNULL as the file name.

Related Methods

- DocumentManager::SetFileName

### GetDocument

This method returns a reference to the document object that belongs to this DocumentManager.

Signature

    ODDocument *GetDocument ()

Parameters

None.

Returns

rv (ODDocument *) - returns

  A reference to the document object that belongs to this DocumentManager.

Remarks

This method returns a reference to the document object belonging to this DocumentManager. This method does not increment the reference count of the returned document. If you cache the returned document, you should call its Acquire method to increment its reference count and then call its Release when you are finished using it.

Related Methods

- ODDocument class definition

### GetDraft

This method returns a reference to the most recent draft object that belongs to this DocumentManager.

Signature

    ODDraft *GetDraft ()

Parameters

None.

Returns

rv (ODDraft *) - returns

  A reference to the draft object that belongs to this DocumentManager.

Remarks

This method returns a reference to the draft object belonging to this DocumentManager. This method does not increment the reference count of the returned draft. If you cache the returned draft, you should call its Acquire method to increment its reference count and then call its Release when you are finished using it.

Related Methods

- ODDraft class definition

### GetDraftList

This method returns a the first draft entry in the draft history list.

Signature

    DraftInfoRec *GetDraftList ()

Parameters

None.

Returns

rv (DraftInfoRec *) - returns

  A reference to the first draft entry in the draft history list.

Remarks

This method returns the first draft entry in the draft history list. You should call the DocumentManager's InternalizeHistory method to build the draft history list before calling this method.

This method is called by the draft history dialog.

Related Methods

- ApplicationShell::DocumentDraftHistory
- DocumentManager::InternalizeHistory

### GetLatestCreatedDraft

This method returns the last saved draft belonging to the current document.

Signature

    ODDraft *GetLatestCreatedDraft ()

Parameters

None.

Returns

rv (ODDraft *) - returns

  A reference to the last saved draft belong to the current document or kODNULL if this document has no previous versions.

Remarks

This method returns a reference to the last saved draft version of this document. If there is no previous version, this method returns kODNULL. This method increments the reference count of the returned draft. You should call the returned draft's Release method when you are finished using it. This Release method is inherited from the ODRefCntObject class.

This method is called by the draft history dialog.

Related Methods

- ApplicationShell::DocumentDraftHistory
- ODDocument::AcquireDraft
- ODDocument::CreateDraft
- ODDraft::Release

### GetOleWrapper (Windows)

This method returns an OLE wrapper for the DocumentManager.

Signature

    OleWrapper GetOleWrapper ()

Parameters

None.

Returns

rv (OleWrapper) - returns

  A reference to an OLE wrapper.

Remarks

This method returns the OLE wrapper for this DocumentManager.

Related Methods

- DocumentManager::SetOleWrapper (Windows)

### GetPartKindName

This method returns the part kind belonging to the root part of the current document.

Signature

    char *GetPartKindName ()

Parameters

None.

Returns

rv (char *) - returns

  The root part kind of this document.

Remarks

This method returns the part kind belonging to the root part of the current document.

Related Methods

- DocumentManager::SetPartKindName

### HasWriteAccess

This method returns a Boolean value that indicates whether the most recent draft has write permission.

Signature

    ODBoolean HasWriteAccess ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A value indicating whether the latest draft has write permission.

  kODTrue | The most recent draft has write permission.
  kODFalse | The most recent draft does not have write permission.

Remarks

This method returns a Boolean value that indicates whether the most recent draft of the current document allows write access.

Related Methods

- ODDraft::GetPermissions

### Initialize

This method initializes the newly created DocumentManager.

Signature

    void Initialize (ODSession *session)

Parameters

session (ODSession) - input

  The current session object.

Returns

None.

Remarks

This method initializes the newly created DocumentManager. This method is called by the OpenDocShell.

Related Methods

- OpenDocShell::CreateDocumentManager

### InternalizeHistory

This method builds the draft history list containing all the previous draft versions created in the current document.

Signature

    void InternalizeHistory ()

Parameters

None.

Returns

None.

Remarks

This method creates a list of draft entries that pertain to the current document. This draft list includes all drafts in the current document except the most recent draft opened for editing. You can call the DocumentManager's GetDraftList method to return the first entry, the head, of the draft history list. The draft history list is built with the most recent saved version on top followed by each previously saved version.

After this method executes, the reference count of each draft contained in the draft history list is incremented. When you finish using the draft history list, you should call the DocumentManager's DeleteDraftList method to release each draft in the draft history list and delete all draft entries.

This method is called by the draft history dialog.

Related Methods

- ApplicationShell::DocumentDraftHistory
- DocumentManager::DeleteDraftList
- DocumentManager::GetDraftList

### OpenDocumentFromFile

This method opens a document from the specified file.

Signature

    char *OpenDocumentFromFile (char *fileName,
                                ODUShort actionFlag)

Parameters

fileName (char *) - input

  The name of the document file to open.

actionFlag (ODUShort) - input

  A flag to indicate how to handle the file if the file to be opened is a stationery document. This parameter should be set to one of the following values:

  kODNULL | Saves a copy of the stationery document to a new file and opens a new file.
  kODEditStationery | Opens the stationery document file.

Returns

rv (char *) - returns

  The root part kind of the document.

Remarks

This method opens a document and its most recent draft from the specified document file. If the document is marked as stationery and actionFlag is set to kODNULL, a copy of the most recent draft in the opened document is saved to a new file and a newly created file is opened. After getting the document and its most recent draft from the file, this method executes shell plug-ins installed in the system and then opens the root part of the document.

This method initializes the reference count of the opened file container, document, and draft. The container and document objects are released in the DocumentManager's CloseDocument method or in the DocumentManager's CreateDraft method when a new draft is created.

This method is called by the ApplicationShell.

Related Methods

- ApplicationShell::OpenDocument
- DocumentManager::CloseDocument
- DocumentManager::CreateDraft

### OpenDocumentFromMemory

This method opens a document from the specified memory handle.

Signature

    char *OpenDocumentFromMemory (ODHandle handle)

Parameters

handle (ODHandle) - input

  The memory handle.

Returns

rv (char *) - returns

  The root part kind of the document.

Remarks

This method opens a document and its most recent draft from the specified memory container. After getting the document and its most recent draft from the memory container, it executes shell plug-ins installed in the system and then opens the root part of the document.

This method initializes the reference count of the opened memory container, document, and draft. The container and document objects are released in the DocumentManager's CloseDocument method or in the DocumentManager's CreateDraft method when a new draft is created.

Related Methods

- DocumentManager::CloseDocument
- DocumentManager::CreateDraft

### OpenDraft

This method opens the specified draft causing its parts to open their windows.

Signature

    ODBoolean OpenDraft (ODDraft *draft,
                         ODBoolean toBeReleased)

Parameters

draft (ODDraft *) - input

  The reference to the opened draft object.

toBeReleased (ODBoolean) - input

  A flag to indicate whether to release the draft specified by the draft parameter.

  kODTrue | Release the draft after opening. new file.
  kODFalse | Do not release the draft after opening.

Returns

rv (ODBoolean) - returns

  kODTrue if the draft is opened successfully; otherwise, kODFalse.

Remarks

This method opens all windows belonging to the specified draft and notifies the data transfer services object that this draft is opened.

Before calling this method, the caller should call the open draft's Acquire method to increment the reference count of the open draft.

This method is called by the draft history dialog and the DocumentManager.

Related Methods

- ApplicationShell::DocumentDraftHistory
- DocumentManager::CloseDraft
- ODLinkManager::DraftOpened
- ODPart::Open
- ODWindowState::Internalize
- ODWindowState::OpenWindows

### Revert

This method reverts to the last saved version of the document.

Signature

    void Revert ()

Parameters

None.

Returns

None.

Remarks

This method closes the most recent draft of the document, removes all changes made in this draft, and opens the last saved version of the document.

This method is called by the ApplicationShell.

Related Methods

- ApplicationShell::DocumentRevert
- DocumentManager::CloseDraft
- DocumentManager::OpenDraft
- ODDraft::RemoveChanges

### SaveACopyAs

This method saves a copy of the specified draft to the specified file.

Signature

    void SaveACopyAs (ODDraft *draft,
                      PlatformFile *file)

Parameters

draft (ODDraft *) - input

  A reference to the draft object to be saved.

file (PlatformFile *) - input

  A platform-specific file where a copy of the specified draft is to be saved.

Returns

None.

Remarks

This method saves a copy of the specified draft to the specified platform-specific file. If the platform-specific file already exists, the existing file is replaced. If the draft is marked dirty, this method externalizes the draft before saving a copy to the new file.

This method is called by the ApplicationShell.

Related Methods

- ApplicationShell::DocumentSaveAs
- ODDraft::Externalize
- ODWindowState::Externalize

### SaveDocument

This method saves the current document.

Signature

    void SaveDocument ()

Parameters

None.

Returns

None.

Remarks

This method clears the redo and undo stacks and saves the current state of the document.

This method is called by the ApplicationShell and the DocumentManager.

Related Methods

- ApplicationShell::DocumentSave
- DocumentManager.:SaveDraft
- ODUndo::ClearActionHistory

### SaveDraft

This method saves the current draft in the current document.

Signature

    void SaveDraft ()

Parameters

None.

Returns

None.

Remarks

This method externalizes the most recent draft in the current document and notifies the data transfer services object that the draft was saved.

Related Methods

- DocumentManager.:CloseDraft
- ODClipboard::DraftSaved
- ODLinkManager::DraftSaved

### SetFileName

This method stores the name of the document file corresponding to the current document.

Signature

    void SetFileName (char *fileName)

Parameters

fileName (char *) - input

  The name of the document file.

Returns

None.

Remarks

This method stores the name of the document file.

Related Methods

- DocumentManager::GetFileName

### SetOleWrapper (Windows)

This method sets an OLE wrapper for the DocumentManager.

Signature

    void SetOleWrapper (OleWrapper *oleWrapper)

Parameters

oleWrapper (OleWrapper *) - input

  A reference to an OLE wrapper.

Returns

None.

Remarks

This method sets the OLE wrapper for this DocumentManager.

Related Methods

- DocumentManager::GetOleWrapper (Windows)

### SetPartKindName

This method sets the part kind of the root part in the current document.

Signature

    void SetPartKindName (char *kindName)

Parameters

kindName (char *) - input

  The root part kind of the current document.

Returns

None.

Remarks

This method sets the part kind belonging to the root part of the current document.

Related Methods

- DocumentManager::GetPartKindName

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]