Smalltalk/X Webserver

Documentation of class 'TopView':

Class: TopView

Inheritance
Description
Related information
Class protocol
- class initialization
- defaults
Instance protocol
Examples

Inheritance:

   Object
   |
   +--GraphicsContext
      |
      +--DeviceGraphicsContext
         |
         +--GraphicsMedium
            |
            +--DisplaySurface
               |
               +--SimpleView
                  |
                  +--View
                     |
                     +--TopView
                        |
                        +--ExternalTopView
                        |
                        +--PopUpView
                        |
                        +--StandardSystemView

Package:: stx:libview

Category:: Views-Basic

Version:: rev: 1.127 date: 2009/06/10 13:30:54; user: ca; file: TopView.st directory: libview; module: stx stc-classLibrary: libview

Author:: Claus Gittinger

Description:

I am an abstract superclass of StandardSystemView and PopUpView;
i.e. views which have no superview.

Do not get confused by the name TopView - your applications
topViews are typically instances of StandardSystemView.

[instance variables:]
    type            <Integer>       encodes master/slave relationship:
                                        #normal, #master, #slave or #partner
                                    for modeless views
                                    (the #master-, #slave- or #partner-type links multiple views 
                                     into a windowManagers windowGroup -> for de-iconification)

                                    encodes window type:
                                        #normal, #dialog, #popup, #undecorated

Related information:

    StandardSystemView
    PopUpView
    DialogBox
    [introduction to view programming]

Class protocol:

class initialization

initialize

defaults

defaultExtent: return the default extent of my instances.
Topviews extents is 2/3 of screen by default
forceModalBoxesToOpenAtCenter: return the flag which forces all modal views to be opened
at the screens center
forceModalBoxesToOpenAtCenter: aBoolean: set/clear a flag which forces all modal views to be opened
at the screens center
forceModalBoxesToOpenAtPointer: return the flag which forces all modal views to be opened
at the current pointer position
forceModalBoxesToOpenAtPointer: aBoolean: set/clear the flag which forces all modal views to be opened
at the current pointer position
takeFocusWhenMapped: aBoolean: if turned on, topViews will grab the keyboard when mapped.
This is useful on systems like openView or Win32, where a view needs a click
otherwise

Instance protocol:

Compatibility-ST80

displayBox
displayBox: aRectangle

accessing

keyboardProcessor: return my keyboard processor
keyboardProcessor: something: set my keyboard processor
label: labelString iconLabel: iconLabelString: ignored here - for compat. with StdSysViews

accessing-behavior

beDialogView: make me a Dialog Window; that is one which raises above all other ST/X views
beIndependent: make this an independent view; i.e. remove any master/slave or partner
attribute (this is the default).
However, the view remains in the current windowGroup
beMDIClientView
beMaster: make this a master-view.
All slave views within the same windowGroup will be closed if any master is closed
and also de/iconify together with their master(s).
(i.e. they follow their master(s)).
bePartner: make this a partner-view. Each partner-view will automatically
close other partner views (within the same windowGroup) when closed.
bePopUpView: the nonInteger handling code is for backward compatibility only.
beScreenDialog: make me a Screen-Dialog Window; that is one which raises above ALL other windows
(not only st/x ones)
beSlave: make this a slave-view. It will be closed automatically,
whenever any master of the windowgroup is closed.
See also: #bePartner
beToolDialog: the nonInteger handling code is for backward compatibility only.
beToolWindow: the nonInteger handling code is for backward compatibility only.
beUndecorated: make me an undecorated Window
focusSequence: aCollectionOfSubcomponents: define the sequence for stepping through my components.
preferFirstInputFieldWhenAssigningInitialFocus: define the focus behavior for dialogs.
If true is returned, input fields take precedence over other keyboard consumers.
This used to return true, but the behavior is somewhat ugly.

accessing-look

addTrayIcon: anImageOrForm toolTipMessage: toolTipMessage: WIN32 only: add a tray icon for myself;
may then receive tray*-events in the future.

event handling

keyPress: key x: x y: y: notice: this ought to be moved into the upcoming
StandardSystemViewController.
showActivity: someMessage: some activityNotification shalt be communicated to the user.
Default for activity notifications here: ignore them
trayButtonDoubleClick: buttonNr: WIN32 only: double-click in the tray.
Nothing done here - must be redefined in a subclass
trayButtonPress: buttonNr: WIN32 only: button-press in the tray.
Nothing done here - must be redefined in a subclass
trayButtonRelease: buttonNr: WIN32 only: button-release in the tray.
Nothing done here - must be redefined in a subclass
trayMouseMotion: WIN32 only: mouse-motion in the tray.
Nothing done here - must be redefined in a subclass

help

flyByHelpDependsOnPositionIn: aView: subclasses where the help-text depends upon the pointer position might
want to redefine this

help stubs

flyByHelpTextFor: aSubView: this will vanish - its temporarily here to allow for stdSysViews to be
used as a masterApp for dialogs
helpTextFor: aSubView: this will vanish - its temporarily here to allow for stdSysViews to be
used as a masterApp for dialogs
showHelp: aHelpText for: aView: dummy - added in case a regular topView is installed
as a dialogs masterApplication.
Concrete application subclasses may redefine this to
display a help text in one of its message areas

initialization & release

addToCurrentProject: for compatibility with views which can
assignInitialKeyboardFocus: assign the initial keyboard focus to a 'useful' component.
assignKeyboardFocusToFirstInputField: assign the keyboard focus to the first first keyboardConsumer.
(in older versions, this used to favour inputfields over editFields;
see (or redefine) preferFirstInputFieldWhenAssigningInitialFocus)
destroy: the receiver is to be destroyed - look for partners and slaves
initialize: initialize the topViews position for the screens center
postRealize
realize
release

misc

raiseDeiconified: deiconify & bring to front
waitUntilClosed: wait until the receiver has been closed.
Can be used to synchronize multiple-window applications,
and (especially) to wait until an application session is finished
when invoking commands with the rDoit mechanism
withCursor: aCursor do: aBlock: evaluate aBlock while showing aCursor in all my views.
Return the value as returned by aBlock.

queries

beepWhenOpening
heightIncludingBorder: return the views overall-height
isActive: true, if I have the focus (w.r.t the windowing system);
i.e. if one of my subViews actually has the real focus.
With click-to-focus behavior, this is obviously the current application.
Use this query with caution, for example, to suppress tooltips for inactive apps.
isCollapsed: ST80 compatibility: return true if the view is not shown (i.e. iconified)
isDialogView: return true if this is a dialog view
isMDIClientView
isMaster: return true, if this is a masterView
isModal: return true, if the receiver has been opened modal
isPartner: return true, if this is a partnerView
isPopUpView: return true if I am a popup view.
(i.e. I want to come up without decoration and popUp to top immediately)
isScreenDialog: return true if I am a screen dialog view.
(i.e. I want to come up anove all other windows
isSlave: return true, if this is a slaveView
isToolDialog: return true if I am a toolWindow dialog view.
(i.e. I want to come up with a smaller window-title area)
isToolWindow: return true if I am a toolWindow view.
(i.e. I want to come up with a smaller window-title area)
isTopView: return true, since I am a topView
isUndecoratedView: return true if I am an undecorated view.
preferredExtent: return my preferred extent - this is the minimum size I would like to have.
The default here is the classes default extent,
however many subclasses redefine this to compute the actual value
depending on the sizes of the contents or subcomponents.
widthIncludingBorder: return the views overall-width
windowStyle: return a symbol describing my style which should be one of
#dialog, #popUp, #undecorated, #normal or #toolWindow.
This is used by the device as a decoration hint.

realization

openModal: added bell to wake up user

show & hide

activate: added for MS-windows - much like raise.
Raise/Activate seem to work only within my own (ST/X)-windows;
they do not raise one of my views above another (for example: command.com)-window.
Can anyone tell me what the difference between raise, activate and setForeground
really is (I mean really - not what is written in the crappy documentation)
fixPosition: aPoint: set origin to aPoint, but make sure, that the box is fully visible
by shifting it into the visible screen area if nescessary.
This prevents invisible modalBoxes (which you could never close).
hide
map: make the view visible on the screen.
For topViews, the windowManager will choose (or ask for) the
views position on the screen.
Notice:
Actually, this method is only valid for topViews;
however, it is defined here to allow things like 'Button new realize'
mapIconified: make the view visible but iconified.
In contrast to map, which does it non-iconified
positionOffset: return the delta, by which the box should be
displaced from the mouse pointer.
Here, the boxes center is returned as a default.
Usually redefined in subclasses to have the most convenient
ok-button appear under the pointer.
setForegroundWindow: make a window the foreground window (so raise and activate it).
Under Win 98/Me/XP/2000 the window is not raised/activated, if a window from
a different process is currently active - in this case the title bar/icon is flashed.
this also raises the priority of the sending thread slightly.

Mark a TopView as #beScreenDialog, to send this on open.

startup

openAt: aPosition transientFor: anotherView: force the view to be opened at some position on the screen
AND tell the windowManager to NOT let the user choose a position
(i.e. suppress any ghostframe).
The view is marked as being a transient (i.e. pop-up) view for
anotherView - it will deiconify with it and (on some windowManagers)
have no iconify button of its own.
Notice, that its up to the windowManager to care for any borders -
it seems not deterministic, where the view actually ends up being positioned.
Not all windowManagers (olwm) honor this - some insist on it ...
openDisplayAt: aPoint: ST-80 compatibility: open the view centered around aPoint
openIconified: open the view in iconified state
openIn: aBoundaryRectangle: set origin & extent and open.
The given extent overrides the receivers preferredExtent.
Added for ST-80 compatibility
openTransientAt: aPosition: force the view to be opened at soem position on the screen
AND tell the windowManager to NOT let the user choose a position
(i.e. suppress any ghostframe).
Notice, that its up to the windowManager to care for any borders -
it seems not deterministic, where the view actually ends up being positioned.
Not all windowManagers (olwm) honor this - some insist on it ...
openWithExtent: anExtent: set extent and open. The given extent overrides the
receivers preferredExtent.
Added for ST-80 compatibility
openWithPriority: aPriority: open the view, run the windowgroup process at
other than UserScehdulingPriority.

window events

mapped: the recevier was mapped (i.e. deiconified);
look for partners and slaves.
masterSlaveMessage: aSelector inGroup: aWindowGroup: send aSelector to partners and/or slaves.
This is a private helper for destroy / mapped / unmapped
unmapped: the recevier was unmapped (i.e. iconified);
look for partners and slaves.

Notice, the following examples only demonstrate the windos style (not its modal behavior). the style is controlled by the systems windowManager, and might even be ignored by some. (for example, the dialog- and normal styles often look the same). The bahavior is controlled by ST/X, and controlled by the open vs. openModeless vs. openModal message. Modeless: regular style:


      |v|

      v := TopView new.
      v extent:200@200.
      v open

dialog:


      |v|

      v := TopView new.
      v beDialogView.
      v extent:200@200.
      v open
      Delay waitForSeconds:10. v destroy.

popUp (always on top):


      |v|

      v := TopView new.
      v bePopUpView.
      v extent:200@200.
      v open.
      Delay waitForSeconds:10. v destroy.

undecorated (looks loke popUp, but is not always on top):


      |v|

      v := TopView new.
      v beUndecorated.
      v extent:200@200.
      v open.
      Delay waitForSeconds:10. v destroy.

toolwindow (looks loke normal, but has smaller windowTitle-area on win32):


      |v|

      v := TopView new.
      v beToolWindow.
      v extent:200@200.
      v open.
      Delay waitForSeconds:10. v destroy.

toolwindow dialog (looks loke normal, but has smaller windowTitle-area on win32):


      |v|

      v := TopView new.
      v beToolDialog.
      v extent:200@200.
      v open.
      Delay waitForSeconds:10. v destroy.

Modal: regular style:


      |v|

      v := TopView new.
      v extent:200@200.
      v openModal