Smalltalk/X Webserver

Documentation of class 'TopView':

Class: TopView

Inheritance
Description
Class protocol
Instance protocol
Examples

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

copyrightCOPYRIGHT (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.

Instance protocol:

Compatibility-ST80

displayBox
displayBox: aRectangle

accessing

keyboardProcessor

return my keyboard processor

keyboardProcessor: something

set my keyboard processor

resources

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

Usage example(s):

     TopView new resources

accessing-behavior

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

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.

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)

bePopUpView

the nonInteger handling code is for backward compatibility only.

Usage example(s):

        (StandardSystemView extent:100@100) bePopUpView open

bePopUpViewNotModal

experimental/unfinished - do not use

Usage example(s):

        (StandardSystemView extent:100@100) bePopUpViewNotModal open

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

beSlave

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

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

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

beUndecorated

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

beUndecoratedResizable

make me an undecorated but resizable Window

focusSequence: aCollectionOfSubcomponents

define the sequence for stepping through my components.

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

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'

label: labelString iconLabel: iconLabelString

ignored here - for compat. with StdSysViews

event handling

keyPress: key x: x y: y: notice: this ought to be moved into the upcoming
StandardSystemViewController.
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.
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.
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

event handling-window move

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

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

helpSpec

help stubs

helpTextFor: aSubView: this will vanish - it's 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 dialog's 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.

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

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

initialize

initialize the topViews position for the screens center

postRealize

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

realize

must clear this flag

release

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

bringIntoBounds: bounds: shift & resize myself to be completely inside bounds.
withCursor: aCursor do: aBlock: evaluate aBlock while showing aCursor in all my views.
Return the value as returned by aBlock.

queries

beepWhenOpening: can be redefined by error and warnBoxes
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.
heightIncludingBorder: return the view's overall-height
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 any decoration and raise to top immediately)
isScreenDialog: return true if I am a screen dialog view.
(i.e. I want to come up above 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, without minimize and maximize buttons)
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)
isTopView: return true, since I am a topView
isUndecoratedView: return true if I am an undecorated view (no minimize, maximize and close buttons).
widthIncludingBorder: return the view's 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.

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)

Usage example(s):

     Transcript topView activate

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

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.

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

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

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.

raiseDeiconified

deiconify & bring to front

Usage example(s):

     Transcript topView raiseDeiconified

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

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

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

openDisplayAt: aPoint

ST-80 compatibility: open the view centered around aPoint

Usage example(s):

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

openIconified

open the view in iconified state

Usage example(s):

     FileBrowser new openIconified
     ChangesBrowser new openIconified

openIn: aBoundaryRectangle

set origin & extent and open.
The given extent overrides the receiver's 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 ...

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

openWithExtent: anExtent

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

openWithPriority: aPriority

open the view, run the windowgroup process at
other than UserScehdulingPriority.

window events

mapped: the receiver 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 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 16:46:06 GMT

Smalltalk/X Webserver

Documentation of class 'TopView':

Class: TopView

Inheritance:

Description:

copyright

Class protocol:

Instance protocol:

Examples: