Class: DeviceGraphicsContext

• Inheritance
• Description
• Related information
• Class protocol
  • cleanup
  • initialization
  • instance creation
• Instance protocol
  • Compatibility-ST80
  • Compatibility-VW
  • accessing
  • accessing-internals
  • bit blitting
  • copying
  • drawing
  • drawing in device coordinates
  • evaluating in another context
  • filling
  • initialization & release
  • private
  • queries

Inheritance:

   Object
   |
   +--GraphicsContext
      |
      +--DeviceGraphicsContext
         |
         +--GraphicsMedium

Package:

stx:libview

Category:

Graphics-Support

Version:

rev: 1.122 date: 2009/10/24 09:04:39

user: cg

file: DeviceGraphicsContext.st directory: libview

module: stx stc-classLibrary: libview

Author:

Claus Gittinger

Description:

I provide the common protocol for a graphicsContext which is associated with a particular
device (i.e. Bitmaps, Pixmaps, RootWindow and Windows in Xs world, but also postscript 
printer pages or fax pages).

My instance variables are mainly caching device-related stuff (such as font- and color-Ids)
to avoid needless message traffic. This class is abstract, no direct instances of it
exist in the system.
All real work is done by my device, which is accessed via the device instance variable.
Most drawing requests are simply forwarded to it, others are simulated by using more basic 
drawing functions (see GraphicsContext drawing vs. basic drawing category).

The added variables foreground/background are the drawing colors actually 
used; these are the real (i.e. non dithered) colors supported by the device.
Direct access to fg/bg is discouraged, since in the future, these may be 
totally replaced by paint/bgPaint 
(there are some operations and special cases, for which a direct access to 
 fg/bg makes sense)

[Instance variables:]

    drawableId      <SmallInteger>  my drawableId on the device (a device handle)

    gcId            <SmallInteger>  my gc's ID on the device (a device handle)

    deviceFont      <Font>          the actual font, currently set in the device

    foreground      <Color>         the device foreground color used for drawing

    background      <Color>         the device background color used for drawing

Related information:

    DeviceWorkstation
    Color
    Font
    Cursor

Class protocol:

 cleanupLobbyForChildrenOfViewWithDevice: aDevice id: anId

clean all the subcomponents of the handle with id anId.
This must be done on finalization, because descendent handles
are destroyed implicitly when a parent handle is destroyed.

 lowSpaceCleanup

 releaseResourcesOnDevice: aDevice

this is sent when a display connection is closed,
to release all cached bitmap/window objects from that device

 initialize

 new

create a new drawable - take the current display as
its device (for now, this may be changed until the view is
physically created)

 on: aDevice

create a new drawable on aDevice

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

 onDevice: aDevice

create a new drawable on aDevice

Instance protocol:

 key

 displayBackgroundIfNeededOn: aGraphicsContext

 inactiveForegroundColor

a dummy method to support VW widgets

 selectionBackgroundColor

a dummy method to support VW widgets

 selectionForegroundColor

a dummy method to support VW widgets

 separatorColor

a dummy method to support VW widgets

 at: aPoint

return the pixel at the coordinate given by aPoint

 at: aPoint put: aPixelColor

set a pixel

 atX: x y: y

return the pixel at the coordinate given by x/y

 atX: x y: y put: aPixelColor

set a pixel

 backgroundPaint: aColor

set the background-paint color; this is used in opaque-draw
operations

 basicFont

return the font for drawing

 basicFont: aFont

set the font for drawing if it has changed.
This is a low level entry, which is not to be redefined
(i.e. it must not imply a redraw operation)

 capStyle: aSymbol

set the style in which the endpoints of lines
are drawn - aSymbol may be #notLast, #butt, #round, #projecting

 clipByChildren

drawing shall be done into my view only (default)

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

 clipRect

return the clipping rectangle for drawing. If there is currently no clipRect,
a dummy is created.

 clippedByChildren: aBoolean

turn on/off drawing over children.
If on, a superview may draw 'over' its children.
If off (the default), drawing is 'under' its children.
Only useful for the rootView, to draw over any visible views.
(for example, when dragging a rubber-line)

 clippingRectangle: aRectangleOrNil

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

 colorAt: aPoint

return the color of the pixel at the coordinate given by x@y

 colorAtX: x y: y

return the color of the pixel at the coordinate given by aPoint

 container

return my container - for protocol compatibility

 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.
This may not be supported by all graphics devices.

 device

return the device, the receiver is associated with

 device: aDevice

set the device

 deviceClippingRectangle: aRectangleOrNil

set the clipping rectangle for drawing (in device coordinates);
a nil argument turns off clipping (i.e. whole view is drawable - incl. margins)

 font

return the font for drawing - here, a device font is returned if
the GC is realized.

 font: aFont

set the font for drawing if it has changed.
This should be redefined in some widget to perform an automatic
redraw. See also: #basicFont:

 function: aSymbol

set the drawing function if it has changed

 gcId

return the receivers graphic context id on the device

 graphicsDevice

return the device, the receiver is associated with.
Same as #device, for ST-80 compatibility.

 id

return the id of the dravable on the device

 joinStyle: aSymbol

set the style in which 2 lines are connected in polygons -
aSymbol may be #miter, #bevel, #round

 lineStyle: aSymbol

set the style in which lines are drawn -
aSymbol may be #solid, #dashed, #doubleDashed,
#dotted, #dashDot or #dashDotDot.

 lineWidth: aNumber

set the line width for drawing if it has changed

 mask: aForm

set the mask form for drawing

 maskOrigin: aPoint

set the origin of the mask-pattern

 maskOriginX: orgX y: orgY

set the origin of the pattern

 noClipByChildren

drawing shall also be done into subviews

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

 paint: aColor

set the drawing color, which may be a real color, a dithered one
or even an image.

 paint: fgColor on: bgColor

set the paint and background-paint color.
The bg-paint is used in opaque-draw operations

 paint: fgColor on: bgColor function: f

set paint, background-paint and function

 setGraphicsExposures: aBoolean

want to if aBoolean is true - or dont want to be notified
of graphics exposures

 background

return the current background drawing color.
OBSOLETE: use #paint: / #backgroundPaint: / #paint:on:

 background: aColor

set the internal background color for drawing - aColor must be a real color.
OBSOLETE: this method will vanish; use #paint: / #backgroundPaint: / #paint:on:

 foreground

return the current foreground drawing color.
OBSOLETE: use #paint: / #paint:on:

 foreground: aColor

set the internal foreground color for drawing - aColor must be a real color.
OBSOLETE: this method will vanish; use #paint: / #paint:on:

 foreground: fgColor background: bgColor

set both internal foreground and internal background colors
- these must be real colors.
OBSOLETE: this method will vanish; use #paint: / #paint:on:

 foreground: fgColor background: bgColor function: fun

set foreground, background colors and function.
OBSOLETE: this method will vanish; use #paint: / #paint:on:

 foreground: aColor function: fun

set the foreground color and function for drawing.
OBSOLETE: this method will vanish; use #paint: / #paint:on:

 copyBitsFrom: aByteArray bitsPerPixel: bpp depth: depth padding: pad width: srcW height: srcH x: srcX y: srcY toX: dstX y: dstY

copy bits from a smalltalk byteArray.
The bits found there are supposed to be in the devices native format (i.e.
translated to allocated color indices on pseudoColor devices and padded as required.
The byteOrder is MSB and will be converted as appropriate by the underlying devices
method to whatever the device needs.

 copyBitsFrom: aByteArray bitsPerPixel: bpp depth: depth width: srcW height: srcH x: srcX y: srcY toX: dstX y: dstY

copy bits from a smalltalk byteArray.
The bits found there are supposed to be in the devices native format (i.e.
translated to allocated color indices on pseudoColor devices and padded as required.
The byteOrder is MSB and will be converted as appropriate by the underlying devices
method to whatever the device needs.
Assumes the source bits are in ST/X's natural padding (i.e. 8-bit padded)

 copyFrom: aDrawable x: srcX y: srcY toX: dstX y: dstY width: w height: h

copy from aDrawable into the receiver;
the source may be the receiver as well - in this case its a scroll.
All coordinates are in device coordinates.

 copyFrom: aDrawable x: srcX y: srcY toX: dstX y: dstY width: w height: h async: async

copy from aDrawable into the receiver;
the source may be the receiver as well - in this case its a scroll.
All coordinates are in device coordinates.
If the receiver is a view AND async is true, the call returns immediately
- otherwise, it returns when the scroll operation is finished.
(not all devices care for this).
If the receiver is a pixmap, the call always returns immediately.

 copyPlaneFrom: aDrawable x: srcX y: srcY toX: dstX y: dstY width: w height: h

copy one plane from aDrawable into the receiver. 0's are drawn in
background, while 1's are drawn with foreground color.
The depth of aDrawable must (should) be 1.
The drawable must have been allocated on the same device.
All coordinates are in device coordinates.

 executor

I am abstract

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

 postCopy

this may not be enough to allow copying of views ...

 postDeepCopy

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

draw an arc; apply transformation if nonNil

 displayForm: formToDraw x: x y: y

draw a form or image non opaque;
if its a 1-plane bitmap, 1-bits are drawn in the
current paint-color, leaving pixels with 0-bits unchanged
(i.e. only 1-bits are drawn from the form).
If its a deep form (i.e. a pixmap) the current paint
settings are ignored and the form is drawn as-is.
Care must be taken, that the paint color is correctly allocated
(by sending #on: to the color) before doing so.
Using functions other than #copy only makes sense if you are
certain, that the colors are real colors (actually, only for
noColor or allColor).

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

draw a line (with current paint-color); apply transformation if nonNil

 displayOpaqueForm: formToDraw x: x y: y

draw a form or image opaque;
if its a 1-plane bitmap, 1-bits are drawn in the
current paint-color and 0-bits in the bgPaint color.
If its a deep form (i.e. a pixmap) the current paint/bgPaint
settings are ignored and the form drawn as-is.
In the 1-plane case, special care must be taken if paint and/or bgPaint
dithered colors or patterns, since are that the colors are correctly allocated
(by sending #on: to the colors) before doing so.
If there is a transformation, the image is scaled as appropiate.

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

draw a substring at the coordinate x/y - draw foreground pixels in
paint-color and background pixels in bgPaint-color.
If the transformation involves scaling,
the fonts point-size is scaled as appropriate.
Assuming that device can only draw in device colors, we have to handle
the case where paint and/or bgPaint are dithered colors

 displayOpaqueString: aString x: x y: y

draw a string at the coordinate x/y - draw foreground pixels in paint-color,
background pixels in bgPaint color. If the transformation involves scaling,
the fonts point-size is scaled as appropriate.
Assuming that device can only draw in device colors, we have to handle
the case where paint and/or bgPaint are dithered colors or images.

 displayPointX: x y: y

draw a point (with current paint-color); apply transformation if nonNil

 displayPolygon: aPolygon

draw (the outline of) a polygon (with current paint-color).
Apply transformation if nonNil

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

draw a rectangle (with current paint-color).
If transformation is nonNil, drawing is in logical coordinates.

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

draw a substring at the coordinate x/y -
draw foreground-pixels only (in current paint-color),
leaving background as-is. If the transformation involves scaling,
the fonts point-size is scaled as appropriate.

 displayString: aString from: index1Arg to: index2Arg x: x y: y opaque: opaqueArg

draw a substring at the coordinate x/y - draw foreground pixels in
paint-color and (if opaque is true), background pixels in bgPaint-color.
If the transformation involves scaling, the font's point-size is scaled as appropriate.
Assuming that device can only draw in device colors, we have to handle
the case where paint and/or bgPaint are dithered colors

 displayString: aString x: x y: y

draw a string at the coordinate x/y -
draw foreground-pixels only (in current paint-color),
leaving background as-is. If the transformation involves scaling,
the fonts point-size is scaled as appropriate.

 displayUnscaledForm: formToDraw x: x y: y

draw a form or image non opaque and unscaled;
if its a 1-plane bitmap, 1-bits are drawn in the
current paint-color, leaving pixels with 0-bits unchanged
(i.e. only 1-bits are drawn from the form).
If its a deep form (i.e. a pixmap) the current paint
settings are ignored and the form is drawn as-is.
Care must be taken, that the paint color is correctly allocated
(by sending #on: to the color) before doing so.
Using functions other than #copy only makes sense if you are
certain, that the colors are real colors (actually, only for
noColor or allColor).
The origins coordinate is transformed, but the image itself is unscaled.

 displayUnscaledOpaqueForm: formToDraw x: x y: y

draw a form or image opaque and unscaled;
if its a 1-plane bitmap, 1-bits are drawn in the
current paint-color, 0 bits in background color.
If its a deep form (i.e. a pixmap) the current paint
settings are ignored and the form is drawn as-is (opaque).
The origins coordinate is transformed, but the image itself is unscaled.

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

draw a substring at the transformed coordinate x/y but do not scale the font.
Draw foreground pixels in paint-color, background pixels in bgPaint color.

 displayUnscaledOpaqueString: aString x: x y: y

draw a string at the transformed coordinate x/y but do not scale the font.
Draw foreground pixels in paint-color, background pixels in bgPaint color.

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

draw a substring at the transformed coordinate x/y but do not scale the font.
draw foreground-pixels only (in current paint-color), leaving background as-is.

 displayUnscaledString: aString x: x y: y

draw a string at the transformed coordinate x/y but do not scale the font.
draw foreground-pixels only (in current paint-color), leaving background as-is.

 displayDeviceForm: aForm x: x y: y

draw a form or image non opaque (i.e. only foreground color is drawn);
If its a 1-plane bitmap, 1-bits are drawn in the
current paint-color, leaving pixels with 0-bits unchanged
(i.e. only 1-bits are drawn from the form).
If its a deep form (i.e. a pixmap) the current paint
settings are ignored and the form is drawn as-is;
however, the mask is applied if present.

The form should must have been allocated on the same device,
otherwise its converted here, which slows down the draw.
No transformation or scaling is done.
Care must be taken, that the paint color is correctly allocated
(by sending #on: to the color) before doing so.
Using functions other than #copy only makes sense if you are
certain, that the colors are real colors (actually, only for
noColor or allColor).

 displayDeviceLineFromX: x0 y: y0 toX: x1 y: y1

draw a line (with current paint-color) in device coordinate space.
This ignores any transformations. The coordinates must be integers.

 displayDeviceOpaqueForm: aForm x: x y: y

draw a form or image opaque (i.e. both fg and bg is drawn);
If its a 1-plane bitmap, 1-bits are drawn in the
current paint-color and 0-bits in the bgPaint color.
If its a deep form (i.e. a pixmap) the current paint/bgPaint
settings are ignored and the form drawn as-is.
Any mask is ignored.
In the 1-plane case, special care must be taken if paint and/or bgPaint
dithered colors or patterns, since are that the colors are correctly allocated (by sending #on:
to the colors) before doing so.
The form should have been allocated on the same device; otherwise,
its converted here, which slows down the draw.
Drawing is in device coordinates; no scaling is done.

 displayDeviceOpaqueString: aString from: index1 to: index2 in: font x: x y: y

draw a substring at the coordinate x/y - draw foreground pixels in
paint-color and background pixels in bgPaint-color.
Assuming that device can only draw in device colors, we have to handle
the case where paint and/or bgPaint are dithered colors.
No translation or scaling is done.

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

draw a substring at the coordinate x/y - draw foreground pixels in
paint-color and background pixels in bgPaint-color.
Assuming that device can only draw in device colors, we have to handle
the case where paint and/or bgPaint are dithered colors.
No translation or scaling is done.

 displayDeviceOpaqueString: aString x: x y: y

draw a string at the coordinate x/y - draw foreground pixels in
paint-color and background pixels in bgPaint-color.
No translation or scaling is done

 displayDeviceString: aString from: index1 to: index2 in: font x: x y: y

draw a substring at the coordinate x/y -
draw foreground-pixels only (in current paint-color), leaving background as-is.
No translation or scaling is done

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

draw a substring at the coordinate x/y -
draw foreground-pixels only (in current paint-color), leaving background as-is.
No translation or scaling is done

 displayDeviceString: aString x: x y: y

draw a string at the coordinate x/y -
draw foreground-pixels only (in current paint-color), leaving background as-is.
No translation or scaling is done

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

draw a filled rectangle in device coordinate space.
This ignores any transformations. The coordinates must be integers.

 reverseDo: aBlock

evaluate aBlock with foreground and background interchanged.
This can be reimplemented here in a faster way.

 withBackground: fgColor do: aBlock

evaluate aBlock with changed background.

 withForeground: fgColor background: bgColor do: aBlock

evaluate aBlock with changed foreground and background.

 withForeground: fgColor background: bgColor function: aFunction do: aBlock

evaluate aBlock with foreground, background and function

 withForeground: fgColor background: bgColor mask: aMask do: aBlock

evaluate aBlock with foreground, background and mask

 withForeground: fgColor do: aBlock

evaluate aBlock with changed foreground.

 withForeground: fgColor function: aFunction do: aBlock

evaluate aBlock with changed foreground and function.

 xoring: aBlock

evaluate aBlock with function xoring

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

draw a filled arc; apply transformation if nonNil

 fillPolygon: aPolygon

draw a filled polygon; apply transformation if nonNil

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

draw a filled rectangle; apply transformation if nonNil

 close

same as destroy - for ST-80 compatibility

 createGC

physically create a device GC.
Since we do not need a gc-object for the drawable until something is
really drawn, none is created up to the first draw.
This method is sent, when the first drawing happens

 destroy

I am abstract

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

 finalizationLobby

answer the registry used for finalization.
DeviceGraphicContexts have their own Registry

 initGC

since we do not need a gc-object for the drawable until something is
really drawn, none is created.
This method is sent, when the first drawing happens

 initialize

setup everything for later use; actual work is done in
initColors and initFont, which are usually redefined.

 prepareForReinit

kludge - clear drawableId and gcId
needed after snapin

 recreate

sent after a snapin or a migration, reinit draw stuff for new device

 reinitialize

 releaseGC

destroy the associated device GC resource - can be done to be nice to the
display if you know that you are done with a drawable.

 setDevice: aDevice id: aDrawbleId gcId: aGCId

private

 setGCForPaint

private; given a complex color (i.e. a pixmap or dithered color,
setup the GC to draw in this color.
A helper for paint and paint:on:

 setId: aDrawbleId

private

 horizontalIntegerPixelPerMillimeter

return the (rounded) number of pixels per millimeter

 horizontalPixelPerInch

return the number of horizontal pixels per inch of the display

 horizontalPixelPerMillimeter

return the number of pixels per millimeter (not rounded)

 horizontalPixelPerMillimeter: millis

return the number of pixels (not rounded) for millis millimeter

 resolution

return a point consisting of pixel-per-inch horizontally and vertically.

 verticalIntegerPixelPerMillimeter

return the (rounded) number of pixels per millimeter

 verticalPixelPerInch

return the number of vertical pixels per inch of the display

 verticalPixelPerMillimeter

return the number of pixels per millimeter (not rounded)

 verticalPixelPerMillimeter: millis

return the number of pixels (not rounded) for millis millimeter