Documentation
www.exept.de
Everywhere
for:

# Class: Rectangle

## Inheritance:

Object
|
+--Geometric
|
+--Rectangle

Package:
stx:libbasic
Category:
Graphics-Geometry-Objects
Version:
rev: 1.105 date: 2019/07/17 08:31:42
user: cg
file: Rectangle.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

## Description:

Rectangles represent a rectangular area in 2D space.

notice, my implementation does not use origin/corner as instance objects
but left/top/width/height to save space and allocations. This means, that my
Rectangles cannot be used to represent Rectangles in a higher than 2D
space. (i.e. only valid if origin/corner are 2D Points)

(aside from that, you will not see any difference from the outside)

Instance variables:

left           <Number>        the left coordinate (i.e origin x)
top            <Number>        the top coordinate (i.e origin y)
width          <Number>        the width of the rectangle
height         <Number>        the height of the rectangle

I am not certain, if implementing Rectangle different was a good idea -
subclasses may expect things to be different ...
Therefore, this may change.

## Related information:

Point
Polygon
Circle
EllipticalArc
Spline
LayoutOrigin
LayoutFrame
AlignmentOrigin
Layout
View
GraphicsContext
StrokingWrapper
FillingWrapper

## Class protocol:

instance creation
center: centerPoint extent: extentPoint
return an instance of me whose center is centerPoint and width
by height is extentPoint.

decodeFromLiteralArray: anArray
create & return a new instance from information encoded in anArray.
Redefined for faster creation.

usage example(s):

 Rectangle decodeFromLiteralArray:#(Rectangle 100 200 300 500)

encompassing: listOfPoints
Return a rectangle, which encompasses all of the given points.

usage example(s):

 Rectangle encompassing:(Array with:10@10 with:50@0 with:0@50)

left: left right: right top: top bottom: bottom
create and return a new Rectangle giving left, top, right and bottom coordinates

left: left top: top extent: extent
create and return a new Rectangle giving left, top, and
an extent point.

left: left top: top right: right bottom: bottom
create and return a new Rectangle giving left, top, right and bottom coordinates

left: left top: top width: w height: h
create and return a new Rectangle giving left and top coordinates
and width, height

merging: listOfRects
return the merge of a number of rectangles.
Avoids creation of temp garbage.

origin: origin corner: corner
create and return a new Rectangle giving top-left and bottom-right points

origin: origin extent: extent
create and return a new Rectangle giving top-left point and extent point

origin: origin width: w height: h
create and return a new Rectangle giving top-left and extent
as individual width/height

vertex: vertex1Point vertex: vertex2Point
create and return a new instance of the receiver,
given two diagonally opposite vertices.

instance creation-interactive
fromUser
let user specify a rectangle on the screen, return it.
If the user presses ESC, an AbortOperationRequest is raised.

usage example(s):

 Rectangle fromUser

originFromUser: extent
let user specify an origin on the screen, return it

usage example(s):

 Rectangle originFromUser:50@50

## Instance protocol:

Compatibility-Squeak
amountToTranslateWithin: aRectangle
Answer a Point, delta, such that self + delta is forced within aRectangle.

containsRect: aRect

isTall
return true, if the receiver is higher then its width

isWide
return true, if the receiver is wider then its height

translatedToBeWithin: aRectangle
Answer a copy of the receiver that does not extend beyond aRectangle. 7/8/96 sw

withHeight: height
Return a copy of me with a different height

accessing
area
return the area
- for screen Rectangles this is the number of pixels

bottom
return the y coordinate of the bottom

bottom: aNumber
set the bottom edge - warning: destructive

bottomCenter
return the bottom center point

bottomLeft
return the bottom-left point

bottomRight
return the bottom-right point

center
return the point in the center of the receiver

corner
return the corner

usage example(s):

 (self origin:0@0 corner:100@100) corner (self origin:0@0 corner:100@100) origin (self origin:5@5 corner:100@100) extent

corner: aPoint
set the bottom-right corner - warning: destructive

extent
return the extent

extent: aPoint
set the extent from the argument, aPoint
with width taken from aPoint x and height taken from aPoint y.
warning: destructive

height
return the height of the rectangle

height: aNumber
change the height of the rectangle.
logically, this changes the corner to get the given height.
warning: destructive

left
return the x-coordinate of the top-left origin

left: aNumber
set the left edge, adjust width - warning: destructive

left: newLeft right: right top: newTop bottom: bottom
set the rectangle given left, top, right and bottom coordinates.
warning: destructive

left: newLeft top: newTop extent: extent
set the rectangle given left, top, coordinates and an extent.
warning: destructive

left: newLeft top: newTop right: right bottom: bottom
set the rectangle given left, top, right and bottom coordinates.
warning: destructive

left: newLeft top: newTop width: newWidth height: newHeight
set the rectangle given left, top coordinates and width, height.
warning: destructive

leftCenter
return the left center point

origin
return the origin

origin: aPoint
set the top-left origin. The corner remains unchanged.
warning: destructive

origin: origin corner: corner
set both origin and corner - warning: destructive

origin: origin extent: extent
set both origin and extent - warning: destructive

origin: origin width: w height: h
set both origin and extent;
the extent is given as individual width and height.
warning: destructive

right
return the x coordinate of the right

right: aNumber
set the right edge - warning: destructive

rightCenter
return the right center point

setLeft: newLeft
set left without adjusting width - warning: destructive

setOrigin: newOrigin corner: newCorner
set the rectangles dimensions - warning: destructive

setTop: newTop
set top without adjusting height - warning: destructive

top
return the y-coordinate of the top-left

top: aNumber
set the top edge, adjust height - warning: destructive

topCenter
return the top center point

topLeft
return the top-left point - the same as origin

topLeft: aPoint
Set the top and left edges.
The bottom right remains unchanged.
warning: destructive

usage example(s):

 ((self origin:0@0 corner:100@100) topLeft:(10@20)) corner

topRight
return the top-right point

topRight: aPoint
Set the top and right edges.
The bottom left remains unchanged.
warning: destructive

usage example(s):

 ((self origin:0@0 corner:100@100) topRight:(10@20)) corner

vertices
return the array containing my points as a closed polygon (for Polygon compatibility)

usage example(s):

 (Rectangle origin:100@100 extent:20@30) vertices (Rectangle origin:100@100 extent:20@30) asPolygon vertices

width
return the width of the rectangle

width: aNumber
change the width of the rectangle.
logically, this changes the corner to get the given width.
warning: destructive

comparing
= aRectangle
return true, if the argument aRectangle represents the same

hash
return an integer useful for hashing -
redefined since = is redefined here

converting
asFractionalLayout
return a layoutFrame in which fractions (top, left, bottom, right)
are taken from corresponding edges of the receiver.
You have to make certain that those are in 0..1.

usage example(s):

 (0.5@0.5 corner:0.75@0.75) asFractionalLayout (0.5@0.5 corner:0.75@0.75) asOffsetLayout (0.5@0.5 corner:0.75@0.75) asLayout (0@0 corner:1@1) asLayout (0@0 corner:1@1) asFractionalLayout (0@0 corner:1@1) asOffsetLayout

asLayout
return a layoutFrame in which offsets (top, left, bottom, right)
are taken from corresponding edges of the receiver.
If all values are between 0.0 .. 1.0, a fractionalLayout is created,
otherwise, an offsetLayout

usage example(s):

 (0.5@0.5 corner:0.75@0.75) asFractionalLayout (0.5@0.5 corner:0.75@0.75) asOffsetLayout (0.5@0.5 corner:0.75@0.75) asLayout (0@0 corner:1@1) asLayout (0@0 corner:1@1) asFractionalLayout (0@0 corner:1@1) asOffsetLayout

asOffsetLayout
return a layoutFrame in which offsets (top, left, bottom, right)
are taken from corresponding edges of the receiver.
You have to make certain that those are in 0..1.

usage example(s):

 (0.5@0.5 corner:0.75@0.75) asFractionalLayout (0.5@0.5 corner:0.75@0.75) asOffsetLayout (0.5@0.5 corner:0.75@0.75) asLayout (10@10 corner:20@20) asFractionalLayout (10@10 corner:20@20) asOffsetLayout (10@10 corner:20@20) asLayout

asPointArray
return an array containing my corners (clockwise) and
the origin again as 5th element. Can be used to convert
a rectangle into a polygon.

usage example(s):

 (10@10 corner:100@100) asPointArray

asPolygon
return a polygon from the receiver

usage example(s):

 (10@10 corner:100@100) asPolygon

asRectangle

fromLiteralArrayEncoding: encoding
read my values from an encoding.
The encoding is supposed to be of the form: (Rectangle orgX orgY cornX cornY)

usage example(s):

 Rectangle new fromLiteralArrayEncoding:#(Rectangle 100 200 300 500)

literalArrayEncoding
encode myself as an array, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.
The encoding is: (Rectangle orgX orgY cornX cornY)

usage example(s):

 Rectangle new fromLiteralArrayEncoding:#(Rectangle 100 200 300 500) (100@200 corner:300@500) literalArrayEncoding

rectangleRelativeTo: aRectangle preferred: prefRectHolder
compute a displayRectangle, treating the receiver like a
layoutFrame.
This allows rectangles to be used interchangable with Layouts.

usage example(s):

 (10@20 corner:20@30) rectangleRelativeTo:(0@0 corner:100@100) preferred:(0@0 corner:50@50) (0.5@0.5) rectangleRelativeTo:(0@0 corner:100@100) preferred:(0@0 corner:50@50)

destructive rectangle operations
expandBy: delta
destructively expanded the receiver in all directions
by amount, a Point, Rectangle or Number.
Warning: this is a destructive operation, modifying the receiver
NOT returning a copy. You have to be certain to be the exclusive

moveBy: aPoint
destructively translate the rectangle by some distance (keeping extent unchanged).
sorry for the name inconsistency - but GNU-ST named it that way

moveTo: aPoint
destructively translate the rectangle to have its origin at aPoint (keeping extent unchanged).

scaleBy: scale
scale the receiver rectangle by scale (a Number or Point).
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver. (use scaledBy if in doubt)

usage example(s):

 (Rectangle origin:10@10 corner:50@50) scaleBy:2

translateBy: amount
translate (i.e. move) the receiver rectangle
by amount, a Point or Number (keeping extent unchanged).
This is destructive (modifies the receiver, not a copy) and
should only be used if you know, that you are the exclusive owner
of the receiver. (use translatedBy if in doubt)

usage example(s):

 (Rectangle origin:10@10 corner:50@50) translateBy:10

displaying
ascentOn: aGC
displayOn: does draw above baseline

displayFilledOn: aGC
display a filled rectangle as represented by the receiver in
the graphicsContext, aGC

displayStrokedOn: aGC
display an unfilled rectangle as represented by the receiver in
the graphicsContext, aGC

inspecting
inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

printing & storing
printOn: aStream

storeOn: aStream
store the receiver on aStream; i.e. print an expression which will

queries
bounds
return the smallest enclosing rectangle

computeBounds
return the smallest enclosing rectangle

contains: aRectangle
return true, if the argument, aRectangle is equal to or
is contained fully within the receiver

usage example(s):

 (0@0 corner:100@100) contains:(10@10 corner:90@90) (0@0 corner:100@100) contains:(10@10 corner:100@100) (0@0 corner:100@100) contains:(10@10 corner:110@100) (0@0 corner:100@100) contains:(10@10 corner:100@110) (10@10 corner:100@100) contains:(0@10 corner:100@100)

containsPoint: aPoint
return true, if the argument, aPoint is contained in the receiver

containsPointX: x y: y
return true, if the point defined by x@y is contained in the receiver.
This is the same as containsPoint:, but can be used if the coordinates
are already available as separate numbers to avoid useless creation of a
temporary point.

corners
Return an array of corner points

innerCorners
Return an array of inner corner points,
ie, the most extreme pixels included.

usage example(s):

 (10@10 corner:100@100) corners (10@10 corner:100@100) innerCorners

intersects: aRectangle
return true, if the intersection between the argument, aRectangle
and the receiver is not empty

isContainedIn: aRectangle
return true, if the receiver is fully contained within
the argument, aRectangle

rectangle operations
+ aPoint
return a new rectangle with same extent as receiver but
origin translated by the argument, aPoint

- aPoint
return a new rectangle with same extent as receiver but
origin translated by the argument, aPoint

usage example(s):

 Modified (format): / 24-08-2017 / 12:23:53 / cg

areasOutside: aRectangle
not intersecting aRectangle.
That is all areas with no common pixels.

areasOutside: aRectangle do: aBlock
evaluate aBlock for Rectangles comprising the parts of the receiver
not intersecting aRectangle.
That is all areas with no common pixels.

usage example(s):

 self assert: ((0@0 corner:100@100) areasOutside:(0@0 corner:50@50)) asArray = { (Rectangle origin:0@50 extent:100@50) . (Rectangle origin:50@0 extent:50@50) } self assert: ((0@0 corner:150@100) areasOutside:(0@0 corner:100@100)) asArray = { (Rectangle origin:100@0 extent:50@100) } self assert: ((0@0 corner:100@150) areasOutside:(0@0 corner:100@100)) asArray = { (Rectangle origin:0@100 extent:100@50) }

encompass: aPoint
return a Rectangle that contains both the receiver and aPoint.

expandedBy: delta
return a new rectangle which is expanded in all directions
by amount, a Point, Rectangle or Number

insetBy: delta
return a new rectangle which is inset in all directions
by delta, a Point, Rectangle or Number

insetOriginBy: originDelta cornerBy: cornerDelta
return a new rectangle which is inset by originDelta
and cornerDelta; both may be instances of Point or Number

intersect: aRectangle
return a new rectangle covering the intersection of the receiver
and the argument, aRectangle (i.e. the area covered by both).
the rectangles must intersect for a valid return

merge: aRectangle
return a new rectangle covering both the receiver
and the argument, aRectangle

usage example(s):

 (Rectangle origin:10@10 corner:100@100) merge:(Rectangle origin:20@20 corner:110@110) (Rectangle origin:10@10 corner:100@100) merge:(Rectangle origin:20@20 corner:100@100)

nonIntersections: aRectangle
this is the same as areasOutside: - for ST/V compatibility only

quickMerge: aRectangle
return the receiver if it encloses the given rectangle,
or the merge of the two rectangles if it doesn't.
This method is an optimized version of merge: to reduce extra rectangle creations.

usage example(s):

 (Rectangle origin:10@10 corner:100@100) quickMerge:(Rectangle origin:20@20 corner:110@110) (Rectangle origin:10@10 corner:100@100) quickMerge:(Rectangle origin:20@20 corner:100@100)

scaledBy: scale
return a new rectangle which is the receiver
scaled by scale

usage example(s):

 (Rectangle origin:10@10 corner:50@50) scaledBy:2

scaledBy: scale translatedBy: translation
return a new rectangle which is translated (i.e. moved)
by translation, aPoint or Number and scaled by scale, aPoint or number.

usage example(s):

 (Rectangle origin:10@10 corner:50@50) scaledBy:2 translatedBy:10

translatedBy: amount
return a new rectangle which is translated (i.e. moved)
by amount, aPoint or Number

usage example(s):

 (Rectangle origin:10@10 corner:50@50) translatedBy:10

testing
canBeFilled
return true, if the receiver can be drawn as a filled geometric.
Always true here.

hasShortPrintString

isRectangle
return true, if the receiver is some kind of rectangle

transformations
align: offset with: someCoordinate
return a new rectangle which is translated (i.e. moved)
such that the point offset in mySelf is placed on someCoordinate.

truncation & rounding
rounded
return a copy of the receiver with rounded coordinates.