eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Rectangle':
Home

everywhere
www.exept.de
for:
[back]

Class: Rectangle

Inheritance:

   Object
   |
   +--Geometric
      |
      +--Rectangle
Package:
stx:libbasic
Category:
Graphics-Geometry-Objects
Version:
rev: 1.83 date: 2009/06/06 10:10:04
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.

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

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

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

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

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

o  extent
return the extent as a point

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

o  topRight
return the top-right point

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

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.

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

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.

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.

o  asPolygon
return a polygon from the receiver

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

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)

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

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

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)

o  translateBy: amount
translate (i.e. move) the receiver rectangle
by amount, a Point or Number.
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)

displaying
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

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

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.

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

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.

o  areasOutside: aRectangle
Answer an Array of Rectangles comprising the parts of the receiver not
intersecting aRectangle.

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

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.

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

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

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

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

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 6.1.1; WebServer 1.620 at exept:8081; Wed, 23 May 2012 20:54:42 GMT