"

 COPYRIGHT (c) 1992 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.

"

Object subclass:#GraphicsContext

	instanceVariableNames:'paint bgPaint function font lineStyle lineWidth joinStyle

		capStyle mask maskOrigin transformation'

	classVariableNames:'White Black DefaultFont'

	poolDictionaries:''

	category:'Graphics-Support'

!

!GraphicsContext class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1992 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.

"

!

documentation

"

    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)

"

!

examples

"

    drawing uses a paint color (which may be a dithered one) which is

    used like a `pen'. 

    A few drawing operations (opaqueForm and opaqueString drawing)

    use two colors, the paint and a backgroundPaint. For example,

    normal string drawing (#displayString:...) only draws the fonts

    on-pixels in the current paint, leaving off-pixels unchanged.

    In contrast, #drawOpaqueString:.. also changes these to the bgPaint color.

    The bgPaint can be changed with #backgroundPaint: or #paint:on: (which modifies both).

    lets try it in a view:

        |v|

        v := View new.

        v openAndWait.

        v paint:(Color red).

        v displayString:'hello' x:10 y:50

    the same using opaque drawing:

        |v|

        v := View new.

        v openAndWait.

        v paint:(Color red) on:(Color yellow).

        v displayOpaqueString:'hello' x:10 y:50

    Lines are drawn using the paint color (if solid) or both paint and bgPaint

    (dashed lines). The look of the line is controlled by joinStyle, capStyle,

    lineWidth and lineStyle.

    `lineStyle' can be one of #solid, #dashed, #doubleDashed

    where: #solid        - is for solid lines, drawn with the current paint color 

           #dashed       - for dashed lines, where only the on-dashes are drawn

                           with the current paint color

           #doubleDashed - dashed lines, draws on-dashes with paint color,

                           off-dashes with bgPaint

    for example:

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

    changing the line-width:

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

    with wide lines, the corners (of polygons or rectangles) can be

    one of the joinStyles: #miter, #bevel, #round. The default is #miter.

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

    the endPoints look is controlled with capStyle;

    possible values are: #notLast, #butt, #round, #projecting.

    The default is #butt. 

    #notLast is mostly useful when exoring (inverting): it will not draw the

    endPoint, to allow another line to join the previous line without inverting

    this point twice. (See the X manual for more info).

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

    You can use a bitmap as a point color:

    (this may be slow on some graphics devices, though)

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

    all views support a translation and scale, so you can draw in another

    coordinate system:

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

    if scaling is on, it is often useful to be able to draw individual

    things unscaled - this still translates the position, but

    uses the unscaled font (for example, to draw strings in a graphic):

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

    Filled objects are drawin using the #fillXXX methods; for example,

    displayRectangleXXX draws the outline, while fillRectangleXXX draws a

    filled one:

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

"

! !

!GraphicsContext class methodsFor:'initialization'!

initialize

    "setup some defaults - these are usually redefined

     during startup."

    White isNil ifTrue:[

	Color isNil ifTrue:[^ self].

	Display isNil ifTrue:[^ self].

	Color initialize.

	White := Color white on:Display.

	Black := Color black on:Display.

	Font initialize.

	DefaultFont := Font family:'courier' face:'medium' style:'roman' size:12

    ]

! !

!GraphicsContext class methodsFor:'instance creation'!

new

    "return a new instance of myself. Redefined to initialize

     the new thingy"

    ^ self basicNew initialize

! !

!GraphicsContext class methodsFor:'accessing defaults'!

defaultFont

    "get the default font used for drawing"

    DefaultFont isNil ifTrue:[

	DefaultFont := Font family:'courier' face:'medium' style:'roman' size:12

    ].

    ^ DefaultFont

!

defaultFont:aFont

    "set the default font used for drawing"

    DefaultFont := aFont

! !

!GraphicsContext class methodsFor:'constants'!

capButt

    "return a constant to specify butt cap"

    ^ #butt

!

capNotLast

    "return a constant to specify not-last cap"

    ^ #notLast

!

capProjecting

    "return a constant to specify projecting cap"

    ^ #projecting

!

capRound

    "return a constant to specify round cap"

    ^ #round

!

joinBevel

    "return a constant to specify bevel join"

    ^ #bevel

!

joinMiter

    "return a constant to specify miter join"

    ^ #miter

!

joinRound

    "return a constant to specify round join"

    ^ #round

! !

!GraphicsContext methodsFor:'ST-80 compatibility'!

findFont:aFontDescription

    "given a fontDescription, return a device font for it

     on my device."

    ^ aFontDescription on:self device

    "Modified: 22.4.1996 / 19:45:41 / cg"

!

widthOfString:aString

    "given a string, return its width in pixels if

     drawn on the receivers device."

    ^ (font on:self device) widthOf:aString

    "Modified: 22.4.1996 / 19:46:10 / cg"

!

widthOfString:aString from:start to:stop

    "given a string, return the width in pixels if

     a substring is drawn on the receivers device."

    ^ (font on:self device) widthOf:aString from:start to:stop

    "Modified: 22.4.1996 / 19:46:25 / cg"

! !

!GraphicsContext methodsFor:'ST-80 displaying'!

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

    "draw an arc around a point"

    self displayArcX:(origin x - radius)

		   y:(origin y - radius)

		   w:(radius * 2) 

		   h:(radius * 2)

		from:startAngle angle:angle

!

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

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

   ^ self displayArcX:(boundingBox left + origin x)

		    y:(boundingBox top + origin y)

		width:(boundingBox width)

	       height:(boundingBox height)

		 from:startAngle

		angle:sweepAngle

!

displayLineFrom:startPoint to:endPoint translateBy:anOffset

    "draw a line - ST-80 compatibility"

    self displayLineFrom:(startPoint + anOffset)

		      to:(endPoint + anOffset)

!

displayPolyline:aPolygon

    "draw a polygon - ST-80 compatibility"

    ^ self displayPolygon:aPolygon 

!

displayRectangularBorder:aRectangle at:aPoint

    "draw a rectangle - ST-80 compatibility"

    self displayRectangle:(aRectangle translateBy:aPoint)

!

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

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

   ^ self fillArcX:(boundingBox left + origin x)

		 y:(boundingBox top + origin y)

	     width:(boundingBox width)

	    height:(boundingBox height)

	      from:startAngle

	     angle:sweepAngle

! !

!GraphicsContext methodsFor:'accessing'!

backgroundPaint

    "return the background paint color.

     (used for opaqueForms and opaqueStrings)"

    ^ bgPaint

!

backgroundPaint:aColor

    "set the background painting color (which is used for

     opaqueForms and opaqueStrings). aColor can be a dithered one."

    ^ self subclassResponsibility

!

capStyle

    "return the current cap-style for line-drawing"

    ^ capStyle

!

capStyle:aStyleSymbol

    "set the cap-style for line-drawing;

     possible styles are: #notLast, #butt, #round, #projecting"

    ^ self subclassResponsibility

!

clipRect

    "return the drawing clip-rectangle"

    ^ self subclassResponsibility

!

clipRect:aRectangle

    "set the drawing clip-rectangle"

    ^ self subclassResponsibility

!

clippingBounds

    "return the drawing clip-rectangle - name alias ST-80 compatibility"