"

 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.

"

"{ Package: 'stx:libview' }"

"{ NameSpace: Smalltalk }"

Object subclass:#GraphicsContext

	instanceVariableNames:'device paint bgPaint function font lineStyle lineWidth joinStyle

		capStyle mask maskOrigin transformation clipRect

		characterEncoding'

	classVariableNames:'White Black DefaultFont DrawingOnClosedDrawableSignal'

	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)

    [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 drawables 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

    [author:]

	Claus Gittinger

    [see also:]

	Color Font Form Image

	Geometric

	DeviceWorkstation

"

!

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 font's

    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:

                                                                        [exBegin]

        |v|

        v := View new.

        v openAndWait.

        v paint:(Color red).

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

                                                                        [exEnd]

    the same using opaque drawing:

                                                                        [exBegin]

        |v|

        v := View new.

        v openAndWait.

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

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

                                                                        [exEnd]

    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:

                                                                        [exBegin]

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

                                                                        [exEnd]

    changing the line-width:

                                                                        [exBegin]

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

                                                                        [exEnd]

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

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

                                                                        [exBegin]

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

                                                                        [exEnd]

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

                                                                        [exBegin]

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

                                                                        [exEnd]

    You can use a bitmap as a point color:

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

                                                                        [exBegin]

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

                                                                        [exEnd]

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

    coordinate system:

                                                                        [exBegin]

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

                                                                        [exEnd]

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

                                                                        [exBegin]

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

                                                                        [exEnd]

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

    displayRectangleXXX draws the outline, while fillRectangleXXX draws a

    filled one:

                                                                        [exBegin]

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

                                                                        [exEnd]

    polygons:

                                                                        [exBegin]

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

                                                                        [exEnd]

"

! !

!GraphicsContext class methodsFor:'initialization'!

initialize

    "setup some defaults - these are usually redefined

     during startup."

    DrawingOnClosedDrawableSignal isNil ifTrue:[

        DrawingOnClosedDrawableSignal := Signal new mayProceed:true.

        DrawingOnClosedDrawableSignal nameClass:self message:#drawingOnClosedDrawableSignal.

        DrawingOnClosedDrawableSignal notifierString:'drawing attempt on closed drawable'.

    ].

    White isNil ifTrue:[

        Color initialize.

        Display notNil ifTrue:[

            White := Display whiteColor.

            Black := Display blackColor.

        ] ifFalse:[

            White := Color white.

            Black := Color black.

        ].

        Font initialize.

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

        Display notNil ifTrue:[

            DefaultFont := DefaultFont onDevice:Display

        ]

    ]

    "Modified: / 29.1.1998 / 12:56:18 / cg"

! !

!GraphicsContext class methodsFor:'instance creation'!

new

    "return a new instance of myself. Redefined to initialize

     the new thingy"

    ^ self basicNew initialize

! !

!GraphicsContext class methodsFor:'Signal constants'!

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

    ^ DrawingOnClosedDrawableSignal

    "demonstration1: (error if closed by the windowManager):

     |v|

     v := StandardSystemView new openAndWait.

     [

        [true] whileTrue:[

            |x y|

            x := Random nextIntegerBetween:0 and:(v width).

            y := Random nextIntegerBetween:0 and:(v height).

            v displayString:'hello' x:x y:y.

            Delay waitForSeconds:0.5.

        ]

     ] fork.

    "

    "demonstration2: (no error if closed by the windowManager):

     |v|

     v := StandardSystemView new openAndWait.

     [

        v class drawingOnClosedDrawableSignal handle:[:ex |

            ex return

        ] do:[

            [true] whileTrue:[

                |x y|

                x := Random nextIntegerBetween:0 and:(v width).

                y := Random nextIntegerBetween:0 and:(v height).

                v displayString:'hello' x:x y:y.

                Delay waitForSeconds:0.5.

            ]

        ]

     ] fork.

    "

    "Created: / 29.1.1998 / 13:10:41 / cg"

    "Modified: / 29.1.1998 / 13:11:14 / cg"

! !

!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

!