Transitioning 2D Graphics to IBM Open Class

This section describes how to transition your VisualAge C++ 3.5 graphics code to the API available with the IBM Open Class Library. It contains the following:

General Transitions

Visual Age C++ 3.5

IBM Open Class

IGraphicBundle IGrafBundle
IRegionHandle no change
ITransformMatrix IGrafMatrix
IFont no change
IFont::FaceNameCursor no change
IFont::PointSizeCursor no change
IGList::Cursor IGraphicGroupIterator
IGraphic IMGraphic
IG3PointArc IGArcThrough3Points, ICurve
IGArc IGCurve2D( IGEllipse, angle, angle ), ICurve
IGBitmap IGImage, IImage (see ibaseactl/inotebk.cpp)
IGEllipse IGEllipse2D, IEllipse
IGLine IGLine2D, ILine
IGList IGraphicGroup
IGPie IGPie2D, ICurve
IGChord IGLoop2D, ILoop (arc constructors)
IGPolyline IGPolyline2D, IPolyline
IGPolygon IGPolygon2D, IPolygon
IGRectangle IGRect2D, IPolygon
IGRegion IGArea, IArea
IGString IGraphicText (from Text Framework)
IGraphicContext IGrafPort

IGraphicContext Replacements

The IGraphicContext class is replaced by IGrafPort and its subclasses, ILinkedGrafPort, IRootGrafPort, IExtendedRootGrafPort, and IStatefulGrafPort as shown in the table below.

Visual Age C++ 3.5

Open Class Technology Preview

IGraphicContext IGrafPort (abstract)
  ILinkedGrafPort
  IRootGrafPort
  IExtendedRootGrafPort
  IStatefulGrafPort

IGraphicContext Constructors

Visual Age C++ 3.5

Open Class Technology Preview

IGraphicContext
(const IPresSpaceHandle&)
IRootGrafPort(IPresSpaceHandle);
IExtendedRootGrafPort(
IPresSpaceHandle,
EDeviceCoordinateSystem =
kLeftHand,
EDeviceMappingMode = kPixel);
IGraphicContext()
draws to memory
IRootGrafPort()
draws on desktop device
IGraphicContext
(const IWindowHandle&)
IRootGrafPort(IManagedPresSpaceHandle(
const IWindowHandle&));
IExtendedRootGrafPort(
IManagedPresSpaceHandle(
const IWindowHandle&),
EDeviceCoordinateSystem =
kLeftHand,
EDeviceMappingMode = kPixel);
IGraphicContext(const ISize&) IGImagePixelAccessor(IGImage& referencedImage);

 

IGraphicContext Boundary Accumulation

Area geometries provide a rich set of functions and superior boundary accumulation. For example:

IGArea boundary = IGArea(IGRect2D) + IGArea(IGRect2D)

Boundary accumulation is done in a device-independent fashion. Instead of using an IGrafPort, call bounds() on a geometry class (such as IGCurve2D), or call geometricBounds on any IMGraphic subclass. Then use the extendTo() function on IGRect2D to accumulate the bounds.

If device-dependent bounds are needed, then call looseFitBounds on IMGraphic, and pass in the appropriate IGrafPort.

Visual Age C++ 3.5

Open Class Technology Preview

addToBoundingRect See IGRect2D::extendTo(const IGRect2D&); with geometricBounds() on IMGraphic or bounds() from any geometry class

Also see IMGraphics::looseFitBounds

(const IGrafPort*) const;

isAccumulatingBoundingRect
startBoundaryAccumulation
stopBoundaryAccumulation

IGraphicContext Conversions

Visual Age C++ 3.5

Open Class Technology Preview

handle -> IPresSpaceHandle See IGrafPort: orphanDeviceContext; -> IPresSpaceHandle

IGraphic Current Drawing Position

All IMGraphic classes offer the translateBy( const IGPoint2D& ) function for setting the location. In addition, the current drawing position can be set absolutely on IGraphicText, a text subclass of IMGraphic.

Visual Age C++ 3.5

Open Class Technology Preview

currentDrawingPosition IGraphicText::location(const IGPoint2D&);
setCurrentDrawingPosition IGraphicText::setLocation(const IGPoint2D&);
IMGraphic::translateBy(const IGPoint2D&);

Default Drawing Attributes

Each IGrafPort subclass can maintain state for retained mode drawing. In particular, IRootGrafPort has a set of default values for its attributes.

IGraphicContext Device Space Transformation

For device space transformations, use IGrafMatrix with ILinkedGrafPort.

Visual Age C++ 3.5

Open Class Technology Preview

pageSize See IGrafMatrix and ILinkedGrafPort
setPageSize
setViewPortRect
viewPortRect See IGrafPort: IGrafMatrix& invertedDeviceTransform

IGraphicContext Drawing

The draw calls on IGrafPort take the new geometry classes, as well as other information, such as the IAttributeState and the IGrafMatrix. Text is drawn from IGraphicText (see Text and International framework)

Visual Age C++ 3.5

Open Class Technology Preview

draw(const IGLine& line), draw(const IGLine2D& geometry);
draw(const IGPolyline& polyline), draw(const IGPolyline2D& geometry);
draw(const IGPolygon& polygon), draw(const IGPolygon2D& geometry);
draw(const IGEllipse& geometry), draw(const IGEllipse2D& geometry);
draw(const IGRectangle&

graphicRectangle),

draw(const IGRect2D& geometry);
draw(const IGArc& arc), draw(const IGCurve2D& geometry);
draw(const IG3PointArc& arc), as above, but with IGArcThrough3Points
draw(const IGPie& pie), draw(const IGLoop2D& geometry) with IGPie2D
draw(const IGChord& chord), draw(const IGLoop2D& geometry)
draw(const IGString& graphicString), See IGraphicText
draw(const IGList& list), See IGraphicGroup: draw(IGrafPort&) const;
draw(const IGRegion& region); draw(const IGArea& geometry);

IGraphicContext Drawing Attributes

IGraphicContext drawing attributes are covered by IAttribute state and the following subclasses:

Unless otherwise stated, all members in the right column are in IAttributeState. Objects of this class are passed to the draw() call on IGrafPort subclasses. Other concepts from IGraphicContext are now expressed as classes such as IPaint, ICap, IJoint, and IPen. IGrafBundle, for example, has setFramePen(const IPen& pen) and const IPen* framePen() const members for relating an IPen.

Visual Age C++ 3.5

Open Class Technology Preview

backgroundColor none
backgroundMixMode always transparent
drawOperation EDrawOperation drawingOperation() const;
fillColor const IBaseColor* fillColor() const;
fillPattern const IPaint* fillPaint() const; then call pattern() on IPaint
graphicBundle See IGrafPort: const IAttributeState* attributes
mixMode const IColorTransferMode* fillTransferMode() const;
const IColorTransferMode* frameTransferMode() const;
const IImageTransferMode* imageTransferMode() const;
patternOrigin See IPaint: const IGPoint2D* patternPhase() const;
penColor const IBaseColor* frameColor() const;
penEndingStyle const ICap* frameEndCap() const;
penJoiningStyle const IJoint* frameJoint() const;
penPattern const IPaint* framePaint() const; then call pattern() on IPaint
penType EPenType penType() const;
penWidth Gcoordinate penWidth() const;
setBackgroundColor none
setBackgroundMixMode always transparent
setDrawOperation setDrawingOperation(IAttributeState::EDrawOperation);
setFillColor setFillColor(const IBaseColor&);
setFillPattern Set the pattern on an IPaint object,

then setFillPaint(const IPaint& paint);

setGraphicBundle See constructors of IGrafPort subclasses
setMixMode setFillTransferMode(const IColorTransferMode&);
setFrameTransferMode(const IColorTransferMode&);
setImageTransferMode(const IImageTransferMode&);
setPatternOrigin See IPaint (patternPhase means origin):
IPaint(

const IBaseColor& aColor,

const IMaskPattern& maskPattern IMaskPattern::kSolid,

const IGPoint2D& patternPhase = IGPoint2D::origin());

IPaint(

const IGImage& imagePattern,

const IGPoint2D& patternPhase = IGPoint2D::origin());

setPenColor setFrameColor(const IBaseColor& color);
setPenEndingStyle setFrameEndCap(const ICap&);
setPenJoiningStyle setFrameJoint(const IJoint&);
setPenPattern Set pattern on an IPaint object,

then setFramePaint(const IPaint& paint);

setPenType Set pen type on an IPen object,

then setFramePen(const IPen& newPen);

setPenWidth Set pen width on an IPen object,

then setFramePen(const IPen& newPen);

Font Operations

Use ITextStyleSet instead of IFont when setting font attributes such as bold. Use IFont only for font manager purposes. See the Text and International documentation.

Hit Testing

The API currently provides simple support for hit testing, which does not replace the full functionality originally provided in VisualAge 3.5. A simple approach is to use the geometricBounds call to obtain an IGRect2D, and then to ask that rectangle if it contains a point or intersects with a rectangle.

From IMGraphic:

IGRect2D geometricBounds() const;

From IGRect2D:

bool contains(const IGPoint2D&) const;

bool intersects(const IGRect2D&) const;

IGraphicContext Mapping Modes

IExtendedRootGrafPort is an extended IRootGrafPort. It defines the coordinate system and mapping mode of the device.

Visual Age C++ 3.5

Open Class Technology Preview

mappingMode Set at construction time only
setMappingMode IExtendedRootGrafPort(

IPresSpaceHandle deviceContextToBeAdopted,

EDeviceCoordinateSystem = kLeftHand,

EDeviceMappingMode = kPixel);

IGraphicContext Recoordination

The recoordination height, which is used to convert to and from coordinates with origin in upper left and lower left, is set by IExtendedRootGrafPort at the time of construction. Apply an ILinkedGrafPort with an IGrafMatrix of type EMatrixKind::kModelMatrix to change it.

Visual Age C++ 3.5

Open Class Technology Preview

recoordinationHeight Retrieve from the model matrix
setRecoordinationHeight IExtendedRootGrafPort and ILinkedGrafPort

IGraphicContext Region Operations

All IGrafPort subclasses can return the clip area. Use ILinkedGrafPort with an IGArea for clipping. Additionally, IStatefulGrafPort can set it directly.

Visual Age C++ 3.5

Open Class Technology Preview

setClipRegion ILinkedGrafPort(

IGrafPort* referencedParent,

const IGArea* referencedClipArea);

See IStatefulGrafPort:

setClipArea(const IGArea& clipArea);

clipRegion See IGrafPort:

const IGArea* clipArea() const;

clearClipRegion set a huge area

IGraphicContext World Space Transformation

Use ILinkedGrafPort with an IGrafMatrix for a world space transform. Specify EMatrixType::kModelMatrix to transform just the geometry, or select EMatrixType::kViewMatrix to transform both the geometry and the attributes (for example, pen width).

Visual Age C++ 3.5

Open Class Technology Preview

setWorldTransformMatrix ILinkedGrafPort(

IGrafPort* referencedParent,

EMatrixKind matrixKind,

const IGrafMatrix*

referencedMatrix);

setMatrix(

EMatrixKind matrixKind,

const IGrafMatrix& matrix);

worldTransformMatrix const IGrafMatrix*

matrix(EMatrixKind) const;

IGraphic

Just as an IGraphic can contain an IGraphicBundle and an ITransformationMatrix, the new class IMGraphic can similarly contain an IAttributeState and an IGrafMatrix. Subclassers of IGraphic have to override drawOn, whereas those of IMGraphic must override draw() as well as geometricBounds and transformBy.

IGraphic Constructors

Both IGraphic and IMGraphic are abstract base classes, and as such have no public constructors. As exhibited by the IGraphic hierarchy, the IMGraphic tree follows the pattern of providing default, copy, and bundle constructors

Visual Age C++ 3.5

Open Class Technology Preview

Model

Geometry

default - uses attributes in drawOn same, but for draw see IGrafPort::draw
copy - uses copy's attributes same ILinkedGrafPort(

IGrafPort* referencedParent,

const IAttributeState*

referencedAttributes);

IGraphicBundle IAttributeState  

Bounding Rectangle

The bounding rectangle concept is similar. Call looseFitBounds for more accurate bounds at device resolution and with respect to the attributes

Visual Age C++ 3.5

Open Class Technology Preview

boundingRect IGRect2D geometricBounds() const
IGRect2D looseFitBounds() const

IGraphic Drawing

IGrafPort replaces IGraphicContext, and draw(IGrafPort&) replaces drawOn(IGraphicContext&)

Visual Age C++ 3.5

Open Class Technology Preview

drawOn draw(IGrafPort&) const

Graphic Bundles

IGrafBundle replaces IGraphicBundle

Visual Age C++ 3.5

Open Class Technology Preview

graphicBundle const IGrafBundle* bundle( ) const;
hasGraphicBundle check if above == NIL
removeGraphicBundle IGrafBundle* orphanBundle();
setGraphicBundle adoptBundle(IGrafBundle* adoptedBundle);

IGraphic Hit Testing

Full support for hit detection is not currently provided. For more information, see the section on IGraphicContext, Hit Testing.

IGraphic Object Identifier

There is no corresponding identification mechanism in the Technology Preview graphics. You can use an IRawArray or a dictionary-like collection to maintain keys.

IGraphic World Space Transformation

An IGraphic supports replacing, pre-multiplying, and post-multiplying transformations. For IMGraphic, transformation is always post-multiply and cannot be undone, because the associated geometry has been transformed. To transform the view but retain the geometry, use EMatrixType::kViewMatrix with ILinkedGrafPort instead.

NOTE: In IGraphic classes, setTransformMatrix replaces the current transform, if any. IMGraphic classes, however, concatenate the transform in transformBy, and do not necessarily store the matrix. This results in a lighter-weight, high-performance object

Visual Age C++ 3.5

Open Class Technology Preview

ITransformMatrix In IGraphicGroup only:

const IGrafMatrix* matrix() const;

setTransformMatrix transformBy(const IGrafMatrix&)
hasTransformMatrix In IGraphicGroup only:

test NIL != const IGrafMatrix* matrix() const;

resetTransformMatrix use the inverse of the matrix
rotateBy rotateBy(

GDegrees,

const IGPoint2D& centerOfRotation= IGPoint2D::origin());

scaleBy scaleBy(

const IGPoint2D&,

const IGPoint2D& centerOfScale= IGPoint2D::origin());

translateBy translateBy(const IGPoint2D&);
setTransformMethod always post-multiply
transformMethod always post-multiply

IGraphicBundle Constructors

The class IAttributeState resembles IGraphicBundle's functionality with the subclasses IFillBundle and IFrameBundle. IFillAndFrameBundle combines these to replace most of the functions. IGrafBundle subsumes IGraphicBundle and adds more functionality, such as the image patterns available through IPaint.

Constructors are described below, and drawing attributes are addressed in the preceding section on IGraphicContext, which uses IGraphicBundle.

Visual Age C++ 3.5

Open Class Technology Preview

default IGrafBundle() - no attributes set
copy IGrafBundle(const IGrafBundle&); copies attributes
from IGraphicContext IGrafBundle(const IAttributeState&);
  IGrafBundle(

const IPaint& fPaint,

IAttributeState::EDrawOperation

attribute = kFrame);

  IGrafBundle(

const IPaint& fillPaint,

const IPaint& framePaint,

IAttributeState::EDrawOperation

attribute = kFillAndFrame);

  IGrafBundle(

const IBaseColor& color,

IAttributeState::EDrawOperation

attribute = kFrame);

  IGrafBundle(

const IBaseColor& fillColor,

const IBaseColor& frameColor,

IAttributeState::EDrawOperation

attribute = kFillAndFrame);