Programming Reference


ODWindowState

     

Class Definition File

WinStat.idl

Class C++ Binding

WinStat.xh

Class Hierarchy

SOMObject
   ODObject
      ODWindowState

Description

An object of the ODWindowState class maintains a list of all the open window objects for all open drafts in an OpenDoc session, references to the base menu bar and the current menu bar, and references to the base popup and current popup.

When a document is opened, the session object creates a single window-state object. All parts of that document share the window-state object; you can obtain a reference to it by calling the session object's GetWindowState method. The document shell and dispatcher use the window-state object to pass events to parts so the parts can activate themselves, handle user input, and adjust their menus as necessary. The document shell may manage more than one open document. Typically, however, there is only one open document in a session, but multiple drafts of the document may be open. A part may be displayed in any number of frames, in any window of a document. The dispatcher passes events to the correct part, without regards to which window encloses the active frame and how many other frames the part has.

Your part accesses the window-state object to create new windows, to access a particular window, and to access the base menu-bar object.

For more information related to window objects, see the class description for ODWindow.

Methods

The methods defined by the ODWindowState class include:

Creating Windows

Manipulating Windows

Window Characteristics

Manipulating Menu Bars

Creating Facets and Canvases

Overridden Methods

There are no methods overridden by the ODWindowState class.

   

AcquireActiveWindow

This method returns a reference to the front-most, non-floating window.

Signature
ODWindow *AcquireActiveWindow ()

Parameters

None.

Returns

rv  (ODWindow *)  -  returns 

A reference to the front-most non-floating window or kODNULL if the front-most non-floating window is not an OpenDoc window.

Remarks

This method increments the reference count of the returned window object. When you have finished using that window object, you should call its Release method.      


AcquireBaseMenuBar

This method is called by the document shell to retrieve a reference to the base menu bar.

Signature
ODMenuBar *AcquireBaseMenuBar ()

Parameters

None.

Returns

rv  (ODMenuBar *)  -  returns 

The base menu bar.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBaseMenuBar method instead of this method.

This method increments the reference count of the returned menu-bar object. When the caller has finished using that menu-bar object, it should call the menu bar's Release method.

Related Methods

     

AcquireBasePopupMenu

This method is called by the document shell to retrieve a reference to the base popup menu.

Signature
ODMenuBar *AcquireBasePopupMenu ()

Parameters

None.

Returns

rv  (ODPopup *)  -  returns 

The base popup menu.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBasePopup method instead of this method.

This method increments the reference count of the returned popup menu object. When the caller has finished using that popup menu object, it should call the popup menu 's Release method.

Related Methods

   

AcquireCurrentMenuBar

This method is called by the document shell to retrieve a reference to the menu bar being displayed by the document shell.

Signature
ODMenuBar *AcquireCurrentMenuBar ()

Parameters

None.

Returns

rv  (ODMenuBar *)  -  returns 

A reference to the menu bar being displayed.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBaseMenuBar method instead of this method.

This method increments the reference count of the returned menu-bar object. When the caller has finished using that menu-bar object, it should call the menu bar's Release method.

Related Methods

   

AcquireCurrentPopupMenu

This method is called by the document shell to retrieve a reference to the popup menu being displayed by the document shell.

Signature
ODPopup *AcquireCurrentPopupMenu ()

Parameters

None.

Returns

rv  (ODPopup *)  -  returns 

A reference to the popup menu being displayed.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBasePopup method instead of this method.

This method increments the reference count of the returned popup menu object. When the caller has finished using that object, it should call the popup menu 's Release method.

Related Methods

   

AcquireFrontFloatingWindow

This method returns a reference to the front-most, floating window.

Signature
ODWindow *AcquireFrontFloatingWindow ()

Parameters

None.

Returns

rv  (ODWindow *)  -  returns 

A reference to the front-most floating window or kODNULL if there are no floating OpenDoc windows.

Remarks

This method increments the reference count of the returned window object. When you have finished using that window object, you should call its Release method.    


AcquireFrontRootWindow

This method returns a reference to the front-most, non-floating root window.

Signature
ODWindow *AcquireFrontRootWindow ()

Parameters

None.

Returns

rv  (ODWindow *)  -  returns 

A reference to the front-most (non-floating) root window.

Remarks

This method increments the reference count of the returned window object. When you have finished using that window object, you should call its Release method.    


AcquireFrontWindow

This method returns a reference to the front-most window.

Signature
ODWindow *AcquireFrontWindow ()

Parameters

None.

Returns

rv  (ODWindow *)  -  returns 

A reference to the front-most window or kODNULL if the front-most window is not an OpenDoc window.

Remarks

This method increments the reference count of the returned window object. When you have finished using that window object, you should call its Release method.    


AcquireODWindow

This method returns a reference to the window object corresponding to the specified platform-specific window.

Signature
ODWindow *AcquireODWindow (ODPlatformWindow aWindow)

Parameters

aWindow  (ODPlatformWindow)  -  input 

A platform-specific window.

Returns

rv  (ODWindow *)  -  returns 

A reference to the window object corresponding to the specified platform-specific window or kODNULL if the window is not an OpenDoc window.

Remarks

OpenDoc calls this method.

This method increments the reference count of the returned window object. When the caller has finished using that window object, it should call the window's Release method.

Related Methods

   

AcquireWindow

This method returns a reference to the window object with the specified ID.

Signature
ODWindow *AcquireWindow (ODID id)

Parameters

id  (ODID)  -  input 

The window ID for the window object.

Returns

rv  (ODWindow *)  -  returns 

A reference to the window object with the specified ID, or kODNULL if the window has been deleted or does not exist.

Remarks

This method increments the reference count of the returned window object. When you have finished using that window object, you should call its Release method.

Related Methods

   

AdjustPartMenus

This method calls both the root part and the part with the menu focus to adjust the displayed menu.

Signature
void AdjustPartMenus ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method when a mouse-down event occurs in the menu bar. This method in turn calls the AdjustMenus method for both the root part and the part with the menu focus, so the parts can enable or disable menu items as necessary. If the root part has the menu focus, then OpenDoc only calls the AdjustMenus method once.

Related Methods

     

CloseWindows

This method is called by the document shell or container application to close all windows belonging to the specified draft.

Signature
void CloseWindows (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the open draft object.

Returns

None.

Remarks

The document shell calls this method when closing a draft.

Related Methods

   

CopyBaseMenuBar

This method copies the base menu-bar object.

Signature
ODMenuBar *CopyBaseMenuBar ()

Parameters

None.

Returns

rv  (ODMenuBar *)  -  returns 

A reference to the newly created copy of the base menu-bar object.

Remarks

Your part calls this method to create a menu-bar object to which it can add its own menus.

This method initializes the reference count of the returned menu-bar object. When you have finished using that menu-bar object, you should call its Release method.

Related Methods

   

CopyBasePopup

This method copies the base pop-up menu object.

Signature
ODPopup *CopyBasePopup ()

Parameters

None.

Returns

rv  (ODPopup *)  -  returns 

A reference to a copy of the pop-up menu object.

Remarks

Your part editor calls this method to create a pop-up menu object to which it can add its own menus items. This method in turn calls its pop-up menu object's Copy method.

This method increments the reference count of the returned pop-up menu object. When you have finished using that pop-up menu object, you should call its Release method.    


CreateCanvas

This method creates a canvas object that will not be attached to a facet.

Signature
ODCanvas *CreateCanvas (ODGraphicsSystem graphicsSystem,
                        ODPlatformCanvas *platformCanvas,
                        ODBoolean isDynamic,
                        ODBoolean isOffscreen)

Parameters

graphicsSystem  (ODGraphicsSystem)  -  input 

The graphics system to be used for the canvas. Valid graphics systems for this parameter are platform-dependent:

platformCanvas  (ODPlatformCanvas *)  -  input 

The graphics-system-specific drawing canvas to be assigned to this canvas or kODNULL if there is no drawing structure associated with the specified graphics system. Valid values for the parameter are graphics-system-dependent.

isDynamic  (ODBoolean)  -  input 

A flag indicating whether this canvas is to be dynamic.
kODTrue The canvas is to be dynamic.
kODFalse The canvas is to be static.

isOffscreen  (ODBoolean)  -  input 

A flag indicating whether this canvas is to be offscreen.
kODTrue The canvas is to be offscreen.
kODFalse The canvas is to be onscreen.

Returns

rv  (ODCanvas *)  -  returns 

A reference to the new canvas object.

Remarks

To create a canvas to attach to a particular facet, you should call that facet's CreateCanvas method.

Related Methods

   

CreateFacet

This method creates a facet object.

Signature
ODFacet *CreateFacet (ODFrame *frame,
                      ODShape *clipShape,
                      ODTransform *externalTransform,
                      ODCanvas *canvas,
                      ODCanvas *biasCanvas)

Parameters

frame  (ODFrame *)  -  input 

A reference to the frame for the facet.

clipShape  (ODShape *)  -  input 

A reference to the initial clip shape for the facet.

externalTransform  (ODTransform *)  -  input 

A reference to the initial external transform for the facet.

canvas  (ODCanvas *)  -  input 

A reference to the canvas the facet should draw to or kODNULL if identical to the canvas associated with the containing facet.

biasCanvas  (ODCanvas *)  -  input 

A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in the standard platform-normal coordinates.

Returns

rv  (ODFacet *)  -  returns 

A reference to the newly created facet object.

Remarks

Your part calls this method to create a root facet (for example, for printing). The frame is defined for the lifetime of the facet object; once set, it cannot be changed.

To create a facet object for a visible embedded frame, your part should call its own display facet's CreateEmbeddedFacet method instead of this method.

Related Methods

     

CreateMenuBar

This method is called by the document shell to create and initialize a menu-bar object.

Signature
ODMenuBar *CreateMenuBar (ODPlatformMenuBar menuBar)

Parameters

menuBar  (ODPlatformMenuBar)  -  input 

A platform-specific menu-bar.

Returns

rv  (ODMenuBar *)  -  returns 

A reference to the newly created menu-bar object.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBaseMenuBar method instead of this method.

This method initializes the reference count of the returned menu bar. When the caller has finished using that menu bar, it should call the menu bar's Release method.

Related Methods

     

CreateMenuBarEx (Windows)

This method is called by the document shell to create and initialize a menu-bar object. This method is similar to CreateMenuBar, but takes additional parameters to specify the IDs for the submenus in the menu being added. This is necessary because Windows NT does not support IDs for submenus.

Signature
ODMenuBar *CreateMenuBarEx (ODPlatformMenuBar menuBar,
                            OSUShort subMenuIDCount,
                            ODMenuIDInfo *subMenuIDInfo)

Parameters

menuBar  (ODPlatformMenuBar)  -  input 

A platform-specific menu-bar.

subMenuIDCount  (ODUShort)  -  input 

The number of submenu IDs to be passed.

subMenuIDInfo  (ODMenuIDInfo *)  -  input 

A reference to an array of submenu ID information. For additional information, see ODMenuBar::AddMenuLastEx.

Returns

rv  (ODMenuBar *)  -  returns 

A reference to the newly created menu-bar object.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBaseMenuBar method instead of this method.

This method initializes the reference count of the returned menu bar. When the caller has finished using that menu bar, it should call the menu bar's Release method.

Related Methods

   

CreatePlatformWindow

Signature
ODPlatformWindow CreatePlatformWindow (ODBoolean isFloating)

Parameters

isFloating  (ODBoolean)  -  input 

A flag indicating whether the window object is to be a floating window.
kODTrue The window object is to be a floating window.
kODFalse The window object is not to be a floating window.

Returns

rv  (ODPlatformWindow)  -  returns 

The document window created; NULL if unable to create.

Remarks

OpenDoc parts cannot directly create document windows. Therefore, this method allows OpenDoc parts to create document windows using platform APIs.      


CreatePopupMenu

This method is called by the document shell to create and initialize a popup menu object.

Signature
ODPopup *CreatePopupMenu (ODPlatformMenuBar popupMenu)

Parameters

popupMenu  (ODPlatformMenuBar)  -  input 

A platform-specific popup menu.

Returns

rv  (ODPopup *)  -  returns 

A reference to the newly created popup menu object.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBasePopup method instead of this method.

This method initializes the reference count of the returned popup menu. When the caller has finished using that popup menu, it should call the popup menu's Release method.

Related Methods

     

CreatePopupMenuEx (Windows)

This method is called by the document shell to create and initialize a popup menu object. This method is similar to CreatePopupMenu but takes additional parameters to specify the IDs for the submenus in the menu being added. This is necessary because Windows NT does not support IDs for submenus.

Signature
ODPopup *CreatePopupMenuEx (ODPlatformMenuBar popupMenu,
                            ODUShort subMenuIDCount,
                            ODMenuIDInfo *subMenuIDInfo)

Parameters

popupMenu  (ODPlatformMenuBar)  -  input 

A platform-specific menu-bar.

subMenuIDCount  (ODUShort)  -  input 

The number of submenu IDs to be passed.

subMenuIDInfo  (ODMenuIDInfo *)  -  input 

A reference to an array of submenu ID information. For additional information, see ODMenuBar::AddMenuLastEx.

Returns

rv  (ODPopup *)  -  returns 

A reference to the new popup menu object.

Remarks

The document shell calls this method. Your part typically calls this window-state object's CopyBasePopup method instead of this method.

This method initializes the reference count of the returned popup menu. When the caller has finished using that popup menu, it should call the popup menu's Release method.

Related Methods

   

CreateWindowIterator

This method creates a window iterator for the windows (of all drafts) in this window-state object.

Signature
ODWindowIterator *CreateWindowIterator ()

Parameters

None.

Returns

rv  (ODWindowIterator *)  -  returns 

A reference to the newly created window iterator.

Remarks

Your part calls this method if it needs to apply an operation to all windows of a window-state object. For example, a root part might use a window iterator to tile all the opened windows.

While you are using the returned window iterator, you must not call any methods that create or delete windows.

You must delete the returned window iterator when it is no longer needed.    


Externalize

This method is called by the document shell to write to persistent storage the window properties of windows of the specified draft and save their frames as the root frames of the draft.

Signature
void Externalize (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the open draft object.

Returns

None.

Remarks

The document shell calls this method when saving a draft. This method saves window properties for those windows of the specified draft that should be saved. For these windows, the ShouldSave method returned kODTrue.

Related Methods

   

GetAppContext (AIX)

This method returns the application context of the window-state object.

Signature
XtAppContext GetAppContext ()

Parameters

None.

Returns

rv  (XtAppContext)  -  returns 

The application context of the window-state object.

Remarks

This method returns the application context of the window-state object. Your part calls this method when it needs the application context.    


GetDisplay (AIX)

This method returns the Xlib display of the window-state object.

Signature
Display *GetDisplay ()

Parameters

None.

Returns

rv  (Display *)  -  returns 

The Xlib display of the window-state object.

Remarks

This method returns the Xlib display of the window-state object. Your part calls this method when it needs the display.    


GetRootWindowCount

This method returns the number of root windows belonging to the specified draft.

Signature
ODUShort GetRootWindowCount (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the open draft object.

Returns

rv  (ODUShort)  -  returns 

The number of root windows belonging to the specified draft.

Remarks

The document shell calls this method when closing a window to determine when to close the draft; the draft is closed when its last root window is closed.

Related Methods

   

GetScreen (AIX)

This method returns the Xlib screen of the window-state object.

Signature
Screen *GetScreen ()

Parameters

None.

Returns

rv  (Screen *)  -  returns 

The Xlib screen of the window-state object.

Remarks

This method returns the Xlib screen of the window-state object. Your part calls this method when it needs the screen.    


GetTotalRootWindowCount

This method returns the total number of root windows of all open drafts.

Signature
ODUShort GetTotalRootWindowCount ()

Parameters

None.

Returns

rv  (ODUShort)  -  returns 

The number of root windows of all drafts.

Related Methods

 

GetWindowCount

This method returns the number of windows (of all open drafts) in this window-state object.

Signature
ODUShort GetWindowCount ()

Parameters

None.

Returns

rv  (ODUShort)  -  returns 

The total number of windows in this window-state object.
   

Internalize

This method is called by the document shell to read into memory all root frames of the specified draft, causing their parts to open the windows.

Signature
void Internalize (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the open draft object.

Returns

None.

Remarks

The document shell calls this method when opening a draft. After reading the root frames, this method reads into memory the part associated with each root frame, then passes that root frame as the parameter to its part's Open method. The Open method in turn creates the root (document) window for the root frame.

Exception Handling
kODErrOutOfMemory There is not enough memory to read in the data.

Related Methods

 

IsODWindow

This method indicates whether this window-state object has a window with the specified platform-specific window.

Signature
ODBoolean IsODWindow (ODPlatformWindow aWindow)

Parameters

aWindow  (ODPlatformWindow)  -  input 

A platform-specific window structure.

Returns

rv  (ODBoolean)  -  returns 

A flag indicating whether this window-state object has a window with the specified platform-specific window.
kODTrue This window-state object has a window with the specified platform-specific window.
kODFalse This window-state object does not have a window with the specified platform-specific window.

Remarks

OpenDoc calls this method.

Related Methods

   

OpenWindows

This method is called by the document shell or container application to open all windows belonging to the specified draft.

Signature
void OpenWindows (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the open draft object.

Returns

None.

Remarks

If the draft is already open, this method brings its window to the front.

Exception Handling
kODErrOutOfMemory There is not enough memory to open all the windows.

Related Methods

   

RegisterWindow

This method creates an OpenDoc window object and root frame for the specified platform-specific window.

Signature
ODWindow *RegisterWindow (ODPlatformWindow newWindow,
                          ODType frameType,
                          ODBoolean isRootWindow,
                          ODBoolean isResizable,
                          ODBoolean isFloating,
                          ODBoolean shouldSave,
                          ODBoolean shouldDispose,
                          ODPart *rootPart,
                          ODTypeToken viewType,
                          ODTypeToken presentation,
                          ODFrame *sourceFrame)

Parameters

newWindow  (ODPlatformWindow)  -  input 

A platform-specific window structure.

frameType  (ODType)  -  input 

The type of root frame for the window object. This parameter must be set to one of the following values:
kODFrameObject A regular frame.
kODNonPersistentFrameObject A nonpersistent frame object.

isRootWindow  (ODBoolean)  -  input 

A flag indicating whether the window object is to be a root window.
kODTrue The window object is to be a root window.
kODFalse The window object is to be a regular window.

isResizable  (ODBoolean)  -  input 

A flag indicating whether the window object is to be resizable.
kODTrue The window object is to be resizable.
kODFalse The window object is not to be resizable.

isFloating  (ODBoolean)  -  input 

A flag indicating whether the window object is to be a floating window.
kODTrue The window object is to be a floating window.
kODFalse The window object is not to be a floating window.

shouldSave  (ODBoolean)  -  input 

A flag indicating whether the window object is to be saved in its draft.
kODTrue The window object is to be saved in its draft.
kODFalse The window object is not to be saved in its draft.

shouldDispose  (ODBoolean)  -  input 

A flag indicating whether the platform window should be removed when this window object is deleted.
kODTrue The window object should be removed.
kODFalse The window object should not be removed.

rootPart  (ODPart *)  -  input 

A reference to the part associated with the root frame of the window.

viewType  (ODTypeToken)  -  input 

A tokenized string representing the view type for the root frame of the window.

This parameter must be the tokenized form of one of the following view-type constants. You can call the session's Tokenize method to obtain a token corresponding to one of these constants.
kODViewAsFrame Framed view type.
kODViewAsLargeIcon Large-icon (standard) view type.
kODViewAsSmallIcon Small-icon view type.
kODViewAsThumbNail Thumbnail view type.

presentation  (ODTypeToken)  -  input 

A tokenized string representing the presentation type for the root frame of the window.

sourceFrame  (ODFrame *)  -  input 

A reference to the frame from which the window object was opened (used when an embedded frame is opened into a window) or kODNULL if the frame does not exist.

Returns

rv  (ODWindow *)  -  returns 

A reference to the newly created window object.

Remarks

This method is a part of the following method sequence.

  1. You should create the platform-specific window as invisible using the CreatePlatformWindow.
  2. Your part calls RegisterWindow to create a window object when there is no preexisting root frame.
  3. After calling RegisterWindow, you should call the Show method of the returned window to make it visible.

This method initializes the reference count of the returned window. When you have finished using that window, you should call its Release method.

Exception Handling
kODErrCannotCreateWindow There is not enough memory to create the new window object.

Related Methods

   

RegisterWindowForFrame

This method creates a window object for the specified platform-specific window and root frame.

Signature
ODWindow *RegisterWindowForFrame (ODPlatformWindow newWindow,
                                  ODFrame *frame,
                                  ODBoolean isRootWindow,
                                  ODBoolean isResizable,
                                  ODBoolean isFloating,
                                  ODBoolean shouldSave,
                                  ODBoolean shouldDispose,
                                  ODFrame *sourceFrame)

Parameters

newWindow  (ODPlatformWindow)  -  input 

A platform-specific window.

frame  (ODFrame *)  -  input 

A reference to the root frame of the window object.

isRootWindow  (ODBoolean)  -  input 

A flag indicating whether the window object is to be a root window.
kODTrue The window object is to be a root window.
kODFalse The window object is to be a regular window.

isResizable  (ODBoolean)  -  input 

A flag indicating whether the window object is to be resizable.
kODTrue The window object is to be resizable.
kODFalse The window object is not to be resizable.

isFloating  (ODBoolean)  -  input 

A flag indicating whether the window object is to be a floating window.
kODTrue The window object is to be a floating window.
kODFalse The window object is not to be a floating window.

shouldSave  (ODBoolean)  -  input 

A flag indicating whether the window object is to be saved in its draft.
kODTrue The window object is to be saved in its draft.
kODFalse The window object is not to be saved in its draft.

shouldDispose  (ODBoolean)  -  input 

A flag indicating whether the platform window should be removed when this window object is deleted.
kODTrue The window object should be removed.
kODFalse The window object should not be removed.

sourceFrame  (ODFrame *)  -  input 

A reference to the frame from which the window object was opened (used when an embedded frame is opened into a window) or kODNULL if the frame does not exist.

Returns

rv  (ODWindow *)  -  returns 

A reference to the newly created window.

Remarks

This method is a part of the following method sequence.

  1. You should create the platform-specific window as invisible using the CreatePlatformWindow.
  2. Your part calls RegisterWindowForFrame to create a window object when there is no preexisting root frame.
  3. After calling RegisterWindowForFrame, you should call the Show method of the returned window to make it visible.

This window initializes the reference count of the returned window object. When you have finished using that window object, you should call its Release method.

Exception Handling
kODErrCannotCreateWindow There is not enough memory to create the new window object.

Related Methods

   

SetBaseMenuBar

This method is called by the document shell or container application to install the specified menu-bar object as the base menu for parts to copy.

Signature
void SetBaseMenuBar (ODMenuBar *theMenuBar)

Parameters

theMenuBar  (ODMenuBar *)  -  input 

A reference to the menu-bar object to be installed as the base menu bar.

Returns

None.

Remarks

The base menu bar contains the Document, Edit, and Help menus.    


SetBasePopup

This method is called by the document shell or container application to install the pop-up menu object used by all parts.

Signature
void SetBasePopup (ODPopup *thePopup)

Parameters

thePopup  (ODPopup *)  -  input 

A reference to the pop-up menu object.

Returns

None.      


SetDefaultWindowTitles

This method is called by the document shell or container application to synchronize window titles with the file name of the document of the specified draft.

Signature
void SetDefaultWindowTitles (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the open draft object.

Returns

None.


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