eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Rectangle':
Home

Documentation
www.exept.de
Everywhere
for:
[back]

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
o  center: centerPoint extent: extentPoint
return an instance of me whose center is centerPoint and width
by height is extentPoint.

o  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)

o  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)

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

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

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

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

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

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

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

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

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

instance creation-interactive
o  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

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

usage example(s): 

     Rectangle originFromUser:50@50

Instance protocol:

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

o  containsRect: aRect
Answer whether aRect is within the receiver (OK to coincide).

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

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

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

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

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

o  bottom
return the y coordinate of the bottom

o  bottom: aNumber
set the bottom edge - warning: destructive

o  bottomCenter
return the bottom center point

o  bottomLeft
return the bottom-left point

o  bottomRight
return the bottom-right point

o  center
return the point in the center of the receiver

o  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

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

o  extent
return the extent

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

o  height
return the height of the rectangle

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

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

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

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

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

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

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

o  leftCenter
return the left center point

o  origin
return the origin

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

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

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

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

o  right
return the x coordinate of the right

o  right: aNumber
set the right edge - warning: destructive

o  rightCenter
return the right center point

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

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

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

o  top
return the y-coordinate of the top-left

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

o  topCenter
return the top center point

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

o  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

o  topRight
return the top-right point

o  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

o  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

o  width
return the width of the rectangle

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

comparing
o  = aRectangle
return true, if the argument aRectangle represents the same
rectangle as the receiver

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

converting
o  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

o  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

o  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

o  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

o  asPolygon
return a polygon from the receiver

usage example(s): 

     (10@10 corner:100@100) asPolygon

o  asRectangle

o  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)

o  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

o  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
o  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
owner of the receiver to avoid side effects. See also: #expandedBy:

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

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

o  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

o  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
o  ascentOn: aGC
displayOn: does draw above baseline

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

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

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

printing & storing
o  printOn: aStream
print the receiver on aStream

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

queries
o  bounds
return the smallest enclosing rectangle

o  computeBounds
return the smallest enclosing rectangle

o  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)

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

o  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.

o  corners
Return an array of corner points

o  innerCorners
Return an array of inner corner points,
ie, the most extreme pixels included.
Added for Aqueak compatibility.

usage example(s): 

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

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

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

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

o  - 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

o  areasOutside: aRectangle
Answer an Array of Rectangles comprising the parts of the receiver
not intersecting aRectangle.
That is all areas with no common pixels.

o  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) }

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

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

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

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

o  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

o  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)

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

o  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)

o  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

o  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

o  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
o  canBeFilled
return true, if the receiver can be drawn as a filled geometric.
Always true here.

o  hasShortPrintString

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

transformations
o  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
o  rounded
return a copy of the receiver with rounded coordinates.
Return the receiver if its coordinates are already integral.

o  truncated
return a Rectangle whose origin and corner have any fractional parts removed.
Return the receiver if its coordinates are already integral.

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Wed, 06 Dec 2023 05:41:44 GMT