Class: StandardSystemView

• Inheritance
• Description
• Related information
• Class protocol
  • Compatibility-VW
  • class initialization
  • defaults
  • image specs
  • instance creation
  • startup
• Instance protocol
  • Compatibility-ST80
  • accessing
  • accessing-behavior
  • accessing-channels
  • accessing-dimensions
  • accessing-look
  • change & update
  • destroying
  • event handling
  • initialization & release
  • printing & storing
  • private
  • queries
  • realization
  • show & hide
• Examples

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--TopView
                  |
                  +--StandardSystemView
                     |
                     +--ApplicationWindow
                     |
                     +--BrowserView
                     |
                     +--ChangesBrowser
                     |
                     +--DebugView
                     |
                     +--FileBrowser
                     |
                     +--MemoryUsageView
                     |
                     +--ModalBox
                     |
                     +--V::MainWindow

Package:

stx:libview

Category:

Views-Basic

Version:

rev: 1.253 date: 2019/07/09 18:21:23

user: cg

file: StandardSystemView.st directory: libview

module: stx stc-classLibrary: libview

Author:

Claus Gittinger

Description:

I represent standard application topViews
i.e. those views which have a title-label, an icon etc.

The name `StandardSystemView' is probably misleading and
results from ST-80 (rel2.x) compatibility reasons.
Think of it as an ApplicationWindow.


In ST/X, StandardSystemViews were subclassed for special views
in the past (for example: FileBrowser, ChangesBrowser etc.).
Although this worked, it may lead to the following
problems and inconveniences:
    - applications inherit a big number of methods through the
      SimpleView->View->TopView->StandardSystemView hierarchy.
      There is quite a danger that by accident, some method gets
      redefined which is required by one of those classes.
      (typical candidates are: terminate, destroy, open ...)
      This may lead to strange effects, which may not be obvious to
      non experts ...

    - applications with multiple topViews are difficult to implement
      and manage.

    - use of a windowBuilder is difficult.

For all those reasons, we HIGHLY recommend to NOT define applications
as subclasses of StandardSystemView, but instead base them on
ApplicationModel, and reference the topView(s) as instance variables of
if (if at all).

[instance variables:]
    label                   <String>    the label in the windows title

    icon                    <Form>      the icon
                                        [ignored if the display does not
                                         support icons]

    iconView                <View>      an optional icon-view (for animated icons)
                                        [ignored if the display does not
                                         supports this]

    iconLabel               <String>    the label in the icon
                                        [ignored if the display does not
                                         support label-tabs with icons]

    minExtent               <Point>     the minimum size
                                        No limit, if nil
                                        [the window manager may have its own
                                         limit; typically some small area]

    maxExtent               <Point>     the maximum size
                                        No limit, if nil.
                                        [the window manager may have its own
                                         limit; typically the screen size]

    sizeFixed               <Boolean>   prevents the view from resizing itself
                                        (especially to freeze a dialog's size)

    application             <AppModel>  if nonNil, that's the application
                                        Many requests (such as open/close etc.
                                        are forwarded to it, if present.



 [class variables:]

    DefaultIcon             <Form>      cached default icon

    TakeFocusWhenMapped     <Boolean>   if true, views grab the keyboard
                                        focus (convenient with some stupid
                                        windowManagers)

    IncludeHostNameInLabel  <Boolean>   if true, the windows title shall
                                        include the hostname.
                                        (convenient if you have many remote
                                        views open simultaneously)

    WindowLabelFormat       <Boolean>   specifies the format for windowLabels

Related information:

    WindowGroup
    ApplicationModel

Class protocol:

 promptForOpen: aBoolean

not implemented here

 initialize

(comment from inherited method)
self initialize

 defaultExtent

return a standardSystemViews default window extent

 defaultIcon

return a topViews default window icon

usage example(s):

DefaultIcon := nil. self defaultIcon inspect

 defaultIconForAboutBox

 defaultLabel

return the default label for views of my kind.
This can be redefined in subclasses or overwritten in
initialize methods.

 defaultWindowLabelFormat

%2 is the hostName;
%1 is the actual window label.

 includeHostNameInLabel

return the flag which controls if a view's label should
include the hostname.
This flag is usually set/cleared in your private.rc file;
the default is false.

 includeHostNameInLabel: aBoolean

set/clear the flag which controls if a view's label should
include the hostname - this is highly useful if you have
multiple smalltalks open simultaneously ...
This flag is usually set/cleared in your private.rc file;
the default is false.

 takeFocusWhenMapped

StandardSystemView takeFocusWhenMapped

 updateStyleCache

extract values from the styleSheet and cache them in class variables

usage example(s):

self updateStyleCache

 windowLabelFormat

 windowLabelFormat: aFormatString

 defaultSTXIcon

 extent: anExtent label: aLabel icon: aForm

create a new topView and define its extent, label and icon

 extent: anExtent label: aLabel icon: aForm minExtent: minExtent

 extent: anExtent label: aLabel icon: aForm minExtent: minExtent maxExtent: maxExtent

 extent: anExtent label: aLabel minExtent: minExtent

create a new topView and define its extent, label and minumum extent

 label: aLabel

create a new topView and define its label

 label: aLabel icon: aForm

create a new topView and define its label and icon

 label: aLabel icon: aForm minExtent: anExtent

create a new topView and define its label, icon and minumum extent

 label: aLabel icon: aForm minExtent: minExtent maxExtent: maxExtent

create a new topView and define its label, icon, min and max extents

 label: aLabel minExtent: anExtent

create a new topView and define its label and minimum extent

 model: aModel label: aLabel minimumSize: minExtent

ST80-style instance creation

 origin: anOrigin extent: anExtent label: aLabel

create a new topView and define its origin, extent and label

 origin: anOrigin label: aLabel icon: aForm minExtent: minExtent maxExtent: maxExtent

create a new topView and define its origin, extent, label, icon
and extent-boundaries.

 cancelAutoRaise

cancel any schedule autoraise action

 start

create, realize the view - this topview and all its subviews will
run as a separate process with its own windowGroup.
This method exists for backward compatibility - use open.

Instance protocol:

 maximumSize

same as maxExtent; for ST-80 compatibility

 maximumSize: anExtent

same as maxExtent; for ST-80 compatibility

 menuBar

return my menuBar or nil if I have none.
This is only valid for topViews which were built with the UIBuilder.

 minimumSize

same as minExtent; for ST-80 compatibility

 minimumSize: anExtent

same as minExtent; for ST-80 compatibility

 quit

same as closeRequest
(but sometimes sent via the sensors event queue from VW programs)

 application

return the topViews application.
This is new protocol for ST-80 compatibility and not yet fully supported

 application: anApplicationModel

set the topViews application.
This is new protocol for ST-80 compatibility and not yet fully supported

 bePartner

define me as a partner-View.
All partners within the applications windowGroup iconify/deiconify together.

usage example(s):

see example in TopView>>bePartner

 beSlave

define me as a slave-View.
All slaves within the application's windowGroup iconify/deiconify with the masterView(s)
(i.e. they follow their master(s))

usage example(s):

see example in TopView>>beSlave

 sendWindowEvents: collectionOfEventSymbols

define the events that are to be forwarded to the application.
This is being implemented ...

 sizeFixed: aBoolean

this prevents the view from resizing itself when realized.
For normal topViews, this is void, since they don't do this anyway.

However, modalBoxes (especially: DialogBoxes) typically resize themselfes
to the preferredExtent of their components. In some cases, this behavior is
not desired and it should be turned off by setting sizeFixed to true.

To avoid confusion:
This does NOT prevent the window manager from resizing the view,
instead it tells the view to NOT resize ITSELF.

 labelChannel

return the labelChannel - or nil

 labelChannel: aValueHolder

set the labelChannel - a valueHolder holding a string
which is shown as title bar

 maxExtent

return the view's maximum allowed extent

 maxExtent: max

define the maximum extent the view may have -
depends on good-will of window manager

 minExtent

return the view's minimum allowed extent

 minExtent: min

define the minimum extent the view may have -
depends on good-will of window manager

 icon

return the form defined as icon

 icon: aFormOrImage

define the form or image (bitmap) used as icon

 iconLabel

return the name displayed in the icon

 iconLabel: aString

define the name to be displayed in the icon

 iconMask

return the form defined as iconMask.
Notice, that many windowManagers ignore this mask
(usually, only managers which place icons on the background desktop
care for an icon - if at all ...)

usage example(s):

only images possibly have iconMasks

 iconName: aString

this method will vanish soon ... - for backward compatibility

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

 iconView

return the view used as icon-view

 iconView: aView

specify the view to be used as icon.
This may not be supported on all display types

 label

return the view's name in the title area

 label: aString

define the view's name in the window's title area.
If IncludeHostNameInLabel is true, prepend the hostname - now done in windowLabelFor:
(you will appreciate this, if you are working on multiple
machines simultaneously - as I do ...)

 label: labelString iconLabel: iconLabelString

set both the label and the iconLabel

 update: something with: aParameter from: changedObject

the MVC way of changing the label ...

 release

 saveAndTerminate

save & terminate request from the windowManager. The application should
save its data/files/text etc. somehow and close.
If there is an application, let it decide how do do that.
Otherwise, forward it to superclasses which knows how to do this.
(it defaults to a terminate there).
Notice, that not all windowmanagers are nice enough
to send this request; some simply distroy the view.

 terminate

terminate request from the windowManager. If there is an application,
let it decide if it really wants to be close. Otherwise, forward it to
superclasses terminate which knows how to do this.
Notice, that not all windowmanagers are nice enough
to send this request; some simply distroy the view.

 delayedAutoRaiseEvent

called with a delay by the focusIn code, iff the userPref setting is active.
Some (a small number only) may want to prevent autoraise in certain situations
- for example, if one view is controlling another. These get a chance to redefine this
method

 focusIn

the view got the keyboard focus (via the window manager).
I.e. the mouse was moved out into the topView area - restore the
focus to the previous focusView..

usage example(s):

'focusIn ' print. windowGroup process name printCR.

 focusOut

the top-view lost the keyboard focus (via the window manager).
I.e. the mouse was moved out of the topView area.

 processShortcut: aKeyEvent

a shortcut key event as forwarded from the keyboardProcessor - if there is the
shortcut key defined, process the shortcut and return true - otherwise false.

 scheduleAutoRaiseAfter: ms

bring the window to the front after some delay.
but not, if my windowGroup is in a modal or popup action

 showActivity: someMessage

some activityNotification shalt be communicated to
the user. Forward it to my application (if any).
(that one should know how to deal with it).
Otherwise, simply ignore it.

 addToCurrentProject

add the receiver (a topview) to the current projects set-of-views.
(If there is a current project)

 defaultControllerClass

for ST-80 compatibility only - not used in ST/X

 initEvents

 initialize

must be called if redefined

 mapped

don't do this in X11 - switching between
virtual desktops would change the window stacking all the time

 reAdjustGeometry

sent as a final step when an image is restarted.
when we come up on a smaller display,
make certain, that the receiver is visible

 reinitialize

reopen the receiver if it was visible before.
This is called right after snapIn; Notice, that all instance variables
(such as shown, realized etc.) are left-overs from the time the snapout
was done. Remap the receiver, if it was mapped at snapout time

 removeFromCurrentProject

remove the receiver (a topview) from the current projects set-of-views.
(If there is a current project)

 restarted

sent by my windowGroup, when restarted from an image.
Nothing done here, but can be redefined to perform any actions
required to reset the application after an image-restart.
(for example: check if application files are still around, restart
subprocesses etc.).

 printOn: aStream

just for your convenience in inspectors ...
... add the view's label to the displayString.

 convertedIcon

make certain, that the icon is compatible with my device;
this means converting it to a format (typically: monochrome) which
the device supports. Return a compatible version of the icon.

 convertedIcon: iconArg

make certain, that the image argument is compatible with my device;
this means converting it to a format (typically: monochrome) which
the device supports. Return a compatible version of the icon.

 convertedIconMask: aMask

return a version of the argument which can be used as an iconMask
on my device. Typically, this means conversion to a monochrome
mask - future versions may add alpha channel masks, if the device supports
them ...

 setWindowGroupFromApplication

get the applications topView and set my windowGroup to its wg.

 windowLabelFor: labelString

return an expanded labelString, according to the hostName-in-window setting.
The labelString may include positional parameters:
%1 - the actual label
%2 - the hostname
%3 - the userName
%4 - the processId
%5 - the TOP-directories name
%6 - the TOP-directories path

 processName

return a string to be shown for my process in the
process monitor. This has no semantic meaning, but exists
for your convenience only.

 create

create - make certain that icon is available

 expand

de-iconify the receiver at its old position

 physicalCreate

common code for create & recreate

 postRealize

postRealize actions - tell the application (if any).

 preRealize

invoked right before the view is realized.
preRealize actions - tell the application (if any).

 recreate

recreate the view after a snap-in or a migration

 collapse

iconify the receiver

Examples:

    |topView|

    topView := StandardSystemView new.
    topView label:'my first view'.
    topView extent:200 @ 200.
    topView open.

    |topView|

    topView := StandardSystemView extent:200 @ 200.
    topView label:'Hello world'.

    topView icon:(Image fromFile:'hello_world.icon').
    topView open.

    |iconView topView|

    iconView := ClockView new.

    topView := StandardSystemView extent:200 @ 200.
    topView label:'Hello world'.

    topView iconView:iconView.
    topView open.

    |topView button|

    topView := StandardSystemView new.
    topView label:'my second view'.
    topView extent:200 @ 200.

    button := Button label:'close' in:topView.
    button action:[topView destroy].

    topView open.

    |topView button|

    topView := StandardSystemView new.
    topView label:'my second view'.
    topView extent:200 @ 200.

    button := Button label:'close' in:topView.
    button action:[topView destroy].
    button origin:0.25 @ 0.25 corner:0.75 @ 0.75.

    topView open.

    |topView panel button1 button2 button3|

    topView := StandardSystemView new.
    topView label:'my second view'.
    topView extent:200 @ 200.

    panel := HorizontalPanelView origin:0.0@0.0 corner:1.0@1.0 in:topView.
    panel inset:10.
    panel level:-1.

    button1 := Button label:'one' in:panel.
    button1 action:[Transcript showCR:'one pressed'].

    button2 := Button label:'two' in:panel.
    button2 action:[Transcript showCR:'two pressed'].

    button3 := Button label:'three' in:panel.
    button3 action:[Transcript showCR:'three pressed'].

    topView open.