Programming Reference

ApplicationShell

SOMObject
   OpenDocShell
      ApplicationShell

AdjustMenu

This method updates the menus using the current state of the document.

Signature

void AdjustMenu ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when a document receives focus. It disables and enables menu items of the Document menu for the current state of the document. It updates the Undo and Redo menu items of the Edit menu and items of the part menus.

Related Methods

• ODPart::AdjustMenus
• ODWindowState::AdjustPartMenus

CloseCleanup

This method performs all platform dependent cleanup tasks when close is requested.

Signature

void CloseCleanup ()

Parameters

None.

Returns

None.

Remarks

This method must be overridden by the platform shell subclass. Because each windowing system handles window closures differently, it is sometimes necessary to do special processing to cleanup when the user requests to closedown the docshell.    

CreateMenuBar

This method creates the default OpenDoc menu bar.

Signature

void CreateMenuBar ()

Parameters

None.

Returns

None.

Remarks

This method must be overridden by the platform shell subclass. It creates the base menubar, popup menu, and acceleration table and installs them in the WindowState object associated with the current OpenDoc session.

Related Methods

• ApplicationShell::Go
• ODWindowState::SetBaseMenuBar
• ODWindowState::SetBasePopup
• ODMenuBar class description

DocumentAbout

This method displays the OpenDoc information dialog.

Signature

void DocumentAbout ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the OpenDoc Information item is selected from the Help menu. It displays a dialog containing copyright information about OpenDoc.    

DocumentClose

This method causes the current document to close itself.

Signature

void DocumentClose ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Close item is selected from the Document menu. This method must be overridden by the platform shell subclass. It sends a close event or message identical to that send when Close is selected from the window system menu. This event is sent so the document closing process can be handled uniformly when the close is requested from the docshell menubar or the window system menu.

Related Methods

• ApplicationShell::CloseCleanup
• DocumentManager::CloseDocument
• OpenDocShell::HandleCloseEvent

DocumentDraftCreate

This method invokes the Create Draft dialog.

Signature

void DocumentDraftCreate ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Create Draft item is selected from the Drafts submenu. It displays the Create Draft dialog that requests the name of the creator and comments. It then creates a new draft.

Related Methods

• ApplicationShell::DocumentDraftHistory
• DocumentManager::CreateDraft

DocumentDraftHistory

This method invokes the Draft History dialog.

Signature

void DocumentDraftHistory ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Draft History item is selected from the Drafts submenu. It displays the Draft History dialog that lists the name of the creator, draft number, date and time the draft was created, and any comments associated with each existing draft.

Related Methods

• ApplicationShell::DocumentDraftCreate
• DocumentManager::InternalizeHistory

DocumentInfo

This method invokes the Document Properties notebook.

Signature

void DocumentInfo ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Document Info item is selected from the Document menu. It displays properties of the root part of the document and the settings extension for the root part in a properties notebook. Some of the fields can be modified while others are informational only.

Related Methods

• ODInfo::ShowPartFrameInfo
• ODSettingsExtension class description

DocumentNew

This method launches a new docshell.

Signature

void DocumentNew ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the New Document item is selected from the Document menu. It invokes a new docshell process with the same root part kind as the current document. The new docshell runs independent of the other and operates on a separate document in a different process.

Related Methods

• ApplicationShell::Exec

DocumentOpen

This method opens an existing document.

Signature

void DocumentOpen ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Open Document item is selected from the Document menu. It invokes the Open File dialog to prompt the user for the name of an existing OpenDoc document. When the document is opened, the original base part kind editor saved with the document is invoked.

Related Methods

• ApplicationShell::Exec

DocumentPageSetup

This method sends the Page Setup menu event to the root part.

Signature

void DocumentPageSetup ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Page Setup item is selected from the Document menu. The root part determines the mechanism for the page setup of the document and its embedded parts. This method passes the request to the root part to handle.

Related Methods

• ApplicationShell::SendEventToRootPart

DocumentPrint

This method sends the Print menu event to the root part.

Signature

void DocumentPrint ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Print item is selected from the Document menu. The root part determines the mechanism for printing the document and its embedded parts. This method passes the request to the root part to handle.

Related Methods

• ApplicationShell::SendEventToRootPart

DocumentRevert

This method discards all the unsaved changes to the current document.

Signature

void DocumentRevert ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Revert to Saved item is selected from the Document menu. After prompting the user for confirmation, this method reopens the last saved version of the current document. Any changes made to the document since the last saved version will be lost.

Related Methods

• DocumentManager::Revert

DocumentSave

This method saves the document.

Signature

void DocumentSave ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Save Document item is selected from the Document menu. It externalizes the current document and its embedded parts, their data, and handler and editor information.

Related Methods

• DocumentManager::SaveDocument

DocumentSaveAs

This method saves a copy of the draft into a new document file.

Signature

void DocumentSaveAs ()

Parameters

None.

Returns

None.

Remarks

This method is invoked when the Save A Copy item is selected from the Document menu. It saves a copy of the draft belonging to the active window in a new file specified by the user. A File dialog box is displayed to allow the user to specify the name and choose a location. The current document remains open.

Related Methods

• DocumentManager::SaveACopyAs

Exec

This method creates a new docshell process.

Signature

void Exec (char *str)

Parameters

str  (char *)  -  input 

A string containing the command to use to execute a new docshell.

Returns

None.

Remarks

This method must be overridden by the platform shell subclass. It creates a new docshell process based on the input string which is created using the selected base part kind of the current document or the name of an existing document specified by the user. This method is invoked from the ApplicationShell's DocumentNew and DocumentOpen methods.

Related Methods

• ApplicationShell::DocumentNew
• ApplicationShell::DocumentOpen

GetEventSubType

This method returns the event subtype value.

Signature

ODULong GetEventSubType (ODEventData *event)

Parameters

event  (ODEventData *)  -  input 

The specific event.

Returns

rv  (ODULong)  -  returns 

The event subtype value.

Remarks

This method must be overridden by the platform shell subclass. This method returns the event subtype value. On Windows and OS/2, the subtype is an event parameter. On AIX, the subtype is only used for menu item values in the menu events. Because event structures are platform specific, methods in the platform shell subclasses are used to access the generic data within the structure. For example, all the platform's event have a type and a window.

Related Methods

• ApplicationShell::GetEventType
• ApplicationShell::GetEventWindow

GetEventType

This method returns the event type value.

Signature

ODULong GetEventType (ODEventData *event)

Parameters

event  (ODEventData *)  -  input 

The specific event.

Returns

rv  (ODULong)  -  returns 

The event type value.

Remarks

This method must be overridden by the platfrom shell subclass. This method returns the event type value. Because event structures are platform specific, methods in the platform shell subclasses are used to access the generic data within the structure. For example, all the platform's event have a type and a window.

Related Methods

• ApplicationShell::GetEventSubType
• ApplicationShell::GetEventWindow

GetEventWindow

This method returns the platform window in which the event occurred.

Signature

ODPlatformWindow GetEventWindow (ODEventData *event)

Parameters

event  (ODEventData *)  -  input 

The specific event.

Returns

rv  (ODPlatformWindow)  -  returns 

The window of the event.

Remarks

This method must be overridden by the platform shell subclass. This method returns the platform window in which the event occurred. Because event structures are platform specific, methods in the platform shell subclasses are used to access the generic data within the structure. For example, all the platform's event have a type and a window.

Related Methods

• ApplicationShell::GetEventType
• ApplicationShell::GetEventSubType

GetExecString

This method returns the original command line invocation string.

Signature

char *GetExecString ()

Parameters

None.

Returns

None.

Remarks

This is an accessor method used to get the original command line invocation string.

Related Methods

• ApplicationShell::SetExecString

Go

This method runs the docshell process.

Signature

ODSLong Go (ODSLong argc, char **argv)

Parameters

argc  (ODSLong)  -  input 

The number of arguments contained in the command invocation string.

argv  (char **)  -  input 

The array of command line arguments.

Returns

rv  (ODSLong)  -  returns 

Zero on successful completion of the docshell application.

Remarks

This is the main method in the shell. It invokes other methods to parse the command line arguments, initialize the program, create the base menubar, create a Document Manager class for the document, process the events, and any task required to terminate the application. Returning from this method indicates the application is complete.

Related Methods

• ApplicationShell::CreateMenuBar
• ApplicationShell::InitWindowSystem
• ApplicationShell::MainLoop
• ApplicationShell::ProcessArgs

HandleCloseEvent

This method handles a close event.

Signature

ODBoolean HandleCloseEvent (ODEventData *event)

Parameters

event  (ODEventData *)  -  input 

The close event.

Returns

rv  (ODBoolean)  -  returns 

kODTrue for successful handling; otherwise, kODFalse.

Remarks

This method determines if a close event is for a part window, draft window, or document window. A part or draft window will be closed on receipt of the close event. If the event is for a document window the event subtype will indicate whether any changes should be saved or discarded before closing the document, or whether a dialog box should be displayed to allow the user to save or discard changes prior to closing or cancel the close.

Related Methods

• OpenDocShell::DispatchEvent

HandleMenuEvent

This method handles a menu event.

Signature

ODBoolean HandleMenuEvent (ODEventData *event)

Parameters

event  (ODEventData *)  -  input 

The menu event.

Returns

rv  (ODBoolean)  -  returns 

kODTrue for successful handling; otherwise, kODFalse.

Remarks

This method is responsible for taking a menu event and invoking the action appropriate for the menu item that was selected. The menu item information is contained in the event subtype.

Related Methods

• OpenDocShell::DispatchEvent

InitWindowSystem

This method performs initialization required by the window system.

Signature

void InitWindowSystem ()

Parameters

None.

Returns

None.

Remarks

This method must be overridden by the platform shell subclass. It performs any initialization required by the window system. This method is invoked by the ApplicationShell's Go method.

Related Methods

• ApplicationShell::Go

IsValidFileName

This method returns a Boolean based on whether the input file name exists and is readable.

Signature

ODBoolean IsValidFileName (char *docName)

Parameters

docName  (char *)  -  input 

The name of the file to validate.

Returns

rv  (ODBoolean)  -  returns 

A flag indicating whether the file was opened successfully.

kODTrue	File exists and is readable.
kODFalse	The file does not exist or is not readable.

Remarks

This method first checks that the input file name references an existing file and then if the file is regular and readable. It returns kODTrue or kODFalse based on the status of the file.    

MainLoop

This method includes the main event processing loop.

Signature

ODSLong MainLoop ()

Parameters

None.

Returns

rv  ODSLong  -  returns 

For AIX and OS/2, zero upon successful completion of the docshell application. For Windows, the wparam value of the last message on successful completion of the docshell application.

Remarks

This method must be overridden by the platform shell subclass. It runs the standard event dispatching loop according to the window system in which it is being run.

Related Methods

• ApplicationShell::Go

OpenDocument

This method opens or creates an OpenDoc document based on whether the part kind or file name is specified.

Signature

ODBoolean OpenDocument (DocumentManager docMgr, char *fileName, char *partKind)

Parameters

docMgr  (DocumentManager)  -  input 

The handle to the Document Manager object associated with the current document.

fileName  (char *)  -  input 

The name of the file to open during the invocation, if specified.

partKind  (char *)  -  input 

The part editor name to load as root part during the invocation of the docshell, if specified.

Returns

rv  (ODBoolean)  -  returns 

A flag indicating whether the document was opened successfully.

kODTrue	The document was opened successfully.
kODFalse	The document was not opened successfully.

Remarks

This method opens an OpenDoc file based on what is specified on the command line during the invocation of the docshell. An existing file is opened if one is specified with or without the -f flag. Using the -f flag and the file is a stationery document, opens a copy of the file instead. If the -k flag and a part kind are specified, a new document is created and opened using the specified part kind as the root part. If the -c flag and a part kind are specified, a new document is created as a stationery document using the specified part kind as the root part but the document is not opened. If no flag or file name is specified, the Select Part Kind dialog is displayed prompting the user to choose from a list of registered part kind editors or to invoke the Open File dialog to choose an existing file.

This method is invoked by the ApplicationShell's Go method

Related Methods

• DocumentManager::CreateDocumentInFile
• DocumentManager::OpenDocumentFromFile

ProcessArgs

This method processes the command line arguments.

Signature

void ProcessArgs (ODSLong argc, char **argv, char *fileName, char *partKind)

Parameters

argc  (ODSLong)  -  input 

The number of arguments contained in the command invocation string.

argv  (char **)  -  input 

The array of command line arguments.

fileName  (char *)  -  input 

The name of the document to open passed on the command line.

partKind  (char *)  -  input 

The part editor name passed on the command line.

Returns

None.

Remarks

This method controls parsing the command line, storing and returning its information, and validating the input file name, if one was entered. If both fileName and partKind parameters are specified, the document file specified by the fileName parameter is opened if the file exists and is readable; otherwise, a new document with the specified partKind parameter as the root part is created and opened.

This method is invoked by the ApplicationShell's Go method.

Related Methods

• ApplicationShell::Go

SendEventToRootPart

This method sends an event directly to the root part.

Signature

void SendEventToRootPart (ODEventData *event)

Parameters

event  (ODEventData *)  -  input 

The data structure containing information about the event.

Returns

None.

Remarks

This method is used for events that are not processed by the shell. These events are passed to the root part for processing.    

SetExecString

This method saves the original command line invocation string.

Signature

void SetExecString ()

Parameters

None.

Returns

None.

Remarks

This is an accessor method used to save the original command line invocation string.

Related Methods

• ApplicationShell::GetExecString

UpdateUndoMenus

This method enables or disables the Undo and Redo menu items as appropriate.

Signature

void UpdateUndoMenus ()

Parameters

None.

Returns

None.

Remarks

This method enables or disables the Undo and Redo menu items depending on whether there is anything on the redo and undo stack.

Related Methods

• ODUndo class definition