IRectangle

The IRectangle class represents a rectangular area defined by two points that form opposite corners of the rectangle. These two points are referred to as the minimum and maximum points.

IRectangle objects are usable independently of the coordinate system in use. The minimum, or origin, is defined as the point with the lowest coordinate values. Therefore, in a coordinate space where 0,0 is the top-left corner and increasing a point's coordinate value moves it to the right and down, the minimum point of an IRectangle will be the top-left corner and the maximum corner the bottom-right corner. Conversely, in a coordinate space where 0,0 is the bottom-left corner and increasing a point's coordinate value moves it to the right and up, the minimum corner of an IRectangle will be the bottom left, and the maximum corner the top right.

IRectangle provides some member functions that use the terms "right," "left," "top," and "bottom." These are synonyms for the functions defined in terms of minimum and maximum corners. The directional orientation for the right, left, top, and bottom functions is correct for a coordinate space where 0,0 is the lower-left corner. For other coordinate systems, left and bottom are the sides of the rectangle with the lowest coordinate value, and top and right the sides with the highest.

Mathematically, a rectangle includes all the points on the lines that intersect its minimum corner. It does not include the points that lie on its edges that do not intersect the origin. This is important when you are doing detailed graphics work. For example, a rectangle specified as having a minimum of 0,0 and maximum of 10,20 will include the points 0,0 though 0,19 but will not include 0,20. Similarly, the points 1,0 through 9,0 are contained, but 10,0 is not.

Various graphics and windowing classes, as well as their member functions, use rectangles.

OS/2 Considerations

You can also construct objects of this class by providing a Presentation Manager Toolkit RECTL structure.

Windows Considerations

You can also construct objects of this class by providing Windows toolkit RECT or RECTL structures.


IRectangle - Member Functions and Data by Group

Constructors & Destructor

You can construct, copy, and assign objects of this class.
Note: The Open Class Library constructs rectangles by taking the two points that are given (or implied) as opposite corners. The minimum point, or origin, is set to be the lesser of the two points. This ensures that internally the origin and corner points always are such that the origin is less than or equal to the corner.


[view class]
IRectangle
Constructs and IRectangle object.


Overload 1
public:
IRectangle( Coord point1X, Coord point1Y, Coord point2X, Coord point2Y )

Constructs a rectangle from four values representing coordinates of the corners.

point1X
The X-coordinate of point 1.
point1Y
The Y-coordinate of point 1.
point2X
The X-coordinate of point 2.
point2Y
The Y-coordinate of point 2.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle(const IPoint& point1, const IPoint& point2)

Constructs a rectangle from two points at opposite corners.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IRectangle(const struct _RECTL& rectl)

Constructs a rectangle from a PM toolkit RECTL structure.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 4
public:
IRectangle(const IPair& pair)

Constructs a rectangle with corners at 0,0 and the specified location. The lower of aPair and 0,0 will be the origin of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IRectangle(const struct tagRECT& rect)

Constructs a rectangle from a Windows toolkit RECT structure.

Supported Platforms

Windows OS/2 AIX
Yes No No


Overload 6
public:
IRectangle(Coord width, Coord height)

Constructs a rectangle of the specified size. The size is specified as follows:

width
The width of the rectangle.
height
The height of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
public:
IRectangle(const IPoint& point, const ISize& size)

Creates a rectangle from a point and size. The maximum point is calculated by adding the width of the size to the X-coordinate of the given point and adding the height of the size to the Y-coordinate of the given point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
IRectangle()

Constructs a rectangle at (0,0),(0,0).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparisons

Use these members to compare two rectangles for equality or inequality.


[view class]
operator !=
public:
bool operator !=(const IRectangle& rectangle) const

If the rectangles differ, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
bool operator ==(const IRectangle& rectangle) const

If the two rectangles are identical, true is returned. Identity of rectangles means that the two defining points are the same.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Conversions

Use these members to convert a rectangle into various formats.


[view class]
asDebugInfo
public:
IString asDebugInfo() const

Renders the rectangle as a diagnostic representation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asRECTL
public:
struct _RECTL asRECTL() const

Converts the rectangle into a system-dependent structure.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

Renders the rectangle as a Presentation Manager Toolkit RECTL structure.

Windows Considerations

Renders the rectangle as a Windows toolkit RECTL structure.


[view class]
asString
public:
IString asString() const

Renders the rectangle as an IString("IRectangle(x1,y1,x2,y2)").

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Dimensions

Use these members to obtain information about a rectangle's size.


[view class]
area
public:
Coord area() const

Returns the area of the rectangle. The area is determined by multiplying the width of the rectangle by the height. For example, a rectangle defined from IPoint(1,1), IPoint(10,20) would have an area of 9*19, or 171.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
height
public:
Coord height() const

Returns the height of the rectangle. The height is determined by subtracting the Y-coordinate of the minimum point from the Y-coordinate of the maximum point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maxX
public:
Coord maxX() const

Returns the X-coordinate of the vertical line that is opposite the origin of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maxY
public:
Coord maxY() const

Returns the Y-coordinate of the horizontal line opposite the origin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minX
public:
Coord minX() const

Returns the X-coordinate of the vertical line that passes though the origin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minY
public:
Coord minY() const

Returns the Y-coordinate of the horizontal line that passes though the origin of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
size
public:
ISize size() const

Returns the ISize(width, height).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
width
public:
Coord width() const

Returns the width of the rectangle. The width is determined by subtracting the X-coordinate of the minimum point from the X-coordinate of the maximum point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These members are used internally to implement the class.


[view class]
validate
protected:
IRectangle& validate()

Corrects an invalid rectangle after creation, expansion, or intersection.
Note: If the rectangle is invalid, the points for both the origin and the corner of the rectangle are reset to IPoint( 0, 0 ).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Manipulation

Use these members to modify the rectangle, changing its size, proportions, or location.


[view class]
centerAt
public:
IRectangle& centerAt(const IPoint& point)

Moves the rectangle so that its center is at the specified point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
centeredAt
public:
IRectangle centeredAt(const IPoint& point) const

Same as centerAt, but returns a new rectangle, leaving the original unmodified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
expandBy

Moves the corners of the rectangle outward from the center by the specified amount. The specified amount can be either a scalar (long integer) or a point.


Overload 1
public:
IRectangle& expandBy(const IPair& pair)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle& expandBy(Coord coord)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
expandedBy

Same as expandBy, but returns a new rectangle, leaving the original unmodified.


Overload 1
public:
IRectangle expandedBy(const IPair& pair) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle expandedBy(Coord coord) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
moveBy
public:
IRectangle& moveBy(const IPair& pair)

Moves the rectangle by the amount specified by aPair.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
movedBy
public:
IRectangle movedBy(const IPair& pair) const

Same as moveBy, but returns a new rectangle, leaving the original unmodified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
movedTo
public:
IRectangle movedTo(const IPoint& point) const

Same as moveTo, but returns a new rectangle, leaving the original unmodified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
moveTo
public:
IRectangle& moveTo(const IPoint& point)

Moves the rectangle so that its origin corner is at the specified point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scaleBy

Scales the rectangle by the specified amount. Scaling a rectangle multiplies its coordinates by the scale amount.


Overload 1
public:
IRectangle& scaleBy(const IPair& pair)

Scales by a point specifying the amounts in the X-axis and Y-axis directions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle& scaleBy(double xfactor, double yfactor)

Scales by a pair of doubles. The function uses the first double to scale in the X-axis direction; the second in the Y-axis direction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IRectangle& scaleBy(Coord coord)

Scales by a long integer value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IRectangle& scaleBy(double factor)

Scales by a double value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scaledBy

Same as scaleBy, but returns a new rectangle, leaving the original unmodified.


Overload 1
public:
IRectangle scaledBy(double factor) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle scaledBy(const IPair& pair) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IRectangle scaledBy(Coord coord) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IRectangle scaledBy(double xfactor, double yfactor) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
shrinkBy

Moves the corners of the rectangle inward toward the center by the specified amount, either a scalar or a point.
Note: shrinkBy(anAmount) is always equivalent to expandBy(-anAmount), and vice versa.


Overload 1
public:
IRectangle& shrinkBy(const IPair& pair)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle& shrinkBy(Coord coord)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
shrunkBy

Same as shrinkBy, but returns a new rectangle, leaving the original unmodified.


Overload 1
public:
IRectangle shrunkBy(const IPair& pair) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle shrunkBy(Coord coord) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizeBy

Scales the rectangle by the specified value, leaving the rectangle at the same location because the bottom-left point remains fixed.


Overload 1
public:
IRectangle& sizeBy(double factor)

Scales by the same double factor in both the X-axis and Y-axis directions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle& sizeBy(double xfactor, double yfactor)

Scales by two doubles specifying factors in the X-axis and Y-axis directions, respectively.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IRectangle& sizeBy(Coord factor)

Scales by the same integer factor in both the X-axis and Y-axis directions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IRectangle& sizeBy(const IPair& pair)

Scales by a pair of integer scalars specifying different factors in the X-axis and Y-axis directions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizedBy
Same as sizeBy, but returns a new rectangle, leaving the original unmodified.


Overload 1
public:
IRectangle sizedBy(double factor) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IRectangle sizedBy(const IPair& pair) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IRectangle sizedBy(Coord factor) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IRectangle sizedBy(double xfactor, double yfactor) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizedTo
public:
IRectangle sizedTo(const IPair& pair) const

Same as sizeTo, but returns a new rectangle, leaving the original unmodified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizeTo
public:
IRectangle& sizeTo(const IPair& pair)

Sizes the rectangle to the specified size.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Manipulation Operators

Use these members to find a rectangle's union and intersection with another rectangle.


[view class]
operator &
public:
IRectangle operator &(const IRectangle& rectangle) const

Returns a rectangle representing the intersection of the specified rectangles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator &=
public:
IRectangle& operator &=(const IRectangle& rectangle)

Resets the rectangle to its intersection with the specified rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator |
public:
IRectangle operator |(const IRectangle& rectangle) const

Returns the rectangle representing the union of the specified rectangles. This is the smallest rectangle that encompasses both specified rectangles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator |=
public:
IRectangle& operator |=(const IRectangle& rectangle)

Resets the rectangle to its union with the specified rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Points

Use these members to access points on or within the rectangle. You can query any of nine points on a rectangle's perimeter or its center by using these members.


[view class]
centerXCenterY
public:
IPoint centerXCenterY() const

Returns the X- and Y-coordinates of the center point of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
centerXMaxY
public:
IPoint centerXMaxY() const

Returns the X- and Y-coordinates of the center point of the horizontal line opposite the origin of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
centerXMinY
public:
IPoint centerXMinY() const

Returns the X- and Y-coordinates of the center point of the horizontal line passing through the origin of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maxXCenterY
public:
IPoint maxXCenterY() const

Returns the X- and Y-coordinates of the center point of the vertical line opposite the origin of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maxXMaxY
public:
IPoint maxXMaxY() const

Returns the X- and Y-coordinates of the corner of the rectangle opposite the origin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maxXMinY
public:
IPoint maxXMinY() const

Returns the X- and Y-coordinates of the corner of the rectangle at the other end of the horizontal line passing though the origin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minXCenterY
public:
IPoint minXCenterY() const

Returns the X- and Y-coordinates of the center of the vertical line that passes through the origin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minXMaxY
public:
IPoint minXMaxY() const

Returns the X- and Y-coordinates of the corner of the rectangle at the other end of the vertical line passing though the origin.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minXMinY
public:
IPoint minXMinY() const

Returns the X- and Y-coordinates of the origin corner of the rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Synonyms

Use these members when you are working in a coordinate space where 0,0 is the bottom-left corner. In this case the right-left-top-bottom orientation is correct. You can still use these members in other coordinate systems, but left and bottom are the sides of the rectangle with the lowest coordinate value, and top and right are the sides with the highest.

The following table lists the members and synonyms defined for them:

Function :ddhd.Synonym
minXMinY
bottomLeft
minXCenterY
leftCenter
minXMaxY
topLeft
centerXMinY
bottomCenter
centerXCenterY
center
centerXMaxY
topCenter
maxXMinY
bottomRight
maxXCenterY
rightCenter
maxXMaxY
topRight
minX
left
minY
bottom
maxX
right
maxY
top


[view class]
bottom
public:
Coord bottom() const

Returns the Y-coordinate of the horizontal line that forms the bottom of the rectangle. This is an alias for minY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bottomCenter
public:
IPoint bottomCenter() const

Returns the X- and Y-coordinates of the bottom-center point of the rectangle. This is an alias for centerXMinY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bottomLeft
public:
IPoint bottomLeft() const

Returns the X- and Y-coordinates of the bottom-left corner of the rectangle This is an alias for minXMinY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bottomRight
public:
IPoint bottomRight() const

Returns the X- and Y-coordinates of the bottom-right corner of the rectangle. This is an alias for maxXMinY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
center
public:
IPoint center() const

Returns the X- and Y-coordinates of the center point of the rectangle. This is an alias for centerXCenterY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
left
public:
Coord left() const

Returns the X-coordinate of the vertical line that forms the left side of the rectangle. This is an alias for minX.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
leftCenter
public:
IPoint leftCenter() const

Returns the X- and Y-coordinates of the left-center point of the rectangle. This is an alias for minXCenterY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
right
public:
Coord right() const

Returns the X-coordinate of the vertical line that forms the right side of the rectangle. This is an alias for maxX.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightCenter
public:
IPoint rightCenter() const

Returns the X- and Y-coordinates of the right-center point of the rectangle. This is an alias for maxXCenterY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
top
public:
Coord top() const

Returns the Y-coordinate of the horizontal line that forms the top of the rectangle. This is an alias for maxY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
topCenter
public:
IPoint topCenter() const

Returns the X- and Y-coordinates of the top-center point of the rectangle. This is an alias for centerXMaxY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
topLeft
public:
IPoint topLeft() const

Returns the X- and Y-coordinates of the top-left corner of the rectangle. This is an alias for minXMaxY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
topRight
public:
IPoint topRight() const

Returns the X- and Y-coordinates of the top-right corner of the rectangle. This is an alias for maxXMaxY.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Testing

Use these members to test various attributes of a rectangle.


[view class]
contains

If the rectangle contains the specified point or rectangle, true is returned. A point is contained by a rectangle if its coordinates are greater than or equal to the minimum point of the rectangle and less than the maximum point. A rectangle is contained within another rectangle if its minimum point is greater than or equal to the containing rectangle's minimum point and its maximum point is less than or equal to the containing rectangle's maximum point.


Overload 1
public:
bool contains(const IPoint& point) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
bool contains(const IRectangle& rectangle) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
intersects
public:
bool intersects(const IRectangle& rectangle) const

If the rectangle and specified rectangle overlap, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IRectangle - Type Definitions


[view class]
Coord
typedef IPair::Coord Coord
Type of the coordinate values; this must match the type of the coordinates supported by the IPair class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IRectangle - Associated Globals


operator <<
ostream& operator <<(ostream& stream, const IRectangle& rectangle)
Streams this object out to an ostream.


IRectangle - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data