Smalltalk/X Webserver

Documentation of class 'DeviceWorkstation':

Class: DeviceWorkstation

Inheritance
Description
Class protocol
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--GraphicsDevice
      |
      +--HostGraphicsDevice
         |
         +--DeviceWorkstation
            |
            +--XWorkstation

Package:: stx:libview

Category:: Interface-Graphics

Version:: rev: 1.815 date: 2024/04/22 17:08:23; user: stefan; file: DeviceWorkstation.st directory: libview; module: stx stc-classLibrary: libview

Description:

this abstract class defines common protocol to all Display types.
For compatibility with ST-80, this class (actually a concrete subclass)
is also bound to the global variable Screen.

DeviceWorkstation (and its concrete subclasses) are the central classes
around windowManagement and event processing.
See the documentation in #events and #workstationDevices for more detailed
info.

[instance variables:]

  displayId       <Number>          the device id of the display
  visualType      <Symbol>          one of #StaticGray, #PseudoColor, ... #TrueColor
  monitorType     <Symbol>          one of #monochrome, #color, #unknown

  depth           <SmallInteger>    bits per color
  ncells          <SmallInteger>    number of colors (i.e. colormap size; not always == 2^depth)
  bitsPerRGB      <SmallInteger>    number of valid bits per rgb component
                                    (actual number taken in A/D converter; not all devices report the true value)
  bitsRed         <SmallInteger>    number of red bits (only valid for TrueColor displays)
  bitsGreen       <SmallInteger>    number of green bits (only valid for TrueColor displays)
  bitsBlue        <SmallInteger>    number of blue bits (only valid for TrueColor displays)
  redMask         <SmallInteger>    shifted red mask (only useful for TrueColor displays)
  greenMask       <SmallInteger>    shifted green mask (only useful for TrueColor displays)
  blueMask        <SmallInteger>    shifted blue mask (only useful for TrueColor displays)
  shiftRed        <SmallInteger>    number of bits to shift red bits (only valid for TrueColor displays)
  shiftGreen      <SmallInteger>    number of bits to shift green bits (only valid for TrueColor displays)
  shiftBlue       <SmallInteger>    number of bits to shift blue bits (only valid for TrueColor displays)

  hasColors       <Boolean>         true, if display supports colors
  hasGreyscales   <Boolean>         true, if display supports grey-scales (i.e is not b/w display)
  width           <SmallInteger>    number of horizontal pixels
  height          <SmallInteger>    number of vertical pixels
  heightMM        <Number>          screen height in millimeter
  widthMM         <Number>          screen width in millimeter
  resolutionHor   <Number>          pixels per horizontal millimeter
  resolutionVer   <Number>          pixels per vertical millimeter

  knownViews      <WeakValueDictionary>  viewId -> view all of my known views

  dispatching     <Boolean>         true, if currently in dispatch loop
  exitDispatchOnLastWindowClose
                  <Boolean>         if true, dispatch is finished when the last
                                    window closes (default:true).

  ctrlDown        <Boolean>         true, if control key currently pressed
  shiftDown       <Boolean>         true, if shift key currently pressed
  metaDown        <Boolean>         true, if meta key (cmd-key) is currently pressed
  altDown         <Boolean>         true, if alt key is currently pressed

  motionEventCompression
                  <Boolean>         if true motion events are compressed
                                    (obsolete: now done in sensor)

  lastId          <Number>          the id of the last events view (internal)
  lastView        <View>            the last events view (internal, for faster id->view mapping)

  keyboardMap     <KeyBdMap>        mapping for keys
  rootView        <DisplayRootView> this displays root window
  isSlow          <Boolean>         set/cleared from startup - used to turn off
                                    things like popup-shadows etc.

  focusMode       <Symbol>          nil, #pointer or #activeWindow
  activeWindow    <View>            WINDOWS only: the currently active (foreground) view

  clipBoardEncoding
                  <Symbol>          encoding of pasted clipBoard text;
                                    nil means: iso8859.
                                    set this to #shiftJis, if pasting
                                    SJIS text (for example, from Netscape)
                                    Some systems pass encoding information
                                    in the clipBoard - there, this is not
                                    needed.

[class variables:]

  MultiClickTimeDelta               in ms; controls how long of a delay is
                                    required between two clicks, to NOT take
                                    it as a multi-click.

  ErrorPrinting                     controls low-level (X-) error message printing

  AllScreens                        a collection of known screens

copyrightCOPYRIGHT (c) 1993 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.

eventsAll events are processed in a workstation's dispatchEvent method.
There, incoming events are first sent to itself, for a first (view independent)
preprocessing. For example, the device's state of the shift-, alt-, control and
meta keys are updated there. After that, the event is forwarded either to
the view's sensor or to the view directly (if it has no sensor).
(Sensorless views are a leftover from ancient times and will sooner or
 later vanish - simplifying things a bit.
 Do not depend on views without sensors to work correctly in future versions.)

This event processing is done by the event dispatcher process, which is
launched in ST/X's startup sequence (see Smalltalk>>start).
Event processing is done at a high priority, to allow keyboard processing
and CTRL-C handling to be performed even while other processes are running.
The code executed by the event process is found in #startDispatch.

Individual events can be enabled or disabled.
The ones that are enabled by default are:
    keypress / keyRelease
    buttonPress / buttonRelease / buttonMotion (i.e. motion with button pressed)
    pointerEnter / pointerLeave

Other events have to be enabled by sending a corresponding #enableXXXEvent
message to the view which shall receive those events.
For example, pointerMotion events (i.e. motion without button being pressed)
are enabled by: 'aView enableMotionEvent'

The above is only of interest, if you write your own widget classes;
existing widgets set things as required in their #initEvents method.

workstationDevicesIn ST/X, all interaction with the graphics device is done through
an instance of (a subclass) of DeviceWorkstation.
Every view has a reference to the device it has been created on in
its 'device' instance variable.

One particular device instance is bound to the global variable Display:
this is the default graphics display, on which new views are created
(however, provisions exist for multi-display operation)

Currently, there is are twoconcrete display classes (released to the public):

    XWorkstation    - a plain X window interface

    GLXWorkstation  - an X window interface with a GL(tm) (3D graphic library)
                      extension; either simulated (VGL) or a real GL
                      (real GL is only available on SGI machines)

the following are coming soon:

    OpenGLWorkstation
                    - an X window interface with a openGL(tm) (3D graphic library)
                      extension; either simulated (MESA) or a real openGL
                      (real openGL is only available on SGI/NT machines)

    WinWorkstation  - what will that be ?

An experimental version for a NeXTStep interface exists, but is currently
no longer maintained and not released.

DeviceWorkstation itself is an abstract class; the methods as defined
here perform things which are common to all graphic devices or block
methods and raise a subclassResponsibilty error condition.
To create a new graphic interface, at least the subclassResponsibility-methods
have to be reimplemented in a concrete subclass.

ST/X is designed to allow the use of multiple workstation devices in parallel,
if the underlying window system supports this.
For example, in X, it is possible to create another instance of XWorkstation,
start a dispatch process for it, and to create and open views on this display.
Multiple display operation does not work with other devices (i.e. Windows).

If you want to experiment with multi-display applications,
you have to:

- create a new instance of XWorkstation:

    Smalltalk at:#Display2 put:(XWorkstation new).
  or:
    Smalltalk at:#Display2 put:(GLXWorkstation new).


- have it connect to the display (i.e. the xServer):
  (replace 'localhost' below with the name of your display)

    Display2 := Display2 initializeFor:'localhost:0.0'

  returns nil, if connection is refused
  - leaving you with Display2==nil in this case.


- start an event dispatcher process for it:
  (this is now no longer needed - the first opened view will do it for you)

    Display2 startDispatch


- optionally set its keyboard map
  (since this is usually done for Display in the startup-file,
   the new display does not have all your added key bindings)

    Display2 keyboardMap:(Display keyboardMap)


- create a view for it:

    (FileBrowser onDevice:Display2) open

    (Workspace onDevice:Display2) open

    (Launcher onDevice:Display2) open
        does not work with Launcher, since its an ApplicationModel (not a view)
        use:
            Launcher openOnDevice:Display2
        instead.

For all of the above, there is now a convenient helper method in
ApplicationModel, which allows to write:
    Application openOnXScreenNamed:'foo:0'

However, as mentioned above, there may be a few places, where the default
display 'Display' is still hard-coded - especially, in contributed and
Public domain code, you may find those.

Beside this (little bug ;-), remote display operation works pretty well.
If you write your application to work around those, multi-display applications are
possible in the current release (and actually being used in a concrete application,
where up to 6 x-terminals are connected to a single linux PC).

To make your application ready for multi-display operation, replace all
references to 'Display' by: 'Screen current', which evaluates to the currently
active display. I.e. each view gets its actual display via this expression.
Since ST/X views already use this, new views opened by remote views should
come up on the remote display.

There is no easy solution for things like Notifiers, WarnBoxes or
Debuggers when opened from some background or non-view process.
These will come up one the default Display, as returned by 'Screen default'.

Finally, your application should care for I/O errors (i.e. lost connection when
a remote display is switched off).
The framework provides per-display signals, which are raised in the corresponding
event dispatchers context.
For a save environment, you should add static exception handler blocks on those
signals; i.e. the setup for remote displays should look somewhat like:
    |newDpy|

    newDpy := GLXWorkstation new.
    newDpy := newDpy initializeFor:'localhost:0.0'.
    newDpy isNil ifTrue:[
        self warn:'cannot connect ...'.
    ] ifFalse:[
        newDpy deviceIOErrorSignal handlerBlock:[:ex |
            Transcript beep.
            Transcript showCR:'Display (' , newDpy displayName , '): connection broken.'.
            AbortSignal raise.
        ].
        newDpy startDispatch.
        Launcher openOnDevice:newDpy.
    ].

There may still some problems to be expected,
if the screens have different display capabilities (b&w vs. greyscale vs.
color display). The current styleSheet approach keeps default values
only once (it should do so per display ...)
For now, expect ugly looking views in this case - or set your styleSheet
for the smallest common capabilities (i.e. for b&w).
This may be fixed in a future version ...

Class protocol:

Signal constants

currentScreenQuerySignal: return the signal which can be used to provide a current
screen (if background processes ask for one)
deviceErrorSignal: return the signal used for device error reporting.
In multi-display configurations, this is the parent of
all per-instance deviceErrorSignals.
deviceIOErrorSignal: return the signal used for device I/O error reporting.
In multi-display configurations, this is the parent of
all per-instance deviceIOErrorSignals.
deviceIOTimeoutErrorSignal: return the signal used for device I/O timeout error reporting.
In multi-display configurations, this is the parent of
all per-instance deviceIOTimeoutErrorSignals.
deviceOpenErrorSignal: return the signal used for reporting of errors while opening a device.
drawingOnClosedDeviceSignal

accessing

default

ST-80 compatibility.
Return the default screen. This is typically the first opened
Display screen in a session. Use of the global variable Display
should vanish over time - replace it by Screen default.

Usage example(s):

     Screen default

default: aDevice

Set the default screen. This is sent very early during startup,
and assigns the first opened screenDevice to both Display and the default
screen.

cleanup

lowSpaceCleanup: cleanup in low-memory situations

clipboard support

bufferAsString: aBuffer: aBuffer (my current selection or the clipBoard) as a string

defaults

defaultButtonPressTimeForMenu
defaultButtonPressTimeForMenu: seconds

error handling

errorInterrupt: errID with: aParameter

an error in the devices low level code (typically Xlib or XtLib)
This is invoked via
XError->errorInterrupt:#DisplayError->registeredErrorInterruptHandlers
or
XError->errorInterrupt:#DisplayIOError->registeredErrorInterruptHandlers

looks if a signal handler for DeviceErrorSignal is present,
and - if so raises the signal.
If the signal not handled, simply output a message and continue.
This allows for non disrupted error reporting OR to catch and
investigate errors as required.
However, io-errors are always delivered as a signal raise.

Usage example(s):

an error in the devices low level code (typically Xlib or XtLib)
     This is invoked via
	XError->errorInterrupt:#DisplayError->registeredErrorInterruptHandlers
     or
	XError->errorInterrupt:#DisplayIOError->registeredErrorInterruptHandlers

     looks if a signal handler for DeviceErrorSignal is present,
     and - if so raises the signal.
     If the signal not handled, simply output a message and continue.
     This allows for non disrupted error reporting OR to catch and
     investigate errors as required.
     However, io-errors are always delivered as a signal raise.

errorPrinting

return the `errorPrinting-is-on' flag

errorPrinting: aBoolean

set/clear the `errorPrinting-is-on' flag

lastErrorString

return a string describing the last error

** This method must be redefined in concrete classes (subclassResponsibility) **

resourceIdOfLastError

return the resource id responsible for the last error

** This method must be redefined in concrete classes (subclassResponsibility) **

initialization

initialize: create local error signals; enable errorPrinting
initializeConstants: initialize some (soft) constants
nativeWindows: aBoolean: enable / disable use of native windows - dummy here.

instance creation

newDispatchingFor: aScreenName: create a new instance of mySelf, which serves aScreenName.
Only useful for device-classes which support multiple devices -
i.e. X-Workstations
newFor: aDisplayName: Create an new instance for a connection to aDisplayName.
If aDisplayName is nil, a connection to the standard display is opened
openDefaultDisplay: aStringOrNil: open the default display. aStringOrNil may be the display name,
if nil, the name is extracted from command-line-arguments or the environment.
Raise a signal if open fails.

queries

allScreens

Return a collection of active display devices.
Typically, there is only one: Display or Screen current.

Usage example(s):

     Screen allScreens

current

Return the currently active screen,
that is, the device of the currently executing windowGroup.
It will be used in multi-display operation, to launch views on
the correct device - even if not specified explicitely.
This does not yet work fully satisfying if a background processes
invokes this ... the default display is returned in this case.
In a headless (i.e. non-GUI) application, nil is returned.

Usage example(s):

the current windowGroup got corrupted somehow ...

Usage example(s):

'DevWorkstation [info]: cannot figure out current screen - use default' infoPrintCR.

Usage example(s):

     Screen current

     |s|
     Transcript topView windowGroup process interruptWith:[s := Screen current].
     Delay waitForSeconds:0.5.
     s inspect

currentIfNone: exceptionValue

Return the currently active screen;
if there is none, return the value from exceptionValue

Usage example(s):

     Screen currentIfNone:[self error]

currentWindow

Return the currently active window,
that is, the topView of the currently executing windowGroup

Usage example(s):

     Screen currentWindow

defaultDisplayName

extract the default display name from command line arguments
and environment. Nil is a valid name which represents the builtin default

Usage example(s):

     self defaultDisplayName

flushCachedLastScreen

isAbstract

answer true, if I am not a concrete Workstation class

Usage example(s):

     DeviceWorkstation isAbstract
     XWorkstation isAbstract

isWindowsPlatform

isX11Platform

platformName

ST-80 compatibility.
Return a string describing the display systems platform.
Returns a dummy here. This must be redefined in concrete
Workstation classes, to return something like 'X11', 'win32', 'os2' etc.

standalone setup

exitOnLastClose: aBoolean: set/clear the flag which controls if the
event dispatching should stop when the last view is closed
on the (main) Display connection.
(standAlone applications will set it)

Instance protocol:

Compatibility-ST80

colorDepth

alias for depth - for ST-80 compatibility

colorPalette

alias for colorMap - for ST-80 compatibility

stackedWindows

supposed to return all topViews in stacking order;
BUGGY: right now, the order is undefined

zoom: startRect to: endRect

animate a rubber-rectangle from startRect to endRect.
Can be used by buttons, which open some dialog for nicer user feedback.
Notice: since the display's window manager typically allows a topWindow
to be placed by the user, this should not be used for modeless
topViews.

Usage example(s):

     Screen current zoom:(10@10 corner:20@20) to:(20@20 corner:1000@1000)
     Screen current zoom:(20@20 corner:1000@1000) to:(10@10 corner:20@20)

zoom: startRect to: endRect duration: milliseconds

Usage example(s):

     Screen current zoom:(10@10 corner:20@20) to:(20@20 corner:1000@1000) duration:1000
     Screen current zoom:(20@20 corner:1000@1000) to:(10@10 corner:20@20) duration:1000

zoom: startRect to: endRect speed: pixelsPerSecond

animate a rubber-rectangle from startRect to endRect.
Can be used by buttons, which open some dialog for nicer user feedback.
The speed is computed for the longest edge to run at the given speed.
Notice: since the display's window manager typically allows a topWindow
to be placed by the user, this should not be used for modeless
topViews.

Usage example(s):

     Screen current zoom:(10@10 corner:20@20) to:(20@20 corner:1000@1000) speed:1000
     Screen current zoom:(20@20 corner:1000@1000) to:(10@10 corner:20@20) speed:10

Compatibility-Squeak

border: aRectangle width: bw

draw a rectangular border on the display with black.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[
	Display border:(10@10 corner:100@100) width:2.
     ]

centerOfMonitorHavingPointer

answer the center of the bounds of the monitor which contains the mouse pointer.

Usage example(s):

     Display centerOfMonitorHavingPointer  => 640@389

cursorPoint

ST-80 compatibility:
return the position of the mouse pointer on this display
(in screen coordinates)

displayOpaqueString: s x: x y: y

draw a string on the display with black.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[
	Display displayOpaqueString:'hello' x:10 y:10.
     ]

displayString: s x: x y: y

draw a string on the display with black.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[
	Display displayString:'hello' x:10 y:10.
     ]

fill: aRectangle fillColor: aColor

fill a rectangular area on the display with aColor.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[
	 Display fill:(10@10 corner:100@100) fillColor:Color yellow
     ]

fillWhite

fill all of the display with white.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[
	 Display fillWhite
     ]

Usage example(s):

     Display restoreAfter:[
	 Display fillWhite:(10@10 corner:100@100)
     ]

fillWhite: aRectangle

fill a rectangular area on the display with white.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[
	 Display fillWhite:(10@10 corner:100@100)
     ]

primMouseButtons

return the current button state

Usage example(s):

     Display primMouseButtons

restoreAfter: aBlock

evaluate aBlock, wait for a buttonPress, then restore the display.
Added to allow for some squeak examples to be evaluated ...

Usage example(s):

     Display restoreAfter:[Display fillWhite:(10@10 corner:100@100)]

supportsDisplayDepth: givenDepth

return true, if the given depth is supported by the display.
(Actually, some displays support multiple depths (i.e. visuals),
but for now, we want the displays native depth here.

waitButton

wait for any button to be pressed

Usage example(s):

     Sensor waitButton.
     Sensor waitNoButton

waitClickButton

wait for any button to be pressed and released again.
Return the screen coordinate of the click.

Usage example(s):

     Sensor waitClickButton.

waitNoButton

wait for no button to be pressed

Usage example(s):

     Sensor waitButton.
     Sensor waitNoButton

Signal constants

deviceErrorSignal: return the per-device signal, which is used for error reporting.
The default here is the global DeviceErrorSignal
(which is the parent of any per-instance error signals).
deviceIOErrorSignal: return the signal used for device I/O error reporting.
The default here is the global DeviceIOErrorSignal
(which is the parent of any per-instance I/O error signals).
deviceIOTimeoutErrorSignal: return the signal used for device I/O timeout error reporting.
The default here is the global DeviceIOTimeoutErrorSignal
(which is the parent of any per-instance I/O timeout signals).

accessing & queries

activateOnClick: aBoolean

enable/disable raise&activate on click;
return the previous setting.
This may be left unimplemented by a device.

activeView

Display activeView

allViews

return a collection of all my known views

buttonMotionMask: aButtonNr

return the state-mask for button<n> in motion events state-field.
This is the devices mask.

** This method must be redefined in concrete classes (subclassResponsibility) **

buttonMotionMask: aMask includesButton: aButton

given a device button mask, return true if a logical button
(1 .. 3 for left .. right) is included.

colorAt: aPoint

Screen current colorAt:0@0

dispatchProcess

displayFileDescriptor

return the file descriptor associated with the display
if any. If there is no underlying filedescriptor, return nil.
(used for event select/polling)

getSystemColor: aKey

retrieve a windows system color.
The styleSheet/View classes may use this to setup default colors.

Usage example(s):

     Display getSystemColor:#COLOR_WINDOW
     Display getSystemColor:#COLOR_HIGHLIGHT

id

return the displayId

isOpen

return true, if there is a valid connection to the display.
Added for ST-80 compatibility.

isOpenAndDispatching

return true, if there is a valid connection to the display and events are dispatched.

isPersistentInSnapshot

return true, if resources on this device are to be made
persistent in a snapshot image.

knownViews

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

mayOpenDebugger

return true, if a debugger may open on this workstation;
if false, the debugger opens on the main display.
This should be made a variable ...

mayOpenDebugger: aBoolean

set/clear the flag, which controls if a debugger may open on this workstation;
if false, the debugger opens on the main display.

multiClickTimeDelta

multiClickTimeDelta: milliseconds

nativeDialogs

nativeFileDialogs

nativeWidgets

true if the use of native widgets is enabled on this device

queryUsableExtent

answer the extent of all monitors

Usage example(s):

        Screen current queryUsableExtent

rootView

return the rootView (i.e. the background window) on the receiver screen.
It is not guaranteed, that a particular display device supports this.

Usage example(s):

     |v|
     v := Display rootView.
     v paint:Color red.
     v clippedByChildren:false.
     v fillRectangleX:10 y:10 width:100 height:100.

Usage example(s):

     |v|
     v := Display rootView.
     v paint:Color red.
     v clippedByChildren:true.
     v fillRectangleX:10 y:10 width:100 height:100.

suppressDebugger

return true, if no debugger should be opened for applications running
on this device (i.e. neither a debugger on the device nor on the
main screen).
If true, the debugger is either opened on the device or on the
main display, depending on the mayOpenDebugger setting.

suppressDebugger: aBoolean

set/clear the flag, which controls if no debugger should be opened for applications running
on this device (i.e. neither a debugger on the device nor on the
main screen).
If true, the debugger is either opened on the device or on the
main display, depending on the mayOpenDebugger setting.

suppressShadowViews

return true, if this device wants to suppress shadow views
(i.e. shadows under popups and modalBoxes).
Some (slow) devices may want to return true here

translatePoint: aPoint from: windowId1 to: windowId2

given a point in window1 (defined by its id), return the coordinate of
aPoint in window2 (defined by its id).
Use to xlate points from a window to rootwindow, mainly for rubber-line
drawing on the display's root window.

** This method must be redefined in concrete classes (subclassResponsibility) **

translatePoint: aPoint fromView: window1 toView: window2

given a point in window1, return the coordinate of aPoint in window2.
Either window argument may be nil to specify the root window (screen)
Use to xlate points from a window to another window (or from a window
to the rootwindow), mainly for rubber-line drawing on the display's root window.

translatePointFromRoot: aPoint toView: window

given a point as absolute root-window coordinate, return the coordinate within the window.
Use to xlate points from the rootWindow to a window.

translatePointToRoot: aPoint fromView: window1

given a point in window1, return the absolute root-window coordinate.
Use to xlate points from a window to the rootwindow,
mainly for rubber-line drawing on the display's root window.

viewFromPoint: aScreenPoint

given a point on the screen, return the ST/X view in which that
point is (this may be a subview).
Return nil, if it's not an ST/X view or if the point is on the background

viewIdFromPoint: aScreenPoint

given a point on the screen, return the id of the ST/X view in which that
point is (this may be a subview). Return nil, if it's not an ST/X view
or if the point is on the background

viewIdFromPoint: aPoint in: windowId

given a point in rootWindow, return the viewId of the subview of windowId
hit by this coordinate. Return nil if no view was hit.
- use to find window to drop objects after a cross-view drag

windowAt: aScreenPoint

given a point on the screen, return the ST/X topview in which that
point is.
Return nil, if it's not an ST/X view or if the point is on the background.
Alias for viewFromPoint: for ST-80 compatibility

accessing-display attributes

bitsBlue

return the number of valid bits in the blue component.

Usage example(s):

     Display bitsBlue

bitsGreen

return the number of valid bits in the green component.

Usage example(s):

     Display bitsGreen

bitsPerRGB

return the number of valid bits per rgb component;
Currently, assume that r/g/b all have the same precision,
which is a stupid assumption (there may be some, where less
resolution is available in the blue component).
Therefore, this may be changed to return a 3-element vector.
In the meantime, use bitsRed/bitsGreen/bitsBlue to get this information.

Usage example(s):

     Display bitsPerRGB

bitsRed

return the number of valid bits in the red component.

Usage example(s):

     Display bitsRed

blackColor

return the black color on this device.
This is the same as 'Color black onDevice:device', but much faster.

Usage example(s):

     Display blackColor

blackpixel

return the colorId of black

** This method must be redefined in concrete classes (subclassResponsibility) **

blueMask

return a mask, which extracts the blueBits from a color id.
This only makes sense with trueColor displays;
therefore, 0 is returned on all others.

Usage example(s):

     Display blueMask

depth

return the depth in pixels of the display

Usage example(s):

     Display depth

focusMode

greenMask

return a mask, which extracts the greenBits from a color id.
This only makes sense with trueColor displays;
therefore, 0 is returned on all others.

Usage example(s):

     Display greenMask

hasColors

return true, if it's a color display

Usage example(s):

     Display hasColors

hasGrayscales

return true, if this workstation supports grayscales
(also true for color displays)

Usage example(s):

     Display hasGrayscales

hasGreyscales

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

redMask

return a mask, which extracts the redBits from a color id.
This only makes sense with trueColor displays;
therefore, 0 is returned on all others.

Usage example(s):

     Display redMask

shiftBlue

return the count by which the blue bits are to be shifted
when forming a color index.
This only makes sense with trueColor displays; therefore,
nil is returned on all others.

Usage example(s):

     Display shiftBlue

shiftGreen

return the count by which the green bits are to be shifted
when forming a color index.
This only makes sense with trueColor displays; therefore,
nil is returned on all others.

Usage example(s):

     Display shiftGreen

shiftRed

return the count by which the red bits are to be shifted
when forming a color index.
This only makes sense with trueColor displays; therefore,
nil is returned on all others.

Usage example(s):

     Display shiftRed

visualType

return a symbol representing the visual type of the display

Usage example(s):

     Display visualType

visualType: aSymbol

set the visual type.
The only situation, where setting the visual makes sense,
is with my plasma-display, which ignores the palette and spits out
grey scales, independent of color LUT definitions.
(of which the server knows nothing).
So, this should be used from a display-specific startup file only.

whiteColor

return the white color on this device.
This is the same as 'Color white onDevice:device', but much faster.

whitepixel

return the colorId of white

** This method must be redefined in concrete classes (subclassResponsibility) **

accessing-display capabilities

hasColors: aBoolean

set the hasColors flag - needed since some servers don't tell the
truth if a monochrome monitor is connected to a color server.
Clearing the hasColors flag in the rc file will force use of grey
colors (which might make a difference, since some colors are hard to
distinguish on a greyscale monitor).

hasDPS

return true, if this workstation supports postscript output into views.
Should be reimplemented in concrete classes which do support this.

Usage example(s):

     Display hasDPS

hasExtension: extensionString

query for an X extension. The method here is provide for XWorkstation
protocol compatibility only.

Usage example(s):

     Display hasExtension:'XVideo'
     Display hasExtension:'Input'
     Display hasExtension:'GLX'
     Display hasExtension:'X3D-PEX'
     Display hasExtension:'XInputExtension'
     Display hasExtension:'SHAPE'
     Display hasExtension:'MIT-SHM'
     Display hasExtension:'SGIFullScreenStereo'

hasGrayscales: aBoolean

set the hasGrayscales flag - can be used to simulate b&w behavior
on greyScale and color monitors.
(You may want to check if your application looks ok if displayed on
a b&w monitor - even if you have a color display. To do so, clear
the hasGreyscales flag from your .rc file)

hasGreyscales: aBoolean

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

hasImageExtension

return true, if this workstation supports the X Image extension

Usage example(s):

     Display hasImageExtension

hasInputExtension

return true, if this workstation supports the X Input extension

Usage example(s):

     Display hasInputExtension

hasMultibuffer

return true, if this workstation supports the X multibuffer extension

Usage example(s):

     Display hasMultibuffer

hasPEX

return true, if this workstation supports PEX graphics.
Should be reimplemented in concrete classes which do support this.

Usage example(s):

     Display hasPEX

hasShape

marked as obsolete by Stefan Vogel at 8-Sep-2023

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

hasShm

return true, if this workstation supports shared memory pixmaps.
Should be reimplemented in concrete classes which do support this.

Usage example(s):

     Display hasShm

hasStereoExtension

return true, if this workstation supports stereo GL drawing.
Both the server must support it, and the feature must have been
enabled in the smalltalk system, for true to be returned.

Usage example(s):

     Display hasStereoExtension

hasXVideo

return true, if this workstation supports the XVideo extension

Usage example(s):

     Display hasXVideo

iconSizes

Get the supported icon sizes. These are typically set by the window manager.
We return nil here (as if there are no special size preferences).

ignoreBackingStore: aBoolean

if the argument is true, the view's backingStore setting will be ignored, and
no backing store used - this can be used on servers where backing store is
very slow (from rc-file)

isSlow

return true, if this is a relatively slow device -
used to turn off things like popup-shadows

isSlow: aBoolean

set/clear the slow flag.
The slow-flag has no semantic meaning by itself;
however, it can be set via the display.rc file and tested at various
other places to turn off some bells&whistles which might slow down
the drawing. For example, shadows under popUps are suppressed if isSlow
is set.

monitorInfoFor: aMonitorId

monitorType

return a symbol representing the monitor type of the display.
It is usually set to #unknown, #color or #monochrome.
But it can be set to any value from the startup file, for later
testing from anywhere. For example the startup for plasma-displays
can set it to #plasma to later influence the colors used in widgets
(indirectly through the resource file).

Usage example(s):

     Display monitorType

monitorType: aSymbol

set the monitorType - see comment in DeviceWorkstation>>monitorType

ncells

return the number of usable color cells, the display has
- this is not always 2 to the power of depth
(for example, on 6bit displays, ncells is 64 while depth is 8)

Usage example(s):

     Display ncells

numberOfMonitors

Display numberOfMonitors

pointIsVisible: aPoint

is the point visible?

Usage example(s):

     Screen current pointIsVisible:(0@0)
     Screen current pointIsVisible:(1500@0)
     Screen current pointIsVisible:(9000@0)
     Screen current pointIsVisible:(Display pointFromUser)

pointsAreOnSameMonitor: point1 and: point2

are the two points on the same (multi-screen) monitors?
To be redefined for display systems which support MULTI SCREEN

preferredIconSize

Get the preferrered icon size. These are typically set by the window manager.

Usage example(s):

     Display preferredIconSize:nil.
     Display preferredIconSize.
     Display preferredIconSize:32@32
     Display preferredIconSize:nil

preferredIconSize: anExtentPoint

set the preferrered icon size.
By default, the preferredIconSize is queried from the display,
however, some windowManagers return stupid values.
This methods allows overriding thngs from a startup file

Usage example(s):

     Display preferredIconSize
     Display preferredIconSize:32@32
     Display preferredIconSize:48@48

scrollsAsynchronous

return true, if this display asynchronously sends expose events after a
scroll operation. False otherwise. Asynchronous expose events are an X
speciality, which affects a few methods outside of the display class (sorry)

supportedClipboards

answer a collection of symbols with the supported clipboards..
At least clipboard should be supported on any platform

supportedImageFormatForDepth: aDepth

given a depth, return the devices image format info,
which provides padding info. If the given depth is not
supported, return nil.

supportedImageFormats

return an array with supported image formats; each array entry
is another array, consisting of depth and bitsPerPixel values.
Here, we return a single format only; every graphics device must
support b&w single bit images.

supportsAlphaChannel

return true, if this workstation supports alpha information.
If not, alpha blending is done 'manually' when images are displayed.
Currently none does

Usage example(s):

     Display supportsAlphaChannel

supportsAnyViewBackgroundPixmaps

return true, if the device allows any pixmap as
viewBackground. False returned here - redefined in some
device classes.

supportsArbitraryShapedViews

return true, if this workstation supports arbitrary shaped
windows.
Should be reimplemented in concrete classes which do support this.

Usage example(s):

     Display supportsArbitraryShapedViews

supportsDeepIcons

return true, if this device supports non b&w (i.e. greyScale
or colored icons). Many Xservers (and/or windowManagers) crash,
if you pass them a deep form as icon; therefore, the default is false.
It may be a good idea to check for the server vendor/release and
return true sometimes.
This flag can be set with #supportsDeepIcons:

Usage example(s):

     Display supportsDeepIcons:true

     |v|

     v := StandardSystemView new.
     v icon:((Image fromFile:'bitmaps/claus.gif') magnifiedTo:68@68).
     v open.

supportsDeepIcons: yesOrNo

set/clear the supportsDeepIcons flag.
Many Xservers (and/or windowManagers) crash,
if you pass them a deep form as icon; therefore, the default is false.

supportsGLDrawing

return true, if this device supports 3D GL drawing.
We do not depend on that being implemented.

Usage example(s):

     Display supportsGLDrawing

supportsHotKeys

can we register/deregister hotKeys?

supportsIconMasks

return true, if this device supports masked icons.
Assume true here - to be redefined in concrete classes.

Usage example(s):

     Display supportsIconMasks

supportsIconViews

return true, if this device supports views as icons.
Only Xservers (currently) support this.

Usage example(s):

     Display supportsIconViews

supportsMaskedDrawingWith: aForm

return true, if the device allows the given form pixmap
to be used as paint color.
False returned here, which forces higher level code to
perform the filling manually (by copying the form)
- redefined in most device classes.

supportsMaskedDrawingWithOffset: aForm

return true, if the device allows the given form pixmap
to be used as paint color AND it supports a pattern offset.
Pattern offset is needed to display the form in a scrolled view,
to correctly start bit-blitting within the pattern.
False returned here, which forces higher level code to
perform the filling manually (by copying the form)
- redefined in most device classes.

supportsNativeDialogs

true if this device supports native dialogs for warning and info dialogs

Usage example(s):

     Screen current supportsNativeDialogs

supportsNativeFileDialogs

true if this device supports native file dialogs

supportsNativeWidgetType: aWidgetTypeSymbol

true, if this device does support this kind of native widget.
If true, that kind of widget is created and NOT a standard view;
also, drawing is then typically done by that widget itself,
instead of by ST/X.
Currently, this is not supported and in an experimental stage.

Usage example(s):

     Screen current supportsNativeWidgetType:#Button

supportsNativeWidgets

true, if this device does support any kind of native widget.

Usage example(s):

     Screen current supportsNativeWidgets

supportsRoundShapedViews

return true, if this workstation supports round shaped
(elliptical & circular) windows.
Should be reimplemented in concrete classes which do support this.

Usage example(s):

     Display supportsRoundShapedViews

supportsScreenReading

can the screen be read?

supportsVariableHeightFonts

are fonts with variable height supported?
Subclasses may redefine this

supportsViewBackgroundPixmap: aForm

return true, if the device allows the given pixmap as
viewBackground. If false is returned,
drawing is done by (possibly) slower smalltalk code.
False returned here - redefined in some concrete device classes.

supportsViewGravity

return true, if this device supports gravity attributes.
We do not depend on the being implemented, but some resizing operations
are faster, it is is.

Usage example(s):

     Display supportsViewGravity

supportsWindowBorder: aNumber

return true, if this device supports bordered windows with the given borderWidth.
Right now, some drawing stuff depends on (at least) a border of 1 pixel
to be supported by the device.
ST/X's views are being rewritten to draw the border manually in the
future, since some systems do not support arbitrary wide borders (i.e. Windows).
Also, most (all?) systems only support drawing a solid border, which may or may not be
what we want.

Usage example(s):

     Display supportsWindowBorder:1

supportsXftFonts

can we draw into windows using Xft fonts?
Obviously, this will only ever be answered true by XWindow displays

supportsXftFontsInBitmaps

can we draw into bitmap/pixmaps using Xft fonts?
Obviously, this will only ever be answered true by XWindow displays.
This is a separate query (for now), because rendering into pixmaps
seems not to work currently

accessing-display geometry

boundingBox

return a rectangle representing the display's bounding box.
For Smalltalk-80 2.x compatibility

bounds

return a rectangle representing the display's bounding box.
For Smalltalk-80 4.x compatibility

Usage example(s):

     Screen default bounds

Usage example(s):

     Display bounds

captionHeight

return the height in pixels of the caption
(i.e. title bar) of topWindows.
Fallback of 0 (i.e. unknown) is returned here.
Applications should not depend on that returned value
to be exact - on some systems (windowManagers),
its value cannot be retrieved

center

return the centerpoint in pixels of the display;
caveat: might misbehave with multiple screens;
see centerOfMonitorHavingPointer

drawingResolution

return a point consisting of the actual drawing resolution
in pixel-per-inch horizontally and vertically.
On screen devices, this is the same as resolution; on postscript
devices, this is usually higher than the coordinate systems unit.
This method is provided for compatibility with postscript media,
to query the device if sub-pixel-coordinate drawing is possible.
(there are a few situations, in which resolution-independ drawing
leads to ugly looking output ... knowing about subPixel resolution
may help there.)

extent

return the extent of the display (in pixels)

Usage example(s):

     Display extent

extentOfResizeHandle

if the window system needs any area for a window resize handle (such as on MACOS-X),
this area's extent is returned here. It is assumed, that this handle is located at the lower-right
of the window.
0@0 is returned for systems which locate the resize handles outside the client area.
This may be used by the UI painter or programmatically to reserve some client area.
This method must be redefined for displays which need it (i.e. X11 on osx)

height

return the height of the display (in pixels)

Usage example(s):

Display height

heightInMillimeter

return the height in millimeter of the display

Usage example(s):

Display heightInMillimeter

heightInMillimeter: aNumber

set the height in millimeter of the display
- needed since some displays do not tell the truth or do not know it

horizontalPixelPerInch

return the number of horizontal pixels per inch of the display.
By default, this is computed from the width and widthInMM infos,
as returned by the system.
However, some systems report this wrong,
and also with mixed resolution monitors, we cannot depend on what
is returned (happens when an additional external monitor is
connected to a retina).
Thus, you can override the resolution via:
Display horizontalPixelPerMillimeter:pixels

Usage example(s):

     Display width
     Display height
     Display monitorBounds

     Display horizontalPixelPerInch
     Display verticalPixelPerInch
     Display widthInMillimeter:(Display width * 25.4) / 120
     Display heightInMillimeter:(Display height * 25.4) / 120

horizontalPixelPerMillimeter

return the number of horizontal pixels per millimeter of the display.
By default, this is computed from the width and widthInMM infos,
as returned by the system.
However, some systems report this wrong,
and also with mixed resolution monitors, we cannot depend on what
is returned (happens when an additional external monitor is
connected to a retina).
Thus, you can override the resolution via:
Display horizontalPixelPerMillimeter:pixels

Usage example(s):

     Display horizontalPixelPerMillimeter
     Display verticalPixelPerMillimeter
     Display width
     Display widthInMillimeter
     Display heightInMillimeter

horizontalPixelPerMillimeter: aNumber

set the number of horizontal pixels per millimeter of the display.
By default, this is computed from the width and widthInMM infos,
as returned by the system.
However, some systems report this wrong,
and also with mixed resolution monitors, we cannot depend on what
is returned (happens when an additional external monitor is
connected to a retina).
Thus, you can override the resolution via:
Display horizontalPixelPerMillimeter:pixels

monitorBounds

answer an Array with the bounds of all available monitors.
The first monitor in the Array is the primary monitor.
The allback here assumes a single monitor (see concrete subclasses)

Usage example(s):

        Screen current monitorBounds

monitorBoundsAt: aPoint

answer the bounds of the monitor which contains aPoint.

monitorBoundsAtPointer

answer the bounds of the monitor which contains the mouse pointer.

Usage example(s):

     Display monitorBoundsAtPointer  => (0@0) extent: (1280@778)

pixelPerInch

return the number of horizontal/vertical pixels per inch of the display as Point

Usage example(s):

Display pixelPerInch

pixelPerMillimeter

return the number of horizontal/vertical pixels per millimeter of the display as Point

Usage example(s):

Display pixelPerMillimeter

resolution

return a point consisting of pixel-per-inch horizontally and vertically.
This is an ST-80 compatibility method

setUsableHeight: h

setUsableWidth: w

smallestMonitorHeight

returns the usable height of the smallest monitor in a mult-monitor setup.
Subclasses supporting multi-monitors redefine this.

usableExtent

return the usable extent of the display (in pixels).
Normally, the same as extent, but may be smaller, in
case some menu space is taken up by the window manager (windows)

Usage example(s):

     Display extent
     Display usableExtent

usableHeight

returns the usable height of the display (in pixels)
Normally, the same as height, but may be smaller, in
case some menu space is taken up by the window manager (windows)

usableHeightAt: aPoint

returns the usable height of the display (in pixels) at a given point
Normally, the same as height, but may be smaller, in
case some menu space is taken up by the window manager (windows).
On multi-display systems with different sized screens, this should care for
which display is at the given x-position

usableWidth

returns the usable width of the display (in pixels)
Normally, the same as width, but may be smaller, in
case some menu space is taken up by the window manager (windows)

usableWidthAt: aPoint

returns the usable width of the display (in pixels) at a given point.
On multi-display systems with different sized screens, this should care for
which display is at the given x-position

verticalPixelPerInch

return the number of vertical pixels per inch of the display.
By default, this is computed from the height and heightInMM infos,
as returned by the system.
However, some systems report this wrong,
and also with mixed resolution monitors, we cannot depend on what
is returned (happens when an additional external monitor is
connected to a retina).
Thus, you can override the resolution via:
Display verticalPixelPerMillimeter:pixels

Usage example(s):

        Display verticalPixelPerInch

verticalPixelPerMillimeter

return the number of vertical pixels per millimeter of the display.
By default, this is computed from the height and heightInMM infos,
as returned by the system.
However, some systems report this wrong,
and also with mixed resolution monitors, we cannot depend on what
is returned (happens when an additional external monitor is
connected to a retina).
Thus, you can override the resolution via:
Display verticalPixelPerMillimeter:pixels

verticalPixelPerMillimeter: aNumber

set the number of vertical pixels per millimeter of the display.
By default, this is computed from the height and heightInMM infos,
as returned by the system.
However, some systems report this wrong,
and also with mixed resolution monitors, we cannot depend on what
is returned (happens when an additional external monitor is
connected to a retina).
Thus, you can override the resolution via:
Display verticalPixelPerMillimeter:pixels

virtualExtent

return the virtual extent of the display (in pixels).
On most systems, this is the same as the physical width;
except, if a window manager with a virtual desktop like olvwm
(simulating a bigger screen) is running.

virtualHeight

return the virtual height of the display (in pixels).
On most systems, this is the same as the physical height;
except, if a window manager with a virtual desktop like olvwm
(simulating a bigger screen) is running.

Usage example(s):

Display virtualHeight

virtualWidth

return the virtual width of the display (in pixels).
On most systems, this is the same as the physical width;
except, if a window manager with a virtual desktop like olvwm
(simulating a bigger screen) is running.

Usage example(s):

Display virtualWidth

width

return the width of the display (in pixels)

Usage example(s):

Display width

widthInMillimeter

return the width in millimeter of the display

Usage example(s):

Display widthInMillimeter

widthInMillimeter: aNumber

set the width in millimeter of the display
- needed since some displays do not tell the truth or do not know it

workableAreaBoundsAt: aPoint

return a rectangle representing the displays bounding box
of the workable area (without TaskBar etc.) of the monitor

accessing-keyboard mappings

buttonTranslation

return the buttonTranslation (for lefthanders)

buttonTranslation: anArray

set the buttonTranslation (for lefthanders)

Usage example(s):

     Screen current buttonTranslation
     Screen current buttonTranslation:#(1 2 1)

keyboardMap

return the keyboard map

Usage example(s):

     Screen current keyboardMap

keyboardMap: aMap

set the keyboard map

shortKeyPrefixSeparator

the saparator shown between the shortcut modified (CTRL, CMD etc.)
and the actual character. I.e. makes a Ctrl+A

shortKeyStringFor: symbolicOrRawKey

For given symbolic or raw key, return a user-friendly shortcut description string.
Examples:
#Find -> Ctrl+f (depending on your settings)
#CtrlX -> Ctrl+X

This method is used in menu panel (#shortcutKeyAsString) to display shortcuts in menus.

Usage example(s):

      Screen current shortKeyStringFor: #Find
      Screen current shortKeyStringFor: #Rename
      Screen current shortKeyStringFor: #CtrlX
      Screen current shortKeyStringFor: #UserInterrupt
      Screen current shortKeyStringFor: #Oacute
      Screen current shortKeyStringFor: #CursorLeft

accessing-misc

asPseudoDeviceWithoutXFTSupport

hack - see XWorkstation

defaultEventMask

return a mask to enable some events by default.

** This method must be redefined in concrete classes (subclassResponsibility) **

displayName

return the display name - that is the name of the display connection
or nil, for default display. For example, in X, this returns a string
like 'hostname:0' for remote connections, and nil for a default local
connection.
- nothing known here, but maybe redefined in subclasses.

Usage example(s):

     Display displayName

glVersion

return a string describing the GL version.
Since the generic display does not support 3D GL graphics,
a dummy is returned here.

Usage example(s):

     Display glVersion

platformName

return a string describing the display system's platform.
Please use isX11Platform or isWindowsPlatform.

Usage example(s):

     Display platformName

protocolVersion

return the display systems protocol version number.
Returns a dummy here

Usage example(s):

     Display protocolVersion

serverVendor

return a string describing the display systems server vendor.
Returns a dummy here

Usage example(s):

     Display serverVendor

vendorRelease

return the display systems release number.
Returns a dummy here.

Usage example(s):

     Display vendorRelease

bitmap/window creation

convertedIcon: iconArg: make certain, that the image argument is compatible with myself;
this means converting it to a format (typically: monochrome) which I support.
Return a compatible version of the icon.
convertedIconMask: aMask: return a version of the argument which can be used as an iconMask on myself.
Typically, this means conversion to a monochrome mask -
future versions may add alpha channel masks, if I support them ...
createBitmapFromArray: anArray width: w height: h: create a monochrome, depth1 bitmap from a given (byte-)array.
The rows are aligned to a multiple of 8

** This method must be redefined in concrete classes (subclassResponsibility) **
createBitmapFromFile: aString for: aForm
createBitmapWidth: w height: h: allocate a bitmap on the Xserver, the contents is undefined
(i.e. random). Return a bitmap id or nil

** This method must be redefined in concrete classes (subclassResponsibility) **
createPixmapWidth: w height: h depth: d: allocate a pixmap on the Xserver, the contents is undefined
(i.e. random). Return a bitmap id or nil

** This method must be redefined in concrete classes (subclassResponsibility) **
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: must be implemented by a concrete class

** This method must be redefined in concrete classes (subclassResponsibility) **
destroyGC: aGCId: destroy a GC

** This method must be redefined in concrete classes (subclassResponsibility) **
destroyPixmap: aDrawableId: ** This method must be redefined in concrete classes (subclassResponsibility) **
destroyView: aView withId: aWindowId: ** This method must be redefined in concrete classes (subclassResponsibility) **
gcFor: aDrawableId: create a GC for drawing into aDrawable

** This method must be redefined in concrete classes (subclassResponsibility) **
gcForBitmap: aDrawableId: create a GC for drawing into a bitmap drawable

** This method must be redefined in concrete classes (subclassResponsibility) **
realRootWindowFor: aView: the name of this method is historic;
- it will vanish
realRootWindowId: return the id of the real root window.
This may or may not be the view you see as background,
since some window managers install a virtual root window on top
of the real one. In this case, this method returns the id of the
covered real-root
(in contrast, rootWindowId returns the id of the visible one).
With most window systems, the realRoot is the same as the root window.
The real root is only seldom of any interest.
rootWindowFor: aView
rootWindowId: return the id of the root window.
This is the window you see as background,
however, it may or may not be the real physical root window,
since some window managers install a virtual root window on top
of the real one. If this is the case, that views id is returned here.

** This method must be redefined in concrete classes (subclassResponsibility) **

clipboard

clipboardEncoding: return the assumed default clibBoards encoding
if a raw string (i.e. without encoding information) is pasted.
Useful on X11, if a sjis or euc string is pasted from a netscape
or other program.
clipboardEncoding: aSymbol: set the assumed default clipBoard's encoding
if a raw string (i.e. without encoding information) is pasted.
Useful on X11, if a sjis or euc string is pasted from a netscape
or other program.
copyBufferAsString: return my current selection as a string
getClipboardObjectFor: drawableId: Retrieve the common per-display selection object.
For clipBoard mechanisms to work (into ST/X),
this must be redefined in a concrete subclass
getClipboardText: selectionBufferSymbol for: drawableId: Retrieve the common per-display selection text.
For clipBoard mechanisms to work (into ST/X),
this must be redefined in a concrete subclass
getCopyBuffer: return the copyBuffers contents.
This is an ST/X internal buffer (i.e. its not visible to alien views).
getCopyBufferHistory: return the copyBufferHistory.
This is an ST/X internal buffer (i.e. its not visible to alien views).
rememberCopyBuffer: remember the current copyBuffer value in the copyBuffer-history (for paste previous);
but only do so, if it is a string
rememberInCopyBufferHistory: aString: add aString to the copyBuffer LRU-cache.
Allows for the last 20 (or so) copy/cut strings to be recovered
(via Shift-Paste)
setClipboardObject: anObject owner: aWindowId: set the common per-display object selection.
This can be used by other Smalltalk(X) applications only.
For clipBoard mechanisms to work (out of ST/X),
this must be redefined in a concrete subclass to copy
anObject to the devices clipBoard.
setClipboardObject: anObject ownerView: aView: 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: aString owner: aView: Set the common per-display selection text.
For clipBoard mechanisms to work (out of ST/X),
this must be redefined in a concrete subclass to copy
aString to the devices clipBoard.
setClipboardText: aStringOrStringCollection ownerView: aView: set the clipboard's text - both the local one, and tell the display
that we have changed it (i.e. place it into the display's clipBoard).
setCopyBuffer: anObject: set the copyBuffers contents.
This is an ST/X internal buffer (i.e. its not visible to alien views).
setPrimaryText: text ownerView: view: Overridden in XWorkstation to support X's PRIMARY selection, intentionally void here
setSelection: anObject owner: aWindowId: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
setSelection: anObject ownerView: aView: Modified (format): / 20-04-2023 / 13:04:57 / Stefan_Vogel

** This is an obsolete interface - do not use it (it may vanish in future versions) **
setTextSelection: aString owner: aWindowId: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
setTextSelection: aString ownerView: aView: ** This is an obsolete interface - do not use it (it may vanish in future versions) **

color stuff

availableDitherColors

return the table of preallocated emergency ditherColors
plus possibly available fixColors.

blueComponentOfColor: colorId

get blue component (0..100) of color in map at:index

colorCell

allocate a color - return index or nil, if no color cell
can be allocated (out of colors or trueColor device)

colorMap

return my displays colormap, or nil, if the display is not colorMap based
(i.e. not PseudoColor)

Usage example(s):

	 those have no colorMap - we're done

Usage example(s):

     Display colorMap

colorNamed: aString

allocate a color with color name - return the color index (i.e. colorID).
Only a subset of the colorNames are available on all displays;
therefore, don't use this method; at least only for the common names such as red, green, blue etc.

Usage example(s):

     Screen current colorNamed:'red'

colorRed: redVal green: greenVal blue: blueVal

marked as obsolete by Stefan Vogel at 8-Sep-2023

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

colorScaledRed: red scaledGreen: green scaledBlue: blue

return an id for a color.
On trueColor displays, nothing is actually allocated,
and the returned colorID is formed by simply packing the RGB values.

** This method must be redefined in concrete classes (subclassResponsibility) **

deviceColorValueToPercent: deviceColorValue

** This method must be redefined in concrete classes (subclassResponsibility) **

ditherColors

return the table of preallocated emergency ditherColors

fixColors

return the table of preallocated fix colors (a colorCube),
or nil if no fix colors were preallocated.

fixGrayColors

return the table of preallocated fix grayScale colors,
or nil if no fix gray colors were preallocated.

freeColor: colorIndex

free a color on the display, when its no longer needed

** This method must be redefined in concrete classes (subclassResponsibility) **

getRGBFrom: index

get rgb components (0..100) of color in map at:index,
and evaluate the 3-arg block, aBlock with them

getRGBFrom: index into: aBlock

get rgb components (0..100) of color in map at:index,
and evaluate the 3-arg block, aBlock with them

getRGBFromName: colorNameArg

get rgb components (0..100) of color named colorName,
and return a 3-element array, containing them.
The method here only handles some often used colors;
getRGBFromName should not be used, since colorNames other
than those below are X specific.

getRGBFromName: colorName into: aBlock

get rgb components (0..100) of color named colorName,
and evaluate the 3-arg block, aBlock with them

Usage example(s):

     Display getRGBFromName:'red' into:[:r :g :b | r printCR. g printCR. b printCR.]

getScaledRGBFrom: index

get rgb components (0..devicesMaxColorVal) of color in map at:index,
and return a 3-element array containing them

** This method must be redefined in concrete classes (subclassResponsibility) **

getScaledRGBFrom: index into: aBlock

get rgb components (0..devicesMaxColorVal) of color in map at:index,
and evaluate the 3-arg block, aBlock with them

getScaledRGBFromName: colorName

get rgb components (0..devicesMaxColorVal) of color named colorName,
and return a 3-element array containing them

getScaledRGBFromName: colorName into: aBlock

get rgb components (0..devicesMaxColorVal) of color named colorName,
and evaluate the 3-arg block, aBlock with them.
Return nil for unknown color names.

greenComponentOfColor: colorId

get green component (0..100) of color in map at:index

listOfAvailableColors

return a list of all available colornames;
This method should not be used, since colornames are
very X specific. However, the names defined here are pretty common

numFixBlue

return the number of blue shades in the
preallocated fix color cube (or 0 if there is none)

numFixGreen

return the number of green shades in the
preallocated fix color cube (or 0 if there is none)

numFixRed

return the number of red shades in the
preallocated fix color cube (or 0 if there is none)

percentToDeviceColorValue: percent

** This method must be redefined in concrete classes (subclassResponsibility) **

redComponentOfColor: colorId

get red component (0..100) of color in map at:index

Usage example(s):

     Display redComponentOfColor:1

releaseFixColors

release the fix colorMap

Usage example(s):

     Display releaseFixColors

releaseFixGrayColors

release the fix colorMap

Usage example(s):

     Display releaseFixGrayColors

setColor: index red: redVal green: greenVal blue: blueVal

change color in map at:index to rgb (0..100).
This is a no-op on TrueColor systems.

setDitherColors: colors

set the table of preallocated emergency dither fix colors
These preallocated colors
(white, black, red, green, blue and a few grayScales) prevent
running out of colors later, when images have to be dithered or
pen colors must be approximated.
((Although, with such a small number of colors, the result will
definitely look poor))

setFixColors: colors numRed: nR numGreen: nG numBlue: nB

set the table of preallocated fix colors (a colorCube),
and the number of r/g/b entries in each dimension.

setFixGrayColors: colors

set the table of preallocated fix gray colors

converting

convertVirtualResolutionPointToCurrentResolutionPoint: aPoint: this is required when you want to access the root display coordinates correctly,
because may the os did scale the application (when the app is not high DPI aware),
and if the os do scale the application, the application gets a virtual display
with a diffrent resolution
convertVirtualResolutionRectangleToCurrentResolutionRectangle: aRectangle: this is required when you want to access the root display coordinates correctly,
because may windows did scale the application (when the app is not high DPI aware),
and if windows did scale the application, the application gets a virtual display
with a diffrent resolution

copying

deepCopyUsing: aDictionary postCopySelector: postCopySelector

cursor stuff

builtInCursorShapes: return a collection of standard cursor names.
Hre none is assumed - so all cursors are created as user cursors
(see Cursor>>initializeNewCursors)
colorCursor: aCursorId foreground: fgColor background: bgColor: change a cursors colors.
Ignored on systems which do not support colored cursors.
createCursorShape: aShapeSymbol: create a cursor given a shape-symbol; return a cursorID or nil.
This only works for a few standard cursors, and returns nil
if no such cursor exists.
Always care for a fallBack, in case of a nil return.
createCursorSourceForm: sourceForm maskForm: maskForm hotX: hx hotY: hy width: w height: h: create a cursor given 2 bitmaps (source, mask) and a hotspot.
Returns nil, if no cursor can be created (for any reason)

** This method must be redefined in concrete classes (subclassResponsibility) **
destroyCursor: aCursorId: free a cursor

** This method must be redefined in concrete classes (subclassResponsibility) **
needDeviceFormsForCursor: return true, if this device requires device-forms as opposed
to a simple bitmap-byteArray for creation.
Redefined in X- and Win- Workstation classes.

** This method must be redefined in concrete classes (subclassResponsibility) **
shapeNumberFromSymbol: shape: given a shape-symbol, return the corresponding cursor-number,
or nil if no such standard cursor exists.

drag & drop

dragFinish: dropHandle
drop: aCollectionOfDropObjects inWindowID: destinationId position: destinationPoint rootPosition: rootPoint: device specific drop here.
Answer true, if the drop was successfull, false otherwise.

drawing

copyFromId: sourceId x: srcX y: srcY gc: srcGCId to: destId x: dstX y: dstY gc: dstGCId width: w height: h: do a bit-blt

** This method must be redefined in concrete classes (subclassResponsibility) **
copyFromPixmapId: sourceId x: srcX y: srcY gc: srcGCId to: destId x: dstX y: dstY gc: dstGCId width: w height: h: do a bit-blt from a pix- or bitmap.
Here, fall back into copyFromId:, which should also work.
Subclasses may redefine this for more performance or if required
copyPlaneFromId: sourceId x: srcX y: srcY gc: srcGCId to: destId x: dstX y: dstY gc: dstGCId width: w height: h: do a bit-blt, using the low-bit plane of the source only

** This method must be redefined in concrete classes (subclassResponsibility) **
copyPlaneFromPixmapId: sourceId x: srcX y: srcY gc: srcGCId to: destId x: dstX y: dstY gc: dstGCId width: w height: h: do a bit-blt from a pix- or bitmap, using the low-bit plane of the source only.
Here, fall back into copyPlaneFromId:, which should also work.
Subclasses may redefine this for more performance or if required
displayArcX: x y: y width: width height: height from: startAngle angle: angle in: aDrawableId with: aGCId: draw an arc

** This method must be redefined in concrete classes (subclassResponsibility) **
displayLineFromX: x0 y: y0 toX: x1 y: y1 in: aDrawableId with: aGCId: draw a line

** This method must be redefined in concrete classes (subclassResponsibility) **
displayLinesFromX: xStart step: xStep yValues: ydata scaleY: yScale transY: yTrans in: drawableId with: gcId: draw a polygon starting at x; the y values derives from the collection yValues.
The associated x is a multiple of step. Each y value will be scaled and translated.
The implementation here is a fallback, using the line-draw primitive;
devices which support fast drawing of a polygon may redefine this for more performance.
displayOpaqueString: aString from: index1 to: index2 x: x y: y in: aDrawableId with: aGCId: draw a sub-string - draw foreground on background.
If the coordinates are not integers, retry with rounded.
displayOpaqueString: aString x: x y: y in: aDrawableId with: aGCId: draw a string - draw foreground on background.
If the coordinates are not integers, retry with rounded.
displayPointX: x y: y in: aDrawableId with: aGCId: draw a point

** This method must be redefined in concrete classes (subclassResponsibility) **
displayPointsX: xColl y: yColl in: aDrawableId with: aGCId: draw a collection of points. Each element of xColl/yCollmust be integer,
otherwise, an error is triggered.
Slow fallback here for protocol completeness
displayPolygon: aPolygon in: aDrawableId with: aGCId: draw a polygon

** This method must be redefined in concrete classes (subclassResponsibility) **
displayPolylines: arrayOfPoints in: aDrawableId with: aGCId: draw a bunch of lines
displayRectangleX: x y: y width: width height: height in: aDrawableId with: aGCId: draw a rectangle

** This method must be redefined in concrete classes (subclassResponsibility) **
displayString: aString from: index1 to: index2 x: x y: y in: aDrawableId with: aGCId: draw a sub-string - draw foreground only.
If the coordinates are not integers, retry with rounded.
displayString: aString from: i1 to: i2 x: x y: y in: aDrawableId with: aGCId opaque: opaque: draw part of a string

** This method must be redefined in concrete classes (subclassResponsibility) **
displayString: aString x: x y: y in: aDrawableId with: aGCId: draw a string - draw foreground only.
If the coordinates are not integers, retry with rounded.
displayString: aString x: x y: y in: aDrawableId with: aGCId opaque: opaque: draw a string
drawBits: imageBits bitsPerPixel: bitsPerPixel depth: imageDepth padding: pad width: imageWidth height: imageHeight x: srcx y: srcy into: aDrawableId x: dstx y: dsty width: w height: h with: aGCId: draw a bitimage which has depth id, width iw and height ih into
the drawable. draw a region of w/h pixels from srcx/srcy to dstx/dsty.
It has to be checked elsewhere, that server can do it with the given
depth; also it is assumed, that the colormap is setup correctly.
The actual bits per pixel may be different from the depth (for example,
on a depth-15 device, 16 bits/pixel may be used; also, many depth-24
systems actually use 32 bits/pixel)

** This method must be redefined in concrete classes (subclassResponsibility) **
drawBits: imageBits bitsPerPixel: bitsPerPixel depth: imageDepth width: imageWidth height: imageHeight x: srcx y: srcy into: aDrawableId x: dstx y: dsty width: w height: h with: aGCId: draw a bitimage which has depth id, width iw and height ih into
the drawable. draw a region of w/h pixels from srcx/srcy to dstx/dsty.
It has to be checked elsewhere, that server can do it with the given
depth; also it is assumed, that the colormap is setup correctly.
The actual bits per pixel may be different from the depth (for example,
on a depth-15 device, 16 bits/pixel may be used; also, many depth-24
systems actually use 32 bits/pixel).
This assumes a padding of 8-bits (i.e. byte-boundary),
which is the natural padding within ST/X.
drawBits: imageBits depth: imageDepth padding: pad width: imageWidth height: imageHeight x: srcx y: srcy into: aDrawableId x: dstx y: dsty width: w height: h with: aGCId: draw a bitimage which has depth id, width iw and height ih into
the drawable. draw a region of w/h pixels from srcx/srcy to dstx/dsty.
It has to be checked elsewhere, that server can do it with the given
depth; also it is assumed, that the colormap is setup correctly
drawBits: imageBits depth: imageDepth width: imageWidth height: imageHeight x: srcx y: srcy into: aDrawableId x: dstx y: dsty width: w height: h with: aGCId: draw a bitimage which has depth id, width iw and height ih into
the drawable. draw a region of w/h pixels from srcx/srcy to dstx/dsty.
It has to be checked elsewhere, that server can do it with the given
depth; also it is assumed, that the colormap is setup correctly.
This assumes a padding of 8-bits (i.e. byte-boundary),
which is the natural padding within ST/X.
fillArcX: x y: y width: width height: height from: startAngle angle: angle in: aDrawableId with: aGCId: fill an arc.
The angles may be floats or integer - they are given in degrees.

** This method must be redefined in concrete classes (subclassResponsibility) **
fillPolygon: aPolygon in: aDrawableId with: aGCId: fill a polygon

** This method must be redefined in concrete classes (subclassResponsibility) **
fillRectangleX: x y: y width: width height: height in: aDrawableId with: aGCId: fill a rectangle

** This method must be redefined in concrete classes (subclassResponsibility) **

enumerating

allTopViews

return a collection of all my known top views

allTopViewsAndLabelsSortedFilteringWindowGroups: windowGroupFilterOrNil

helper to return all windows on THIS screen sorted by a label to suite

Usage example(s):

     Display allTopViewsAndLabelsSortedFilteringWindowGroups:nil

allTopViewsFilteringWindowGroups: windowGroupFilterOrNil withLabelsDo: aBlock

helper enumerating all windows on THIS device with a label to suite

allViewsDo: aBlock

evaluate the argument, aBlock for all of my known views.
Warning: do not use this to remove a view
(never remove elements from an enumerated collection)

Usage example(s):

     View defaultStyle:#iris.
     Display allViewsDo:[:v | v initStyle. v redraw]

Usage example(s):

     View defaultStyle:#next.
     Display allViewsDo:[:v | v initStyle. v redraw]

Usage example(s):

     View defaultStyle:#normal.
     Display allViewsDo:[:v | v initStyle. v redraw]

error handling

primitiveFailedOrClosedConnection: sent by all primitives here, when something is wrong.
Check what was wrong and raise a corresponding error here.
resourceOfId: id: search through all device stuff for a resource.
Needed for error handling.

Since id may be an ExternalAddress, do not compare with ==

event forwarding

buttonMotion: buttonAndModifierState x: x y: y view: aView

forward a button-motion for some view

buttonMultiPress: button x: x y: y view: aView

forward a button-multi-press event for some view

buttonPress: buttonArg x: x y: y view: aView

forward a button-press event for some view

buttonRelease: button x: x y: y view: aView

forward a button-release event for some view

configureX: x y: y width: w height: h view: aView

forward a configure (i.e. size or position change) event for some view

coveredBy: otherView view: aView

forward a covered for some view
(aView has been covered by otherView)

destroyedView: aView

forward a destroyed event for some view

exposeX: x y: y width: w height: h view: aView

forward an expose for some view

focusInView: aView

forward a focusIn event for some view

focusOutView: aView

forward a focusOut event for some view

graphicsExposeX: x y: y width: w height: h final: final view: aView

forward a graphic expose for some view

hotkeyWithId: aHotkeyId key: aKey view: aView

forward a hotkey press for a view

keyPress: untranslatedKeyArg code: keyCode x: x y: y view: aView

forward a key-press event for some view

keyPress: untranslatedKeyArg x: x y: y view: aView

forward a key-press event for some view

Usage example(s):

Logger info:'Display keyPress: %1 (%2@%3)' with:untranslatedKey with:x with:y.

keyRelease: untranslatedKeyArg code: keyCode x: x y: y view: aView

forward a key-press event for some view

keyRelease: untranslatedKeyArg x: x y: y view: aView

forward a key-release event for some view

Usage example(s):

Logger info:'Display keyRelease: %1 (%2@%3)' with:untranslatedKey with:x with:y.

mappedView: aView

forward a mapped event for some view

mouseWheelMotion: buttonState x: x y: y amount: amountArg deltaTime: dTime view: aView

the mousewheel was moved by some amount (signed).
This event is sent to the current pointer view (like keyPress/release).

noExposeView: aView

forward a noExpose event for some view

pointerEnter: buttonState x: x y: y view: aView

forward a pointer enter for some view

pointerLeave: buttonState view: aView

forward a pointer leave for some view

saveAndTerminateView: aView

forward a saveAndTerminate event for some view

terminateView: aView

forward a terminate event for some view

Usage example(s):

Logger debug:'terminateView:%1 to sensor %2' with:aView with:sensor.

unmappedView: aView

forward an unmapped event for some view

event handling

addToKnownScreens
checkForEndOfDispatch: if there are no longer any views of interest - stop dispatch.
This ends the dispatcher process when the last view is closed on that device.
We only do this for displays other that the default Display.
cleanupAfterDispatch: make sure, no one is waiting
dispatchEvent: get and process the next pending event - for any view
dispatchEventFor: aViewIdOrNil withMask: eventMask: central event handling method:
get next event and send an appropriate message to the view's sensor,
or to the view directly (if the view has none).
If the argument aViewIdOrNil is nil, events for any view are processed,
otherwise only events for the view with given id are processed
(in this case, nothing is done if no events are pending);
if the argument aMask is nonNil, only events for this eventMask are
handled. The mask is a device dependent event mask.

** This method must be redefined in concrete classes (subclassResponsibility) **
dispatchLoop: the actual event dispatching loop.
dispatchModalWhile: aBlock: get and process next event for any view as long as the
argument-block evaluates to true.
This is a modal loop, not switching to other processes,
effectively polling the device in a (nice) busy loop.
This should only be (and is only) used for emergency cases.
(such as a graphical debugger, debugging the event-dispatcher itself)
dispatchPendingEvents: go dispatch events as long as there is one.
dispatchProcessPriority
disposeButtonEventsFor: aViewIdOrNil: dispose (i.e. forget) all pending button events on this display
disposeEvents: dispose (i.e. forget) all events pending on this display
disposeEventsWithMask: aMask for: aWindowId: dispose (throw away) specific events

** This method must be redefined in concrete classes (subclassResponsibility) **
eventMaskFor: anEventSymbol: ** This method must be redefined in concrete classes (subclassResponsibility) **
eventPending: return true, if any event is pending

** This method must be redefined in concrete classes (subclassResponsibility) **
eventPending: anEventSymbol for: aWindowId: return true, if a specific event is pending for a specific window.
This expects device independent event symbols (such as #buttonPress,
#buttonRelease etc.) as first argument.

** This method must be redefined in concrete classes (subclassResponsibility) **
eventPending: anEventMask for: aWindowId withSync: doSync: return true, if any of the masked events is pending
for a specific window.
This expects a device dependent event mask as first argument.

** This method must be redefined in concrete classes (subclassResponsibility) **
eventPendingWithSync: doSync: return true, if any event is pending

** This method must be redefined in concrete classes (subclassResponsibility) **
eventQueued: return true, if any event is pending in some internal queue.
The fallBack here returns true if events are pending on the display connection;
only devices which use internal queues (i.e. Xlib) need to redefine this.
eventQueuedAlready: return true, if any event is pending in some internal queue.
The fallBack here returns true if events are pending on the display connection;
only devices which use internal queues (i.e. Xlib) need to redefine this.
eventsPending: anEventMask for: aWindowId withSync: doSync: obsolete - will vanish.
getEventFor: aViewIdOrNil withMask: eventMask into: anEventArray: read next event if there is one and put event's data into anEventArray.
If aViewIdOrNil is nil, events for any view are fetched;
otherwise only events for that specific view will be fetched.
Returns true, if there was an event, false otherwise.
This method may block - so you better check for pending events
before calling for it.

** This method must be redefined in concrete classes (subclassResponsibility) **
registerHotKeyForWindow: aDrawableId withId: anId modifiers: aModifier virtualKeyCode: aVirtualKeyCode: Defines a system-wide hotkey.

** This method must be redefined in concrete classes (subclassResponsibility) **
setEventMask: aMask in: aWindowId: arrange that only events from aMask are reported to a view.
Highly device specific, to be defined in concrete subclasses

** This method must be redefined in concrete classes (subclassResponsibility) **
setupDispatchLoop: create & start the display event dispatch process.
startDispatch: create & start the display event dispatch process.
stopDispatch: stop the dispatch process
unregisterHotKeyForWindow: aDrawableId withId: anId: Release a system-wide hotkey.

** This method must be redefined in concrete classes (subclassResponsibility) **
viewIsRelevantInCheckForEndOfDispatch: aView: return true, if the argument is not to be treated as a user view.
These, if any of them is still present, will prevent the endOfDispatch if the
exitOnLastClose flag is set.

event sending

sendKeyOrButtonEvent: typeSymbol x: xPos y: yPos keyOrButton: keySymCodeOrButtonNr state: stateMask toViewId: targetId: send a keyPress/Release or buttonPress/Release event to some (possibly alien) view.
TypeSymbol must be one of: #keyPress, #keyRelease, #buttonPress , #buttonRelease.
For buttonEvents, the keySymCodeOrButtonNr must be the buttons number (1, 2 ...);
for key events, it can be either a symbol (as listen in X's keySyms)
or a numeric keysym code. If state is nil, the modifier bits (shift & control)
are computed from the keyboardMap - if non-nil, these are passed as modifierbits.
The non-nil case is the lowlevel entry, where state must include any shift/ctrl information
(not very user friendly)

** This method must be redefined in concrete classes (subclassResponsibility) **
simulateKeyboardInput: aCharacterOrString inViewId: viewId: send input to some other view, by simulating keyPress/keyRelease
events.
Only a few control characters are supported.
Notice: not all alien views allow this kind of synthetic input;
some simply ignore it.

font helpers

ascentOf: aFontId: return the number of pixels above the base line of a font

** This method must be redefined in concrete classes (subclassResponsibility) **
descentOf: aFontId: return the number of pixels below the base line of a font

** This method must be redefined in concrete classes (subclassResponsibility) **
encodingOf: aFontId: return the characterEncoding of a font.
Here, we assume an iso8859-1 encoding
maxAscentOf: aFontId: return the number of pixels above the base line of the tallest character
in a font

** This method must be redefined in concrete classes (subclassResponsibility) **
maxDescentOf: aFontId: return the number of pixels below the base line of the tallest character
in a font

** This method must be redefined in concrete classes (subclassResponsibility) **
maxWidthOfFont: aFontId: return the width in pixels of the widest character a specific font

** This method must be redefined in concrete classes (subclassResponsibility) **
minWidthOfFont: aFontId: return the width in pixels of the smallest character a specific font

** This method must be redefined in concrete classes (subclassResponsibility) **

font stuff

facesInFamily: aFamilyName

return a set of all available font faces in aFamily on this display

Usage example(s):

     Display facesInFamily:'times'
     Display facesInFamily:'fixed'

facesInFamily: aFamilyName filtering: filterBlock

return a set of all available font faces in aFamily on this display.
But only those matching filterBlock (if nonNil).

Usage example(s):

     Display facesInFamily:'fixed' filtering:[:f |
        f encoding notNil and:[f encoding startsWith:'jis']]

flushListOfAvailableFonts

flush any cached font information - dummy here,
but should be implemented in subclasses, which keep
a list of available device fonts.
This should be flushed, to allow update whenever new fonts
are installed or the system-font-path changes.

fontFamilies

return a set of all available font families on this display

Usage example(s):

     Display fontFamilies

fontFamiliesFiltering: aFilterBlock

return a set of all available font families on this display,
but only those matching aFilterBlock (if nonNil).

Usage example(s):

     Display fontFamiliesFiltering:[:f |
        f encoding notNil and:[f encoding startsWith:'jis']]

fontMetricsOf: fontId

return a fonts metrics info object

fontResolutionOf: fontId

return the resolution (as dpiX @ dpiY) of the font - this is usually the displays resolution,
but due to errors in some XServer installations, some use 75dpi fonts on higher
resolution displays and vice/versa.

fontsFiltering: aFilterBlock

return a set of all available font on this display,
but only those matching aFilterBlock (if nonNil).

Usage example(s):

     Display fontsFiltering:[:f |
        f encoding notNil and:[f encoding startsWith:'jis']]

fontsInFamily: aFamilyName face: aFaceName filtering: filter

return a set of all available fonts in aFamily/aFace on this display.
But only those matching filter (if nonNil).

Usage example(s):

     Display fontsInFamily:'fixed' face:'medium' filtering:[:f |
	f encoding notNil and:[f encoding startsWith:'jis']]

fontsInFamily: aFamilyName face: aFaceName style: aStyleName filtering: filter

return a set of all available font in aFamily/aFace/aStyle
on this display.
But only those matching filter (if nonNIl).

Usage example(s):

     Display fontsInFamily:'fixed' face:'medium' style:'roman' filtering:[:f |
	f encoding notNil and:[f encoding startsWith:'jis']]

Usage example(s):

     Display fontsInFamily:'fixed' face:'*' style:'roman' filtering:[:f |
	f encoding notNil and:[f encoding startsWith:'jis']]

Usage example(s):

     Display fontsInFamily:'courier' face:'medium' style:'roman' filtering:nil
     Display fontsInFamily:'courier' face:'normal' style:'roman' filtering:nil
     Display fontsInFamily:'Courier' face:'normal' style:'roman' filtering:nil

fontsInFamily: aFamilyName filtering: filter

return a set of all available font in aFamily on this display.
But only those matching filterBlock (if nonNil).

Usage example(s):

     Display fontsInFamily:'fixed' filtering:[:f |
	f encoding notNil and:[f encoding startsWith:'jis']]

Usage example(s):

     Display fontsInFamily:'*' filtering:[:f |
	f encoding notNil and:[f encoding startsWith:'jis']]

fullFontNameOf: aFontId

return the full name of a font.
Here, we return nil, not knowing anything about fonts

getDefaultFontWithEncoding: encoding

return a default font id
- used when class Font cannot find anything usable.
Subclasses will redefine this.

** This method must be redefined in concrete classes (subclassResponsibility) **

getFontWithFamily: familyString face: faceString style: styleString pixelSize: sizeArg encoding: encodingSym

try to get the specified font, return id.
If not available, try next smaller font.
If no font fits, return nil

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

getFontWithFamily: familyString face: faceString style: styleString size: sizeArg encoding: encodingSym

try to get the specified font, return id.
If not available, try next smaller font.
If no font fits, return nil

getFontWithFamily: familyString face: faceString style: styleString size: sizeArg sizeUnit: sizeUnit encoding: encodingSym

try to get the specified font, return id.
If not available, try next smaller font.
If no font fits, return nil

** This method must be redefined in concrete classes (subclassResponsibility) **

heightOf: aString from: index1 to: index2 inFont: aFontId

return the width in pixels of a substring in a specific font

** This method must be redefined in concrete classes (subclassResponsibility) **

heightOf: aString inFont: aFontId

return the width in pixels of a string in a specific font

listOfAvailableFonts

return a list containing all fonts on this display.
The returned list is an array of FontDescriptions.

** This method must be redefined in concrete classes (subclassResponsibility) **

pixelSizesInFamily: aFamilyName face: aFaceName style: aStyleName filtering: filterBlock

return a set of all available pixel sizes in aFamily/aFace/aStyle on this display.
But only those matching filterBlock (if notNil).

Usage example(s):

     Display
        pixelSizesInFamily:'fixed' face:'medium' style:'roman'
        filtering:[:f |
            f encoding notNil and:[f encoding startsWith:'jis']
        ]

     Display
        pixelSizesInFamily:'arial' face:'medium' style:'roman'
        filtering:[:f |
            f encoding == #'ms-ansi'
        ]

releaseFont: aFontId

free a font

** This method must be redefined in concrete classes (subclassResponsibility) **

sizesInFamily: aFamilyName face: aFaceName style: aStyleName

return a set of all available font sizes in aFamily/aFace/aStyle
on this display

Usage example(s):

     Display sizesInFamily:'times' face:'medium' style:'italic'

sizesInFamily: aFamilyName face: aFaceName style: aStyleName filtering: filterBlock

return a set of all available font sizes in aFamily/aFace/aStyle
on this display.
But only those matching filterBlock (if notNil).

Usage example(s):

     Display sizesInFamily:'fixed' face:'medium' style:'roman' filtering:[:f |
        f encoding notNil and:[f encoding startsWith:'jis']]

stylesInFamily: aFamilyName face: aFaceName

return a set of all available font styles in aFamily/aFace on this display

Usage example(s):

     Display stylesInFamily:'times' face:'medium'
     Display stylesInFamily:'times' face:'bold'

stylesInFamily: aFamilyName face: aFaceName filtering: filterBlock

return a set of all available font styles in aFamily/aFace on this display.
But only those matching filterBlock (if notNil).

Usage example(s):

     Display stylesInFamily:'fixed' face:'medium' filtering:[:f |
        f encoding notNil and:[f encoding startsWith:'jis']]

widthOf: aString from: index1 to: index2 inFont: aFontId

return the width in pixels of a substring in a specific font

** This method must be redefined in concrete classes (subclassResponsibility) **

widthOf: aString inFont: aFontId

return the width in pixels of a string in a specific font

grabbing

activeKeyboardGrab: return the view, which currently has the keyboard grabbed,
or nil, if there is none
activePointerGrab: return the view, which currently has the pointer grabbed,
or nil, if there is none
grabKeyboardIn: aWindowId: grab the keyboard - all keyboard input will be sent to the view
with id aWindowId

** This method must be redefined in concrete classes (subclassResponsibility) **
grabKeyboardInView: aView: grab the keyboard - all keyboard input will be sent to aView.
Return true if ok, false if it failed for some reason.
grabPointerIn: aWindowId: grap the pointer; all pointer events will be reported to the view
with id aWindowId. Return true if ok, false if it failed for some reason.
grabPointerIn: aWindowId withCursor: cursorId pointerMode: pMode keyboardMode: kMode confineTo: confineId: grap the pointer - all pointer events will be reported to aWindowId. The cursor will be set to cursorId
for the duration of the grab. For pMode/kMode, see X documentation. The pointer is restricted to
confineId - if non-nil.

** This method must be redefined in concrete classes (subclassResponsibility) **
grabPointerIn: aWindowId withCursorId: aCursorIdOrNil: grap the pointer; all pointer events will be reported to the view
with id aWindowId. Return true if ok, false if it failed for some reason.
grabPointerInView: aView: grap the pointer; all pointer events will be reported to
aView. Return true if ok, false if it failed for some reason.
grabPointerInView: aView withCursor: aCursorOrNil: grap the pointer; all pointer events will be reported to
aView. Return true if ok, false if it failed for some reason.
setActivePointerGrab: aView: DO NOT USE. private kludge - will vanish
ungrabKeyboard: release the keyboard

** This method must be redefined in concrete classes (subclassResponsibility) **
ungrabPointer: release the pointer

** This method must be redefined in concrete classes (subclassResponsibility) **

graphic context stuff

noClipIn: aDrawableId gc: aGCId: disable clipping rectangle

** This method must be redefined in concrete classes (subclassResponsibility) **
setBackground: bgColorIndex in: aGCId: set background color-index to be drawn with

** This method must be redefined in concrete classes (subclassResponsibility) **
setBackgroundColor: color in: aGCId: set background color to be drawn with
setBitmapMask: aBitmapId in: aGCId: set or clear the drawing mask - a bitmap mask using current fg/bg

** This method must be redefined in concrete classes (subclassResponsibility) **
setClipByChildren: aBool in: aDrawableID gc: aGCId: enable/disable drawing into child views

** This method must be redefined in concrete classes (subclassResponsibility) **
setClipX: clipX y: clipY width: clipWidth height: clipHeight in: drawableId gc: aGCId: clip to a rectangle

** This method must be redefined in concrete classes (subclassResponsibility) **
setDashes: dashList dashOffset: offset in: aGCId: set dash attributes.
Ignored here - it may be left unimplemented by some devices.

** This method must be redefined in concrete classes (subclassResponsibility) **
setFont: aFontId in: aGCId: set font to be drawn in

** This method must be redefined in concrete classes (subclassResponsibility) **
setForeground: fgColorIndex background: bgColorIndex function: blitOpSymbol in: aGCId: set foreground and background color-indices and blit-function to be drawn with
setForeground: fgColorIndex background: bgColorIndex in: aGCId: set foreground and background color-indices to be drawn with
setForeground: fgColorIndex in: aGCId: set the foreground color-index to be drawn with

** This method must be redefined in concrete classes (subclassResponsibility) **
setForegroundColor: fgColor backgroundColor: bgColor in: aGCId: set foreground and background colors to be drawn with
setForegroundColor: color in: aGCId: set the foreground color to be drawn with
setFunction: aFunctionSymbol in: aGCId: set alu function to be drawn with.
functionSymbol is one of:
#copy,#copyInverted,#xor,#and,#andReverse
#andInverted,#or,#orReverse,#orInverted
#invert,#clear,#set,#noop,#equiv,#nand

** This method must be redefined in concrete classes (subclassResponsibility) **
setGraphicsExposures: aBoolean in: aGCId: set or clear the graphics exposures flag

** This method must be redefined in concrete classes (subclassResponsibility) **
setLineWidth: aNumber style: lineStyle cap: capStyle join: joinStyle in: aGCId: set line attributes

** This method must be redefined in concrete classes (subclassResponsibility) **
setMaskOriginX: orgX y: orgY in: aGCid: set the mask origin

** This method must be redefined in concrete classes (subclassResponsibility) **
setPixmapMask: aPixmapId in: aGCId: set or clear the drawing mask - a pixmap mask providing full color

** This method must be redefined in concrete classes (subclassResponsibility) **

hooks

addModalWindowListener: aListener
addNonModalWindowListener: aListener
addSelectionHandler: someone: ignored here
modalWindowListenersDo: aBlock: aboutToOpenModalWindowHooks := nil
nonModalWindowListenersDo: aBlock
removeModalWindowListener: aListener
removeNonModalWindowListener: aListener
removeSelectionHandler: someone: ignored here
withoutExitingOnLastCloseDo: aBlock: evaluate a block, but do not exit when the last view is closed.
This is used when an operation is to be performed, which possibly
leads to a temporary no-more-windows-open situation.
Concrete: when reopening a launcher

initialization & release

brokenConnection: the connection to the display device was lost.
close: close down connection to Display - usually never done for the main screen
closeConnection: close down connection to Display - usually never done

** This method must be redefined in concrete classes (subclassResponsibility) **
emergencyCloseConnection: close down connection to the Display in case of emergency;
this is usually invoked after an error and should not try to flush
any outstanding graphics requests - usually never done
exitOnLastClose: aBoolean: set/clear the flag which controls if the
event dispatching should stop when the last view is closed.
initializeDefaultKeyboardMappingsIn: aKeyboardMap: this is called to pre-initialize a new keyboard map.
Usually, a real mapping comes from the keyboard.rc startup file,
but here, some mappings are defined in case the keyboard.rc file is
missing (i.e. for standalone programs which have not been deployed correctly)
initializeDefaultValues
initializeDeviceResources: initialize heavily used device resources - to avoid looking them up later
initializeDeviceSignals
initializeFor: aDisplayOrNilForAny: initialize the receiver for a connection to a display. If the
argument is non-nil, it should specify which workstation should be
connected to (in a device specific manner). For X displays, this is
to be the display-string i.e. hostname:displayNr.
If the argument is nil, connect to the default display.

** This method must be redefined in concrete classes (subclassResponsibility) **
initializeKeyboardMap: keystrokes from the server are translated via the keyboard map.
Untranslated keystrokes arrive either as characters, or symbols
(which are the keySyms as symbol). The mapping table which is
setup here, is used in sendKeyPress:... later.
Here, an empty (no-translation) keyboard map is setup initially;
this is usually filled via the keyboard.rc startup file.
initializeModifierMappings: Display initializeModifierMappings
initializeScreenProperties: setup screen specific properties.
initializeViewStyle: late viewStyle init - if no viewStyle has been read yet.
invalidateConnection: clear my connection handle - sent after an imageRestart to
forget about our previous life
nativeWidgets: aBoolean: enable/disable native widgets on a display
reinitialize: historic leftover (old subclasses call super reinitialize)
reinitializeFor: aDisplayName: reinit after snapin
releaseDeviceResources: release any cached device resources.
This is invoked when closed or when the display connection is broken
(i.e. be prepared to not be able to release resources regularily)

interactive queries

colorFromUser

let user specify a point on the screen (by pressing the left button),
return the color of that pixel.

Usage example(s):

     Display colorFromUser

originFromUser: extent

let user specify a rectangle's origin on the screen, return the rectangle.
Start with initialRectangle.
Can be used for dragging operations.

Usage example(s):

     Display originFromUser:200@200

pointFromUser

let user specify a point on the screen (by pressing the left button).
The point is relative to/within the root window
(which makes trouble with OSX, where the top menu is not included in X's root window)

Usage example(s):

     Display pointFromUser

pointFromUserShowing: aCursor

let user specify a point on the screen (by pressing leftButton).
Show aCursor while waiting.
The point is relative to/within the root window
(which makes trouble with OSX, where the top menu is not included in X's root window)

Usage example(s):

     Display pointFromUserShowing:(Cursor stop)
     Display pointFromUserShowing:(Cursor crossHair)
     Display pointFromUserShowing:(Cursor origin)
     Display pointFromUser

pointFromUserShowing: aCursor positionFeedback: feedbackBlockOrNil

let user specify a point on the screen (by pressing leftButton).
Show aCursor while waiting. Pressing shift or ctrl cancels the operation,
and aborts.
The point is relative to/within the root window
(which makes trouble with OSX, where the top menu is not included in X's root window)

Usage example(s):

     Display pointFromUserShowing:(Cursor stop)
     Display pointFromUserShowing:(Cursor crossHair)
     Display pointFromUserShowing:(Cursor origin)
     Display pointFromUser

rectangleFromUser

let user specify a rectangle in the screen, return the rectangle.
If the user presses ESC, an AbortSignal is raised.
The rectangle is relative to/within the root window
(which makes trouble with OSX, where the top menu is not included in X's root window)

Usage example(s):

     Display rectangleFromUser

rectangleFromUser: initialRectangle

let user specify a rectangle on the screen, return the rectangle.
Start with initialRectangle.
The point is relative to/within the root window
(which makes trouble with OSX, where the top menu is not included in X's root window).
A helper for rectangleFromUser; can also be used for resizing operations.

Usage example(s):

     Display rectangleFromUser:(100@100 corner:300@300)

rectangleFromUser: initialRectangle keepExtent: keepExtent

let user specify a rectangle on the screen, return the rectangle.
Start with initialRectangle.
If keepExtent is true, only the origin is asked for.
A helper for rectangleFromUser;
can also be used for resizing operations.

Usage example(s):

     Display rectangleFromUser
     Display rectangleFromUser:(100@100 corner:300@300)
     Display rectangleFromUser:(100@100 corner:300@300) keepExtent:true

topviewFromUser

let user specify a view on the screen; if the selected view is
not an ST/X view, nil is returned.
Otherwise, the topview is returned.

Usage example(s):

     Display topviewFromUser

viewFromUser

let user specify a view on the screen; if the selected view is
not an ST/X view, nil is returned.
This returns the view being clicked in, which is not always a topView.
(send topView to the returned view or use topviewFromUser,
to get the topview)

Usage example(s):

     Display viewFromUser

Usage example(s):

     |v|
     v := Display viewFromUser.
     v notNil ifTrue:[v topView] ifFalse:[nil]

viewIdFromUser

let user specify a view on the screen, return its window id.
This works even for non smalltalk views.
This returns the id of the view being clicked in,
which is not always a topView.

Usage example(s):

     Display viewIdFromUser

keyboard mapping

altModifiers

Return the set of keys which are treated as Alt-keys.
This set is initialized at startup from what the server thinks
are alt-keys.

Usage example(s):

     Display altModifiers

altModifiers: arrayOfAltModifierKeys

Change the set of keys which are treated as Alt-keys.
This is useful for ST/X on OSX on XQuartz, where the window manager
uses the CMD keys, making it unavailable for ST/X.
Here, we map the left ALT key onto the command key
(see keyboard.rc). Lefthanders might want to use the right ALT key for that.

Usage example(s):

     Screen current cmdModifiers
     Screen current altModifiers:#(#'Meta_L' #'Meta_R' #'Hyper_R')

appleAltModifierMask

return the Xlib mask bit for the ALT modifier key on OS-X.
Nil returned for other displays

appleCmdModifierMask

return the Xlib mask bit for the CMD modifier key on OS-X.
Nil returned for other displays

metaModifiers

Return the set of keys which are treated as Meta-keys (i.e. Cmd-keys).
This set is initialized at startup from what the server thinks
are meta-keys.

Usage example(s):

     Display metaModifiers

metaModifiers: arrayOfMetaModifierKeys

Change the set of keys which are treated as Meta-keys (i.e. Cmd keys).
This is useful for ST/X on OSX on XQuartz, where the window manager
uses the CMD keys, making it unavailable for ST/X.
Here, we map the left ALT key onto the command key
(see keyboard.rc). Lefthanders might want to use the right ALT key for that.

modifierKeyProcessing: key down: pressedOrNil

internal, private method.
Called with every keyPress/keyRelease to update the xxxDown flags.

modifierKeyTopFor: key

reverse translation for a modifier key
(i.e. to get the keyTop from a modifier)

Usage example(s):

       Screen current modifierKeyTopFor:#Cmd
       Screen current modifierKeyTopFor:#Alt

modifierKeyTranslationFor: untranslatedKey

map possible modifiers to a smaller set of common symbols.
Especially, left/right keys are mapped to a common one.

modifierKeys

a list of possible modifiers

prependModifierToKey: untranslatedKey

prepend Shift, Ctrl, Alt and Cmd modifiers to a key;
The order is:
<Shift><Alt><Cmd><Ctrl><key>
i.e. if both Alt and Ctrl are pressed with x,
the result will be:
AltCtrlx
not
CtrlAltx
Shift is only prepended as modifier if <key> is symbolic (not a single character);
therefore, if all of Shift, Alt and Ctrl are pressed with x,
the result is:
AltCtrlX
not
ShiftAltCtrlx
However, for a symbolic key, like F1, we'll get:
ShiftAltCtrlF1

translateKey: untranslatedKey forView: aView

Return the key translated via the translation table.
Your application program should never depend on the values returned
by this method, but instead use symbolic keys (such as #FindNext).
Doing so allows easier reconfiguration by changing the translation map
in the 'smalltalk.rc' or 'display.rc' startup files.

First, the modifier is prepended, making character X into
AltX, CtrlX or CmdX (on many systems, no separate Cmd (or Meta)
key exists; on those we always get AltX if the metaModifiers are not set correctly).
If multiple modifiers are active, the symbol becomes the concatenation
as in AltCtrlq (for control-alt-q).
Shift will affect the last component IFF it is a single character,
thus the above with shift becomes: AltCtrlQ instead.
Some keyboards offer both Alt and Meta keys - on those, the first has a
prefix of Alt, the second has Cmd as prefix. Keyboards with only an Alt
key will will create prefix codes of Cmd for that.
For symbolic keys (i.e.Tab, BackSpace etc, shift is ignored).
Then the result is used as a key into the translation keyboardMap
to get the final return value.

keyboard queries

altDown

return true, if the alt-key is currently pressed.

altModifierMask

return the mask bit for the alt modifier key

** This method must be redefined in concrete classes (subclassResponsibility) **

ctrlDown

return true, if the control-key is currently pressed.
Here, we don't differentiate between left and right ctrl keys.

ctrlModifierMask

return the mask bit for the ctrl modifier key

** This method must be redefined in concrete classes (subclassResponsibility) **

leftCtrlDown

return true, if the left control-key is currently pressed.

leftShiftDown

return true, if the left shift-key is currently pressed.

Usage example(s):

     10 timesRepeat:[
        Transcript showCR:'l:%1 r:%2' with:Display leftShiftDown with:Display rightShiftDown.
        Delay waitForSeconds:1.
     ]

metaDown

return true, if the meta-key (alt-key on systems without meta)
is currently pressed.

metaModifierMask

return the mask bit for the meta modifier key

** This method must be redefined in concrete classes (subclassResponsibility) **

rightCtrlDown

return true, if the right control-key is currently pressed.

Usage example(s):

     10 timesRepeat:[
        Transcript showCR:'right: %1' with:(Display rightCtrlDown).
        Transcript showCR:'left: %1' with:(Display leftCtrlDown).
        Transcript showCR:'ctrl: %1' with:(Display ctrlDown).
        Delay waitForSeconds:1.
     ].

rightShiftDown

return true, if the right shift-key is currently pressed

shiftDown

return true, if the shift-key is currently pressed.
Here, we don't differentiate between left and right shift keys.

shiftModifierMask

return the mask bit for the shift modifier key

** This method must be redefined in concrete classes (subclassResponsibility) **

misc

beep

output an audible beep or bell

beepInEditor

output an audible beep or bell, if enabled.

Beep to wakeup the user after some error/not found condition in an editor.
Use this ONLY to beep in response to a bad user operation (not system failure beeps).
Can be disabled via the settings if too annoying

buffered

buffer drawing - do not send it immediately to the display.
This is the default; see comment in #unBuffered.

buttonLongPressedHandlerProcess

buttonLongPressedHandlerProcess: aProcess

buttonPressTimeForMenu

buttonPressTimeForMenu: seconds

compressMotionEvents: aBoolean

turn on/off motion event compression
- compressions makes always sense except in free-hand drawing of curves

focusView

the view, which has got the focus from the operating system

focusView: aViewOrNil

remember the view, which has got the focus from the operating system

focusWindowGroup

the last windowGroup, which has got the focus from the operating system

focusWindowGroup: aWindowGroupOrNil

remember the last windowGroup, which has got the focus from the operating system

redrawAllWindows

Display redrawAllWindows

repadBits: givenBits width: imageWidth height: imageHeight depth: imageDepth from: givenPadding to: wantedPadding

repadding support - required for some devices when drawing images

restoreWindows

restore the display.
Here, a view is popped over all of the screen temporarily

Usage example(s):

     Display restoreWindows
     Display redrawAllWindows

rightButtonIsLowerWindow: aBooleanOrNil

ignored here. Used with windows displays, to control the
bahavior of the right mouse button, when clicking into the
title area (to lower a view).
With a non-nil argument, the flag is set.
with a nil value, its current value is returned

ringBell

alias for beep; for ST-80 compatibility

setInputFocusTo: aWindowId

** This method must be redefined in concrete classes (subclassResponsibility) **

shiftedLeftButtonIsLowerWindow: aBooleanOrNil

ignored here. Used with windows displays, to control the
bahavior of the shifted right mouse button, when clicking into the
title area (to lower a view).
With a non-nil argument, the flag is set.
with a nil value, its current value is returned

sync

send all buffered drawing to the display and wait until its processed/drawn.
See also #flush, which does not wait.
ST-80 seems to only support flush.

synchronizeOutput

send all buffered drawing to the display.
OBSOLETE: please use #flush for ST-80 compatibility.

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

unBuffered

make all drawing be sent immediately to the display.
This may horribly slow down your drawings, but will result
in any errors to be delivered right after the bad operation
(in X only). Only useful for debugging.

multi monitor support

openViewWithBlock: openAction view: aView at: origin: HACK for multi monitor support.
sub views needs to be opened on the same monitor as their top view,
so that Windows create/place them into the same virtual resolution/display.
after the sub views are opened we can move them within the same virtual resolution/display.
to their actually origin

USED BY WINDOWS ONLY

native window stuff

changeButtonState: state in: drawableId: ** This method must be redefined in concrete classes (subclassResponsibility) **
changeLabel: state in: drawableId: ** This method must be redefined in concrete classes (subclassResponsibility) **
enableScrollBar: enableBoolean in: drawableId: ** This method must be redefined in concrete classes (subclassResponsibility) **

pointer stuff

anyButtonMotionMask

return an integer for masking out any button from a motion
buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

anyButtonPressed

return true, if the any button is currently pressed.
You should not use it in 'normal' applications.
Instead, keep track of the buttons state in your view's or controller's
button-event methods.

anyButtonStateMask

return an integer for masking out any button from a
buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

button1MotionMask

return an integer for masking out the left button from a
motion buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

button2MotionMask

return an integer for masking out the middle button from a
motion buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

button3MotionMask

return an integer for masking out the right button from a
motion buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

buttonStates

return an integer representing the state of the pointer buttons;
a one-bit represents a pressed button. The bit positions are device specific
and to be returned by the *ButtonStateMask methods.
Must be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

leftButtonPressed

return true, if the left button is currently pressed

leftButtonStateMask

return an integer for masking out the left button from a
buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

middleButtonPressed

return true, if the middle button is currently pressed

middleButtonStateMask

return an integer for masking out the middle button from a
buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

pointerPosition

return the current pointer position in root-window coordinates.
Must be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

rightButtonPressed

return true, if the right button is currently pressed

rightButtonStateMask

return an integer for masking out the right button from a
buttonStates value. This is very device specific and to
be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

rootPositionOfLastEvent

return the position in root-window coordinates
of the last button, key or pointer event.
Must be redefined by concrete subclasses.

** This method must be redefined in concrete classes (subclassResponsibility) **

setPointerPosition: newPosition

change the pointer position in root-window coordinates.
Warning: moving the mouse pointer may lead to the mouse falling off the table
after a while. So it should be used very very seldom (if at all)

Usage example(s):

     Display setPointerPosition:10@30

setPointerPosition: newPosition in: aWindowID

change the pointer position relative to some views origin.
Must be redefined by concrete subclasses.
Warning: moving the mouse pointer may lead to the mouse falling off the table
after a while. So it should be used very very seldom (if at all)

** This method must be redefined in concrete classes (subclassResponsibility) **

printing & storing

printOn: aStream: for your convenience, add the name of the display connection
or 'default' to the printed representation.

queries

isWindowsPlatform
isX11Platform
screenImagePixelOffset

queries - monitor

isHighDpiAware

answers if this app is high dpi aware

monitorRealResolutionByMonitorDeviceName: anIgnoredMonitorDeviceName

this is the real resolution of the display,
without any effect of os scaling

for e.g.
real resolution -> 1080p
os scaling 150%
virtual resolution -> 720p

real resolution -> 1080p
os scaling 100%
virtual resolution -> 1080p

Usage example(s):

        Screen current monitorRealResolutionByMonitorDeviceName:nil.
        Screen current monitorRealResolutionByMonitorDeviceName:'ereswt'.
        Screen current monitorRealResolutionByMonitorDeviceName:'\\.\DISPLAY1'.
        Screen current monitorRealResolutionByMonitorDeviceName:'\\.\DISPLAY2'.

monitorRealResolutionByPoint: aPoint

Usage example(s):

        Screen current monitorRealResolutionByPoint:nil.     
        Screen current monitorRealResolutionByPoint:0@0.     
        Screen current monitorRealResolutionByPoint:500@0.       
        Screen current monitorRealResolutionByPoint:2000@0.

monitorScaleFactorForView: aView

this method always returns the os scale factor,
regardless if the app is high dpi aware or not.

this is the scale factor the user did enter in the os settings,
for e.g. the user can choose between 100, 125, 150 etc.
here we return 1, 1.25 1.5

Usage example(s):

        Screen current monitorScaleFactorForView:Transcript topView.

retrieving pixels

getBitsFromId: aDrawableId x: srcx y: srcy width: w height: h into: imageBits: get bits from a view drawable into the imageBits. The storage for the bits
must be big enough for the data to fit. If ok, returns an array with some
info and the bits in imageBits. The info contains the depth, bitOrder and
number of bytes per scanline. The number of bytes per scanline is not known
in advance, since the X-server is free to return whatever it thinks is a good padding.

** This method must be redefined in concrete classes (subclassResponsibility) **
getBitsFromPixmapId: aDrawableId x: srcx y: srcy width: w height: h into: imageBits: get bits from a drawable into the imageBits. The storage for the bits
must be big enough for the data to fit. If ok, returns an array with some
info and the bits in imageBits. The info contains the depth, bitOrder and
number of bytes per scanline. The number of bytes per scanline is not known
in advance, since the X-server is free to return whatever it thinks is a good padding.
getBitsFromViewId: aDrawableId x: srcx y: srcy width: w height: h into: imageBits: get bits from a drawable into the imageBits. The storage for the bits
must be big enough for the data to fit. If ok, returns an array with some
info and the bits in imageBits. The info contains the depth, bitOrder and
number of bytes per scanline. The number of bytes per scanline is not known
in advance, since the X-server is free to return whatever it thinks is a good padding.
getPixelX: x y: y from: aDrawableId with: gcId: return the pixel value at x/y

** This method must be redefined in concrete classes (subclassResponsibility) **

style defaults

defaultStyleValueFor: aKey: return a default style value, given a key.
These defaults are used if nothing is specified
in the style sheet
This allows for empty values in style sheets, and defaults
being provided by the display (which makes sense with Windows,
where the systemDefaults are used ...

tray access

addTrayIconFor: aView icon: wicon iconMask: wiconMask toolTipMessage: toolTipMessage: add an icon to the tray for aView (which will receive tray-events in the future.
intentionally ignored here - only supported by win32 (for now)
removeTrayIconFor: aView: remove the tray icon.
intentionally ignored here - only supported by win32 (for now)
setTrayIconFor: aView icon: wicon iconMask: wiconMaskArg: change the tray icon.
intentionally ignored here - only supported by win32 (for now)
setTrayIconsToolTipMessageFor: aView to: toolTipMessageArg: Change the toolTopText.
intentionally ignored here - only supported by win32 (for now)

view registration

addKnownView: aView withId: aWindowID: add the View aView with id:aWindowID to the list of known views/id's.
This map is needed later (on event arrival) to get the view from
the view's id (which is passed along with the devices event) quickly.
applyTopViewRealizeHooksFor: aView: callBack from a topView's realize method.
apply intercepting hooks...
initializeTopViewHookFor: aView: marked as obsolete by exept MBP at 05-07-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
realizedTopViewHookFor: aView: marked as obsolete by exept MBP at 05-07-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
removeKnownView: aView withId: aViewId: remove aView from the list of known views/id's.
One of aView of aViewId may be nil - the nil one is computed from the other variable.
viewFromId: aWindowID: given an Id, return the corresponding view.
Return nil for unknown windows
(can happen for external window, if a key grab is active)
viewIdKnown: aWindowID: return true, if I still consider a windowId as being valid

window stuff

activateWindow: aWindowId

make a window active.
Fall back to raiseWindow here

clearRectangleX: x y: y width: width height: height in: aWindowId

clear a rectangular area of a window to its view background

** This method must be redefined in concrete classes (subclassResponsibility) **

clearWindow: aWindowId

clear a windows to its view background

** This method must be redefined in concrete classes (subclassResponsibility) **

iconify: aView id: aWindowId

iconify a window.
Generic workaround for workstations not having a iconify method.

lowerWindow: aWindowId

lower a window

** This method must be redefined in concrete classes (subclassResponsibility) **

mapView: aView id: aWindowId iconified: aBoolean atX: xPos y: yPos width: w height: h

marked as obsolete by Stefan Vogel at 9-Jun-2022

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

mapView: aView id: aWindowId iconified: aBoolean atX: xPos y: yPos width: w height: h minExtent: minExt maxExtent: maxExt

make a window visible - either as icon or as a real view - needed for restart

** This method must be redefined in concrete classes (subclassResponsibility) **

mapWindow: aWindowId

map a window

** This method must be redefined in concrete classes (subclassResponsibility) **

mapWindow: aWindowId animation: animationSymbolorNil time: timeInMillisOrNil

unmap a window

moveResizeWindow: aWindowId x: x y: y width: w height: h

move & resize a window

moveWindow: aWindowId x: x y: y

move a window

** This method must be redefined in concrete classes (subclassResponsibility) **

raiseWindow: aWindowId

raise a window.
In some systems (aka MSWindows), this raises only above all other st/x views,
but not above other-application's views, which have a TOPMOST attribute.
Se raiseWindowToTop for this.

** This method must be redefined in concrete classes (subclassResponsibility) **

raiseWindowToTop: aWindowId

raise a window above all others (even above non-st/x windows)

raiseWindowToTopMost: aWindowId

raise a window above all others (even above non-st/x windows)

reparentWindow: windowId to: newParentWindowId

change a windows parent (an optional interface).
Returns true if successful.

resizeWindow: aWindowId width: w height: h

resize a window

** This method must be redefined in concrete classes (subclassResponsibility) **

restoreCursors

restore the cursors of all views to their current cursor.
This undoes the effect of #setCursors:

Usage example(s):

     Display setCursors:(Cursor wait).
     Delay waitForSeconds:5.
     Display restoreCursors

setBackingStore: how in: aWindowId

turn on/off backing-store for a window.
A view with backingStore will redraw automatically
from the backing pixmap (without sending expose events).
An implementation may ignore this request.

setBitGravity: how in: aWindowId

set bit gravity for a window

setCursor: aCursorId in: aWindowId

set a window's cursor

** This method must be redefined in concrete classes (subclassResponsibility) **

setCursors: aCursor

change the cursor of all views on the receiver device
to aCursorId, without affecting the view's idea of what
the cursor is (so that it can be restored from the view's
cursor instance variable later).
Use of this is not recommended - it's better to change
the cursor of a windowGroup alone.

Usage example(s):

     Display setCursors:(Cursor wait).
     Delay waitForSeconds:5.
     Display restoreCursors.

setForegroundWindow: aWindowId

make a window active.
Fall back to raiseWindow here

setIconName: aString in: aWindowId

set a windows icon name

setSaveUnder: yesOrNo in: aWindowId

turn on/off save-under for a window.
A view with saveUnder will save the pixels of the
area covered by itself and repair from those when
unmapped (therefore, no expose events are generated later).
It is especially useful for popUp menus.
An implementation may ignore this request.

setTransient: aWindowId for: aMainWindowId

set aWindowId to be a transient of aMainWindow.
This informs the windowManager that those are to
be handled as a group w.r.t. iconification and deiconification.
An implementation may ignore this
(being somewhat inconvenient to the user, though)

setWindowBackground: aColorIndex in: aWindowId

set a windows background color

** This method must be redefined in concrete classes (subclassResponsibility) **

setWindowBackgroundPixmap: aPixmapId in: aWindowId

set a windows background pattern to be a form.
No need to be implemented in concrete workstation;
if not implemented, its done by (slower) smalltalk code
(must return false from #supportsViewBackgroundPixmap query)

setWindowBorderColor: aColorIndex in: aWindowId

set a windows border color

setWindowBorderPixmap: aPixmapId in: aWindowId

set a windows border pattern

setWindowBorderShape: aPixmapId in: aWindowId

set a windows border shape

setWindowBorderWidth: aNumber in: aWindowId

set a windows border width

** This method must be redefined in concrete classes (subclassResponsibility) **

setWindowClass: wClass name: wName in: aWindowId

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

setWindowGravity: how in: aWindowId

set window gravity for a window

setWindowIcon: aForm in: aWindowId

define a bitmap to be used as icon

setWindowIcon: aForm mask: aMaskForm in: aWindowId

set a windows icon & iconMask

setWindowIconWindow: aView in: aWindowId

set a windows icon window

setWindowMinExtent: minExt maxExtent: maxExt in: aWindowId

set a windows minimum & max extents.
nil arguments are ignored.

setWindowMinExtentX: minW y: minH maxExtentX: maxW y: maxH in: aWindowId

set a windows minimum & max extents.
nil arguments are ignored.

** This method must be redefined in concrete classes (subclassResponsibility) **

setWindowName: aString in: aWindowId

define a windows name (i.e. windowTitle)

** This method must be redefined in concrete classes (subclassResponsibility) **

setWindowPid: anIntegerOrNil in: aWindowId

Sets the _NET_WM_PID property for the window (in X11).
This may be used by the window manager to group windows.
If anIntegerOrNil is nil, then PID of currently running
Smalltalk is used

setWindowShape: aPixmapId in: aWindowId

set a windows visible shape

unmapWindow: aWindowId

unmap a window

** This method must be redefined in concrete classes (subclassResponsibility) **

unmapWindow: aWindowId animation: animationSymbolorNil time: timeInMillisOrNil

unmap a window

windowIsIconified: aWindowId

return true, if a window is iconified

** This method must be redefined in concrete classes (subclassResponsibility) **

Private classes:

    DeviceFontMetrics

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 06:30:45 GMT