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.

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.

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

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.

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.

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.

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.

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.