Smalltalk/X Webserver

Documentation of class 'DisplaySurface':

Class: DisplaySurface

Inheritance
Description
Related information
Class protocol
- initialization
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--GraphicsContext
      |
      +--DeviceGraphicsContext
         |
         +--GraphicsMedium
            |
            +--DisplaySurface
               |
               +--DisplayRootView
               |
               +--SimpleView

Package:: stx:libview

Category:: Graphics-Support

Version:: rev: 1.145 date: 2009/12/07 14:56:46; user: cg; file: DisplaySurface.st directory: libview; module: stx stc-classLibrary: libview

Author:: Claus Gittinger

this abstract class describes stuff common to any Window on a display
device. i.e. RootWindow, TopWindows, PopUps and Subwindows.
That is, they have a viewBackground, cursor etc. and especially events.
A special feature is the delegate field, which allows key- and button
events to be stolen from a view.
If the delegate is non-nil, these events will be sent to it instead.
So you can change a views behavior even if it was not initially designed
for it. Also, controller functionality could be simulated using delegates.

[instance variables:]

viewBackground <Color|Form|Image> the views background

cursor <Cursor> the cursor

eventMask mask specifying the enabled
events.

moreAttributes optional dictionary, allowing for more attributes
to be store there
fields:
middleButtonMenu a fix popup menu for the middle button.

keyCommands not yet supported

backed one of #always, #whenMapped or #never
corresponds to X's backing store mechanism.
May be ignored by other devices.

flags flag bits

saveUnder bit 1; 1 if saveunder store for
that view is enabled

gotExpose bit 2; 1 if an expose/noExpose event arrived
(for exposure handling after a scroll)

delegate for event delegation

Related information:

    DeviceWorkstation
    WindowGroup
    StandardSYstemView
    SimpleView
    View

Class protocol:

initialization

initialize

Instance protocol:

accessing

addUpdateRectangle: newRectangle: return true, if the newRectangle is not already contained in the updateRegion
(i.e. if it added any pixels to the region
basicViewBackground: something: set the viewBackground to something, a color, image or form.
The viewBackground is the color or pattern with which exposed
regions are filled - do not confuse this with the drawing background
color, which is used with opaque drawing.
controller: return nil - I have no controller
depth: return the depth in pixels of the view.
Notice, that this is currently the devices depth,
but support for mixed depth views is being prepared.
(especially useful on SGI, with 24bit view)
insideColor: aColor: set the views background color - ST-80 compatibility
keyboardMap: by default, use my devices standard mapping.
However, subclasses may redefine this, to return their own
keyboard map (for example a terminalView may want treat CTRL-C as regular key)
renderer: warning: this is experimental and not yet implemented
renderer: something: warning: this is experimental and not yet implemented
sensor: I can only return a SynchronousWindowSensor,
since I do not have a window group
setViewBackground: install the viewBackground for the receiver on the device
updateRegion
updateRegion: something
viewBackground: return the viewBackground
viewBackground: something: set the viewBackground to something, a color, image or form.
The viewBackground is the color or pattern with which exposed
regions are filled - do not confuse this with the drawing background
color, which is used with opaque drawing.
viewBackgroundAndClear: something: set the viewBackground to something, a color, image or form.
and clear the View.
The viewBackground is the color or pattern with which exposed
regions are filled - do not confuse this with the drawing background
color, which is used with opaque drawing.
viewGravity: return the views gravity
viewOrigin: 0@0 here, since by default we cannot be scrolled
widget: ST-80 compatibility
windowGroup: return nil - I have no windowGroup

accessing-cursor

cursor: return the views cursor
cursor: aCursor: set the views cursor. This cursor will be automatically displayed whenever
the mouse-pointer enters the receiver.
Cursors are typically set at view creation time and left as installed.
cursor: aCursor now: showImmediately: set the views cursor. This cursor will be automatically displayed whenever
the mouse-pointer enters the receiver.
Cursors are typically set at view creation time and left as installed.
setCursor
withCursor: aCursor do: aBlock: evaluate aBlock showing aCursor until ready; then restore the old cursor
and return the value as returned by aBlock.

Notice, that this method only changes the cursor for a SINGLE (sub-)view.
Most applications want to have the cursor changed in all of its views.
Use 'aView windowGroup withCursor:do:' or 'aView topView withCursor:do:'
to acomplish this.
withExecuteCursorDo: aBlock: evaluate aBlock while showing an execute cursor in all my views.
Return the value as returned by aBlock.
withReadCursorDo: aBlock: evaluate aBlock while showing a readCursor in all my views.
Return the value as returned by aBlock.
withWaitCursorDo: aBlock: evaluate aBlock while showing a waitCursor in all my views.
Return the value as returned by aBlock.

accessing-hierarchy

delegate: return the delegate - thats the one getting keyboard and button events
delegate: someOne: set the delegate - keyboard- and button events will be forwarded to
that object if it is interested in them.
See the sendEvent... method in WindowEvent.
superView: return the superView - nil here
topComponent: return the topView - that the one with no superview
topView: return the topView - that the one with no superview

accessing-limits

maxExtent: return the views maximum extent - this is nil here.
Only standardSystemViews support this.
maxExtent: extent: set the views maximum extent - ignored here.
Only standardSystemViews support this.
minExtent: return the views minimum extent - this is nil here.
Only standardSystemViews support this.
minExtent: extent: set the views minimum extent - ignored here.
Only standardSystemViews support this.

accessing-misc

backingStore: how: turn on/off backingStore (saving my pixels)
how may true/false, but also #always, #whenMapped or #never.
eventMask: return a (numeric) mask of allowed events -
this is X-specific and will be removed / replaced by symbolic values)
eventMask: aMask: set a (numeric) mask of allowed events -
this is X-specific and will be removed / replaced by symbolic values)
getKeyboardFocus: tell the Display to assign keyboard focus to the receiver
isInputOnly: return true, if the receiver is an input only view - that is:
the view will realize as a transparent view, into which you cannot
draw, but get events as usual. Thich can be used to catch events away from
others, which where never meant to work in such a setup.
(for example, if you want to manipulate views in some DrawTool-like manner).
This uses a special X feature, which might not be supported in the near future
or on other plattforms.
preferredDepth: return a non nil integer, if a specific depth is wanted in this view.
Return nil if we do not care (i.e. the displays default is wanted).
This is experimental and may change/vanish - do not use it.
preferredVisual: return a non nil id, if a specific visual is wanted in this view.
Return nil if we do not care (i.e. the displays default is wanted).
This is experimental and may change/vanish - do not use it.
saveUnder: return the saveUnder flag
saveUnder: aBoolean: turn on/off saveUnder (saving pixels under myself)
- used for temporary views (i.e. PopUps and ModalBoxes)
setPointerPosition: aRelativePoint: set the pointer to aRelativePoint relative to the views origin

accessing-names

icon: return the views icon - this is nil here.
Only standardSystemViews support labels and icons.
icon: aBitmap: set the views icon - ignored here.
Only standardSystemViews support labels and icons.
iconLabel: return the views icon label - this is nil here.
Only standardSystemViews support labels and icons.
iconLabel: aLabel: set the views icon label - ignored here.
Only standardSystemViews support labels and icons.
iconMask: return the views iconMask - this is nil here.
Only standardSystemViews may support labels and icons.
iconView: return the views iconView - this is nil here.
Only standardSystemViews support labels and icons.
iconView: aView: set the views icon view - ignored here.
Only standardSystemViews support labels and icons.
label: return the views label - this is nil here.
Only standardSystemViews support labels and icons.
label: aLabel: set the views label - ignored here.
Only standardSystemViews support labels and icons.

accessing-private

clearGotExposeFlag: internal; used to wait for an expose-event after a scroll operation
getAttribute: key
gotExpose: internal; used to wait for an expose-event after a scroll operation
setAttribute: key to: newValue
setGotExposeFlag: internal; used to wait for an expose-event after a scroll operation

binary storage

readBinaryContentsFrom: stream manager: manager: tell the newly restored View to recreate itself.
Bug: does not work correctly yet.
(restored view looses its position & wg process)

button menus

middleButtonMenu: return the menu associated with the middle mouse button
middleButtonMenu: aMenu: associate aMenu with the middle mouse button
setMiddleButtonMenu: aMenu: associate aMenu with the middle mouse button.
Do not destroy the old menu if any

clipboard

getClipboardObject: return the object selection
- either the local one, or the displays clipBoard buffer.
getClipboardText: return the copyBuffers contents
- either the local one, or the displays clipBoard buffer.
getClipboardText: selectionBufferSymbol: return the text selection - either the local one, or one of the displays
clipBoard buffers determined by selectionBufferSymbol, which should be one of:
#clipboard
or:
#selection.

Return aString or nil if there is no selection
getSelection: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
getTextSelection: return the copyBuffers contents
- either the local one, or the displays clipBoard buffer.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
getTextSelection: selectionBufferSymbol: return the text selection - either the local one, or one of the displays
clipBoard buffers determined by selectionBufferSymbol, which should be one of:
#clipboard
or:
#selection.

Return aString or nil if there is no selection

** This is an obsolete interface - do not use it (it may vanish in future versions) **
setClipboardObject: something: set the object selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).
setClipboardText: something: set the text selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).
setSelection: something: set the object selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).

** This is an obsolete interface - do not use it (it may vanish in future versions) **
setTextSelection: something: set the text selection - both the local one, and tell the display
that we have changed it (i.e. place it into the clipBoard).

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

drawing

clearDeviceRectangleX: x y: y width: w height: h: clear a rectangular area to viewBackground -
redefined since GraphicsMedium fills with background
- not viewBackground as we want here.
clearRectangleX: x y: y width: w height: h: clear a rectangular area to viewBackground -
redefined since GraphicsMedium fills with background
- not viewBackground as we want here.
fillDeviceRectangleWithPattern: aPixmap x: xIn y: yIn width: wIn height: hIn patternOffset: pattOffs: fill a rectangular area with some pattern.
A helper for devices which do not support pixmap drawing (i.e. win95).
This is never invoked with X11 or Win-NT/XP/Vista systems.
Caller must ensure that aPixmap is really a form
fillDeviceRectangleWithViewBackgroundX: xIn y: yIn width: wIn height: hIn: fill a rectangular area with the viewBackground.
A helper for devices which do not support background pixmaps (i.e. win95 screens).
This is never invoked with X11 or Win-NT/XP/Vista systems.
Caller must ensure that the viewBackground is really a form
fillRectangleWithPattern: aPixmap x: x y: y width: w height: h patternOffset: pattOffs: fill a rectangular area with aPixmap.
A helper for devices which do not support pixmap filling (i.e. win95 screens).
This is never invoked with X11 or Win-NT/XP/Vista systems.
Caller must ensure that the aPixmap is really a form
fillRectangleWithViewBackgroundX: x y: y width: w height: h: fill a rectangular area with the viewBackground.
A helper for devices which do not support background pixmaps (i.e. win95 screens).
This is never invoked with X11 or Win-NT/XP/Vista systems.
Caller must ensure that the viewBackground is really a form
redraw: nothing done here

enable/disable events

compressMotionEvents: aBoolean: enable/disable motion event compression
(i.e. replacing all motion events by the last one).
Compression makes almost always sense, except when
doing things like freehand drawing
disableButtonEvents: disable all button events
disableButtonMotionEvents: disable button motion-while-button-is-pressed events
disableButtonPressEvents: disable button press events
disableButtonReleaseEvents: disable button release events
disableEnterLeaveEvents: disable both mouse-pointer enter and leave events
disableEvent: anEventSymbol: disable an event -
this is a private (internal) method not to be used externally.
for a list of allowed event symbols see Workstation class
disableMotionEvents: disable mouse-pointer motion events
enableButtonEvents: enable both mouse button press and release events.
These are enabled by default anyway.
enableButtonMotionEvents: enable mouse-pointer motion-while-button-is-pressed events.
These are enabled by default anyway.
enableButtonPressEvents: enable mouse button press events.
These are enabled by default anyway.
enableButtonReleaseEvents: enable mouse button release events.
These are enabled by default anyway.
enableEnterEvents: enable mouse-pointer enter events
enableEnterLeaveEvents: enable both mouse-pointer enter and leave events
enableEvent: anEventSymbol: enable an event -
this is a private (internal) method not to be used externally.
for a list of allowed event symbols see Workstation class
enableFocusEvents: enable keyboard focus change events
enableKeyEvents: this is a compatibility leftover -
starting with 2.10.3, keyPress is always enabled to allow
^C processing.
enableKeyPressEvents: this is a compatibility leftover -
starting with 2.10.3, keyPress is always enabled to allow
^C processing.
enableKeyReleaseEvents: enable key release events
enableLeaveEvents: enable mouse-pointer leave events
enableMotionEvents: enable mouse-pointer motion events (those without a pressed button)

event dispatching

dispatchEvent: event: dispatch an event
dispatchEvent: type arguments: arguments: dispatch an event
dispatchEvent: ev type: type arguments: argArray withFocusOn: focusView delegate: doDelegate: dispatch the event represented by type and arguments either to my delegate,
or to my controller (which may be myself, if I implement the controller functionality myself).
If focusView is nonNil, and it is a keyboard event, it is forwarded to this
view (but not if there was a delegate in the first place).

If doDelegate is true, keyboard and button events are forwarded to a
delegate object (if non-nil). DoDelegate may be passed as true, to
handle events which are already delegated.
If there is a delegate, only messages which are understood by it are
forwarded. Also, the delegate is asked if it is willing to handle the event
before.
Delegated messages get the original view as an extra argument.
Delegation has higher priority than both controller or focusView
forwarding.
dispatchEvent: event withFocusOn: focusViewOrNil: dispatch the event
dispatchEvent: event withFocusOn: focusViewOrNil delegate: doDelegate: dispatch the event

event handling

activateMenu: if there is a menu, show it.
buttonMotion: state x: x y: y: mouse was moved while button is pressed - do nothing here
buttonMultiPress: button x: x y: y: button was pressed fast after previous press - default to press-again
buttonPress: button x: x y: y: button was pressed - if its middle button and there is a menu, show it.
buttonRelease: button x: x y: y
catchExpose: this MUST be sent BEFORE doing a bit-blt copy (i.e. copyFrom...),
to tell the sensor that incoming expose events are to be remembered.
Sometime after the bit-blt, waitForExpose should be sent, to finally
suspend until the expose/noExpose event arrives.
This is an X speciality - for devices which do not need this kind of
asynchronous bit-blt confirmation, this is a noop.
coveredBy: aView: the receiver has been covered by another view;
we are not interested in that here (but see modalBox for more).
deviceButtonMotion: state x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a #buttonMotion with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonMotion:x:y:
deviceButtonMultiPress: butt x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonMultiPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonMultiPress:x:y:
deviceButtonPress: butt x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonPress:x:y:
deviceButtonRelease: butt x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonRelease with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonRelease:x:y:
deviceButtonShiftPress: butt x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a buttonShiftPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #buttonShiftPress:x:y:
deviceExposeX: x y: y width: w height: h: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send an expose with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #exposeX:x:y:width:height:
deviceGraphicsExposeX: x y: y width: w height: h final: final: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a graphicsExpose with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #graphicsExposeX:x:y:width:height:
deviceKeyPress: key x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a keyPress with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #keyPress:x:y:
deviceKeyRelease: key x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a keyRelease with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #keyRelease:x:y:
devicePointerEnter: state x: x y: y: this is the low-level (untransformed) event as received
from the device (i.e. coordinates are in device coordinates).
If there is a transformation, apply the inverse
and send a pointerEnter with the logical coordinates.

Views which are interested in deviceCoordinates should
redefine this method -
those which are interested in logical coordinates
should redefine #pointerEnter:x:y:
exposeX: x y: y width: w height: h: an expose event - nothing done here
focusIn: got keyboard focus - do nothing here
focusOut: lost keyboard focus - do nothing here
graphicsExposeX: x y: y width: w height: h final: final: an expose event after a scroll - do normal redraw processing
keyPress: key x: x y: y: a key was pressed in this view.
Here only keyCommands are handled - more action has to
be implemented by redefining this method
keyRelease: key x: x y: y: default action is to do nothing
noExpose: a no expose event after a scroll (event-mode only)
pointerEnter: state x: x y: y: mouse cursor entered view - do nothing here
pointerLeave: state: mouse cursor left view - do nothing here
resizeRequest
waitForExpose: wait until an expose event arrives (to wait for scroll-finish)

initialization & release

destroy: view is about to be destroyed -
first destroy menu if there is one and also destroy the GC.
then the view is physically destroyed.
destroyGC: physically destroy the gc
destroyView: physically destroy the view.
destroyed: view has been destroyed by someone else
executor: redefined for faster creation of finalization copies
(only device, gcId and drawableId are needed)
initCursor: default cursor for all views
initStyle: nothing done here
initialize: initialize defaults
reAdjustGeometry: sent late during snapin processing, nothing done here
recreate: recreate (i.e. tell X about me) after a snapin or a migration
reinitStyle: nothing done here
releaseDeviceResources
unregisterFromLobby

keyboard commands

addActionForKey: aKey action: aBlock: define a keyboard command function
keyCommands
keyCommands: aDictionaryOrNil
removeActionForKey: aKey

queries

buttonMotionEventPending: return true, if a button motion event is pending.
Normally, you dont want to use this, since no polling is needed
(not even for mouse-tracking).
Dont use it, since it does not honor the windowGroup, but
goes directly to the device instead.
Actually, its a historical leftover
buttonReleaseEventPending: return true, if a button release event is pending.
Dont use it, since it does not honor the windowGroup, but
goes directly to the device instead.
Actually, its a historical leftover
exposeEventPending: return true, if an expose event is pending.
isPopUpView: return true, if this view should be put on top (raised) automatically.
usually this is true for alertBoxes etc.
isRootView: return true, if the receiver is a root view
false is returned here, this is only redefined in DisplayRootView.
isTopView: return true, if the receiver is some kind of topview;
false is returned here; redefined in some subclasses.
isView: return true, if the receiver is some kind of view;
true is returned here.
isXtWidget
redrawsFull
shown: return true if at least a part of myself is currently visible
(I am mapped and not completely covered).
Assumed that I am always visible when realized.

queries-contents

heightOfContents: return the height of the contents in pixels.
Since we dont know here, just return the views size.
This will make your scrollbars show 100%-visible.
Must be redefined in subviews to make scrollbars really work.
widthOfContents: return the width of the contents in pixels.
Since we dont know here, just return the views size.
This will make your scrollbars show 100%-visible.
Must be redefined in subviews to make scrollbars really work.
xOriginOfContents: return the x-origin of the contents in pixels.
Since we dont know here, just return 0 for left.
Must be redefined in subviews to make scrollbars really work.
yOriginOfContents: return the y-origin of the contents in pixels.
Since we dont know here, just return 0 for top.
Must be redefined in subviews to make scrollbars really work.

user interaction & notifications

beep: output an audible beep or bell on my screen device
showActivity: aMessage: this is sent indirectly by the activityNotification mechanism.
Defined here as a fallback, if ever sent to non topviews.

Private classes:

    DeviceViewHandle

ST/X 6.1.1; WebServer 1.620 at exept:8081; Thu, 24 May 2012 11:14:25 GMT