Programming Reference: OpenDocShell

# Programming Reference

## OpenDocShell

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

Class Hierarchy

    SOMObject
       OpenDocShell

Description | The OpenDocShell class is the top layer of the shell class hierarchy. It defines the features required by any OpenDoc Shell application. It controls the OpenDoc session, manages document initialization and termination sequences, dispatches events, and controls the associated instances of DocumentManager.

Methods

The methods defined by the OpenDocShell class include:

- CreateDocumentManager
- CreateDocumentManagerIterator
- DeleteDocumentManager
- DeleteDocumentManagerIterator
- DispatchEvent
- GetActiveDocumentManager
- GetArgc
- GetArgv
- GetDocumentManagerOfDraft
- GetSession
- GetWindowState
- GetWindowSystemData
- InitOpenDocShell
- SetActiveDocumentManager
- SetArgc
- SetArgv
- SetWindowSystemData
- SubClassResponsibility
- Terminate
- UpdateActiveDocumentManager

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

### CreateDocumentManager

This method creates a DocumentManager object.

Signature

    DocumentManager *CreateDocumentManager ()

Parameters

None.

Returns

rv (DocumentManager *) - returns

  A reference to a newly created DocumentManager object.

Remarks

This method creates and initializes a newly created DocumentManager object.

### CreateDocumentManagerIterator

This method creates an iterator for the list of DocumentManager objects associated with the shell.

Signature

    OrderedCollectionIterator *CreateDocumentManagerIterator ()

Parameters

None.

Returns

rv (OrderedCollectionIterator *) - returns

  A reference to an iterator for the document manager list.

Remarks

This method creates an iterator for the list of DocumentManager objects associated with the shell.

### DeleteDocumentManager

This method deletes a DocumentManager object.

Signature

    void DeleteDocumentManager (DocumentManager *docMgr)

Parameters

docMgr (DocumentManager *) - input

  A reference to the DocumentManager object.

Returns

None.

Remarks

This method deletes a DocumentManager object and removes it from the list of document managers.

### DeleteDocumentManagerIterator

This method deletes an iterator for the list of DocumentManager objects associated with the shell.

Signature

    void DeleteDocumentManagerIterator (OrderedCollectionIterator *docMgrIter)

Parameters

docMgrIter (OrderedCollectionIterator *) - input

  The iterator to be deleted.

Returns

None.

Remarks

This method deletes an iterator for DocumentManager objects.

### DispatchEvent

This method dispatches events.

Signature

    ODBoolean DispatchEvent (ODEventData *event)

Parameters

event (ODEventData *) - input

  The event to be dispatched.

Returns

rv (ODBoolean) - returns

  kODTrue if the event was handled; otherwise, kODFalse.

Remarks

This method receives incoming events from the window system and passes them to the Dispatcher. Certain items, like focus and menu events are handled by the OpenDoc shell.

Related Methods

- ApplicationShell::AdjustMenu
- ApplicationShell::HandleCloseEvent
- ApplicationShell::HandleMenuEvent

### GetActiveDocumentManager

This method returns the active DocumentManager.

Signature

    DocumentManager *GetActiveDocumentManager ()

Parameters

None.

Returns

rv (DocumentManager) - returns

  The active DocumentManager.

Remarks

This method returns a reference to the DocumentManager object corresponding to the current, active document.

Related Methods

- OpenDocShell::SetActiveDocumentManager
- OpenDocShell::UpdateActiveDocumentManager

### GetArgc

This method returns the number of arguments in the command invocation string of the shell process.

Signature

    long GetArgc ()

Parameters

None.

Returns

rv (long) - returns

  The number of arguments.

Remarks

This method returns the command line's argc value. During shell initialization, the command invocation is saved.

Related Methods

- OpenDocShell::GetArgv
- OpenDocShell::SetArgc
- OpenDocShell::SetArgv

### GetArgv

This method returns the array of command line arguments.

Signature

    char **GetArgv ()

Parameters

None.

Returns

rv (char **) - returns

  The array of arguments.

Remarks

This method returns the command line's argv value. During shell initialization, the command invocation is saved.

Related Methods

- OpenDocShell::GetArgc
- OpenDocShell::SetArgc
- OpenDocShell::SetArgv

### GetDocumentManagerOfDraft

This method returns a reference to the DocumentManager object corresponding to a specific draft.

Signature

    DocumentManager *GetDocumentManagerOfDraft (ODDraft *draft)

Parameters

draft (ODDraft *) - input

  The draft.

Returns

rv (char **) - returns

  The DocumentManager object.

Remarks

Given a reference to a draft object, this method iterates through the list of DocumentManager objects to find the one corresponding to document of the draft.

### GetSession

This method returns a reference to the session object.

Signature

    ODSession *GetSession ()

Parameters

None.

Returns

rv (ODSession *) - returns

  The reference to the session object.

Remarks

This method returns a reference to a session object. When the shell creates the session object, it stores a reference that the shell can later call.

### GetWindowState

This method returns a reference to the window state object.

Signature

    ODWindowState *GetWindowState ()

Parameters

None.

Returns

rv (ODWindowState *) - returns

  The reference to the window state object.

Remarks

This method returns a reference to a window state object. When the shell creates the window state object, it stores a reference that the shell can later call.

### GetWindowSystemData

This method returns a reference to the window system data structure.

Signature

    WindowSystemData *GetWindowSystemData ()

Parameters

None.

Returns

rv (WindowSystemData) - returns

  A reference to the window system data structure.

Remarks

The shell defines a data structure, WindowSystemData, for holding values regarding the window system and user interface. The structure is created and initialized in the platform shell's InitWindowSystem method. Shell methods can call GetWindowSystemData to obtain a reference to this data. The WindowSystemData members may then be updated, if necessary, and SetWindowSystemData can be called to save the new values.

Related Methods

- ApplicationShell::InitWindowSystem
- OpenDocShell::SetWindowSystemData

### InitOpenDocShell

This method performs the initialization of the shell.

Signature

    void InitOpenDocShell ()

Parameters

None.

Returns

None.

Remarks

This method performs the actions necessary to initialize the OpenDoc environment. The session is created and initialized and shell plug-ins are initialized.

Related Methods

- ODSession::InitSession

### SetActiveDocumentManager

This method identifies the active DocumentManager.

Signature

    void SetActiveDocumentManager (DocumentManager docMgr)

Parameters

docMgr (DocumentManager) - input

  A reference to the active DocumentManager object.

Returns

None.

Remarks

This method saves a reference to a newly active DocumentManager when the focus switches from one document to another. An active document manager is one that corresponds to the document having the focus.

Related Methods

- OpenDocShell::GetActiveDocumentManager
- OpenDocShell::UpdateActiveDocumentManager

### SetArgc

This method identifies the number of arguments in the command invocation string of the shell process.

Signature

    void SetArgc (long argc)

Parameters

argc (long) - input

  The number of arguments.

Returns

None.

Remarks

This method sets the command line's argc value. During shell initialization, the command invocation needs to be saved.

Related Methods

- OpenDocShell::GetArgc
- OpenDocShell::GetArgv
- OpenDocShell::SetArgv

### SetArgv

This method identifies the array of command line arguments.

Signature

    void SetArgv (char **argv)

Parameters

argv (char **) - input

  The array of arguments.

Returns

None.

Remarks

This method sets the command line's argv value. During shell initialization, the command invocation needs to be saved.

Related Methods

- OpenDocShell::GetArgc
- OpenDocShell::GetArgv
- OpenDocShell::SetArgc

### SetWindowSystemData

This method identifies the window system data structure of the shell.

Signature

    void SetWindowSystemData (WindowSystemData *windowSystemData)

Parameters

windowSystemData (WindowSystemData) - input

  The window system data structure of the shell.

Returns

None.

Remarks

The shell defines a data structure, WindowSystemData, for holding values regarding the window system and user interface. The structure is created and initialized in the platform shell's InitWindowSystem method. Shell methods can call GetWindowSystemData to obtain a reference to this data. The WindowSystemData members may then be updated, if necessary, and SetWindowSystemData can be called to save the new values.

Related Methods

- ApplicationShell::InitWindowSystem
- OpenDocShell::GetWindowSystemData

### SubClassResponsibility

This method displays a warning message indicating that the subclass failed to override a required method.

Signature

    void SubClassResponsiblity ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method at runtime to indicate that a subclass that should have overridden a particular method failed to do so.

### Terminate

This method performs all actions required at termination.

Signature

    void Terminate ()

Parameters

None.

Returns

None.

Remarks

This method is called after the shell's main event loop has exited and preforms all actions prior to exiting.

### UpdateActiveDocumentManager

This method determines and sets the active DocumentManager object.

Signature

    void UpdateActiveDocumentManager (ODWindow *window)

Parameters

window (ODWindow *) - input

  The ODWindow for which the corresponding DocumentManager object needs to be determined.

Returns

None.

Remarks

This method determines which DocumentManager object is associated with the given ODWindow object and marks it as active.

Related Methods

- OpenDocShell::GetActiveDocumentManager
- OpenDocShell::SetActiveDocumentManager

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