Programming Reference

DocumentManager

SOMObject
  somf_MLinkable
    DocumentManager

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