Programming Reference: ODFacet

# Programming Reference

## ODFacet

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

Class Hierarchy

    SOMObject
       ODObject
          ODBaseFacet
             ODFacet

Description

An object of the ODFacet class holds nonpersistent information about the layout of parts and describes the location of a frame on a particular canvas for display and event dispatching.

A facet object represents a visible, drawable frame or portion of a frame. In the simplest case, each embedded frame in a document is displayed and manipulated using only a single facet. In some cases, however, your part might need to display portions of the same embedded frame in several places, such as in a split view. In that case, one or more facets might manage the layout of one frame. All facets of a frame might display that frame's content identically, or a part might store user-defined part information data in the facet to distinguish among its different facets. The part information might also consist of graphics-system-specific information used for displaying the facet.

Facets are organized hierarchically. Each window or printed page has a single facet, the root facet, that is the topmost facet visible in the document window. All other facets contained in that window descend from the root facet. Each facet of a given frame is contained within a facet of that frame's containing frame.

Facets that are contained within a root facet with an onscreen, dynamic canvas are each associated with a facet window. On OS/2, a facet window is a Presentation Manager (PM) window that is created and managed by OpenDoc. On AIX, a facet widget is created with a XmDrawingAreaWidgetClass for each facet. On Windows, a facet window is a child window created by OpenDoc. Parts should not attempt to manipulate their facet windows; however, the handle for the facet window is available through the facet's GetFacetHWND method so that parts can specify the facet window as the parent and owner of embedded PM controls, such as buttons and scroll bars. Notification messages from these controls are sent to the part by the facet window in the part's HandleEvent method. The hwnd field in the ODEventData structure identifies these messages as having come from the facet window rather than through the OpenDoc dispatcher.

Your part creates a facet object for each visible embedded frame by calling its own display facet's CreateEmbeddedFacet method. Your part can also create a root facet (for printing) by calling the window-state object's CreateFacet method. These methods return a reference to a facet object.

Facets may or may not exist for frames that have been previously visible and that have scrolled out of view, and parts may or may not create facets for frames that are expected to be visible soon. The only requirement is that facets must exist for all visible frames. A visible facet has a frame, and that frame is defined for the lifetime of the facet; once set, it cannot be changed. Facets that are not visible in a window may be purged from memory under low-memory conditions.

Facet Geometry

Facets hold information regarding the geometry of their corresponding frames. Each facet maintains an active shape, a clip shape and an external transform. The clip shape and external transform must be valid.

- The active shape defines the area within a frame in that the facet's embedded part is willing to receive geometry-based user events, such as mouse clicks. It is commonly identical to the frame shape of the facet's frame, but it might be modified to coincide with the used shape or some other shape. The facet's embedded part controls the active shape.

- The clip shape defines the area within a frame in which drawing can occur; it is the area visible by overlapping content of the containing part. If it is visible, the clip shape is identical to the frame shape of the facet's frame. The facet's containing part controls the clip shape.

- The external transform describes the transform that is applied to a facet to position, scale, or otherwise transform the image drawn within the facet in the coordinate space of its containing part. The facet's containing part controls the external transform.

Facets and Canvases

An on-screen dynamic canvas object is created by OpenDoc if the parent has an on-screen dynamic canvas. You can create a canvas to pass to the CreateEmbeddedFacet or, after the facet is created, call the ChangeCanvas method to replace the default on-screen canvas.

Because a facet can simultaneously have both a window canvas and an offscreen canvas, there are two environments to consider. The aggregate clip shape, the content transform, and the frame transform position and clip the facet on the closest drawing environment (the closest canvases in the facet hierarchy that may or may not be the window canvas). During real-time interactions, such as rubber-banding or dragging, your part might need to display directly in the window. In such cases, the window aggregate clip shape, window content transform, and window frame transform specifically position and clip the facet on the window canvas.

The ODFacet class includes several methods that specify geometry (shape and transform objects) or calculate positions on a canvas. Because these calculations necessarily assume a coordinate system, the ODFacet methods include a parameter, biasCanvas, that allows you to specify a canvas to whose coordinate space the geometry is biased. The bias canvas uses a bias transform to convert from the coordinate system used for drawing on the canvas to the coordinate system (platform-normal coordinates) used by the current graphics system.

On OS/2, facets that are displayed on a window canvas are displayed in separate PM windows. This is of concern to your part only if you want to contain PM controls, such as buttons or scroll bars, or if you want to specify a micro or normal presentation space for your facet's window. See "Facet Windows and Using Embedded Controls" recipe in the OpenDoc Programming Guide for more information.

For more information related to bias transform, see the class description for ODCanvas.

Methods

The methods defined by the ODFacet class include:

- AcquireActiveShape
- AcquireAggregateClipShape
- AcquireClipShape
- AcquireContentTransform
- AcquireExternalTransform
- AcquireFrameTransform
- AcquireWindowAggregateClipShape
- AcquireWindowContentTransform
- AcquireWindowFrameTransform
- ActiveBorderContainsPoint
- ChangeActiveShape
- ChangeCanvas
- ChangeGeometry
- ChangeHighlight
- ContainsPoint
- CopyAggregateClipRegion (OS/2)
- CreateCanvas
- CreateEmbeddedFacet
- DrawChildrenAlways
- CreatePlatformCanvas (AIX)
- CreatePlatformCanvas (OS/2)
- CreatePlatformCanvas (Windows)
- CreateShape
- CreateTransform
- Draw
- DrawActiveBorder
- DrawChildren
- DrawChildrenAlways
- DrawnIn
- GetCanvas
- GetContainingFacet
- GetFacetHWND (OS/2, Windows)
- GetFacetWidget (AIX)
- GetHandleMouseEvents (OS/2)
- GetFrame
- GetHandleMouseEvents (OS/2)
- GetHighlight
- GetPartInfo
- GetWindow
- HasCanvas
- Invalidate
- InvalidateActiveBorder
- IsEventInActiveBorder (AIX)
- IsSelected
- MoveBefore
- MoveBehind
- RemoveFacet
- SetHandleMouseEvents (OS/2)
- SetPartInfo
- SetSelected
- Update
- Validate

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

### AcquireActiveShape

This method returns a reference to the active shape for this facet.

Signature

    ODShape *AcquireActiveShape (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODShape *) - returns

  A reference to the active shape for this facet or the frame shape of this facet's frame if no active shape has been set.

Remarks

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

Related Methods

- ODFacet::ChangeActiveShape

### AcquireAggregateClipShape

This method calculates and returns a reference to a shape object that represents the aggregate clip shape of this facet.

Signature

    ODShape *AcquireAggregateClipShape (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODShape *) - returns

  A reference to a shape object that represents the aggregate clip shape.

Remarks

The aggregate clip shape describes the facet's clip shape on its canvas. The aggregate clip shape is calculated by intersecting the facet's clip shape with the appropriately transformed clip shapes of all containing facets displayed on this facet's canvas.

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

Related Methods

- ODFacet::AcquireClipShape
- ODFacet::AcquireWindowAggregateClipShape

### AcquireClipShape

This method returns a reference to this facet's clip shape.

Signature

    ODShape *AcquireClipShape (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODShape *) - returns

  A reference to this facet's clip shape.

Remarks

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

Related Methods

- ODFacet::AcquireAggregateClipShape
- ODFacet::AcquireWindowAggregateClipShape

### AcquireContentTransform

This method returns a reference to a transform object that represents the content transform of this facet.

Signature

    ODTransform *AcquireContentTransform (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODTransform *) - returns

  A reference to a transform object that represents the content transform.

Remarks

The content transform describes the content coordinate space of this facet on its canvas. The content transform is calculated by concatenating the internal transform of this facet's frame with this facet's external transform and the internal and external transforms of all containing facets displayed on this facet's canvas.

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

Related Methods

- ODFacet::AcquireExternalTransform
- ODFacet::AcquireFrameTransform
- ODFacet::AcquireWindowContentTransform

### AcquireExternalTransform

This method returns a reference to this facet's external transform.

Signature

    ODTransform *AcquireExternalTransform (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODTransform *) - returns

  A reference to this facet's external transform.

Remarks

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

Related Methods

- ODFacet::AcquireContentTransform
- ODFacet::AcquireFrameTransform

### AcquireFrameTransform

This method returns a reference to a transform object that represents the frame transform of this facet.

Signature

    ODTransform *AcquireFrameTransform (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODTransform *) - returns

  A reference to a transform object that represents the frame transform.

Remarks

The frame transform describes the frame coordinate space of this facet on its canvas. The frame transform is calculated by concatenating this facet's external transform with the internal and external transforms of all containing facets displayed on this facet's canvas.

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

Related Methods

- ODFacet::AcquireContentTransform
- ODFacet::AcquireExternalTransform
- ODFacet::AcquireWindowFrameTransform

### AcquireWindowAggregateClipShape

This method returns a reference to a shape object that represents the window aggregate clip shape of this facet.

Signature

    ODShape *AcquireWindowAggregateClipShape (ODCanvas *biasCanvas)

Parameters

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 platform-normal coordinates.

Returns

rv (ODShape *) - returns

  A reference to a shape object that represents the window aggregate clip shape.

Remarks

The window aggregate clip shape describes the facet's clip shape on its window. The window aggregate clip shape is calculated by intersecting the clip shape of this facet with the clip shapes of all containing facets displayed on this facet's window canvas.

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

Related Methods

- ODFacet::AcquireAggregateClipShape
- ODFacet::AcquireClipShape

### AcquireWindowContentTransform

This method returns a reference to a transform object that represents the window-content transform of this facet.

Signature

    ODTransform *AcquireWindowContentTransform (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODTransform *) - returns

  A reference to a transform object that represents the window-content transform.

Remarks

The window-content transform describes the content coordinate space of this facet on its window. The window-content transform is calculated by concatenating the internal transform of this facet's frame with this facet's external transform and the internal and external transforms of all containing facets displayed on this facet's window canvas.

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

Related Methods

- ODFacet::AcquireContentTransform
- ODFacet::AcquireWindowFrameTransform

### AcquireWindowFrameTransform

This method returns a reference to a transform object that represents the window-frame transform of this facet.

Signature

    ODTransform *AcquireWindowFrameTransform (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODTransform *) - returns

  A reference to a transform object that represents the window-frame transform.

Remarks

The window-frame transform describes the frame coordinate space of this facet on its window. The window-frame transform is calculated by concatenating this facet's external transform with the internal and external transforms of all containing facets displayed on this facet's window canvas.

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

Related Methods

- ODFacet::AcquireFrameTransform
- ODFacet::AcquireWindowContentTransform

### ActiveBorderContainsPoint

This method indicates whether the specified point is within its active frame border.

Signature

    ODBoolean ActiveBorderContainsPoint (ODPoint *point,
                                         ODCanvas *biasCanvas)

Parameters

point (ODPoint *) - input

  The location to be tested, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified point is in the active frame border.

  kODTrue | The specified point is in the active frame border.
  kODFalse | The specified point is not in the active frame border.

Remarks

Your part calls its embedded facet's ActiveBorderContainsPoint method when it receives a WM_MOUSEMOVE event to determine if it should change the pointer shape. You should not change the pointer shape if the mouse is over the active border of an embedded frame.

OpenDoc draws this facet's active frame border on the border of the active shape associated with this facet. The active frame border is derived from the active shape, but is not identical to it.

Related Methods

- ODFacet::ContainsPoint

### ChangeActiveShape

This method assigns the specified shapes as the active shape of this facet.

Signature

    void ChangeActiveShape (ODShape *activeShape,
                            ODCanvas *biasCanvas)

Parameters

activeShape (ODShape *) - input

  A reference to a shape to be assigned as this facet's active shape.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

When this facet's frame has the selection focus, OpenDoc handles the changing of the facet's active border shape and redrawing the active frame border; otherwise, only this facet's part should change this facet's active shape.

Related Methods

- ODFacet::AcquireActiveShape

### ChangeCanvas

This method attaches a canvas to this facet.

Signature

    void ChangeCanvas (ODCanvas *canvas)

Parameters

canvas (ODCanvas *) - input

  A reference to a canvas to be attached to this facet.

Returns

None.

Remarks

This method in turn calls its canvas' SetFacet method to ensure the canvas has a reference back to this facet. After this method executes successfully, you can display this facet and its embedded facets on the specified canvas.

It is the caller's responsibility to deallocate the canvas' storage when it is no longer needed.

Related Methods

- ODCanvas::SetFacet
- ODFacet::GetCanvas
- ODFacet::HasCanvas

### ChangeGeometry

This method assigns the specified clip shape, external transform, or both to this facet.

Signature

    void ChangeGeometry (ODShape *clipShape,
                         ODTransform *transform,
                         ODCanvas *biasCanvas)

Parameters

clipShape (ODShape *) - input

  A reference to a shape to be assigned as this facet's clip shape.

transform (ODTransform *) - input

  A reference to a transform to be assigned as this facet's external transform.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

This method invalidates any cached aggregate clip shape and transforms. This facet's containing part calls this method to change the facet's clip shape, external transform, or both. This method in turn calls the GeometryChanged method associated with this facet's part to notify the part (and parts of all its embedded facets) that its clip shape, external transform, or both have changed.

Related Methods

- ODPart::GeometryChanged

### ChangeHighlight

This method changes the highlight state of this facet.

Signature

    void ChangeHighlight (ODHighlight highlight)

Parameters

highlight (ODHighlight) - input

  The highlight state to be assigned to this facet. This parameter can be set to one of the following values:

  kODNoHighlight | The facet is not highlighted.
  kODFullHighlight | The facet is highlighted in foreground style.
  kODDimHighlight | The facet is highlighted in background style.

Returns

None.

Remarks

The facet's containing part calls this method to change the facet's highlight state. This method in turn calls the HighlightChanged method associated with this facet's part to notify the part that its highlight state has changed.

Related Methods

- ODFacet::GetHighlight
- ODPart::HighlightChanged

### ContainsPoint

This method indicates whether the specified point is within the area of this facet.

Signature

    ODBoolean ContainsPoint (ODPoint *point,
                             ODCanvas *biasCanvas)

Parameters

point (ODPoint *) - input

  The location to be tested, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified point is within the area of this facet.

  kODTrue | The specified point is within the area of this facet.
  kODFalse | The specified point is outside the area of this facet.

Remarks

Your part calls its embedded facet's ContainsPoint method when it needs to do hit-testing on those facets. This method tests the result against the intersection of the clip shape and the active shape.

Related Methods

- ODFacet::ActiveBorderContainsPoint

### CopyAggregateClipRegion (OS/2)

This method calculates the clip region of the facet window by excluding siblings and children region intersecting with this facet.

Signature

    ODRgnHandle CopyAggregateClipRegion (HPS hps)

Parameters

hps (HPS) - input

  A handle to the presentation space.

Returns

rv (ODRgnHandle) - returns

  The clip region of the facet window.

Remarks

This method determines the clip region of the facet.

Because OpenDoc creates a facet size child window for each embedded facet. If you use WS_CLIPCHILDREN and WS_CLIPSIBLINGS, it does not clip properly for irregular shaped parts. These parts include circles.

### CreateCanvas

This method creates a canvas object to a facet.

Signature

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

Parameters

graphicsSystem (ODGraphicsSystem) - input

  The graphics system you want to use for the canvas. Valid graphics systems are platform-dependent:
  - On OS/2, use kODGPI.
  - On Windows, use kODWin32, kODWin95, or kODWinNT.
  - On AIX, use kODAIX.

platformCanvas (ODPlatformCanvas *) - input

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

isDynamic (ODBoolean) - input

  A flag indicating whether this canvas is to be dynamic.

  kODTrue | This canvas is to be dynamic.
  kODFalse | This canvas is to be static.

isOffscreen (ODBoolean) - input

  A flag indicating whether this canvas is to be offscreen.

  kODTrue | This canvas is to be offscreen.
  kODFalse | This canvas is to be onscreen.

Returns

rv (ODCanvas *) - returns

  A reference to a new canvas object.

Remarks

To create a canvas that will not be attached to any facet, call the window-state object's CreateCanvas method.

Related Methods

- ODWindowState::CreateCanvas

### CreateEmbeddedFacet

This method creates a facet for the specified frame, embedded in this facet.

Signature

    ODFacet *CreateEmbeddedFacet (ODFrame *frame,
                                  ODShape *clipShape,
                                  ODTransform *externalTransform,
                                  ODCanvas *canvas,
                                  ODCanvas *biasCanvas,
                                  ODFacet *siblingFacet,
                                  ODFramePosition position)

Parameters

frame (ODFrame *) - input

  A reference to a frame for this facet.

clipShape (ODShape *) - input

  A reference to an initial clip shape for this facet.

externalTransform (ODTransform *) - input

  A reference to an initial external transform for this facet.

canvas (ODCanvas *) - input

  A reference to the canvas this 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 platform-normal coordinates.

siblingFacet (ODFacet *) - input

  A reference to an existing embedded facet of this facet or kODNULL if the embedded facet does not exist.

position (ODFramePosition) - input

  The desired position of the new facet relative to the sibling facet. This parameter can be set to one of the following values:

  kODFrameBehind | This frame is behind its sibling.
  kODFrameInFront | This frame is in front of its sibling.
  kODNULL | The new facet is placed in front of or behind all its sibling facets.

Returns

rv (ODFacet *) - returns

  A reference to a new facet object.

Remarks

The facet's part calls this method to create a facet for an embedded frame. This method calls its frame's FacetAdded method, that in turn calls the FacetAdded method associated with the frame's part to notify the part that a facet has been added to one of its display frames. If the part does not provide a canvas, this method calls the GetCanvas method to create an onscreen dynamic canvas.

Exception Handling

kODErrInvalidFacet | The specified sibling facet is not an embedded facet of this facet.
kODErrUnsupportedFramePositionCode | The specified designated position is not a valid position code.

Related Methods

- ODFrame::FacetAdded
- ODPart::FacetAdded

### CreateFacetIterator

This method creates a facet iterator object for the embedded facets of this facet.

Signature

    ODFacetIterator *CreateFacetIterator (ODTraversalType traversalType,
                                          ODSiblingOrder siblingOrder)

Parameters

traversalType (ODTraversalType) - input

  The traversal type to be assigned to the facet iterator. This parameter can be set to one of the following values:

  kODBottomUp | The facet hierarchy is traversed bottom up, visiting this facet after visiting all its children.
  kODChildrenOnly | Only the children of the specified facet are traversed, not the facet itself.
  kODTopDown | The facet hierarchy is traversed top down, visiting this facet and then all of its children.

siblingOrder (ODSiblingOrder) - input

  The order that the iterator traverses the sibling facets. This parameter can be set to one of the following values:

  kODBackToFront | The siblings in a facet hierarchy are processed from back to front.
  kODFrontToBack | The siblings in a facet hierarchy are processed from front to back.

Returns

rv (ODFacetIterator *) - returns

  A reference to a new facet iterator object.

Remarks

Your part calls this method if it needs to apply an operation to a facet and all its embedded facets. For example, OpenDoc might use a facet iterator to make sure that all facets within a facet being invalidated are also invalidated. It is your responsibility to delete the iterator when it is no longer needed.

While you are using a facet iterator, you should not modify the list of embedded facets. You must postpone adding items to or removing items from the list of embedded facets until after you have deleted the iterator.

Related Methods

- ODFrame::CreateFacetIterator

### CreatePlatformCanvas (AIX)

This method creates and initializes a platform canvas for an offscreen static, offscreen dynamic, or onscreen dynamic canvas using the specified presentation space handle.

Signature

    ODAIXStandardCanvas *CreatePlatformCanvas (Display *display,
                                               Pixmap pixmap, GC gc)

Parameters

display (Display *) - input

  A pointer to the display object.

pixmap (Pixmap) - input

  A handle to the pixmap.

gc (GC) - input

  A handle to the graphics context.

Returns

rv (ODAIXStandardCanvas *) - returns

  A newly created and initialized platform canvas object. This object can be specified as an input parameter to the facet's CreateCanvas method.

Related Methods

- ODFacet::CreateCanvas

### CreatePlatformCanvas (OS/2)

This method creates and initializes an platform canvas for an offscreen static, offscreen dynamic, or onscreen dynamic canvas using the specified presentation space handle.

Signature

    ODOS2StandardCanvas *CreatePlatformCanvas (HPS hps)

Parameters

hps (HPS) - input

  A handle to the presentation space created using the GpiCreatePS function.

Returns

rv (ODOS2StandardCanvas *) - returns

  A newly created and initialized platform canvas object. This object can be specified as an input parameter to the facet's CreateCanvas method.

Related Methods

- ODFacet::CreateCanvas

### CreatePlatformCanvas (Windows)

This method creates and initializes an platform canvas for an offscreen static, offscreen dynamic, or onscreen dynamic canvas using the specified presentation space handle.

Signature

    ODWin32StandardCanvas *CreatePlatformCanvas (HDC hdc)

Parameters

hdc (HDC) - input

  A handle to the device context.

Returns

rv (ODWin32StandardCanvas *) - returns

  A newly created and initialized platform canvas object. This object can be specified as an input parameter to the facet's CreateCanvas method.

Related Methods

- ODFacet::CreateCanvas

### CreateShape

This method creates a shape object.

Signature

    ODShape *CreateShape ()

Parameters

None.

Returns

rv (ODShape *) - returns

  A reference to a new shape object.

Remarks

Your part calls this method to create a shape object for any purpose.

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

Related Methods

- ODFrame::CreateShape

### CreateTransform

This method creates a transform object.

Signature

    ODTransform *CreateTransform ()

Parameters

None.

Returns

rv (ODTransform *) - returns

  A reference to a new transform object.

Remarks

Your part calls this method to create a transform object for any purpose.

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

Related Methods

- ODFrame::CreateTransform

### Draw

This method tells this facet's part to draw itself within the specified portion in this facet.

Signature

    void Draw (ODShape *invalidShape,
               ODCanvas *biasCanvas)

Parameters

invalidShape (ODShape *) - input

  A reference to a shape within which the part should draw itself, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

This facet's containing part calls this method when the embedded facets of this facet require updating. This method in turn calls the Draw method associated with this facet's part.

Related Methods

- ODFacet::DrawChildren
- ODFacet::DrawChildrenAlways
- ODPart::Draw

### DrawActiveBorder

This method updates the active frame border for this facet.

Signature

    void DrawActiveBorder ()

Parameters

None.

Returns

None.

Remarks

When this facet's frame has the selection focus, OpenDoc handles the changing of the facet's active border shape and redrawing the active frame border.

Under normal circumstances, there is no need to invalidate the active frame border for the active part or its container part; however, parts could call this method if they want to force the active frame border to be redrawn. To do so, the part must invalidate the active frame border by calling its facet's InvalidateActiveBorder method and redraw the active frame border by calling its facet's DrawActiveBorder method.

Related Methods

- ODFacet::InvalidateActiveBorder
- ODFrame::DrawActiveBorder

### DrawChildren

This method draws all embedded facets of this facet that need updating.

Signature

    void DrawChildren (ODShape *invalidShape,
                       ODCanvas *biasCanvas)

Parameters

invalidShape (ODShape *) - input

  A reference to a shape within which the embedded facets should draw, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

This facet's containing part calls this method when the embedded facets of this facet require updating. This method in turn calls the Draw method associated with this facet's embedded part.

Related Methods

- ODFacet::DrawChildrenAlways
- ODPart::Draw

### DrawChildrenAlways

This method draws all embedded facets of this facet, whether they need updating or not.

Signature

    void DrawChildrenAlways (ODShape *invalidShape,
                             ODCanvas *biasCanvas)

Parameters

invalidShape (ODShape *) - input

  A reference to a shape within which the embedded facets should draw, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

This facet's containing part calls this method to draw all embedded facets of this facet, whether they need updating or not. This method in turn calls the Draw method associated with this facet's embedded part.

Related Methods

- ODFacet::DrawChildren
- ODPart::Draw

### DrawnIn

This method is called when this facet has been drawn in without an update event being generated.

Signature

    void DrawnIn (ODShape *shape,
                  ODCanvas *biasCanvas)

Parameters

shape (ODShape *) - input

  A reference to a shape object defining the area in this facet that was updated, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

This facet's part calls this method when it has drawn asynchronously to the facet. This method in turn calls the CanvasUpdated method associated with the owner of this facet's canvas to notify it that its canvas has changed. The owning part decides when to process the update.

Exception Handling

kODErrFacetNotFound | The requested facet was not found.

Related Methods

- ODPart::CanvasUpdated

### GetCanvas

This method returns a reference to the canvas associated with this facet.

Signature

    ODCanvas *GetCanvas ()

Parameters

None.

Returns

rv (ODCanvas *) - returns

  A reference to the canvas associated with this facet.

Remarks

If this facet has no canvas of its own, this method creates an onscreen dynamic canvas, if the parent has an onscreen dynamic canvas. Otherwise, it returns the parent canvas.

Exception Handling

kODErrInvalidCanvas | Neither this facet nor any of its containing facets has a canvas.

Related Methods

- ODFacet::ChangeCanvas
- ODFacet::HasCanvas

### GetContainingFacet

This method returns a reference to the containing facet of this facet.

Signature

    ODFacet *GetContainingFacet ()

Parameters

None.

Returns

rv (ODFacet *) - returns

  A reference to the containing facet of this facet or kODNULL if the facet has no containing facet.

### GetFacetHWND (OS/2, Windows)

On OS/2, this method returns a handle to the PM window associated with this facet. On Windows, this method returns a handle to a child window.

Signature

    HWND GetFacetHWND ()

Parameters

None.

Returns

rv (HWND) - returns

  On OS/2, a handle to the PM window associated with this facet or zero if the facet does not have a window. On Windows, a handle to the child window.

Remarks

Facet windows are created and managed by OpenDoc for facets that descend from a root facet with a window (onscreen) canvas. In general, parts should not attempt to manipulate the facet window; however, the HWND for the facet window is provided so that it can be used as the parent and owner of embedded PM controls, such as buttons and scroll bars. Notification messages sent to the facet window are forwarded to the facet's part in that part's HandleEvent method. Parts can determine that an event came from the facet window rather than the OpenDoc dispatcher by examining the hwnd field of the ODEventData data structure. If the event came from the facet window, this field contains the window handle of the facet.

Just because a facet has a facet window does not mean that drawing should be directed to the window. The facet's containing facet, or any of its ancestors, can have an offscreen canvas set. In this case, the facet window is not shown and any drawing directed to the window is not seen. Drawing should generally be directed to the presentation space obtained from the facet's platform canvas object.

### GetFacetWidget (AIX)

This method returns the widget identifier associated with the facet.

Signature

    Widget GetFacetWidget ()

Parameters

None.

Returns

rv (Widget) - returns

  The widget ID associated with this facet.

### GetFrame

This method returns a reference to this facet's frame.

Signature

    ODFrame *GetFrame ()

Parameters

None.

Returns

rv (ODFrame *) - returns

  A reference to this facet's frame.

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.

### GetHandleMouseEvents (OS/2)

This method returns the flags used to determine how mouse events are dispatched to PM controls, such as buttons and scroll bars.

Signature

    ODULong GetHandleMouseEvents ()

Parameters

None.

Returns

rv (ODULong) - returns

  A bit field that can contain one or both of the following flags:

  kODPartHandlesDragDropEvents | Drag-and-drop events that occur over PM windows which are children of this facet's facet window are handled by this facet's part in its DragEnter, DragWithin, and DragLeave methods.
  kODPartHandlesMouseEvents | Mouse events (excluding drag-and-drop events) that occur over PM windows which are children of this facet's facet window are handled by this facet's part in its HandleEvent method.

  To include both flags, use the "or" operand.

Remarks

The OpenDoc standard dispatch module calls this method to determine how to dispatch events that occur over a facet which contains non-OpenDoc PM windows.

Related Methods

- ODFacet::GetFacetHWND (OS/2, Windows)
- ODFacet::SetHandleMouseEvents (OS/2)

### GetHighlight

This method returns the highlight state for this facet.

Signature

    ODHighlight GetHighlight ()

Parameters

None.

Returns

rv (ODHighlight) - returns

  The highlight state for this facet. This parameter can be set to one of the following values:

  kODDimHighlight | The facet is highlighted in background style.
  kODFullHighlight | The facet is highlighted in foreground style.
  kODNoHighlight | The facet is not highlighted.

Remarks

This facet's part uses the highlight state to draw its content consistently with the content highlighting of this facet's containing part.

Related Methods

- ODFacet::ChangeHighlight

### GetPartInfo

This method returns the part-information data for this facet.

Signature

    ODInfoType GetPartInfo ()

Parameters

None.

Returns

rv (ODInfoType) - returns

  The part-information data for this facet.

Remarks

You should cast the return value to a pointer to your part's own representation of the data.

Related Methods

- ODFacet::SetPartInfo
- ODFrame::GetPartInfo

### GetWindow

This method returns a reference to the ODWindow in which this facet is displayed.

Signature

    ODWindow *GetWindow ()

Parameters

None.

Returns

rv (ODWindow *) - returns

  A reference to the ODWindow in which this facet is displayed or kODNULL if this facet does not actually appear in any window. For example, a printing facet does not appear in a window.

Remarks

If this facet has no ODWindow of its own, this method searches recursively for the containing facet's window. Only the root facet has a reference to the ODWindow; all its embedded facets then inherit this value. To get the docshell window handle, call GetPlatformWindow of the ODWindow object.

Related Methods

- ODFrame::AcquireWindow

### HasCanvas

This method indicates whether this facet has its own canvas.

Signature

    ODBoolean HasCanvas ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this facet has its own canvas.

  kODTrue | The facet has its own canvas.
  kODFalse | The facet does not have its own canvas.

Related Methods

- ODFacet::ChangeCanvas
- ODFacet::GetCanvas

### Invalidate

This method marks the specified area in this facet as in need of updating.

Signature

    void Invalidate (ODShape *invalidShape,
                     ODCanvas *biasCanvas)

Parameters

invalidShape (ODShape *) - input

  A reference to the shape object defining the area in this facet that needs updating, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

OpenDoc calls this method. This method transforms and clips the shape from the coordinate space of the facet to the coordinate space its canvas. The shape is marked on the canvas (and all parent canvases) associated with this facet, ensuring that changes to this facet are reflected across all appropriate canvases.

Exception Handling

kODErrInvalidFacet | The facet associated with the specified canvas does not have a parent facet.

Related Methods

- ODCanvas::Invalidate
- ODFacet::Validate
- ODFrame::Invalidate

### InvalidateActiveBorder

This method marks the active frame border of this facet as in need of updating.

Signature

    void InvalidateActiveBorder ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method when invalidating the active frame border if there is no explicit active frame border defined. When this facet's frame has the selection focus, OpenDoc handles the changing of the facet's active border shape and redrawing the active frame border.

Under normal circumstances, there is no need to invalidate the active frame border for the active part or its containing part; however, parts could call this method if they want to force the active frame border to be redrawn when they change the shape of an embedded part. To do so, the part must invalidate the active frame border by calling its facet's InvalidateActiveBorder method and redraw the active frame border by calling its facet's DrawActiveBorder method.

Related Methods

- ODFacet::DrawActiveBorder
- ODFrame::InvalidateActiveBorder

### IsEventInActiveBorder (AIX)

This method indicates whether the specified point is within its active frame border.

Signature

    ODBoolean IsEventInActiveBorder (ODEventData *event)

Parameters

event (ODEventData *) - input

  A reference to the event structure.

Returns

rv (ODBoolean) - returns

  A flat indicating whether the specified point is in the active border.

  kODTrue | The point is within the active border.
  kODFalse | The point is outside of the active border.

Remarks

OpenDoc draws this facet's active frame border on the border of the active shape.

### IsSelected

This method indicates whether this facet is selected within its containing part.

Signature

    ODBoolean IsSelected ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this facet is selected within its containing part.

  kODTrue | This facet is selected within the containing part.
  kODFalse | This facet is not selected within the containing part.

Remarks

A containing part calls this method when it believes this facet's frame has the selection focus. The criteria for facet selection is specific to the containing part that calls this method. OpenDoc uses the return value to determine whether to dispatch mouse events to this facet or to its containing facet.

Related Methods

- ODFacet::SetSelected

### MoveBefore

This method repositions an embedded facet of this facet in front of a sibling facet.

Signature

    void MoveBefore (ODFacet *child,
                     ODFacet *sibling)

Parameters

child (ODFacet *) - input

  A reference to a embedded facet to be repositioned.

sibling (ODFacet *) - input

  A reference to a sibling facet to be directly behind the embedded facet or kODNULL if the embedded facet is to be repositioned in front of all its sibling facets.

Returns

None.

Remarks

After this method executes successfully, the sibling order associated with the embedded facets may or may not have changed. Any changes to the sibling order of the embedded facets are reflected in the facet iterator, if a facet iterator exists.

While you are using a facet iterator, you should not call this method to modify the list of embedded facets. You must postpone repositioning facets in this list of embedded facets until you have deleted the iterator.

Exception Handling

kODErrInvalidFacet | The child or sibling facet is not an embedded facet of this facet.

Related Methods

- ODFacet::MoveBehind

### MoveBehind

This method repositions an embedded facet of this facet behind a sibling facet.

Signature

    void MoveBehind (ODFacet *child,
                     ODFacet *sibling)

Parameters

child (ODFacet *) - input

  A reference to a embedded facet to be repositioned.

sibling (ODFacet *) - input

  A reference to a sibling facet to be moved directly in front of the embedded facet or kODNULL if the embedded facet is repositioned behind all its sibling facets.

Returns

None.

Remarks

After this method executes successfully, the sibling order associated with the embedded facets may or may not have changed. Any changes to the sibling order of the embedded facets are reflected in the facet iterator, if a facet iterator exists.

While you are using a facet iterator, you should not call this method to modify the list of embedded facets. You must postpone repositioning facets in this list of embedded facets until after you have deleted the iterator.

Exception Handling

kODErrInvalidFacet | The child or sibling facet is not an embedded facet of this facet.

Related Methods

- ODFacet::MoveBefore

### RemoveFacet

This method removes an embedded facet from this facet.

Signature

    void RemoveFacet (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to an embedded facet to be removed.

Returns

None.

Remarks

This facet's containing part calls this method before removing one of its embedded frames or optionally when scrolling an embedded frame out of view. This method in turn calls the FacetRemoved method associated with this facet's part to notify the part that a facet has been removed from one of its frames. After this method executes successfully, the removed facet should not be used again; the caller should delete the removed facet.

Exception Handling

kODErrInvalidFacet | The specified facet is not an embedded facet of this facet.

Related Methods

- ODFrame::FacetRemoved
- ODPart::FacetRemoved

### SetHandleMouseEvents (OS/2)

This method indicates if events that occur over non-OpenDoc PM windows, such as buttons or scroll bars, which are children of this facet's facet window are sent to the PM window or to this facet's part in its HandleEvent method.

Signature

    void SetHandleMouseEvents (ODULong flags)

Parameters

flags (ODULong) - input

  A bit field that can contain one or both of the following flags.

  kODPartHandlesDragDropEvents | Drag-and-drop events that occur over PM windows which are children of this facet's facet window are to be handled by this facet's part in its DragEnter, DragWithin, and DragLeave methods.
  kODPartHandlesMouseEvents | Mouse events (excluding drag-and-drop events) that occur over PM windows which are children of this facet's facet window are to be handled by this facet's part in its HandleEvent method. For both flags, use the "or" operand.

Returns

None.

Remarks

By default, all mouse and drag-and-drop events that occur over PM windows are sent to that window.

Related Methods

- ODFacet::GetFacetHWND (OS/2, Windows)
- ODFacet::GetHandleMouseEvents (OS/2)

### SetPartInfo

This method assigns part-information data to this facet.

Signature

    void SetPartInfo (ODInfoType partInfo)

Parameters

partInfo (ODInfoType) - input

  The data for this facet's part information.

Returns

None.

Related Methods

- ODFacet::GetPartInfo
- ODFrame::SetPartInfo

### SetSelected

This method specifies whether this facet is being selected within its containing part.

Signature

    void SetSelected (ODBoolean isSelected)

Parameters

isSelected (ODBoolean) - input

  A flag indicating whether this facet is being selected within its containing part.

  kODTrue | This facet is being selected.
  kODFalse | This facet is not being selected.

Returns

None.

Remarks

The criteria for facet selection is specific to the containing part that calls the method.

Related Methods

- ODFacet::IsSelected

### Update

This method updates this facet's canvas by drawing this facet and any of its embedded facets whose clip shape intersects the specified area of the canvas.

Signature

    void Update (ODShape *invalidShape,
                 ODCanvas *biasCanvas)

Parameters

invalidShape (ODShape *) - input

  A reference to a shape object defining the area of the canvas that needs updating, expressed in frame coordinates or kODNULL if the facets are to be updated based on the invalid shape for the facet's canvas.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

When an update event occurs that involves a facet of your part, OpenDoc calls its window's Update method, that then calls this method. This method in turn call the Draw method associated with this facet's part.

On OS/2, if you want to control the sequence of updating embedded parts from within your part's Draw method (to interleave drawing of embedded parts with content objects, for example), you can call the Update method of an embedded facet with the invalidShape parameter equal to kODNULL. This causes the embedded facet (and its embedded facets, and so on) to be updated as required. When kODNULL is specified for the invalidShape parameter, facets are updated based on the invalid shape for the facet's canvas. If you modify the invalid shape of an embedded facet from within your draw method prior to calling that facet's Update method, you should specify the modified invalid shape (expressed in the embedded part's frame coordinates).

Related Methods

- ODPart::Draw
- ODWindow::Update

### Validate

This method marks the specified area in this facet as no longer in need of updating.

Signature

    void Validate (ODShape *validShape,
                   ODCanvas *biasCanvas)

Parameters

validShape (ODShape *) - input

  A reference to a shape object defining the area in this facet that no longer needs updating, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

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

Returns

None.

Remarks

OpenDoc calls this method. This method transforms and clips the shape from the coordinate space of the facet to the coordinate space of its canvas. It then subtracts the shape from any existing invalid area of the canvas.

Related Methods

- ODCanvas::Validate
- ODFacet::Invalidate
- ODFrame::Validate

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