Class: ModalBox

• Inheritance
• Description
• Related information
• Class protocol
  • defaults
  • initialization
• Instance protocol
  • accessing
  • event handling
  • initialization & release
  • move & resize
  • queries-internal
  • show & hide

Inheritance:

   Object
   |
   +--GraphicsContext
      |
      +--DeviceGraphicsContext
         |
         +--GraphicsMedium
            |
            +--DisplaySurface
               |
               +--SimpleView
                  |
                  +--View
                     |
                     +--TopView
                        |
                        +--StandardSystemView
                           |
                           +--ModalBox
                              |
                              +--DialogBox

Package:

stx:libview

Category:

Views-Basic

Version:

rev: 1.102 date: 2009/11/17 13:30:07

user: cg

file: ModalBox.st directory: libview

module: stx stc-classLibrary: libview

Author:

Claus Gittinger

Description:

this class implements modal boxes; ModalBoxes are different from
others, in that they take control over the current topview, until 
all processing is done (i.e. the currently active topview and all of
its subviews will not handle user events while the box is active).

ModalBoxes are either implemented as transient windows
(if UseTransientViews := true) or as override redirect views.
Some window managers have problems with either; so you may want to
change the default setting from your display.rc file.

Related information:

    StandardSystemView
    DialogBox
    [introduction to view programming]

Class protocol:

 defaultExtent

this defines the defaultExtent for instances of me;
the value returned here is usually not correct for concrete subclasses,
so you better redefine this method.
The value returned here is usually ignored, and
the value from preferredExtent taken instead.

 defaultLabel

return the boxes default window title.

 updateStyleCache

extract values from the styleSheet and cache them in class variables

 useTransientViews: aBoolean

change the way modalBoxes are created on the Display.
If the argument is true, transient views are used;
otherwise override redirect views are used.
Depending on your windowmanager, either one may have problems.
You may want to change the setting
from your display.rc or d_xxx.rc file.
This is now obsolete - transient views work and are always used.

 usingTransientViews

return true, if transient views are used
for modalBoxes. This is somewhat obsolete.

 initialize

Instance protocol:

 escapeIsCancel

return the escapeIsCancel setting - defaults to true for modalMox here.

 exclusiveKeyboard: aBoolean

set/clear exclusive locking of the keyboard;
If set, the box will take total control over the
keyboard, not allowing input to other views/boxes
while active.
DANGER:
only use this for very very urgent boxes, since
no interaction with ANY view on the screen is possible then.

 coveredBy: aView

the receiver has been covered by another view.
If the other view is a non-modal one, raise

 terminate

this is the close from a windowmanager
(only if UseTransientViews == true)

 visibilityChange: how

raise when covered - this should not be needed, since we
have been created as override-redirect window (which should
stay on top - but some window managers (fvwm) seem to ignore
this ...

 xxxpointerEnter: state x: x y: y

mhmh: this seems to be a special X kludge;
without the following, we will not regain input focus after
pointer is reentered.

 addToCurrentProject

ignored here

 create

 destroy

destroy the view.
redefined to also destroy my shadow, if there is one,
and to release the global keyboard grab (if there is one)

 initEvents

initialize event handling; redefined to enable visibility changes

 initStyle

setup viewStyle specifics

 initialize

 isPopUpView

return true, if I want to come up without decoration
and popUp to top immediately.

 realize

 reinitialize

if I have already been reinited - return

 resize

resize myself to make everything visible

 resizeUnderPointer

resize myself to make everything visible, AND possibly change the origin
to have the mouse pointer stay within my bounds.
This is used for self-resizing enterBoxes, to avoid moving
the box away from the cursor.

 doMove

the move button was pressed.
This method is only used with non-transient views
(UseTransientViews == false).

 doResize

the resize button was pressed.
This method is only used with non-transient views
(UseTransientViews == false).

 windowLabelFor: labelString

dialogs do not include the hostname in the window label

 windowStyle

return a symbol describing my style (one of: #dialog, #popUp or #normal)
(may be used internally by the device as a decoration hint)

 autoHideAfter: seconds with: anAction

install a background process, which hides the box
after some time. Also, if non-nil, anAction will be
evaluated then. The action will not be evaluated if
the box is closed by the user pressing a button.

 fixSize

this is sent right before the modalBox is made visible;
If the size is not fixed, adjust my size.

 hide

make the receiver invisible and leave control

 hideRequest

hide request from windowGroup (i.e. via Escape key).
Can be redefined in subclasses which dont like this

 mapped

wait till visible for grabbing

 open

default for modalboxes is to come up modal at the pointer position

 openAt: aPoint

default for modalboxes is to come up modal at the pointer position

 openAtCenter

default for modalboxes is to come up modal at the pointer position

 openModal: aBlock

open the box modal;
In addition to the basic (inherited) modalloop, change
the current active windowgroups cursors to the busy-stop cursor, show
a shadow, and raise the box.

 show

make myself visible (at the last or default position) and take control.
If that position is out of the screen area, moves the receiver to make
it fully visible.

 showAt: aPoint

make myself visible at aPoint.
Fix position to make box fully visible

 showAt: aPoint center: center

make myself visible at aPoint. center specifies
if the view should show up centered around aPoint.

 showAt: aPoint centerX: centerX centerY: centerY

make myself visible at aPoint. centerX/centerY specify
if the view should show up centered around aPoint.
Fix position to make box fully visible

 showAtCenter

make myself visible at the screen center.

 showAtPointer

make myself visible at mouse pointer shifted to have
convenient button under cursor. self positionOffset should
return that offset (usually redefined, since we dont know here,
which button should be under cursor).

 showAtPointerNotCovering: aView

make myself visible at mouse pointer shifted to have
convenient button under cursor.
Fix position to make the box fully visible AND to make sure that
aView is not covered.

 showCenteredIn: aView

make myself visible at the center if aView.

 unmapped

mhmh - unmapped by the windowManager - if realized (i.e. not closing),
keep the realized flag true (to avoid exiting the modal event loop).
Consider this a kludge.