Programming Reference: ApplicationShell

# Programming Reference

## ApplicationShell

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

Class Hierarchy

    SOMObject
       OpenDocShell
          ApplicationShell

Description.

The ApplicationShell class inherits from the OpenDocShell class and adds behavior of the shell application that is provided with OpenDoc. It adds support for a menu bar that is shared by the part editors of a document and provides operations of the Document menu. It also adds the application command line processing and event loop.

The ApplicationShell is a platform-independent class. It provides only the implementation of the methods that are platform-independent. The remaining methods must be overridden in a platform-specific subclass.

Methods

The methods defined by the ApplicationShell class include:

- AdjustMenu
- CloseCleanup
- CreateMenuBar
- DocumentAbout
- DocumentClose
- DocumentDraftCreate
- DocumentDraftHistory
- DocumentInfo
- DocumentNew
- DocumentOpen
- DocumentPageSetup
- DocumentPrint
- DocumentRevert
- DocumentSave
- DocumentSaveAs
- Exec
- GetEventSubType
- GetEventType
- GetEventWindow
- GetExecString
- Go
- HandleCloseEvent
- HandleMenuEvent
- InitWindowSystem
- IsValidFileName
- MainLoop
- OpenDocument
- ProcessArgs
- SendEventToRootPart
- SetExecString
- UpdateUndoMenus

Overridden Methods

The methods overridden by the ApplicationShell class include:

- OpenDocShell::DispatchEvent

### 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

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