Programming Reference: ODShape

# Programming Reference

## ODShape

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

Class Hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODBaseShape
                ODShape

Description

An object of the ODShape class represents a geometric shape that OpenDoc uses to manage the display of parts.

Shape objects encapsulate geometric shapes. The simplest shape is an empty shape. An empty space occupies no area.

Your part creates an empty shape by calling the CreateShape method of a frame, the CreateShape method of a facet, or the NewShape method of an existing shape. Your part can create a copy of an existing shape by calling that shape's Copy method.

Frames and facets use shape objects for frame negotiation, clipping, and hit-testing. Shape objects represent four kinds of shapes used for those purposes:

Active shape | Defines the area of a facet within which the embedded part responds to mouse events.
Clip shape | Defines the area of a facet in which drawing can occur; it is the area not obscured by overlapping content of the containing part.
Frame shape | Defines the area that the containing part delegates to an embedded part's display frame.
Used shape | Defines the area of an embedded part's frame that has actual content to display; the containing part is free to display its own content within the embedded frame, but it must remain outside the used shape area.

Typically, your part creates a shape object by calling the shape object's Copy method; however, your part can also create a shape by calling the NewShape and CreateShape methods. Both of these methods return a shape object.

Geometric Representation

The geometric representation of a shape is a description of the area it encompasses in its coordinate space. Shape objects can maintain their geometric representation as a polygon or in a platform specific manner (such as an OS/2 GPI region or a Windows HRGN). A polygon representation of a shape can be converted to a platform specific representation. If a shape does not have a polygonal representation, one can be generated from the platform-specific representation; however, the resulting polygon will only be an approximation of the shape. For example, if a polygon is generated from a region that represents a triangular shape, the resulting polygon will have many more than 3 vertexes. That is because the polygon is generated by tracing the exposed edges of the region rectangles, with one vertex for each corner of the region rectangle.

Geometry Mode

The geometry mode of a shape object that indicates if the shape is required to maintain its geometric representation. The geometry mode has three possible values:

Preserve geometry | Indicates that the shape must maintain its polygonal representation for as long as possible. A shape's polygonal representation is lost if the shape is combined with (that is, unioned with, subtracted from, or intersected with) a shape that does not have polygonal representation. The shape's polygonal representation is replaced by the area that results from combining the two shapes. This is the default.
Lose geometry | Indicates that the shape does not need to use a polygon to describe its geometric representation. The polygonal representation can be discarded to optimize speed, but at the expense of accuracy and persistent storage capability.
Needs geometry | Indicates that the shape must maintain its polygonal representation. The shape cannot be unioned with, subtracted from, or intersected with a shape that does not have a polygonal representation. If you attempt to do so, the shape raises an exception and does not notify its geometric representation.

Geometric Operations

Shape objects support geometric operations such as union, intersection, and difference. A platform-specific shape-manipulation engine may be used to perform these operations. As a consequence, the results of certain operations, such as test for equality, difference, union, and intersection, may vary slightly from platform to platform; these cross-platform differences should be apparent only at the pixel level.

For more information about frame shapes and used shapes, see the description of the ODFrame class. For information about clip shapes and active shapes, see the description of the ODFacet class. For more information on graphics systems available on OS/2, see the Graphics Programming Interface Programming Guide

Methods

The methods defined by the ODShape class include:

Creating Shapes

- Copy
- NewShape

Manipulating Shape Geometry

- CopyFrom
- CopyPolygon
- CopyRegion
- GetBoundingBox
- GetPlatformShape
- GetRegion
- ReadShape
- Reset
- SetPlatformShape
- SetPolygon
- SetRectangle
- SetRegion
- WriteShape

Testing Shapes

- ContainsPoint
- HasGeometry
- IsEmpty
- IsRectangular
- IsSameAs

Manipulating Geometry Mode

- GetGeometryMode
- SetGeometryMode

Performing Geometric Operations

- Intersect
- InverseTransform
- Outset
- Subtract
- Transform
- Union

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

### ContainsPoint

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

Signature

    ODBoolean ContainsPoint (ODPoint *point)

Parameters

point (ODPoint *) - input

  The point to test, expressed in this shape's coordinate space.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the point is within this shape's area.

  kODTrue | The point is within this shape's area.
  kODFalse | The point is outside of this shape's area.

Exception Handling

kODErrNullInput | The reference to the ODPoint was null.

### Copy

This method creates a new shape object that is a copy of this shape.

Signature

    ODShape *Copy ()

Parameters

None.

Returns

rv (ODShape *) - returns

  A reference to the newly created shape.

Remarks

This method creates a shape to place the copy.

The new shape does not share any data with this shape; therefore, you can modify each of the shapes independently. This method deletes the new shape if the copy operation fails.

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

Exception Handling

kODErrOutOfMemory | There is not enough memory to copy this shape.

Related Methods

- ODShape::CopyFrom

### CopyFrom

This method modifies this shape to make it equivalent to the specified source shape.

Signature

    void CopyFrom (ODShape *sourceShape)

Parameters

sourceShape (ODShape *) - input

  A reference to the source shape.

Returns

None.

Remarks

After this method executes successfully, this shape and the source shape do not share any data. Therefore, you can modify each of them independently.

Exception Handling

kODErrOutOfMemory | There is not enough memory to update this shape.

Related Methods

- ODShape::Copy

### CopyPolygon

This method returns a copy of this shape's geometric representation, expressed as a polygon.

Signature

    void CopyPolygon (ODPolygon *copy)

Parameters

copy (ODPolygon *) - output

  A structure whose fields are set to represent a polygon that describes this shape's geometric representation, or an empty polygon if this shape's geometric representation cannot be represented by a polygon.

Returns

None.

Remarks

To check whether the shape's geometric representation can be described by a polygon, call the HasGeometry method. Some geometric representations, such as curves, can only be approximated by a polygon.

The polygon returned in the copy output parameter is not owned by this shape; you are allowed to modify it. When you no longer need the polygon, you should deallocate its storage.

Exception Handling

kODErrNoShapeGeometry | This shape has no geometric representation, so it cannot be described as a polygon.
kODErrOutOfMemory | There is not enough memory to copy this shape's geometric representation.

Related Methods

- ODShape::HasGeometry

### CopyRegion

On OS/2, this method returns a GPI region equivalent to the shape; on Windows, an HRGN

Signature

    ODRgnHandle CopyRegion ()

Parameters

None.

Returns

rv (ODRgnHandle) - returns

  On OS/2, a handle to the GPI region; on Windows, an HRGN.

Remarks

Before calling this method, you must transform the shape to the region-coordinate space of the device you intend to use.

This method creates a new region and copies the shapes into it. The region is owned by the caller, and the caller is responsible for destroying the region when it is done using it.

### GetBoundingBox

This method returns, in the specified structure, the smallest rectangle that surrounds this shape.

Signature

    void GetBoundingBox (ODRect *bounds)

Parameters

bounds (ODRect *) - output

  A rectangle describing this shape's bounding box.

Returns

None.

### GetGeometryMode

This method returns the current geometry mode of this shape.

Signature

    ODGeometryMode GetGeometryMode ()

Parameters

None.

Returns

rv (ODGeometryMode) - returns

  The geometry mode for this shape. This parameter can return one of the following values:

  kODLoseGeometry | The shape does not need to use a polygon to describe its geometric representation. The polygonal representation can be discarded to optimize speed, at the expense of accuracy and persistent storage capability. A facet's clip shape generally has this mode.
  kODNeedsGeometry | The shape must maintain its polygonal presentation. A facet's frame shape and used shape has this mode because they are stored persistently in polygonal form.
  kODPreserveGeometry | The shape must maintain its polygonal representation for as long as possible. This is the default value.

Remarks

The geometry mode of a shape object specifies whether the shape is required to maintain its geometric (polygonal) representation.

Related Methods

- ODShape::SetGeometryMode

### GetPlatformShape

This method returns a graphics-system-specific data structure representing this shape.

Signature

    ODPlatformShape GetPlatformShape (ODGraphicsSystem graphicsSystem)

Parameters

graphicsSystem (ODGraphicsSystem) - input

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

Returns

rv (ODPlatformShape) - returns

  The requested graphics-system-specific shape. Before using the returned value, you must cast it to a valid graphics system type. On OS/2, this method returns a GPI region handle; on Windows, an HRGN.

Remarks

The returned region handle is owned by the shape object. You must not modify or destroy the region.

Exception Handling

kODErrInvalidGraphicsSystem | This implementation of OpenDoc does not support the specified graphics system, or that graphics system is not installed or available.

Related Methods

- ODShape::SetPlatformShape

### GetRegion

On OS/2, this method returns a GPI region equivalent to the shape; on Windows, an HRGN.

Signature

    ODRgnHandle GetRegion ()

Parameters

None.

Returns

rv (ODRgnHandle) - returns

  On OS/2, a handle to the GPI region; on Windows, an HRGN.

Remarks

The returned region handle is owned by the shape object. You must not modify or destroy the region.

### HasGeometry

This method indicates whether the geometric representation of this shape object can be described by a polygon.

Signature

    ODBoolean HasGeometry ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this shape's geometric representation can be described by a polygon. This method always returns kODTrue.

Remarks

Your part can use this method, before calling the CopyPolygon method, to verify that a shape's geometric representation can be described by a polygon.

Related Methods

- ODShape::CopyPolygon
- ODShape::SetGeometryMode

### Intersect

This method modifies this shape by intersecting it with the specified shape.

Signature

    ODShape *Intersect (ODShape *sectShape)

Parameters

sectShape (ODShape *) - input

  A reference to the shape to be intersected with this shape.

Returns

rv (ODShape *) - returns

  A reference to this shape after the intersection operation.

Remarks

After this method executes successfully, this shape is equivalent to the intersected area.

Exception Handling

kODErrNoShapeGeometry | The geometry mode of this shape is kODNeedsGeometry, but the other shape has no geometric representation.
kODErrOutOfMemory | There is not enough memory to intersect the shapes.

### InverseTransform

This method modifies this shape by applying the inverse of the specified transform.

Signature

    ODShape *InverseTransform (ODTransform *transform)

Parameters

transform (ODTransform *) - input

  A reference to the transform whose inverse is to be applied to this shape.

Returns

rv (ODShape *) - returns

  A reference to this shape after it has been transformed.

Remarks

This method is the inverse operation of the Transform method.

Exception Handling

kODErrNoShapeGeometry | This shape does not have enough geometric information to be transformed with the inverse of the specified transform.
kODErrTransformErr | The transform has no inverse, or an overflow or underflow error occurred when calculating the inverse transform.

Related Methods

- ODShape::Transform
- ODTransform::Invert

### IsEmpty

This method indicates whether this shape is empty (occupies no area).

Signature

    ODBoolean IsEmpty ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the shape is empty.

  kODTrue | The shape is empty.
  kODFalse | The shape is not empty.

Remarks

A shape that occupies no area is known as an empty shape. An empty shape is typically described by the empty rectangle (0,0,0,0). Alternatively, it can be described by a polygon with 0 contours.

### IsRectangular

This method indicates if this shape can be described by a rectangle.

Signature

    ODBoolean IsRectangular ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this shape is rectangular.

  kODTrue | The shape is rectangular.
  kODFalse | The shape is not rectangular.

Remarks

Empty shapes are considered to be rectangular; they can be described by the empty rectangle (0,0,0,0).

Related Methods

- ODShape::GetBoundingBox
- ODShape::SetRegion

### IsSameAs

This method indicates whether this shape is identical to the specified shape.

Signature

    ODBoolean IsSameAs (ODShape *compareShape)

Parameters

compareShape (ODShape *) - input

  A reference to the shape to be compared with this shape.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the shapes are equivalent.

  kODTrue | The shapes are equivalent.
  kODFalse | The shapes are not equivalent.

Remarks

If both shapes have polygonal representations, they are equivalent if they consist of the same contours. The order of the contours does not matter. Each of the corresponding contours in the two polygons must have their vertexes listed in the same direction.

If this shape is described only by a platform shape (such as a region), the platform graphics system is used to determine equality; typically, the compareShape parameter must be a platform shape of the same type.

Exception Handling

kODErrOutOfMemory | There is not enough memory to compare the two shapes.

### NewShape

This method creates a new empty shape object.

Signature

    ODShape *NewShape ()

Parameters

None.

Returns

rv (ODShape *) - returns

  A reference to the newly created shape or kODNULL if an error occurred.

Remarks

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

Exception Handling

kODErrOutOfMemory | There is not enough memory to create a new shape.

### Outset

This method modifies this shape by moving its boundary outwards, away from its interior, by the specified distance.

Signature

    ODShape *Outset (ODCoordinate distance)

Parameters

distance (ODCoordinate) - input

  The distance (expressed in the shape's coordinate system) to move the shape's outline.

Returns

rv (ODShape *) - returns

  A reference to this shape after the outset operation.

Remarks

This method is typically used to create a border around a shape. To do this, copy the original shape, outset the copy, then subtract the original shape from the copy.

To inset a shape (move the boundary inwards), then call this method with a negative distance.

Exception Handling

kODErrOutOfMemory | There is not enough memory to complete the operation. The shape will be unmodified.

### ReadShape

This method reads shape data from the specified storage unit into this shape.

Signature

    ODShape *ReadShape (ODStorageUnit *storageUnit)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to the storage unit from which data is to be read.

Returns

rv (ODShape *) - returns

  A reference to this shape.

Remarks

Before calling this method, you must focus the storage unit to the property that contains the shape data.

If the focused property contains a value of type kODPolygon, the method reads the shape data from that value. Otherwise, if the focused property contains a value of a platform-specific shape value type, this method reads the shape data from that value.

Exception Handling

kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or a value.

Related Methods

- ODShape::WriteShape

### Reset

This method replaces this shape's geometric representation with an empty area.

Signature

    void Reset ()

Parameters

None.

Returns

None.

Remarks

Except for shapes created by the Copy method, newly created shapes start out as empty shapes; this method changes a shape back to the initial state.

The effect of this method is the same as replacing this shape with an empty rectangle by using the SetRectangle method with the empty rectangle (0,0,0,0); however, the Reset method is slightly more efficient.

Related Methods

- ODShape::SetRectangle

### SetGeometryMode

This method sets the geometry mode of this shape.

Signature

    void SetGeometryMode (ODGeometryMode mode)

Parameters

mode (ODGeometryMode) - input

  The geometry mode for this shape.

  kODLoseGeometry | The shape does not need to use a polygon to describe its geometric representation. The polygonal representation can be discarded to optimize speed, at the expense of accuracy and persistent storage capability. A facet's clip shape generally has this mode.
  kODNeedsGeometry | The shape must maintain its polygonal presentation. A facet's frame shape and used shape has this mode because they are stored persistently in polygonal form.
  kODPreserveGeometry | The shape must maintain its polygonal representation for as long as possible. This is the default value.

Returns

None.

Remarks

The geometry mode of a shape object specifies whether the shape is required to maintain its geometric (polygonal) representation.

Exception Handling

kODErrNoShapeGeometry | The specified geometry mode is kODNeedsGeometry, but the shape has no geometry.

Related Methods

- ODShape::GetGeometryMode

### SetPlatformShape

This method modifies this shape to make it equivalent to the specified graphics-system-specific shape.

Signature

    void SetPlatformShape (ODGraphicsSystem graphicsSystem,
                           ODPlatformShape platformShape)

Parameters

graphicsSystem (ODGraphicsSystem) - input

  A graphics system for which you are specifying a shape. Valid graphics systems are platform-dependent:
  - For OS/2, use kODGPI.
  - For Windows, use kODWin32, kODWin95, or kODWinNT.
  - For AIX, use kODAIX.

platformShape (ODPlatformShape) - input

  The valid graphics-system-specific shape. Valid values are graphics-system-dependent. On OS/2 and Windows, this is a region handle (HRGN)

Returns

None.

Remarks

After this method executes successfully, the region is owned by the shape object. The caller must not modify or destroy the region.

Exception Handling

kODErrInvalidGraphicsSystem | The implementation of OpenDoc does not support the specified graphics system, or that graphics system is not installed or available.

Related Methods

- ODShape::GetPlatformShape

### SetPolygon

This method modifies this shape to make it equivalent to the specified polygon.

Signature

    ODShape *SetPolygon (ODPolygon *polygon)

Parameters

polygon (ODPolygon *) - input

  A valid polygon.

Returns

rv (ODShape *) - returns

  A reference to this shape after it has been changed to be equivalent to the specified polygon.

Remarks

After this method executes successfully, you are still responsible for deleting the original polygon; this shape does not use or modify it.

If the specified polygon is self-intersecting, certain methods, such as Intersect, Outset, Subtract, and Union simplify the polygon by removing the areas of self intersection.

Related Methods

- ODShape::CopyPolygon

### SetRectangle

This method modifies this shape to make it equivalent to the specified rectangle.

Signature

    ODShape *SetRectangle (ODRect *rect)

Parameters

rect (ODRect *) - input

  A valid rectangle.

Returns

rv (ODShape *) - returns

  A reference to this shape after it has been changed to be equivalent to the specified rectangle.

### SetRegion

This method replaces the geometric representation of this shape with the specified region. This method is similar to SetPlatformShape.

Signature

    void SetRegion (ODRgnHandle rgn)

Parameters

rgn (ODRgnHandle) - input

  On OS/2, a handle to the GPI region; on Windows, an HRGN.

Returns

None.

Remarks

The region is consumed by the shape, and the caller must not use or destroy it. This call is identical to the following call:

    s->SetPlatformShape(kODGPI, (ODPlatformShape) hrgn);

### Subtract

This method modifies this shape by subtracting the specified shape from it.

Signature

    ODShape *Subtract (ODShape *diffShape)

Parameters

diffShape (ODShape *) - input

  A reference to the shape to be subtracted from this shape.

Returns

rv (ODShape *) - returns

  A reference to this shape after the subtraction operation.

Remarks

After this method executes successfully, this shape is equivalent to its previous shape minus the specified shape.

Exception Handling

kODErrNoShapeGeometry | The geometry mode of this shape is kODNeedsGeometry, but the other shape has no geometric representation.
kODErrOutOfMemory | There is not enough memory to subtract the shape.

### Transform

This method modifies this shape by applying the specified transform.

Signature

    ODShape *Transform (ODTransform *transform)

Parameters

transform (ODTransform *) - input

  A reference to the transform to be applied to this shape.

Returns

rv (ODShape *) - returns

  A reference to this shape after it has been transformed.

Remarks

You can use this method to move a shape from one coordinate system to another. For example, a facet's clip shape is in the coordinate system of the frame. To get it into the coordinate system of the canvas, (which you need to do prior to obtaining a clipping region) you have to transform it by the facet's external transform.

Shapes without a geometric representation may not be transformable except by simple offsets.

Exception Handling

kODErrNoShapeGeometry | The specified shape does not have enough geometric information to be transformed in this way.
kODErrOutOfMemory | There is not enough memory to transform the shape.

### Union

This method modifies this shape to be the union of this shape and the specified shape.

Signature

    ODShape *Union (ODShape *unionShape)

Parameters

unionShape (ODShape *) - input

  A reference to the shape to be unioned with this shape.

Returns

rv (ODShape *) - returns

  A reference to this shape after the union operation.

Remarks

After this method executes successfully, this shape is equivalent to the union of its previous shape and the specified shape.

Exception Handling

kODErrNoShapeGeometry | The geometry mode of this shape is kODNeedsGeometry, but the other shape has no geometric representation.
kODErrOutOfMemory | There is not enough memory to compute the union.

### WriteShape

This method writes this shape to the specified storage unit.

Signature

    void WriteShape (ODStorageUnit *storageUnit)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to the storage unit where the shape data is to be written.

Returns

None.

Remarks

Before calling this method, you must focus the storage unit to the property where the shape data is to be written.

If the shape can be represented as a polygon, it is written as such to the value of type kODPolygon in the focus property, replacing any polygon that was previously stored in that value or creating the value if it does not already exist.

Exception Handling

kODErrOutOfMemory | There is not enough memory to write the shape's data to the storage unit.
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or a value.

Related Methods

- ODShape::ReadShape

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