eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'TopView':

Home

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

Class: TopView

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--TopView
                  |
                  +--ExternalTopView
                  |
                  +--PopUpView
                  |
                  +--StandardSystemView
Package:
stx:libview
Category:
Views-Basic
Version:
rev: 1.196 date: 2023/07/05 08:06:48
user: cg
file: TopView.st directory: libview
module: stx stc-classLibrary: libview

Description:


I am an abstract (typically) 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


copyright
COPYRIGHT (c) 1995 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

accessing
o  currentWindowBeingMoved
the current window move operation
(only used with modeless popup windows; i.e. windows without decoration,
which want to be moved by click-motion on the background)

class initialization
o  initialize
self initialize

defaults
o  defaultExtent
return the default extent of my instances.
Topviews extents is 2/3 of screen by default

o  forceModalBoxesToOpenAtCenter
return the flag which forces all modal views to be opened
at the screens center

o  forceModalBoxesToOpenAtCenter: aBoolean
set/clear a flag which forces all modal views to be opened
at the screens center

Usage example(s): 

     TopView forceModalBoxesToOpenAtCenter:true
     TopView forceModalBoxesToOpenAtCenter:false

o  forceModalBoxesToOpenAtPointer
return the flag which forces all modal views to be opened
at the current pointer position

o  forceModalBoxesToOpenAtPointer: aBoolean
set/clear the flag which forces all modal views to be opened
at the current pointer position

o  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

Usage example(s): 

     StandardSystemView takeFocusWhenMapped:true

help specs
o  helpSpec

Instance protocol:

Compatibility-ST80
o  displayBox

o  displayBox: aRectangle

accessing
o  keyboardProcessor
return my keyboard processor

o  keyboardProcessor: something
set my keyboard processor

o  resources
if I have no private resources, return my class's resources

Usage example(s): 

     TopView new resources

accessing-behavior
o  beDialogView
make me a Dialog Window; that is one which raises above all other ST/X views

Usage example(s): 

        (StandardSystemView extent:100@100) beDialogView open

o  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

o  beMDIClientView

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

o  bePartner
make this a partner-view. Each partner-view will automatically
close other partner views (within the same windowGroup) when closed.

Usage example(s): 

     create two topViews within the same group:
     if any of them is iconified/deiconified/closed, the other one is also

     |top1 top2|

     top1 := StandardSystemView new label:'partner'; extent:300@300.
     top2 := StandardSystemView new label:'partner'; extent:200@200.
     top1 bePartner.
     top2 bePartner.

     top1 open.
     top2 openInGroup:(top1 windowGroup)

o  bePopUpView
the nonInteger handling code is for backward compatibility only.

Usage example(s): 

        (StandardSystemView extent:100@100) bePopUpView open

o  bePopUpViewNotModal
experimental/unfinished - do not use

Usage example(s): 

        (StandardSystemView extent:100@100) bePopUpViewNotModal open

o  beScreenDialog
make me a Screen-Dialog Window; that is one which raises above ALL other windows
(not only st/x ones)

Usage example(s): 

        (StandardSystemView extent:100@100) beScreenDialog open

o  beSlave
make this a slave-view. It will be closed automatically,
whenever any master of the windowgroup is closed.
See also: #bePartner

o  beToolDialog
make me a tool dialog Window with a smaller title area.
Warning: not all window systems support that.
Will be normal decorated on some systems (macosx)

Usage example(s): 

        (StandardSystemView extent:100@100) beToolDialog open

o  beToolWindow
make me a tool Window with a smaller title area.
Warning: not all window systems support that. Will be normal decorated on some systems (macosx)

Usage example(s): 

        (StandardSystemView extent:100@100) beToolWindow open

o  beUndecorated
make me an undecorated Window.
Warning: not all window systems support that. Will be decorated on some systems (macosx)

o  beUndecoratedResizable
make me an undecorated but resizable Window

o  focusSequence: aCollectionOfSubcomponents
define the sequence for stepping through my components.

o  windowType: aTypeSymbol
backward compatibility, type symbols are no longer supported - do not use

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

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

Usage example(s): 

     |v icon|

     v := StandardSystemView new.
     v openAndWaitUntilVisible.

     icon := Icon stxIcon.
     v addTrayIcon:icon toolTipMessage:'Hi There'

o  label: labelString iconLabel: iconLabelString
ignored here - for compat. with StdSysViews

event handling
o  keyPress: key x: x y: y
notice: this ought to be moved into the upcoming
StandardSystemViewController.

o  processOutsideButtonEventWhileModal: anEvent
a button event (press/release) arrived for another view,
while I (a topView) am open as modal view.
Can be redefined to react on clicks outside (eg. CriticsWindow);
if handled, the redefining method should return true.
If not handled, it should return false.

o  showActivity: someMessage
some activityNotification shalt be communicated to the user.
The default here is to ignore it,
but it is redefined in StdSysView to present it to the user.

o  trayButtonDoubleClick: buttonNr
WIN32 only: double-click in the tray.
Nothing done here - must be redefined in a subclass

o  trayButtonPress: buttonNr
WIN32 only: button-press in the tray.
Nothing done here - must be redefined in a subclass

o  trayButtonRelease: buttonNr
WIN32 only: button-release in the tray.
Nothing done here - must be redefined in a subclass

o  trayMouseMotion
WIN32 only: mouse-motion in the tray.
Nothing done here - must be redefined in a subclass

event handling-window move
o  doWindowMove
a window move operation
(only used with modeless popup windows; i.e. windows without decoration,
which want to be moved by click-motion on the background)

o  endWindowMove
a window move operation
(only used with modeless popup windows; i.e. windows without decoration,
which want to be moved by click-motion on the background)

o  startWindowMove
a window move operation
(only used with modeless popup windows; i.e. windows without decoration,
which want to be moved by click-motion on the background)

o  startWindowMoveOnButtonPress
this allows undecorated windows (i.e. modeless popups) to be moved by
drag-moving in their window area
(similar to how mac windows and realplayer are moved).
Return true here, if a window move should be initiated

help
o  flyByHelpDependsOnPositionIn: aView
subclasses where the help-text depends upon the pointer position might
want to redefine this.
If true is returned, the tooltip-process will monitor mouse movements and
ask for the help text again.
If false is returned (the default here), it will only look at
mouse-enter/leave time.

help specs
o  helpSpec

help stubs
o  helpTextFor: aSubView
this will vanish - it's temporarily here to allow for stdSysViews to be
used as a masterApp for dialogs

o  showHelp: aHelpText for: aView
dummy - added in case a regular topView is installed
as a dialog's masterApplication.
Concrete application subclasses may redefine this to
display a help text in one of its message areas

initialization & release
o  addToCurrentProject
for compatibility with views which can

o  assignInitialKeyboardFocus
assign the initial keyboard focus to a 'useful' component.

o  destroy
the receiver is to be destroyed - look for partners and slaves

Usage example(s): 

... since destroy nils em

Usage example(s): 

destroy slaves and partners

o  destroyWithConfirmation: withConfirmation
if the receiver usually opens a confirmation dialog when destroying,
it should redefine this to enforce destroy without a dialog, if
the withConfirmation argument is false.
This is only used for emergency-close of topViews in case the underlying
windowGroup process died.
Currently: only the debugger does this

o  initialize
initialize the topViews position for the screens center

o  postRealize
(comment from inherited method)
invoked after a view was realized.
Can be redefined in subclasses to perform delayed actions.

o  realize
must clear this flag

o  release

o  rememberLastExtent
can be redefined in subclasses to return true
iff the default size should be the same as the size when last closed.
If false is returned, the default size is computed from the contents.
Remembering is useful for file-selection boxes,
when the user resized the box for many files.
It is NOT useful for generic box (like information:) which should just
adopt to their contents.
Here, false is returned as default, because I am abstract, not knowing what is
shown in me.

misc
o  bringIntoBounds: bounds
shift & resize myself to be completely inside bounds.

o  withCursor: aCursor do: aBlock
evaluate aBlock while showing aCursor in all my views.
Return the value as returned by aBlock.

queries
o  beepWhenOpening
can be redefined by error and warnBoxes

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

o  heightIncludingBorder
return the view's overall-height

o  isCollapsed
ST80 compatibility: return true if the view is not shown (i.e. iconified)

o  isDialogView
return true if this is a dialog view

o  isMDIClientView

o  isMaster
return true, if this is a masterView

o  isModal
return true, if the receiver has been opened modal

o  isPartner
return true, if this is a partnerView

o  isPopUpView
return true if I am a popup view.
(i.e. I want to come up without any decoration and raise to top immediately)

o  isScreenDialog
return true if I am a screen dialog view.
(i.e. I want to come up above all other windows)

o  isSlave
return true, if this is a slaveView

o  isToolDialog
return true if I am a toolWindow dialog view.
(i.e. I want to come up with a smaller window-title area, without minimize and maximize buttons)

o  isToolWindow
return true if I am a toolWindow view.
(i.e. I want to come up with a smaller window-title area, without minimize and maximize buttons)

o  isTopView
return true, since I am a topView

o  isUndecoratedView
return true if I am an undecorated view (no minimize, maximize and close buttons).

o  widthIncludingBorder
return the view's overall-width

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

show & hide
o  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)

Usage example(s): 

     Transcript topView activate

o  fixPosition: aPoint
set origin to aPoint, but make sure, that the box is fully visible
by shifting it into the visible screen area if necessary.
This prevents invisible modalBoxes (which you could never close).

o  hide
if I am a modal-opened application's view

Usage example(s): 

to intercept the hide.

Usage example(s): 

if myApp called closeDownViews, it wants me to hide.

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

o  mapIconified
make the view visible but iconified.
In contrast to map, which does it non-iconified

o  openModal
added bell to wake up user

Usage example(s): 

     self warn:'hello'
     self information:'hello'
     ModalBox new openModal
     WarningBox new openModal
     InfoBox new openModal

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

o  raiseDeiconified
deiconify & bring to front

Usage example(s): 

     Transcript topView raiseDeiconified

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

Usage example(s): 

     Transcript topView raise
     Transcript topView setForegroundWindow

o  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

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

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

o  openDisplayAt: aPoint
ST-80 compatibility: open the view centered around aPoint

Usage example(s): 

     (TopView new extent:200@200) openDisplayAt:300@300

o  openIconified
open the view in iconified state

Usage example(s): 

     FileBrowser new openIconified
     ChangesBrowser new openIconified

o  openIn: aBoundaryRectangle
set origin & extent and open.
The given extent overrides the receiver's preferredExtent.
Added for ST-80 compatibility

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

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

o  openWithExtent: anExtent
set extent and open. The given extent overrides the
receiver's preferredExtent.
Added for ST-80 compatibility

o  openWithPriority: aPriority
open the view, run the windowgroup process at
other than UserScehdulingPriority.

window events
o  mapped
the receiver was mapped (i.e. deiconified);
look for partners and slaves.

o  masterSlaveMessage: aSelector inGroup: aWindowGroup
send aSelector to partners and/or slaves.
This is a private helper for destroy / mapped / unmapped

o  unmapped
the receiver was unmapped (i.e. iconified);
look for partners and slaves.

Examples:


Notice, the following examples only demonstrate the windows style (not its modal behavior). the style is controlled by the system's 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
dialog: 
      |v|

      v := TopView new.
      v beDialogView.
      v extent:200@200.
      v openModal
popUp (always on top): 
      |v|

      v := TopView new.
      v bePopUpView.
      v extent:200@200.
      v openModal
undecorated (looks loke popUp, but is not always on top): 
      |v|

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

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 21 Dec 2024 14:19:30 GMT