Class: Form

• Inheritance
• Description
• Class protocol
  • Compatibility-ST80
  • Compatibility-Squeak
  • accessing private classes
  • cleanup
  • file search
  • initialization
  • instance creation
  • obsolete instance creation
  • obsolete patterns
• Instance protocol
  • Compatibility-ST80
  • Compatibility-Squeak
  • accessing
  • comanche processing
  • converting
  • copying-private
  • editing
  • getting a device form
  • image manipulations
  • initialization
  • misc ui support
  • printing & storing
  • private
  • queries
• Private classes

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--Form
         |
         +--ColorForm
         |
         +--Form::ImageForm
         |
         +--Pixmap

Package:

stx:libview

Category:

Compatibility-ST80-Graphics-Display Objects

Version:

rev: 1.181 date: 2023/06/26 15:36:00

user: cg

file: Form.st directory: libview

module: stx stc-classLibrary: libview

Description:

NOTICE:
    Not for public use.

    the Form class is a historic leftover and now only used for real
    device forms (i.e. on devices which support downloading bitmaps).

    In your application, you should always use Image, both for compatibility
    with ST-80 and for device independence, since not all Form depths are supported
    by all devices, whereas Image contains all the required code to convert as
    required.


Instances of this class represent forms (i.e. bit- and pixmaps)
which are present on a drawing device.

In X, these are XPixmaps; on Windows, these are bitmaps.

WARNING:
    Forms created on some device may not be recreatable, when an
    image is restarted on a display with different display capabilities.
    For example, a 24bit truecolor form will be lost when the image is
    saved and restarted in an 8bit or monochrome display.
    Worse: the information is completely lost.

    With images, the original information is always preserved, although
    the display may have less resolution, need dither or other approximation.

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

Class protocol:

 and

return a constant usable as bitblt-combinationrule.
In ST-80rel2.x, these used to be numeric constants; in ST/X,
these are symbolic.

 black

ST80 compatibility;
In old st80, you could use `Form black' for drawing
- here we return the black color.

 darkGray

ST80 compatibility;
In old st80, you could use `Form darkGray' for drawing
- here we return the darkGray color.

 darkGrey

marked as obsolete by exept MBP at 20-09-2021

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

 gray

ST80 compatibility;
In old st80, you could use `Form gray' for drawing
- here we return the grey color.

 grey

ST80 compatibility;
In old st80, you could use `Form grey' for drawing
- here we return the grey color.

 lightGray

ST80 compatibility;
In old st80, you could use `Form lightGray' for drawing
- here we return the lightGray color.

 lightGrey

marked as obsolete by exept MBP at 20-09-2021

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

 over

return a constant usable as bitblt-combinationrule.
In ST-80rel2.x, these used to be numeric constants; in ST/X,
these are symbolic.

 paint

return a constant usable as bitblt-combinationrule.
In ST-80rel2.x, these used to be numeric constants; in ST/X,
these are symbolic.

 reverse

return a constant usable as bitblt-combinationrule.
In ST-80rel2.x, these used to be numeric constants; in ST/X,
these are symbolic.

 under

return a constant usable as bitblt-combinationrule.
In ST-80rel2.x, these used to be numeric constants; in ST/X,
these are symbolic.

 white

ST80rel2.x compatibility;
In old st80, you could use `Form white' for drawing
- here we return the white color.

 extent: ext depth: d bits: data

 extent: ext depth: d fromArray: data offset: offs

 fromUser

Delay waitForSeconds:1.
Form fromUser inspect.
Delay waitForSeconds:1.

 imageForm

 lowSpaceCleanup

cleanup in low-memory situations

 findBitmapFile: fileName

find the bitmap file in one of the standard places;
return the pathName or nil

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

 initialize

initialize set of dictionaries to look for bitmaps

 reinitializeAllOn: aDevice

recreate all forms on aDevice; called by Workstation after snapIn, to
have all background bitmaps at hand, when views are restored

 update: something with: aParameter from: changedObject

sent just before snapOut and just after a snapIn

 dotOfSize: size

create and return a form which contains a dot (filled circle)
of the given size.

Usage example(s):

(Form dotOfSize:8) inspect (Form dotOfSize:20) inspect

 extent: ext

create a new, cleared form, take dimensions from ext.
Smalltalk-80 compatibility

 extent: ext depth: d

create a new, cleared form.
Smalltalk-80 compatibility

 extent: ext depth: d onDevice: aDevice

create a new form on device, aDevice; depth is what device likes most

 extent: ext fromArray: data

create a new form, take dimensions from ext, bits from data.
Smalltalk-80 compatibility.

 extent: ext fromArray: data offset: offs

create a new form, take dimensions from ext, bits from data.
Smalltalk-80 compatibility.

 extent: ext fromArray: data offset: offs onDevice: aDevice

create a new form, take dimensions from ext, bits from data.

 extent: ext fromArray: data onDevice: aDevice

create a new form, take dimensions from ext, bits from data.

 extent: ext offset: anOffset

create a new, cleared form, take dimensions from ext.
Smalltalk-80 compatibility

 extent: ext onDevice: aDevice

create a new form on device, aDevice; depth is what device likes most

 width: w height: h

create a new form on the default device

 width: w height: h depth: d

create a new form on the default device

 width: w height: h depth: d onDevice: aDevice

create a new form with depth d on device, aDevice

 width: w height: h fromArray: anArray

create a new form on the default device

 width: w height: h fromArray: anArray onDevice: aDevice

create a new form on device, aDevice and
initialize the pixels from anArray

 width: w height: h offset: offs fromArray: anArray

create a new form on the default device

 width: w height: h offset: offs fromArray: anArray onDevice: aDevice

create a new form on the default device

 width: w height: h onDevice: aDevice

create a new form on device, aDevice; depth is what device likes most

 darkGreyFormOn: aDevice

return a darkGrey form

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

 extent: ext depth: d on: aDevice

create a new form on device, aDevice; depth is what device likes most

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

 extent: ext fromArray: data offset: offs on: aDevice

create a new form, take dimensions from ext, bits from data.

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

 extent: ext fromArray: data on: aDevice

create a new form, take dimensions from ext, bits from data.

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

 extent: ext on: aDevice

create a new form on device, aDevice; depth is what device likes most

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

 grey: percent on: aDevice

return a form for dithering

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

 lightGreyFormOn: aDevice

return a lightGrey form

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

 mediumGreyFormOn: aDevice

return a grey form

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

 veryDarkGreyFormOn: aDevice

return a veryDarkGrey form

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

 veryLightGreyFormOn: aDevice

return a veryLightGrey form

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

 width: w height: h depth: d on: aDevice

create a new form with depth d on device, aDevice

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

 width: w height: h fromArray: anArray on: aDevice

create a new form on device, aDevice and
initialize the pixels from anArray

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

 width: w height: h offset: offs fromArray: anArray on: aDevice

create a new form on the default device

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

 width: w height: h on: aDevice

create a new form on device, aDevice; depth is what device likes most

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

 darkGreyFormBits

return a pattern usable to simulate darkGray on monochrome device

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

 grey12Bits

return a pattern with 12% grey, usable for dithering

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

 grey25Bits

return a pattern with 25% grey, usable for dithering

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

 grey37Bits

return a pattern with 37% grey, usable for dithering

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

 grey50Bits

return a pattern with 50% grey, usable for dithering

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

 grey6Bits

return a pattern with 6% grey, usable for dithering

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

 greyFormBits

return a pattern usable to simulate gray on monochrome device

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

 lightGreyFormBits

return a pattern usable to simulate lightGray on monochrome device

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

 veryDarkGreyFormBits

return a pattern usable to simulate veryDarkGray on monochrome device

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

 veryLightGreyFormBits

return a pattern usable to simulate veryDarkGray on monochrome device

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

Instance protocol:

 displayAt: aPoint

show the receiver on the current display screen

Usage example(s):

(Form dotOfSize:8) displayAt:10@10

 displayOn: aGC at: aPoint rule: rule

draw in aGC.
Smalltalk-80 (2.x) compatibility

 displayOn: aGC rule: rule

draw in aGC.
Smalltalk-80 (2.x) compatibility

 displayOn: aGC x: x y: y

draw in aGC.
Smalltalk-80 (2.x) compatibility

 displayOn: aGC x: x y: y rule: rule

draw in aGC.
Smalltalk-80 (2.x) compatibility

 isOpen

 offset

set the offset.
Smalltalk-80 compatibility

 offset: org

set the offset.
Smalltalk-80 compatibility

 preferredBounds

 colormapIfNeededForDepth: destDepth

 magnify: aRectangle by: scale smoothing: smoothBoolean

Squeak compatibility:
a little inefficient hack: convert to image, then magnify,
then convert back

 pixelAt: aPoint

 pixelAt: aPoint put: aPixelValue

 bits

return a ByteArray filled with my bits -
for depth 8 forms, 1 pixel/byte is filled;
for depth 1 forms, 8 pixels/byte are filled
for depth 4 forms, 2 pixels/byte are filled.
Padding is done row-wise to the next BYTE-boundary
If multiple pixels are contained in a single byte,
left bits are in the most significant bit positions.
(i.e. for width==13 and depth==1 it will return 2 bytes per scanline)

 bits: aByteArray

set the forms bits;
for depth-8 forms, 1 pixel/byte is expected;
for depth-1 forms, 8 pixels/byte are expected
for depth-4 forms, 2 pixels/byte are expected.
Padding is expected to the next byte-boundary
(i.e. for width==13 and depth==1 2 bytes per scanline are expected)

 bitsPerSample

for compatibility with Image class ...

 colorMap

return the receiver's colormap

 colorMap: anArrayOrColorMap

set the receiver's colormap

 depth

return the receiver's depth

 forgetBits

for image, which also keeps the bits - so there is
no need to hold them again here

 mask

for compatibility with images; forms have no mask/alpha channel

 maskedPixelsAre0

 maskedPixelsAre0: something

 photometric

for compatibility with Image class ...

 samplesPerPixel

for compatibility with Image class ...

 valueAt: aPoint

return the pixel at aPoint; the coordinates start with 0@0
in the upper left, increasing to the lower right

 valueAt: aPoint put: value

set the pixel at aPoint; the coordinates start with 0@0
in the upper left, increasing to the lower right.

Usage example(s):

|f| f := Form width:10 height:10 depth:1. f clear. 1 to:10 do:[:i | f valueAt:(i @ i) put:1 ]. f inspect

 asHtmlElementIn: htmlContainer
( an extension from the stx:goodies/webServer/comanche package )

answer my HTML representation (String),
as I would look like inside htmlContainer

 asHttpResponseTo: request
( an extension from the stx:goodies/webServer/comanche package )

 asWebImage
( an extension from the stx:goodies/webServer/comanche package )

return a MIMEDocument

 asForm

convert & return the receiver into a Form instance - nothing to be done here

 asImage

convert & return the receiver into an Image instance

 asImageForm

convert & return the receiver into a ImageForm instance

 postCopy

redefined to copy the colorMap as well

 show

open an imageView on the receiver

Usage example(s):

(Form fromFile:'bitmaps/SBrowser.xbm') show

 asFormOn: aDevice

convert & return the receiver into a Form instance
and associate it to a device (i.e. download its bits).
Added for protocol compatibility with Image.

 asMonochromeFormOn: aDevice

added for protocol compatiblity with Image

 exactOn: aDevice

for compatibility with color protocol - here, the same as #onDevice.

 exactOrNearestOn: aDevice

for compatibility with color protocol - here, the same as #onDevice.

 nearestOn: aDevice

for compatibility with color protocol - here, the same as #onDevice.

 on: aDevice

associate the receiver to a device (i.e. download its bits);
return a deviceForm (possibly different from the receiver).

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

 onDevice: aDevice

associate the receiver to a device (i.e. download its bits);
return a deviceForm (possibly different from the receiver).

 clearMaskedPixels

Added for protocol compatibility with Image.

 clearMaskedPixels: maskForm

clear any masked pixels.
This will allow faster drawing in the future.

 darkened

return a darkened version of the receiver.
Added for protocol compatibility with Color and Image.
Here, the receiver is returned as a kludge
- actually should return a darkened image (or Color black ?) ..

 easyMagnifiedBy: extent into: newForm

return a new form magnified by extent, aPoint.
If non-integral magnify is asked for, pass the work on to 'hardMagnifiedBy:'

 flip: how

return a new form flipped horizontally or vertically

Usage example(s):

|testForm| testForm _ Form extent: 8@8 depth: 1 fromArray: #( 2r10000000 2r11000000 2r11100000 2r11110000 2r11111000 2r11111100 2r11111110 2r11111111) offset: 0@0. testForm inspect. (testForm flip:#vertical) inspect. (testForm flip:#horizontal) inspect.

 flipHorizontal

return a new form flipped vertically

Usage example(s):

|testForm| testForm := Form extent: 8@8 depth: 1 fromArray: #( 2r10000000 2r11000000 2r11100000 2r11110000 2r11111000 2r11111100 2r11111110 2r11111111) offset: 0@0. testForm inspect. testForm flipVertical inspect. testForm flipHorizontal inspect.

 flipVertical

return a new form flipped horizontally

Usage example(s):

|testForm| testForm _ Form extent: 8@8 depth: 1 fromArray: #( 2r10000000 2r11000000 2r11100000 2r11110000 2r11111000 2r11111100 2r11111110 2r11111111) offset: 0@0. testForm inspect. testForm flipVertical inspect. testForm flipHorizontal inspect.

 hardMagnifiedBy: extent

return a new form magnified by extent, aPoint.
This method handles non-integral factors.

 lightened

return a lightened version of the receiver.
Added for protocol compatibility with Color and Image.
Here, the receiver is returned unchanged as a kludge
- actually should return a lightened image (or Color white ?) ..

 magnifiedBy: extent

return a new form magnified by extent, aPoint.
If non-integral magnify is asked for, pass the work on to 'hardMagnifiedBy:'

Usage example(s):

(ArrowButton upArrowButtonForm:#iris on:Screen current) magnifiedBy:(2 @ 2) (Form fromFile:'bitmaps/SBrowser.xbm') magnifiedBy:(2 @ 2) (Form fromFile:'bitmaps/SBrowser.xbm') magnifiedBy:(0.4 @ 0.4)

 magnifiedTo: anExtent

return a new form magnified to have the size specified by extent.
This may distort the image if the arguments ratio is not the images ratio.
See also #magnifiedPreservingRatioTo: and #magnifiedBy:

 magnifyBy: scale

obsolete: has been renamed to magnifiedBy: for ST-80 compatibility
and name consistency ...

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

 initGC

redefined to setup the drawing colors to paint 1's on 0's
and to stop the server from sending exposure events for Forms -
(this would fill up stream-queue on some stupid (i.e. sco) systems

 initialize

(comment from inherited method)
must be called if redefined

 recreate

reconstruct the form after a snapin or a migration

 releaseFromDevice

flush device data.
The sender has to take care that the Form has been
unregistered from (Finalization-)Lobby

 inspectorClass
( an extension from the stx:libtool package )

redefined to launch an ImageInspector
(instead of the default InspectorView).

 displayOn: aStreamOrGC

(comment from inherited method)
Compatibility
append a printed desription on some stream (Dolphin, Squeak)
OR:
display the receiver in a graphicsContext at 0@0 (ST80).
This method allows for any object to be displayed in some view
(although the fallBack is to display its printString ...)

Notice: displayString and displayOn: are for developers, debugging and inspectors,
whereas printString and printOn: are for the program to print data.

 storeOn: aStream

append an ascii representation of the receiver to aStream,
from which a copy of the receiver can be reconstructed

 beImmediateForm

read the pixels from the device into a local data array.
To make the image smaller (i.e. not keep all those bitmaps),
this is NOT done by default.

Usage example(s):

Form allInstances:[:f | f beImmediateForm ]

 flushDeviceHandles

flush device handles (sent after a restart)

 getBits

if the receiver was not created from a file, or
an array (i.e. it was drawn), read the pixels from the
device into a local data array. This has to be done before
an image is saved, or the receiver is storedBinary, since
the information present in the device is lost after restart/reload

 restored

private: instance has been restored (either from snapin or binary store);
flush device data

 width: w height: h

actual create of a monochrome form

 width: w height: h depth: d

actual create of an arbitrary deep form (but, must be supported by device).
Return nil (after raising a notification) if the allocation failed

 width: wIn height: hIn fromArray: anArray

actual create of a monochrome form from array.
This method is somewhat more complicated as it should be due to
supporting both byte-wise (ST/X-type) and short-word-wise (ST-80-type)
Arrays; in the later case, the shorts are first converted to bytes in
a ByteArray, then passed to the device.

 width: w height: h offset: offs fromArray: anArray

actual create of a monochrome form from array

 ascentOn: aGC

displayOn: does not draw above baseline

 bounds

return my bounds (added to make forms usable as VisualComponents)

 colorFromValue: pixel

given a pixelValue, return the corresponding color.
For compatibility with Images

 hasBits

return true, if the receiver has its pixel data available.
For forms, which were created from data, this is always true.
For forms, which were created as off-screen device forms on some
device, this is always false.

 heightOn: aGC

return my height, if displayed on aGC;
since my height is independent of the device (the number of pixels),
return the pixel-height

 isDithered

for compatibility with color protocol

 isForm

return true, if the receiver is some kind of form;
true is returned here - the method is redefined from Object.

 isImageOrForm

return true, if the receiver is some kind of image or form;
true is returned here - the method is redefined from Object.

 widthOn: aGC

return my width, if displayed on aGC;
since my width is independent of the device (the number of pixels),
return the pixel-width

Private classes:

    ImageForm