eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Point':

Home

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

Class: Point


Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Point

Package:
stx:libbasic
Category:
Graphics-Geometry
Version:
rev: 1.82 date: 2018/03/20 10:46:00
user: stefan
file: Point.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


I represent a point in 2D space. Or I can be used to represent
an extent (of a rectangle, for example), in which case my x-coordinate
represents the width, and y-coordinate the height of something.

The x and y coordinates are usually numbers.

[Instance variables:]

    x              <Number>        the x-coordinate of myself
    y              <Number>        the y-coordinate of myself


Related information:

    Rectangle
    Polygon
    LayoutOrigin
    LayoutFrame
    AlignmentOrigin
    Layout
    View
    GraphicsContext

Class protocol:

constants
o  unity
return the neutral element for multiplication

o  zero
return the neutral element for addition

initialization
o  initialize

instance creation
o  decodeFromLiteralArray: anArray
create & return a new instance from information encoded in anArray.
Redefined for faster creation.
usage example(s):
     Point
	decodeFromLiteralArray:#(Point 10 10)

o  r: distance angle: angle
create and return a new point given polar coordinates.
The angle is given in degrees.

OBSOLETE STX interface, use #r:theta:

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

o  r: distance degrees: angle
create and return a new point given polar coordinates.
The angle is given in degrees.
Added for Squeak compatibility
usage example(s):
     Point r:100 degrees:90

o  r: distance theta: angleInRadians
create and return a new point given polar coordinates.
The angle is given in radians
usage example(s):
     Point r:100 theta:0
     Point r:100 theta:Float pi/2

o  readFrom: aStringOrStream onError: exceptionBlock
return the next Point from the (character-)stream aStream;
skipping all whitespace first; return the value of exceptionBlock,
if no point can be read.
usage example(s):
     Point readFrom:'1.234 @ 5.678'
     Point readFrom:'1'
     Point readFrom:'1' onError:[1@1]
     Point readFrom:'fooBar' onError:[0@0]

o  x: newX y: newY
create and return a new point with coordinates newX and newY

queries
o  isBuiltInClass
return true if this class is known by the run-time-system.
Here, true is returned for myself, false for subclasses.


Instance protocol:

Compatibility-Squeak
o  adhereTo: aRectangle
If the receiver lies outside aRectangle, return the nearest point on the boundary of the rectangle, otherwise return self.

o  area

o  asFloatPoint
Squeak mimicri return the receiver as Point - this is the receiver

o  asLargerPowerOfTwo

o  asSmallerPowerOfTwo

o  maxDimension
Answer the larger of the two dimensions.

accessing
o  x
return the x coordinate

o  x: newX
set the x coordinate to be the argument, aNumber.
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.

o  x: newX y: newY
set both the x and y coordinates.
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.

o  y
return the y coordinate

o  y: newY
set the y coordinate to be the argument, aNumber.
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.

coercing & converting
o  coerce: anObject
convert the argument aNumber into an instance of the receiver's class and return it.

o  generality
return the generality value - see ArithmeticValue>>retry:coercing:

comparing
o  < aPointOrNumber
return true if the receiver is above and to the left
of the argument, aPointOrNumber
usage example(s):
notice the funny result if one coordinate has the same value ...

     (3@4) < (4@4)
     (3@4) <= (4@4)
     (3@4) > (4@4)
     (4@4) >= (3@4)
     (4@4) > (3@4)

o  = aPointOrNumber
return true if the receiver represents the same point as
the argument, aPoint

o  > aPointOrNumber
return true if the receiver is below and to the right
of the argument, aPoint

o  hash
return a number for hashing

o  isLeftOrAbove: aPoint
return true if the receiver is above or to the left
of the argument, aPoint.
When sorting this enumerates points from left to right and top to bottom

o  max: aPoint
return the lower right corner of the rectangle uniquely defined by
the receiver and the argument, aPoint

o  min: aPoint
return the upper left corner of the rectangle uniquely defined by
the receiver and the argument, aPoint

converting
o  asComplex
Return a complex number whose real and imaginary components are the x and y
coordinates of the receiver.

o  asFractionalLayout
return a LayoutOrigin from the receiver,
treating the receiver coordinates as fractional parts
(i.e. relative to superview).
Notice: in 10.5.x LayoutOrigin is not yet officially released.
usage example(s):
     (0@0.5) asFractionalLayout
     (0@0.5) asLayout
     (0@10) asLayout
     (0@10) asOffsetLayout

o  asIntegerPoint

o  asLayout
return a LayoutOrigin from the receiver.
If the receiver coordinates are between 0 and 1, take
them as fractional parts (relative to superview).
Otherwise, treat them as absolute offsets.
Notice: in 10.5.x LayoutOrigin is not yet released.
usage example(s):
     (0@0.5) asFractionalLayout
     (0@0.5) asLayout
     (0@10) asLayout
     (0@10) asOffsetLayout

o  asOffsetLayout
return a LayoutOrigin from the receiver,
treating the receiver coordinates as absolute offsets.
Notice: in 10.5.x LayoutOrigin is not yet released.
usage example(s):
     (0@0.5) asFractionalLayout
     (0@0.5) asLayout
     (0@10) asLayout
     (0@10) asOffsetLayout

o  asPoint
return the receiver as Point - this is the receiver

o  asRectangle
return a zero-width rectangle consisting of origin
and corner being the receiver
usage example(s):
     (0@10) asRectangle

o  corner: aPoint
return a rectangle whose origin is self and corner is aPoint

o  extent: aPoint
return a rectangle whose origin is self and extent is aPoint

o  fromLiteralArrayEncoding: encoding
read my values from an encoding.
The encoding is supposed to be of the form: (Point xValue yValue)
usage example(s):
     Point new fromLiteralArrayEncoding:#(Point 10 20)

o  literalArrayEncoding
encode myself as an array, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.
The encoding is: (Point xValue yValue)
usage example(s):
     Point new fromLiteralArrayEncoding:#(Point 10 20)
     (10@20) literalArrayEncoding

o  rectangleRelativeTo: aRectangle preferred: prefRectHolder
compute a displayRectangle, treating the receiver like a
layoutorigin. This allows point to be used interchangable with
LayoutOrigins.
usage example(s):
     consider the case, where a view has a preferred extent of 50@50
     and is to be positioned in its superview which has size 100@100.
     For absolute origin:
	 (10@20) rectangleRelativeTo:(0@0 corner:100@100) preferred:(0@0 corner:50@50)

     for relative origin:
	 (0.5@0.5) rectangleRelativeTo:(0@0 corner:100@100) preferred:(0@0 corner:50@50)

destructive transformations
o  scaleBy: aScale
scale the receiver, by replacing coordinates by the product
of the receiver's coordinates and the scale (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.

o  translateBy: anOffset
translate the receiver, by replacing coordinates by the sum
of the receiver's coordinated and the scale (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.

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

interpolating
o  interpolateTo: end at: amountDone
Interpolate between the instance and end after the specified amount has been done (0 - 1).
usage example(s):
     (10@10) interpolateTo:(20@20) at:0.5
     (10@10) interpolateTo:(20@20) at:0.3
     (0@0) interpolateTo:(0@20) at:0.5

misc
o  abs
return a new point with my coordinates taken from the absolute values.

o  ceiling
return a new point with my coordinates truncated towards positive infinity.
Return the receiver if its coordinates are already integral.

o  floor
return a new point with my coordinates truncated towards negative infinity.
Return the receiver if its coordinates are already integral.

o  quadrant
return the number of the quadrant containing the receiver.
quadrants are named as follows:

^ 2 | 3
Y ------
1 | 0

X >

Q: what is to be returned if any coordinate is 0 ?

usage example(s):
     (1@1) quadrant
     (-1@1) quadrant
     (-1@-1) quadrant
     (1@-1) quadrant
     (0@0) quadrant

o  quadrantContaining: aPoint
return the number of the quadrant containing aPoint placing
the receiver at the origin, where the quadrants are numbered as
follows:
^ 2 | 3
Y ------
1 | 0

X >
This can be used for polygon operations (see Foley for examples).

usage example(s):
      (10 @ 10) quadrantContaining:(15 @ 15)
      (10 @ 10) quadrantContaining:(5 @ 5)
      (10 @ 10) quadrantContaining:(5 @ 15)
      (10 @ 10) quadrantContaining:(15 @ 5)

o  rounded
return a new point with my coordinates rounded to the next integer.
Return the receiver if its coordinates are already integral.
usage example(s):
     (1.5 @ 2.6) rounded
     (1 @ 2) rounded

o  truncateTo: aNumber
return a new point with my coordinates truncated towards zero to the next
multiple of aNumber.

o  truncated
return a new point with my coordinates truncated as integer.
Return the receiver if its coordinates are already integral.

point functions
o  crossProduct: aPoint
Return a number that is the cross product of the receiver and the
argument, aPoint.

o  dist: aPoint
return the distance between aPoint and the receiver.

o  dotProduct: aPoint
return a number that is the dot product of the receiver and
the argument, aPoint. That is, the two points are
multiplied and the coordinates of the result summed.

o  fourNeighbors
Modified (format): / 17-07-2017 / 14:20:40 / cg

o  grid: gridPoint
return a new point with coordinates grided (i.e. rounded to the
nearest point on the grid)

o  nearestIntegerPointOnLineFrom: point1 to: point2
return the closest integer point to the receiver on the line
determined by (point1, point2)--much faster than the more
accurate version if the receiver and arguments are integer points.
This method was found in the Manchester goody library.
usage example(s):
     120@40 nearestIntegerPointOnLineFrom: 30@120 to: 100@120
     0@0 nearestIntegerPointOnLineFrom: 10@10 to: 100@100

o  normalized
interpreting myself as the endPoint of a 0@0 based vector,
return the endPoint of the corresponding normalized vector.
(that is the endPoint of a vector with the same direction but length 1)
usage example(s):
     (10 @ 10) normalized
     (1 @ 1) normalized
     (10 @ 0) normalized
     (0 @ 10) normalized
     (-10 @ 0) normalized
     (0 @ -10) normalized
     (0 @ 0) normalized

o  transposed
return a new point with x and y coordinates exchanged

polar coordinates
o  angle
return the receiver's angle (in degrees) in a polar coordinate system.
(i.e. the angle of a vector from 0@0 to the receiver).
OBSOLETE ST/X interface; use theta for ST-80 compatibility.

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

o  degrees
return the receiver's angle (in degrees) in a polar coordinate system.
(i.e. the angle of a vector from 0@0 to the receiver).
The angle is counted counter-clock-wise, starting with 0 for a horizontal
line (i.e. 0@0 -> 100@0 has an angle of 0 and 0@0 -> 0@100 has an angle of 90).
Added for Squeak compatibility.
usage example(s):
     (1@1) degrees
     (2@1) degrees

o  r
return the receiver's radius in a polar coordinate system.
(i.e. the length of a vector from 0@0 to the receiver)
usage example(s):
     (1@1) r
     (2@1) r
     (2@0) r
     (0@2) r
     (-2@-2) r
     (2@2) r

o  theta
return the receiver's angle (in radians) in a polar coordinate system.
(i.e. the angle of a vector from 0@0 to the receiver)
usage example(s):
     (1@1) theta
     (2@1) theta
     (-2@1) theta
     (-2@-1) theta
     (0@-1) theta

printing & storing
o  printOn: aStream
append a printed representation of the receiver to aStream

o  storeOn: aStream
append my storeString to aStream

queries
o  isPoint
return true, if the receiver is some kind of point

testing
o  isFinite

o  isInfinite

transformations
o  * scale
Return a new Point that is the product of the
receiver and scale (which is a Point or Number).

o  + translation
Return a new Point that is the sum of the
receiver and translation (which is a Point or Number).

o  - translation
Return a new Point that is the difference of the
receiver and translation (which is a Point or Number).

o  / scale
Return a new Point that is the integer quotient of the
receiver and scale (which is a Point or Number).

o  // scale
Return a new Point that is the quotient of the
receiver and scale (which is a Point or Number).

o  negated
return a new point with my coordinates negated
i.e. the receiver mirrored at the origin
usage example(s):
	(1 @ 1) negated

o  reciprocal
return a new point where the coordinates are
the reciproce of mine

o  rotateBy: angle about: center
Return a new point, generated by rotating the receiver
counterClockWise by some angle in radians around the given center point.
Even though Point.theta is measured CW,
this rotates with the more conventional CCW interpretateion of angle.
usage example(s):
     (10@10) rotateBy:Float pi about:0@0
     (10@0) rotateBy:Float pi about:0@0

o  scaledBy: aScale
return a new Point that is the product of the
receiver and scale (which is a Point or Number).

o  translatedBy: anOffset
return a new Point that is the sum of the
receiver and scale (which is a Point or Number).



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Mon, 16 Jul 2018 14:19:32 GMT