eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'DeviceGraphicsContext':
Home

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

Class: DeviceGraphicsContext

Inheritance:

   Object
   |
   +--GraphicsContext
      |
      +--DeviceGraphicsContext
         |
         +--PrinterContext
         |
         +--X11GraphicsContext
Package:
stx:libview
Category:
Graphics-Support
Version:
rev: 1.216 date: 2019/08/10 07:27:52
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. 
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:

cleanup
o  lowSpaceCleanup
in low memory situations, give up cached forms

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

usage example(s): 

    'Warning: DeviceGraphicsContext (' print. self name print. ') should not be created with new' printNL.

o  on: aDevice
create a new drawable on aDevice

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

o  onDevice: aDevice
create a new drawable on aDevice

Instance protocol:

accessing
o  at: aPoint
return the pixel at the coordinate given by aPoint

o  at: aPoint put: aPixelColor
set a pixel

usage example(s): 

     Display rootView at:(0@0) put:(Color red).
     Display rootView at:(1@1) put:(Color red).
     Display rootView at:(2@2) put:(Color red).
     Display rootView at:(3@3) put:(Color red).
     Display rootView at:(4@4) put:(Color red).
     Display rootView at:(5@5) put:(Color red).

o  atX: x y: y
return the pixel at the coordinate given by x/y

o  atX: x y: y put: aPixelColor
set a pixel

o  backgroundPaint: aColor
set the background-paint color; this is used in opaque-draw
operations

o  basicFont: aFont
compatibility with GraphicsMedium

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

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

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

o  colorAt: aPoint
return the color of the pixel at the coordinate given by x@y

o  colorAtX: x y: y
return the color of the pixel at the coordinate given by aPoint

o  container
return my container - for protocol compatibility

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

o  device
return the device, the receiver is associated with

o  device: aDevice
set the device

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

o  deviceClippingBoundsOrNil
get the clipping rectangle for drawing (in device coordinates);
a nil clipping rectangle means: no clipping (i.e. whole view is drawable - incl. margins)

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

o  drawableId
return the id of the drawable on the device

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

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

o  function: functionSymbol
set the drawing function if it has changed.
functionSymbol 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

o  gcId
return the receiver's graphic context id on the device

o  id
return the id of the drawable on the device

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

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

o  lineWidth: aNumber
set the line width for drawing if it has changed

o  mask: aForm
set the mask form for drawing

o  maskOrigin: aPoint
set the origin of the mask-pattern

o  maskOriginX: orgX y: orgY
set the origin of the pattern

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

o  paint: fgColor on: bgColor
set the paint and background-paint color.
The bg-paint is used in opaque-draw operations

o  paint: fgColor on: bgColor function: f
set paint, background-paint and function

o  setClippingBounds: aRectangleOrNil
set the clipping rectangle for drawing (in logical coordinates).
Only set the variable, do not change the gc

o  setDeviceLineWidth: aNumber
set the untransformed line width.
This ignores any transformation and sets the lineWidth to the given number of
pixels.

o  setDeviceMaskOriginX: x y: y
set the origin of the mask-pattern

o  setGraphicsExposures: aBoolean
want to if aBoolean is true - or don't want to be notified
of graphics exposures

o  setPaint: fgColor on: bgColor
set the paint and background-paint color.
The bg-paint is used in opaque-draw operations.
Only set the variables, but do not send it to the device,
Used on initialization.

accessing-internals
o  background
return the current background drawing color.
OBSOLETE: use #paint: / #backgroundPaint: / #paint:on:

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

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

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

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

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

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

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

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

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

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

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

bit blitting
o  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.

o  copyFrom: aGC x: srcX y: srcY toX: dstX y: dstY width: w height: h depth: depth
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.

o  copyPlaneFrom: aGC 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.

copying-private
o  postCopy
this may not be enough to allow copying of views ...

usage example(s): 

super postCopy.

o  postDeepCopy

drawing
o  displayArcX: x y: y width: w height: h from: startAngle angle: angle
draw an arc; apply transformation if nonNil

o  displayForm: formOrImageToDraw x: x y: y
draw a form or image non opaque;
if it's 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 it's 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).

o  displayLineFrom: p0 to: p1
draw a line (with current paint-color); apply transformation if nonNil

o  displayLineFromX: x0 y: y0 toX: x1 y: y1
draw a line (with current paint-color); apply transformation if nonNil

o  displayOpaqueForm: formToDraw x: x y: y
draw a form or image opaque.
Somewhat backward compatible hacky:

if it's a 1-plane form,
1-bits are drawn in the current paint-color and
0-bits in the bgPaint color.

If it's a deep form (i.e. a pixmap) or an image,
the current paint/bgPaint settings are ignored and the image is 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.

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

o  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 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 or images.

o  displayPointX: x y: y
draw a point (with current paint-color); apply transformation if nonNil

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

o  displayRectangleX: x y: y width: w height: h
draw a rectangle (with current paint-color).
If transformation is nonNil, drawing is in logical coordinates.

o  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 font's point-size is scaled as appropriate.

o  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

o  displayString: aStringArg from: index1Arg to: index2Arg x: x y: y opaque: opaqueArg maxWidth: maxWidth
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.
maxWidth is the maximum width of the string in pixels or nil if unknown.

o  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 font's point-size is scaled as appropriate.

o  displayUnscaledForm: formToDraw x: x y: y
draw a form or image non opaque and unscaled;
if it's 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 it's 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.

o  displayUnscaledOpaqueForm: formToDraw x: x y: y
draw a form or image opaque and unscaled;
if it's a 1-plane bitmap, 1-bits are drawn in the
current paint-color, 0 bits in background color.
If it's 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.

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

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

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

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

drawing in device coordinates
o  displayDeviceForm: aFormOrImage x: x y: y
draw a form or image non opaque (i.e. only foreground color is drawn);
If it's 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 it's 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 have been allocated on the same device,
otherwise it's 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).

o  displayDeviceFormNoAlpha: aForm x: x y: y
draw a form or image non opaque (i.e. only foreground color is drawn);
If it's 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 it's 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 have been allocated on the same device,
otherwise it's 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).

o  displayDeviceFormWithAlpha: anImage x: x y: y
draw a form or image non opaque;
The current paint settings are ignored and the image is drawn as-is;
however, the alpha channel is taken care of.
This is a (slow) fallback helper for displays which do not support alpha blending

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

o  displayDeviceOpaqueForm: aFormOrImage x: x y: y
draw a form or image opaque (i.e. both fg and bg is drawn)
Somewhat backward compatible hacky:

if it's a 1-plane form,
1-bits are drawn in the current paint-color and
0-bits in the bgPaint color.

If it's a deep form (i.e. a pixmap) or an image,
the current paint/bgPaint settings are ignored and the image is 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.
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.

o  displayDeviceOpaqueString: aStringArg from: index1 to: index2 in: fontArg 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.

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

o  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

o  displayDeviceString: aStringArg from: index1 to: index2 in: fontArg 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

o  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

o  displayDeviceString: aString from: index1 to: index2 x: x y: y opaque: opaque
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

o  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

o  fillDevicePolygon: aCollectionOfPoints
draw a filled polygon in device coordinates

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

evaluating in another context
o  reverseDo: aBlock
evaluate aBlock with foreground and background interchanged.
This can be reimplemented here in a faster way.

o  withBackground: fgColor do: aBlock
evaluate aBlock with changed background.

o  withForeground: fgColor background: bgColor do: aBlock
evaluate aBlock with changed foreground and background.

o  withForeground: fgColor background: bgColor function: aFunction do: aBlock
evaluate aBlock with foreground, background and function

o  withForeground: fgColor background: bgColor mask: aMask do: aBlock
evaluate aBlock with foreground, background and mask

o  withForeground: fgColor do: aBlock
evaluate aBlock with changed foreground.

o  withForeground: fgColor function: aFunction do: aBlock
evaluate aBlock with changed foreground and function.

o  withPaint: aColor do: aBlock
evaluate aBlock with changed paint color.

o  xoring: aBlock
evaluate aBlock with function xoring

filling
o  clearDeviceRectangleX: x y: y width: w height: h
clear a rectangular area to background

o  clearRectangleX: left y: top width: w height: h
clear the rectangular area in the receiver to background

o  fillArcX: x y: y width: w height: h from: startAngle angle: angle
draw a filled arc; apply transformation if nonNil

o  fillPolygon: aCollectionOfPoints
draw a filled polygon; apply transformation if nonNil

o  fillRectangleX: x y: y width: w height: h
draw a filled rectangle; apply transformation if nonNil

finalization
o  executor

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

initialization & release
o  close
same as destroy - for ST-80 compatibility

o  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

o  destroy

o  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.
Answer the gcId.

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

o  prepareForReinit
kludge - clear drawableId and gcId
needed after snapin

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

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

private
o  setDevice: aDevice id: aDrawbleId gcId: aGCId
private

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

o  setId: aDrawableId
private

queries
o  horizontalIntegerPixelPerMillimeter
return the (rounded) number of pixels per millimeter

o  horizontalPixelPerInch
return the number of horizontal pixels per inch of the display

o  horizontalPixelPerMillimeter
return the number of pixels per millimeter (not rounded)

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

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

o  verticalIntegerPixelPerMillimeter
return the (rounded) number of pixels per millimeter

o  verticalPixelPerInch
return the number of vertical pixels per inch of the display

o  verticalPixelPerMillimeter
return the number of pixels per millimeter (not rounded)

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

testing
o  isPixmap

o  isWindow

view creation
o  createBitmapFromArray: data width: width height: height
create a bitmap from data and set the drawableId

o  createPixmapWidth: w height: h depth: d
create a pixmap and set the drawableId

o  createRootWindowFor: aView

o  createWindowFor: aView type: typeSymbol origin: org extent: ext minExtent: minE maxExtent: maxE borderWidth: bw subViewOf: sv style: styleSymbol inputOnly: inp label: label owner: owner icon: icn iconMask: icnM iconView: icnV
create a window and set the drawableId

view properties
o  backingStore: how
turn on/off backingStore (saving my pixels)
how may true/false, but also #always, #whenMapped or #never.

o  bitGravity: gravity
set the bitGravity
- that's the direction where the contents will move when the view is resized.

o  saveUnder: aBoolean
turn on/off saveUnder (saving pixels under myself)
- used for temporary views (i.e. PopUps and ModalBoxes)

o  setCursorId: id

o  setWindowPid: pid
Sets the _NET_WM_PID property for the window.
This may be used by the window manager to group windows.
If anIntegerOrNil is nil, then PID of currently running
Smalltalk is used

o  viewGravity: gravity
set the viewGravity
- that's the direction where the view will move when the superView is resized.

o  windowBorderShape: aForm
set the windows border shape

o  windowClass: windowClassNameString name: nameString
define class and name of a window.
This may be used by the window manager to
select client specific resources.

o  windowName: aString
define the view's name in the window's title area.

o  windowShape: aForm
set the windows shape.
Returns false, if the display does not support the
X shape extension.

Private classes:

    DevicePixmapGCHandle
    DeviceWindowGCHandle

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Sat, 20 Apr 2024 09:52:17 GMT