Class: GraphicsContext

• Inheritance
• Description
• Related information
• Class protocol
  • Signal constants
  • accessing-defaults
  • constants
  • initialization
  • instance creation
  • queries
• Instance protocol
  • Compatibility-ST80
  • Compatibility-Squeak
  • accessing
  • accessing-transformation
  • basic drawing
  • basic filling
  • drawing
  • drawing in device coordinates
  • edge drawing
  • filling
  • initialization
  • misc
  • printing & storing
  • queries
• Examples

Inheritance:

   Object
   |
   +--GraphicsContext
      |
      +--DeviceGraphicsContext

Package:

stx:libview

Category:

Graphics-Support

Version:

rev: 1.159 date: 2019/07/27 10:43:42

user: cg

file: GraphicsContext.st directory: libview

module: stx stc-classLibrary: libview

Author:

Claus Gittinger

Description:

this is an abstract superclass for all kinds of graphic drawables -
both windows and printed pages (i.e. printers) are inheriting from
this class (even drawables not at all associated with any device would do so).

Drawing is done in paint/bgPaint colors, which can be true colors (i.e.
directly supported by the underlying hardware) or simulated colors
(i.e. dithered colors or images).
The paint/bgPaint instance variables are set to the logical colors,
device specific drawable may like to keep actual colors in addition.

The transformation instance variable is typically nil, for a 1-to-1
coordinate mapping (i.e. x/y coordinates are pixels in the drawable).
If nonNil, the transformation must be an  instance of WindowingTransformation
and offers both a scale-factor and a translation.
Also, drawing in metric- or inch-units can be done using transformations.
(see instance creation methods of WindowingTransformation, and examples
 in 'doc/coding').

All drawing is defined upon a few basic drawing methods, which must be
implemented by subclasses (some subclasses also redefine the others for
more performance)

[Instance variables:]

    paint           <Color>         the paint used for drawing
    bgPaint         <Color>         the background used for drawing texts and bitmaps
    function        <Symbol>        the drawing function (i.e. #copy, #or, #xor ...)
                                    - not all Drawables support every function
                                    (i.e. paper only allows #copy)
    font            <Font>          the current font to be used for drawing
    lineStyle       <Symbol>        the lineStyle (i.e. #solid, #dashed, #doubleDashed)
    lineWidth       <SmallInteger>  the lineWidth (device dependent, usually pixels)
    joinStyle       <Symbol>        the style in which lines (in polygons)
                                    are joined (i.e. #miter, #bevel, #round)
    capStyle        <Symbol>        the style in which the last point of a line is drawn
                                    (i.e. #notLast, #butt, #round, #projecting)
    mask            <Form>          a mask used for drawing
                                    - not all Drawables support it
    maskOrigin      <Point>         the origin of the mask relative to
                                    the drawable's origin
    transformation
                    <WindowingTransformation>
                                    controls scale & translation of nonNil

    clipRect        <Rectangle>     a clip rectangle (device dep. usually pixels or inches)
                                    or nil.

[Class variables:[

    White           <Color>         cached white color - its needed so often
    Black           <Color>         cached black color - its needed so often

    DefaultFont     <Font>          default font to use

Related information:

    Color
    Font
    Form
    Image
    Geometric
    DeviceWorkstation

Class protocol:

 drawingOnClosedDrawableSignal

return the signal which is raised, if drawing is attempted
on a closed drawable.
This is especially useful, if a forked thread animates
a view in the background, and is not properly synchronized
with the window thread - i.e. the window gets closed by the user,
and the background process continues to draw.
In this case, the background thread should handle this signal
and terminate itself in the handler.

 defaultFont

get the default font used for drawing

 defaultFont: aFont

set the default font used for drawing

 capButt

return a constant to specify butt cap

 capNotLast

return a constant to specify not-last cap

 capProjecting

return a constant to specify projecting cap

 capRound

return a constant to specify round cap

 joinBevel

return a constant to specify bevel join

 joinMiter

return a constant to specify miter join

 joinRound

return a constant to specify round join

 initialize

setup some defaults - these are usually redefined
during startup.

 new

return a new instance of myself. Redefined to initialize
the new thingy

 isAbstract

Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

Instance protocol:

 displayArc: origin radius: radius from: startAngle angle: angle

draw an arc around a point

 displayArcBoundedBy: boundingBox startAngle: startAngle sweepAngle: sweepAngle

draw an arc/circle/ellipse - ST-80 compatibility

 displayArcBoundedBy: boundingBox startAngle: startAngle sweepAngle: sweepAngle at: origin

draw an arc/circle/ellipse - ST-80 compatibility

 displayLineFrom: startPoint to: endPoint translateBy: anOffset

draw a line - ST-80 compatibility

 displayPolyline: aPolygon

draw a polygon - ST-80 compatibility

 displayRectangularBorder: aRectangle

draw a rectangle - ST-80 compatibility

 displayRectangularBorder: aRectangle at: aPoint

draw a rectangle - ST-80 compatibility

 displayWedgeBoundedBy: boundingBox startAngle: startAngle sweepAngle: sweepAngle

fill an arc/circle/ellipse - ST-80 compatibility

 displayWedgeBoundedBy: boundingBox startAngle: startAngle sweepAngle: sweepAngle at: origin

fill an arc/circle/ellipse - ST-80 compatibility

 findFont: aFontDescription

given a fontDescription, return a device font for it
on my device.

 phase

return the origin within the mask (used to draw with patterns).
This is an alias for ST/X's #maskOrigin

 phase: aPoint

set the origin within the mask (used to draw with patterns).
This is an alias for ST/X's #maskOrigin:

 setDevicePattern: aColorOrMask

ST/X can paint in any color or image

 tilePhase

return the origin within the mask (used to draw with patterns).
This is an alias for ST/X's #maskOrigin

 tilePhase: aPoint

set the origin within the mask (used to draw with patterns).
This is an alias for ST/X's #maskOrigin

 widthOfString: aString

given a string, return its width in pixels if
drawn on the receiver's device.

 widthOfString: aString from: start to: stop

given a string, return the width in pixels if
a substring is drawn on the receiver's device.

 fill: aRectangle fillColor: aColor

fill a rectangle with the given color color

 fillRectangle: aRectangle color: aColor

fill a rectangle with the given paint color

 backgroundPaint

return the background paint color.
(used for opaqueForms and opaqueStrings)

 backgroundPaint: aColor

set the background painting color (which is used for
opaqueForms and opaqueStrings). aColor can be a dithered one.

 basicFont

return the font for drawing

 blackColor

return the black color on this device.
This is the same as 'Color black onDevice:self device', but much faster.

 capStyle

return the current cap-style for line-drawing.
possible styles are: #notLast, #butt, #round, #projecting

 capStyle: aStyleSymbol

set the cap-style for line-drawing;
possible styles are: #notLast, #butt, #round, #projecting

 characterEncoding

returns a symbol describing how the contents is encoded internally.
This is now obsolete, as we are always using unicode internally.
(encoding is something like #'iso8859-5' #euc, #sjis, #jis7, #gb, #big5 or #ksc)

 characterEncoding: encodingArg

define how the contents is encoded internally.
This should normally never be required, as ST/X now assumes
unicode (of which iso8859-1 is a subset) encoding.
The possibility to change the characterEncoding is provided as
a backward compatibility hook for programs which want to use
another encoding internally.
One such view is the CharacterSetView,
which wants to show character as they are actually present in a font.

 clippingBounds

return the clip-rectangle for drawing (in logical coordinates).
If there is currently no active clip, return the underlying
medium (i.e. device) bounds. Added for ST-80 compatibility.

 clippingBounds: aRectangleOrNil

set the clipping rectangle for drawing (in logical coordinates);
a nil argument turn off clipping (i.e. whole view is drawable)

 clippingBoundsOrNil

return the clipping bounds (a Rectangle) for drawing in logical coordinates, nil if there is none.

 dashStyle: aDashList offset: dashOffset

define dashes. Each element of the dashList specifies the length
of a corresponding dash. For example, setting it to [4 4]
defines 4on-4off dashing;
Setting it to [1 2 4 2] defines 1on-2off-4on-2off dashes.
The dashOffset specifies where in the dashList the dashing starts.
Ignored here - this may not be supported by all graphics devices.

 font

return the current drawing font

 font: aFont

set the drawing font

** This method raises an error - it must be redefined in concrete classes **

 function

return the current drawing function

 function: aFunctionSymbol

set the (bitblt) drawing function.
The argument is one of:
#copy,#copyInverted,#xor,#and,#andReverse
#andInverted,#or,#orReverse,#orInverted
#invert,#clear,#set,#noop,#equiv,#nand.
Notice: not all graphicMedia support all functions

** This method raises an error - it must be redefined in concrete classes **

 graphicsContext

for ST-80 compatibility

 graphicsDevice

same as #device, for ST-80 compatibility

 joinStyle

return the current join-style for polygon-drawing.
possible styles are: #miter, #bevel, #round

 joinStyle: aStyleSymbol

set the join-style of lines in polygon-drawing;
possible styles are: #miter, #bevel, #round

 lineStyle

return the current line-drawing-style.
possible styles are: #solid, #dashed, #doubleDashed,
#dotted, #dashDot or #dashDotDot.

 lineStyle: aStyleSymbol

set the line-drawing-style;
possible styles are: #solid, #dashed, #doubleDashed,
#dotted, #dashDot or #dashDotDot.

 lineWidth

return the current drawing linewidth

 lineWidth: aNumber

set the line drawing width in pixels

 mask

return the current drawing mask

 mask: aForm

set the drawing mask

** This method raises an error - it must be redefined in concrete classes **

 maskOrigin

return the origin within the mask (used to draw with patterns).
Should be redefined in classes which support it.
This is an alias for ST-80's #phase

 maskOrigin: aPoint

set the origin within the mask (used to draw with patterns).
Should be redefined in classes which support it.
This is an alias for ST-80's #phase:

 maskOriginX: x y: y

set the origin within the mask (used to draw with patterns).
Should be redefined in classes which support it.
This is an alias for ST-80's #phase:

 medium

return the destination medium i.e. the underlying graphics device

 paint

return the current paint drawing color

 paint: aColor

set the drawing painting color, aColor can be a dithered one

 paint: fgColor on: bgColor

set the paint and backgroundPaint, used for text and bitmaps.
Both colors may be dithered colors

 setDevice: aDevice

 viewOrigin

return the drawable's visible origin (for scrolling)

 whiteColor

return the white color on this device.
This is the same as 'Color white onDevice:self device', but much faster.

 scale

return the scale factor (as point) of the transformation

 scale: aPoint

set the scale factor of the transformation

 scale: scale translation: aPoint

 transformation

return the transformation

 transformation: aTransformation

set the transformation

 translateBy: aPoint

add to the translation offset of the transformation

 translation

return the translation factor (as point) of the transformation

 translation: aPoint

set the translation offset of the transformation

 displayArcX: x y: y width: width height: height from: startAngle angle: angle

draw an arc in a box
- this could be recoded to draw using displayLine

** This method raises an error - it must be redefined in concrete classes **

 displayDottedRectangleX: x y: y width: w height: h

draw a dotted-line rectangle
A general implementation is found here; deviceGC's
may reimplement this if directly supported by the device

 displayHorizontalWavelineFromX: x0 y: y0 toX: x1

draw a horizontal wave-line from x0/y0 to x1/y0

 displayLineFromX: x0 y: y0 toX: x1 y: y1

draw a line from x0/y0 to x1/y1

** This method raises an error - it must be redefined in concrete classes **

 displayOpaqueForm: aForm x: x y: y

draw a form at x/y; if the form has depth 1, 1's in the form are
drawn in current fg, 0's in current bg color.
If the form has depth ~~ 1, it is copied as is onto the receiver

** This method raises an error - it must be redefined in concrete classes **

 displayOpaqueString: aString from: index1 to: index2 x: x y: y

draw part of a string with both fg and bg at x/y in current font

** This method raises an error - it must be redefined in concrete classes **

 displayOpaqueString: aString from: index1 to: index2 x: x y: y maxWidth: maxWidth

draw part of a string with both fg and bg at x/y in current font

** This method raises an error - it must be redefined in concrete classes **

 displayOpaqueString: aString from: index1 to: index2 x: x y: y maxWitdh: maxWidth

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

 displayPolygon: aPolygon

draw a polygon
- this could be recoded to draw using displayLine

** This method raises an error - it must be redefined in concrete classes **

 displayRectangleX: x y: y width: w height: h

draw a rectangle
- this could be recoded to draw using displayLine

** This method raises an error - it must be redefined in concrete classes **

 displayString: aString from: index1 to: index2 x: x y: y

draw part of a string with fg at x/y in current font

** This method raises an error - it must be redefined in concrete classes **

 displayString: aString from: index1 to: index2 x: x y: y opaque: opaque

draw part of a string with both fg and bg at x/y in current font

 fillArcX: x y: y width: w height: h from: start angle: angle

fill an arc with current paint color

** This method raises an error - it must be redefined in concrete classes **

 fillPolygon: points

fill a polygon with current paint color

** This method raises an error - it must be redefined in concrete classes **

 fillRectangleX: x y: y width: w height: h

fill a rectangle with current paint color

** This method raises an error - it must be redefined in concrete classes **

 fillRectangleX: x y: y width: w height: h color: aColor

fill a rectangle with given color

 display: someObject at: aPoint

draw someObject - this must understand the #displayOn:at: message

 displayArcIn: aRectangle from: startAngle angle: angle

draw an arc in a box

 displayArcOrigin: origin corner: corner from: startAngle angle: angle

draw an arc in a box

 displayCircle: aPoint radius: r

draw a circle around a center point

 displayCircleIn: aRectangle

draw a circle in a box

 displayCircleX: x y: y radius: r

draw a circle around a center point

 displayForm: aFormOrImage

draw a form (or image) at the origin

 displayForm: aFormOrImage at: aPoint

draw a form (or image)

 displayForm: aFormOrImage x: x y: y

draw a form (or image) at x/y;
if the form has depth 1, 1's in the form are
drawn in current paint color, 0's are ignored.
If the form has depth ~~ 1, the current fg color setting is ignored.

 displayForm: aFormOrImage x: x y: y opaque: opaque

draw a form (or image) at x/y;
if the form has depth 1, 1's in the form are
drawn in current paint color, 0's are ignored.
If the form has depth ~~ 1, the current fg color setting is ignored.

 displayImage: aFormOrImage

draw an image (or form).
Provided for ST-80 compatibilty;
in ST/X, images are also handled by #displayForm:

 displayImage: aFormOrImage at: aPoint

draw an image (or form).
Provided for ST-80 compatibilty;
in ST/X, images are also handled by #displayForm:

 displayImage: aFormOrImage x: x y: y

draw an image (or form).
Provided for ST-80 compatibilty;
in ST/X, images are also handled by #displayForm:

 displayLineFrom: point1 to: point2

draw a line

 displayLineFromX: xStart y: yStart toX: xEnd y: yEnd brush: aForm

draw a line using a brush.
Here, a slow fallback is used, drawing into a
temporary bitmap first, which is then displayed

 displayOpaqueString: aString from: start to: stop at: aPoint

draw part of a string - drawing both fg and bg

 displayOpaqueString: aString x: x y: y

draw a string with both fg and bg

 displayOpaqueString: aString x: x y: y angle: drawAngle

draw a string along a (possibly non-horizontal) line,
drawing both fg and bg pixels.
The angle is in degrees, clock-wise, starting with 0 for
a horizontal draw.
Drawing is done by first drawing the string into a temporary bitmap,
which is rotated and finally drawn as usual.
NOTICE: due to the rotation of the temporary bitmap, this is a slow
operation - not to be used with cillions of strings ...

 displayPoint: aPoint

draw a pixel

 displayPointX: x y: y

draw a point at x/y

 displayRectangle: aRectangle

draw a rectangle

 displayRectangleOrigin: origin corner: corner

draw a rectangle

 displayRectangleOrigin: origin extent: extent

draw a rectangle

 displayRoundRectangleX: left y: top width: width height: height wCorner: wCorn hCorner: hCorn

BIG KLUDGE WARNING HERE: the code below looks "good" on windows displays;

 displayString: aString at: aPoint

draw a string - drawing fg only

 displayString: aString centeredAt: aPoint

draw a string - drawing fg only

 displayString: aString centeredAtX: x y: y

draw a string - drawing fg only

 displayString: aString from: start to: stop at: aPoint

draw part of a string - drawing fg only

 displayString: aString x: x y: y

draw a string - drawing fg only

 displayString: aString x: x y: y angle: drawAngle

draw a string along a (possibly non-horizontal) line - drawing fg only.
The angle is in degrees, clock-wise, starting with 0 for
a horizontal draw.
Drawing is done by first drawing the string into a temporary bitmap,
which is rotated and finally drawn as usual.
NOTICE: due to the rotation of the temporary bitmap, this is a slow
operation - not to be used with cillions of strings ...

 displayString: aString x: x y: y angle: drawAngle opaque: opaque

common code to draw a string along a (possibly non-horizontal) line.
The angle is in degrees, clock-wise, starting with 0 for
a horizontal draw.
Drawing is done by first drawing the string into a temporary bitmap,
which is rotated and finally drawn as usual.
NOTICE: due to the rotation of the temporary bitmap, this is a slow
operation - not to be used with cillions of strings ...
CAVEAT: if the string is not a real string (i.e. a LabelAndIcon),
this can (currently) only be done opaque

 displayDeviceLineFromX: x1 y: y1 toX: x2 y: y2

draw a line in device coordinates

 displayDeviceRectangleX: x y: y width: w height: h

draw a rectangle in device coordinates

 fillDeviceRectangleX: x y: y width: w height: h

fill a rectangle with current paint color (device coordinates)

 drawEdgesForX: x y: y width: w height: h level: l

draw 3D edges into a rectangle

 drawEdgesForX: x y: y width: w height: h level: lvl shadow: shadowColor light: lightColor halfShadow: halfShadowColor halfLight: halfLightColor style: edgeStyle

draw 3D edges into a rectangle

 edgeDrawn: whichOne

a redefinable hook for views which like to draw
over their edges (some checkToggles do).
Nothing done here.

 fillArc: origin radius: r from: startAngle angle: angle

draw a filled arc around a point

 fillArcIn: aRectangle from: startAngle angle: angle

draw a filled arc in a box

 fillArcOrigin: origin corner: corner from: startAngle angle: angle

draw a filled arc in a box

 fillArcX: x y: y width: w height: h from: startAngle to: endAngle

draw a filled arc in a box, given startAngle and endAngle.

 fillCircle: aPoint radius: aNumber

draw a filled circle around aPoint

 fillCircleIn: aRectangle

draw a filled circle in a box

 fillCircleX: x y: y radius: r

draw a filled circle around x@y

 fillRectangle: aRectangle

fill a rectangle with current paint color

 fillRectangleLeft: left top: top right: cornerX bottom: cornerY

draw a filled rectangle.
Notice: the cornerPoint itself is NOT included

 fillRectangleOrigin: origin corner: corner

draw a filled rectangle.
Notice: the cornerPoint itself is NOT included

 fillRectangleOrigin: origin extent: extent

draw a filled rectangle.
Notice: the cornerPoint itself is NOT included

 fillRectangleOrigin: origin width: w height: h

draw a filled rectangle.
Notice: the cornerPoint itself is NOT included

 fillRoundRectangleX: left y: top width: width height: height wCorner: wCorn hCorner: hCorn

bug workaround

 initialize

set up some useful default values

 clippedTo: aRectangle do: aBlock

 flush

send all buffered drawing to the device.

 sync

send all buffered drawing to the device and wait until the device responds

 storeOn: aStream

blocked: ascii storeString not possible (recursive - view - subviews - container)

 fontAscent

answer the ascent of the current font on the current device

Examples:

    |v|

    v := View new.
    v openAndWait.

    v paint:(Color red).
    v displayString:'hello' x:10 y:50

    |v|

    v := View new.
    v openAndWait.

    v paint:(Color red) on:(Color yellow).
    v displayOpaqueString:'hello' x:10 y:50

    |v|

    v := View new.
    v openAndWait.

    v paint:(Color red) on:(Color blue).
    v displayLineFrom:(10@10) to:(90@90).

    v lineStyle:#dashed.
    v displayLineFrom:(90@10) to:(10@90).

    v lineStyle:#doubleDashed.
    v displayRectangle:((5@5) corner:(95@95)).

    |v|

    v := View new.
    v openAndWait.

    v paint:(Color red).
    v displayLineFrom:(20@20) to:(80@80).

    v lineWidth:5.
    v displayLineFrom:(80@20) to:(20@80).

    v lineWidth:8.
    v displayRectangle:((5@5) corner:(95@95)).

    |v|

    v := View new extent:200@200.
    v openAndWait.

    v lineWidth:15.
    v paint:(Color red).

    v displayRectangle:((65@65) corner:(135@135)).

    v joinStyle:#bevel.
    v displayRectangle:((45@45) corner:(155@155)).

    v joinStyle:#round.
    v displayRectangle:((25@25) corner:(175@175)).

    |v|

    v := View new extent:200@200.
    v openAndWait.

    v lineWidth:15.
    v paint:(Color red).

    v displayLineFrom:(25@25) to:(175@25).

    v capStyle:#round.
    v displayLineFrom:(25@55) to:(175@55).

    v capStyle:#projecting.
    v displayLineFrom:(25@85) to:(175@85).

    |v|

    v := View new extent:200@200.
    v openAndWait.

    v lineWidth:15.
    v paint:(Image fromFile:'granite_small.tiff').

    v displayLineFrom:(25@25) to:(175@25).

    v capStyle:#round.
    v displayLineFrom:(25@55) to:(175@55).

    v capStyle:#projecting.
    v displayLineFrom:(25@85) to:(175@85).

    |v|

    v := View new extent:200@200.
    v openAndWait.

    v displayForm:(Image fromFile:'SBrowser.xbm') x:10 y:10.

    v scale:(2@2); translation:50.
    v displayForm:(Image fromFile:'SBrowser.xbm') x:10 y:10.

    v scale:(0.5@0.5); translation:0.
    v displayForm:(Image fromFile:'SBrowser.xbm') x:10 y:10.

    |v|

    v := View new extent:200@200.
    v openAndWait.

    v displayForm:(Image fromFile:'SBrowser.xbm') x:10 y:10.
    v displayString:'hello' x:50 y:40.

    v scale:(2@4).
    v displayForm:(Image fromFile:'SBrowser.xbm') x:10 y:10.
    v displayUnscaledString:'hello' x:50 y:40.

    |v|

    v := View new extent:200@200.
    v openAndWait.

    v displayArcIn:(20@20 corner:50@50) from:0 angle:180.
    v paint:Color yellow.
    v fillArcIn:(120@120 corner:150@150) from:0 angle:180.

    v paint:Color red.
    v displayCircle:150@50 radius:30.
    v paint:Color blue.
    v fillCircle:50@150 radius:30.

    |v poly1 poly2|

    poly1 := OrderedCollection new.
    poly1 add:(10 @ 10).
    poly1 add:(100 @ 50).
    poly1 add:(50 @ 50).
    poly1 add:(20 @ 100).
    poly1 add:(10 @ 100).

    poly2 := poly1 copy.
    poly2 add:(poly2 first).

    v := View new extent:200@200.
    v openAndWait.

    v scale:2.
    v paint:Color red.
    v fillPolygon:poly1.

    v scale:1.
    v paint:Color blue.
    v displayPolygon:poly2.

    v scale:0.5.
    v paint:Color yellow.
    v fillPolygon:poly1.