Programming Reference: ODWindow

# Programming Reference

## ODWindow

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

Class Hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODWindow

Description

An object of the ODWindow class is a wrapper for a platform-specific window structure.

Every window, except a modal dialog box, must be associated with an OpenDoc window object so that the part belonging to the root frame of the window, and its embedded parts, can receive events from the dispatcher. To make platform-specific calls, part editors can retrieve the platform-specific window from a window object. In most cases, the interface to the ODWindow class provides the capability you need for interacting with your platform-specific windows.

Your part creates a window object by calling the window-state object's RegisterWindow or RegisterWindowForFrame method.

When your part creates a window, it specifies whether the new window should be a root window. A document remains open as long as it has an open root window; the document shell closes the document when the last root window is closed. A root window is also called a document window. The initial window of a document is a root window; its root part is the root part of the document. Part windows, which display embedded parts, and the dialog boxes are not root windows. OpenDoc permits a single document to have multiple root windows while the root part provides a user interface to support them.

Your part should not maintain references to window objects for accessing OpenDoc windows because the document shell or the window-state object can close the window object and invalidate the reference. You should instead maintain window IDs, from the which the window object can be reconstructed.

Methods

The methods defined by the ODWindow class include:

Manipulating Windows

- Close
- CloseAndRemove
- GetID
- GetPlatformWindow
- Hide
- Select
- Show
- Update

Window Characteristics

- IsActive
- IsFloating
- IsResizable
- IsRootWindow
- IsShown
- SetShouldSave
- SetShouldShowLinks
- ShouldDispose
- ShouldSave
- ShouldShowLinks

Manipulating Facets

- GetFacetUnderPoint
- GetRootFacet
- Open

Manipulating Frames

- AcquireSourceFrame
- AdjustWindowShape
- GetRootFrame
- SetSourceFrame

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

### AcquireSourceFrame

This method returns a reference to the frame, if any, from which this window was opened.

Signature

    ODFrame *AcquireSourceFrame ()

Parameters

None.

Returns

rv (ODFrame *) - returns

  A reference to the frame from which this window was opened or kODNULL if the window does not have a source frame (for example, a root window).

Remarks

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

If your part class implements shared dialog windows (which are shared by all part objects of your class in a document), your part objects can use the source frame of the dialog window to find out which frame is associated with the dialog window.

It is possible to change the source frame later on by calling this window's SetSourceFrame method.

Related Methods

- ODWindow::SetSourceFrame

### AdjustWindowShape

This method reshapes the root frame to match the size of this window.

Signature

    void AdjustWindowShape ()

Parameters

None.

Returns

None.

Remarks

Your part (the root part) calls this method after sizing the window.

### Close

This method is called by the document shell or container application to close this window object.

Signature

    void Close ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method when closing a document; parts typically call this window object's CloseAndRemove method instead of this method.

### CloseAndRemove

This method closes this window object and removes the root frame from its draft.

Signature

    void CloseAndRemove ()

Parameters

Returns

None.

Remarks

This method closes this window object, releases this window object, deletes the root facet, and removes the root frame from the draft. Your part calls this method to remove auxiliary windows, such as palettes or part windows.

### GetFacetUnderPoint

This method returns a reference to the facet of this window under the specified point.

Signature

    ODFacet *GetFacetUnderPoint (ODPoint *aPoint)

Parameters

aPoint (ODPoint *) - input

  The location to test, expressed in window coordinates.

Returns

rv (ODFacet *) - returns

  A reference to the facet under the specified point.

Remarks

OpenDoc calls this method for event dispatching; this method is not called by most parts.

If several nested facets are under the point, the innermost one is returned. If multiple overlapping frames are under the point, the front-most, visible one is returned. The bundled and selected properties of frames and facets are respected.

### GetID

This method returns the window ID for this window object.

Signature

    ODID GetID ()

Parameters

None.

Returns

rv (ODID) - returns

  The window ID for this window object.

Remarks

The window-state object assigns window IDs that are valid for the length of the session. You can use this method to get the window ID of this window object when it is created, and then pass that ID to the window-state object's AcquireWindow method for subsequent access to this window object.

Related Methods

- ODWindowState::AcquireWindow

### GetPlatformWindow

This method returns the platform-specific window for this window object.

Signature

    ODPlatformWindow GetPlatformWindow ()

Parameters

None.

Returns

rv (ODPlatformWindow) - returns

  The platform-specific window for this window object.

### GetRootFacet

This method returns a reference to the root facet of this window object.

Signature

    ODFacet *GetRootFacet ()

Parameters

None.

Returns

rv (ODFacet *) - returns

  A reference to the root facet of this window object.

### GetRootFrame

This method returns a reference to the root frame of this window object.

Signature

    ODFrame *GetRootFrame ()

Parameters

None.

Returns

rv (ODFrame *) - returns

  A reference to the root frame of this window object.

Remarks

This method does not increment the reference count of the returned frame. For that reason, if you cache the returned frame, you should call its Acquire method to increment its reference count and then call its Release method when you have finished using it.

### Hide

This method makes this window invisible.

Signature

    void Hide ()

Parameters

None.

Returns

None.

Related Methods

- ODWindow::Show

### IsActive

This method indicates whether this window is active.

Signature

    ODBoolean IsActive ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window is active.

  kODTrue | This window is active. It is the front-most, non-floating window or a floating window.
  kODFalse | This window is not active.

### IsFloating

This method indicates whether this window is a floating window.

Signature

    ODBoolean IsFloating ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window is a floating window.

  kODTrue | The window is a floating window.
  kODFalse | The window is not a floating window.

### IsResizable

This method indicates whether this window is resizable.

Signature

    ODBoolean IsResizable ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window is resizable.

  kODTrue | This window is resizable.
  kODFalse | This window is not resizable.

### IsRootWindow

This method indicates whether this window object is a root window.

Signature

    ODBoolean IsRootWindow ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window object is a root window.

  kODTrue | This window object is a root window.
  kODFalse | This window object is not a root window.

### IsShown

This method indicates whether this window is visible.

Signature

    ODBoolean IsShown ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window is visible.

  kODTrue | This window is visible.
  kODFalse | This window is not visible.

Related Methods

- ODWindow::Hide
- ODWindow::Show

### Open

This method creates a facet hierarchy in this window object.

Signature

    void Open ()

Parameters

None.

Returns

None.

Remarks

Your part calls this method when first opening a window. This method does not make the window visible or change window ordering; for those operations, your part calls this window object's Show and Select methods instead.

Related Methods

- ODWindow::Select
- ODWindow::Show

### Select

This method makes this window the front-most window and activates it.

Signature

    void Select ()

Parameters

None.

Returns

None.

Remarks

Your part calls this method when first opening or when later activating a window. This method changes window ordering.

Related Methods

- ODWindow::Show

### SetShouldSave

This method specifies whether this window object should be saved in its draft.

Signature

    void SetShouldSave (ODBoolean shouldSave)

Parameters

shouldSave (ODBoolean) - input

  A flag indicating whether the window should be saved in the draft.

  kODTrue | The window should be saved.
  kODFalse | The window should not be saved.

Returns

None.

Remarks

This property should generally be set to kODTrue for root windows and kODFalse for other windows.

Related Methods

- ODWindow::ShouldSave

### SetShouldShowLinks

This method specifies whether links should be highlighted in this window.

Signature

    void SetShouldShowLinks (ODBoolean shouldShowLinks)

Parameters

shouldShowLinks (ODBoolean) - input

  A flag indicating whether the links should be highlighted in this window.

  kODTrue | The links should be highlighted in this window.
  kODFalse | The links should not be highlighted in this window.

Returns

None.

Related Methods

- ODWindow::ShouldShowLinks

### SetSourceFrame

This method sets the source frame of this window object.

Signature

    void SetSourceFrame (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to the new source frame.

Returns

None.

Related Methods

- ODWindow::AcquireSourceFrame

### ShouldDispose

This method indicates whether this window object should be disposed of when a window object is deleted.

Signature

    ODBoolean ShouldDispose ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window object should be disposed of when a window object is deleted.

  kODTrue | This window object is to be removed.
  kODFalse | This window object is not to be removed.

Remarks

This method returns an ODBoolean value that indicates whether the platform window should be disposed of when this window objct is deleted.

Related Methods

- ODWindow::ShouldSave

### ShouldSave

This method indicates whether this window object is saved in its draft.

Signature

    ODBoolean ShouldSave ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this window object is saved in its draft.

  kODTrue | This window object is saved.
  kODFalse | This window object is not saved.

Related Methods

- ODWindow::ShouldSave

### ShouldShowLinks

This method indicates whether links are highlighted in this window.

Signature

    ODBoolean ShouldShowLinks ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether links are highlighted in this window.

  kODTrue | The links are highlighted in this window.
  kODFalse | The links are not highlighted in this window.

Related Methods

- ODWindow::SetShouldShowLinks

### Show

This method makes this window visible.

Signature

    void Show ()

Parameters

None.

Returns

None.

Remarks

Your part calls this method when first opening a window, when making a window visible, or after having called its Hide method. This method does not change window ordering.

Related Methods

- ODWindow::Hide
- ODWindow::Select

### Update

This method forces immediate updating of this window, rather than waiting for an update event.

Signature

    void Update (ODEventData *theEvent)

Parameters

theEvent (ODEventData *) - returns

  The event that just occurred within your part.

Returns

None.

Remarks

When an update event occurs that involves a facet of your part, OpenDoc calls this method, which in turn calls its facet's Update method, which then calls the Draw method associated with the facet's part. Your part might call this method to force updating when it is not automatic. An instance is when a mouse-down event occurs and you cannot wait for an update event.

Related Methods

- ODFacet::Update
- ODPart::Draw

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