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.134 date: 2024/03/11 14:24:28
user: cg
file: Rectangle.st directory: libbasic
module: stx stc-classLibrary: libbasic

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.


copyright
COPYRIGHT (c) 1989 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

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.
That is a rectangle, which encompasses all of the given 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  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: newHeight
Return a copy of me with a different height

o  withWidth: newWidth
Return a copy of me with a different width

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

o  bottom
return the y coordinate of the bottom.
For integer-coordinate rectangles (view areas),
that is the y-coordinate of the corner point,
which is the y coordinate just outside the rectangle

o  bottom: aNumber
set the bottom edge.
Warning: this is a destructive operation

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: this is a destructive operation

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: this is a destructive operation

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: this is a destructive operation

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

o  left: aNumber
set the left edge, adjust width.
Warning: this is a destructive operation

o  left: newLeft right: right top: newTop bottom: bottom
set the rectangle given left, top, right and bottom coordinates.
Warning: this is a destructive operation

o  left: newLeft top: newTop extent: extent
set the rectangle given left, top, coordinates and an extent.
Warning: this is a destructive operation

o  left: newLeft top: newTop right: right bottom: bottom
set the rectangle given left, top, right and bottom coordinates.
Warning: this is a destructive operation

o  left: newLeft top: newTop width: newWidth height: newHeight
set the rectangle given left, top coordinates and width, height.
Warning: this is a destructive operation

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: this is a destructive operation

o  origin: origin corner: corner
set both origin and corner.
Warning: this is a destructive operation

o  origin: origin extent: extent
set both origin and extent.
Warning: this is a destructive operation

o  origin: origin width: w height: h
set both origin and extent;
the extent is given as individual width and height.
Warning: this is a destructive operation

o  right
return the x coordinate of the right.
For integer-coordinate rectangles (view areas),
that is the x-coordinate of the corner point,
which is the x coordinate just outside the rectangle

o  right: aNumber
set the right edge.
Warning: this is a destructive operation

o  rightCenter
return the right center point

o  setLeft: newLeft
set left without adjusting width.
Warning: this is a destructive operation

o  setOrigin: newOrigin corner: newCorner
set the rectangles dimensions.
Warning: this is a destructive operation

o  setTop: newTop
set top without adjusting height.
Warning: this is a destructive operation

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

o  top: aNumber
set the top edge, adjust height.
Warning: this is a destructive operation

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: this is a destructive operation

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: this is a destructive operation

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: this is a destructive operation

o  width: newWidth height: newHeight
change the width and height of the rectangle.
logically, this changes the corner to get the given width.
Warning: this is a destructive operation

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
( an extension from the stx:libview2 package )
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
( an extension from the stx:libview2 package )
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
( an extension from the stx:libview2 package )
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,
it 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:

Usage example(s): 

     |r|
     r := Rectangle origin:10@10 corner:100@100.
     r expandBy:5.

     r := Rectangle origin:10@10 corner:100@100.
     r expandBy:(5 @ 0).

     r := Rectangle origin:10@10 corner:100@100.
     r expandBy:(10 @ 10).

     r := Rectangle origin:10@10 corner:100@100.
     r expandBy:( 10@10 corner:20@20 )

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

o  moveTo: aPoint
translate the rectangle to have its origin at aPoint (keeping extent unchanged).
Warning: this is a destructive operation

o  scaleBy: scale
scale the receiver rectangle by scale (a Number or Point).
Warning: this is a destructive operation
it 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

Usage example(s): 

     |r1 r2|

     r1 := Rectangle origin:10@10 corner:50@50.
     r2 := r1 scaleBy:2.
     r1

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

Usage example(s): 

     |r1 r2|

     r1 := Rectangle origin:10@10 corner:50@50.
     r2 := r1 translateBy:10.
     r1

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

Usage example(s): 

     |v|

     v := View new openAndWaitUntilVisible.

     (Rectangle origin:10@10 corner:50@50) displayFilledOn:v

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

Usage example(s): 

     |v|

     v := View new openAndWaitUntilVisible.

     (Rectangle origin:10@10 corner:50@50) displayStrokedOn:v

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

** This is an obsolete interface - do not use it (it may vanish in future versions) **

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  containsRect: aRectangle
return true, if the argument, aRectangle is equal to or
is contained fully within the receiver

o  corners
Return an array of corner points

o  dist: aPoint
the distance of aPoint to this rectangle.
That is the shortest distance to any of my boundary lines

Usage example(s): 

     (Rectangle origin:(0@0) corner:(100@100)) dist:110@110 =>  14.142135623731   
     (Rectangle origin:(0@0) corner:(100@100)) dist:110@100 =>  10.0
     (Rectangle origin:(0@0) corner:(100@100)) dist:100@110 =>  10.0
     (Rectangle origin:(0@0) corner:(100@100)) dist:50@50   =>  10.0

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

Usage example(s): 

     |r|

     r := Rectangle origin:10@10 corner:100@100.
     r isContainedIn: (Rectangle origin:10@10 corner:100@100).
     r isContainedIn: (Rectangle origin:11@10 corner:100@100).
     r isContainedIn: (Rectangle origin:9@10 corner:100@100).

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

Usage example(s): 

     |r|
     r := Rectangle origin:10@10 corner:100@100.
     r expandedBy:5.
     r expandedBy:(5 @ 0).
     r expandedBy:(10 @ 10).
     r expandedBy:( 10@10 corner:20@20 )

o  insetBy: delta
return a new rectangle which is inset in all directions
by delta, a Point, Rectangle or Number.
With a negative delta, the new rectangle is larger;
otherwise, it will be smaller

Usage example(s): 

     |r|
     r := Rectangle origin:10@10 corner:100@100.
     r insetBy:5. 
     r insetBy:-1. 
     r insetBy:(5 @ 0).
     r insetBy:(10 @ 10).
     r insetBy:( 10@10 corner:20@20 ).
     r insetBy:( 0@0 corner:-10@0 ).

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

Usage example(s): 

     |r|
     r := Rectangle origin:10@10 corner:100@100.
     r insetOriginBy:5 cornerBy:10.
     r insetOriginBy:10@5 cornerBy:10.
     r insetOriginBy:10 cornerBy:10@5.
     r insetOriginBy:10@10 cornerBy:20@20.

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

Usage example(s): 

     |r1 r2|

     r1 := Rectangle origin:10@10 corner:100@100.
     r2 := Rectangle origin:50@50 corner:150@75.
     r1 intersect:r2

o  merge: aRectangle
return a new rectangle covering both the receiver
and the argument, aRectangle.
That is the smallest rectangle which includes both.

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)

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

o  isFinite
return true, if all coordinates of the receiver are finite
I.e. neither nil, NaN and not +/-INF.

Compatibility with Point.

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.

Usage example(s): 

     |r|

     r := Rectangle origin:10@10 corner:50@50.
     r align:(r center) with:100@100.

o  normalized
return the same rectangle as myself
but ensuring that both width and height are positive
(i.e. possibly with exchanged corner points).
This may be needed by some graphics operations,
especially when drawing to a Windows or X-display

Usage example(s): 

     (Rectangle origin:50@10 corner:10@50)    
     (Rectangle origin:50@10 corner:10@50) normalized  
     (Rectangle origin:50@40 corner:10@10) normalized

o  roundedToNearestIntegerPoint
return a copy of the receiver, where all points are rounded to ly on the nearest integer coordinate

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

Usage example(s): 

     |r1 r2|

     r1 := Rectangle origin:10@10 corner:50@50.
     r2 := r1 scaledBy:2.
     r1

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  transformedBy: aMatrix
return a new rectangle (or polygon) which is me transformed by aMatrix

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

Usage example(s): 

     |r1 r2|

     r1 := Rectangle origin:10@10 corner:50@50.
     r2 := r1 translatedBy:10.
     r1

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.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 23 Nov 2024 10:16:16 GMT