"

 COPYRIGHT (c) 1993 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.

"

"{ Package: 'stx:libview' }"

Object subclass:#WindowGroup

	instanceVariableNames:'graphicsDevice views topViews myProcess mySensor isModal

		previousGroup focusView focusSequence preEventHook postEventHook

		pointerView isForModalSubview focusByTab groupHasFocus busyHook

		busyHookTimeout inModalLoop preEventHooks postEventHooks

		creatingProcess traceEvents processPriority'

	classVariableNames:'LastActiveGroup LastActiveProcess LeaveSignal

		WindowGroupQuerySignal LastEventQuerySignal BusyHookTime'

	poolDictionaries:''

	category:'Interface-Support'

!

!WindowGroup class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 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.

"

!

documentation

"

    In Smalltalk/X, the known (ST-80) concept of a controller has been

    extended (split) into a WindowGroup which handles process related stuff, 

    and the Controller, which only handles events for a view and defines the user interaction.

    The controller functionality might be (actually: often is) included in the view components.

    All interaction is via event queues - there is no polling in controllers (not even conceptionally).

    WindowGroups are responsible to wait for and forward events for a group of 

    windows. All views in a windowGroup share a single windowSensor which holds the

    event queue (therefore subviews all share the same input event queue).

    Actually, there are two separate event queues - one for damage and view-visibility-related events,

    another one for user interaction (such as mouse, keyboard etc.)

    The event queues are filled with incoming events as arriving from the physical display.

    This is done by a separate process (so called event-dispatcher) which runs at a higher

    priority. The event dispatcher determines the queue into which an event has to be placed,

    by asking the view for which the event is destined (via the views sensor).

    There may be multiple event dispatchers running (to support multiple displays);

    see the documentation/examples in DeviceWorkstation/XWorkstation on how this is done.

    Except for modal boxes, a separate process is created for each windowGroup 

    which waits for events to arrive and processes them, by sending corresponding

    event messages to the views controller or the view (*). 

    The controller is determined by asking the view (for which the event is destined);

    if the returned controller is nil, the event is sent directly to the view.

    This allows for simple views to work without a controller.

    (all of this is actually done in a WindowEvent method)

    Therefore, multiple applications run pseudo parallel.

    Even if some window performs a long time computation, events are still received

    and entered into the corresponding event queues (because the event dispatcher process

    runs at a higher priority). However, the actual processing of the event is only

    possibly if no other process is busy at the same or a higher priority (unless timeslicing is enabled).

    If timeslicing is off, it is possible to change a windowProcesses priority in order to give 

    other windows a chance to execute (some views do this while performing longtime actions).

    Modal boxes create an extra window group for the components of the modal

    box, but execute the event-processing loop for this new group in the original process - 

    therefore, the original windowgroup is blocked for the duration of the modal 

    interaction.

    However, the modal-event processing loop peeks into the original groups event queue

    from time to time, and handles expose events. Thus, even while blocked for user input,

    the original group continues to get update/redraw events.

    Normally, one windowgroup is associated to each topview (StandardSystemView)

    and all of its subviews. However, this is not strictly required; 

    it is possible to create extra windowgroups for subviews, which will let them

    run in parallel 

        (for example, the FileBrowsers kill-Button is created that 

         way, to allow a kill of an executing unix command, while the browser 

         itself reads the pipeStream for incoming text.

         Even if the fileBrowser is busy reading the pipe, the killButton is still

         working and allows terminating the pipe-read action).

    On the other hand, multiple topviews can be placed into the same windowGroup;

    which allows for multiview applications, of which only one communicates with

    the user at a time (for example: the GUI painters canvas and gallery are in the same group).

    Multiple topviews within a windowGropup can be configured to behave like one 

    unit with respect to iconification, deiconification and termination.

    This is done by creating multiple topViews in one group, and setting up a master/slave

    or partner relation among them (see TopView>>beSlave and TopView>>bePartner).

    WindowGroups also support a focus window: this is the one that gets the

    keyboard input - even if the cursor is located in another subview.

    The sequence is defined by the topView or its model (typically an applicationModel).

    It should return an orderedCollection of subviews when asked via #focusSequence.

    For debugging or special event manipulations, windowGroups allow for hooks to be installed 

    around the processing of events - preEventHook is sent a #procesEvent: message before an event is processed,

    postEventHook is informed after the event has been processed.

    The preEventHook should return a boolean - if it returns true, the event is considered

    being already processed by the hook and ignored.

    This allows for event-tracing, timing or even filtering (if preEventHook returns true).

    (notice: there is also an eventHook facility available in the sensor class.)

    Finally, windowgroups are the perfect place for things like defining a

    cursor for all associated views, flushing all input, waiting for expose events etc.

    Late News:

      a busyHook and busyHookTimeout has been added; this hook-(block) gets invoked, whenever

      the process was busy handling an event for some time. This can be used to automatically install

      a busy cursor (hour-glass) in an application, if some processing takes some time

      (without a need for #withCursorDo: all over the place in the application)

    Dont get confused:

        You dont have to care for all those details in the normal case;

        a windowgroup is created for you automatically, when a view is opened.

        All of the internals are not required to be known for most applications.

    [instance variables:]

        views                   collection of views of this group

        topViews                collection of topviews of this group

        myProcess               the process executing the events

        mySensor                my input sensor

        isModal                 true if this is for a modal box

        previousGroup           if modal, the group that started this one

        focusView               the one that has the keyboard focus (or nil)

        focusByTab              if focus came via tabbing 

                                (as opposed to an implicit focus change)

        focusSequence           defines the focus sequence

        preEventHook            if non-nil, that one gets notified of incoming

                                events BEFORE an event is dispatched.

                                May eat events (i.e. suppress dispatch)

                                (hook for event filters or recorders)

        postEventHook           if non-nil, that one gets notified

                                AFTER an event was dispatched.

        isForModalSubView

        groupHasFocus           true, if this windowGroup has the focus

    [class variables:]

        LeaveSignal             if raised, a modal box leaves (closes)

        WindowGroupQuerySignal  to ask for the current windowGroup,

                                anywhere in the program, simply raise this

                                signal. The raise returns nil, for processes,

                                which are not under control of a windowGroup.

                                (i.e. wg := WindowGroup windowGroupQuerySignal raise)

        LastEventQuerySignal    to ask for the event which was responsible

                                for being where you are (whereever that is).

                                The raise returns nil, if you did not arrive

                                there due to an event.

                                (i.e. ev := WindowGroup lastEventQuerySignal raise)

                                The event can be asked for the view, the type

                                of event, x/y position etc.

    (*) 

        due to historic reasons, many views have the controller functionality

        integrated, and handle events themself. The windowSensor takes care

        of this, by checking if a view has a controller, and, if so, forwarding 

        the events to it. Otherwise, events are sent directly to the view.

        In the future, all views will be rewritten to actually use a controller.

        Currently (being in the middle of this migration), only some views

        (buttons, toggles and subclasses) do so.

    For more information, read 'introduction to view programming' in the

    doc/online directory.

    [author:]

        Claus Gittinger

    [see also:]

        WindowSensor WindowEvent EventListener KeyboardForwarder

        DeviceWorkstation

        View StandardSystemView

        ApplicationModel

        Process ProcessorScheduler

        (``Working with processes (programmers manual)'': programming/processes.html#VIEWSNPROCS)

"

! !

!WindowGroup class methodsFor:'initialization'!

initialize

    LeaveSignal isNil ifTrue:[

	LeaveSignal := (Signal new) mayProceed:true.

	LeaveSignal nameClass:self message:#leaveSignal.

	LeaveSignal notifierString:'unhandled leave signal'.

	WindowGroupQuerySignal := QuerySignal new.

	WindowGroupQuerySignal nameClass:self message:#windowGroupQuerySignal.

	WindowGroupQuerySignal notifierString:'query for windowgroup'.

	LastEventQuerySignal := QuerySignal new.

	LastEventQuerySignal nameClass:self message:#lastEventQuerySignal.

	LastEventQuerySignal notifierString:'query for last event'.

    ].

    "WindowGroup initialize"

    "Modified: 9.11.1996 / 17:00:53 / cg"

! !

!WindowGroup class methodsFor:'instance creation'!

new

    "create and return a new WindowGroup object"

    ^ self basicNew initialize

! !

!WindowGroup class methodsFor:'Signal constants'!

lastEventQuerySignal

    "return the signal which is used to query for the last event"

    ^ LastEventQuerySignal

    "Created: 17.7.1996 / 20:36:04 / cg"

!

leaveSignal

    "return the signal which is used to exit a modal loop.

     This private signal, is always caught while a modalbox is active.

     Raising it will exit the modal loop and return from the views #openModal

     method."

    ^ LeaveSignal

!

windowGroupQuerySignal

    "return the signal which is used to query for the windowGroup"

    ^ WindowGroupQuerySignal

    "Created: 17.7.1996 / 20:36:04 / cg"

! !

!WindowGroup class methodsFor:'accessing'!

activeApplication

    "return the currently active application.

     Notice: this may be a modal dialogs application - i.e. it is not

     always the main application."

    |activeGroup|

    (activeGroup := self activeGroup) notNil ifTrue:[

        ^ activeGroup application

    ].

    ^ nil

    "

     WindowGroup activeApplication 

    "

!

activeGroup

    "return the currently active windowGroup.

     The returned value may not be fully correct, in case the current process

     handles multiple windowGroups simultaneously. In this case, 

     (usually) the first group is returned (prefering a modal if there is one). 

     (maybe we should return a collection of windowGroups here).

     This method is required to simulate the historic ST-80 single display

     behavior for Cursor>>show / Cursor>>showWhile and some others (raising the

     activeGroups topView when modalBoxes appear) on multiple display screens. 

     These methods should change the cursor for the currently 

     active windowGroup ONLY, instead of globally affecting the display or

     all views

     (since, depending on the priority, other views could be unaffacted by this 

      and an overall cursor change does not make sense.)"

    |activeProcess groups wg|

    Processor isNil ifTrue:[^ nil]. "/ only during very early init phase

    activeProcess := Processor activeProcess.

    " caching the last value ..."

    activeProcess == LastActiveProcess ifTrue:[

        (LastActiveGroup notNil 

            ^ LastActiveGroup

        ]

    ].

    WindowGroupQuerySignal isNil ifTrue:[^ nil]. "/ only during very early init phase

    wg := WindowGroupQuerySignal query.

    wg isNil ifTrue:[

        "/ mhmh - noone willing to answer that question ...

        "/ (how can this happen ?)

        groups := self scheduledWindowGroups 

                    select:[:wg | wg process == activeProcess].

        groups notEmpty ifTrue:[

            wg := groups detect:[:wg | wg isModal] ifNone:nil.

            wg isNil ifTrue:[

                wg := groups anElement

            ]

        ].

    ].

    wg notNil ifTrue:[

        LastActiveProcess := activeProcess.

        LastActiveGroup := wg.

    ].

    ^ wg

    "

     WindowGroup activeGroup 

    "

    "Modified: / 3.9.1995 / 14:49:53 / claus"

    "Modified: / 17.4.1998 / 11:49:28 / cg"

    "Modified: / 18.3.1999 / 18:30:33 / stefan"

!

activeMainApplication

    "return the currently active main application.

     Notice: 

        if invoked by a modal application, this returns the main (non-modal)

        application."

    |activeGroup mainView|

    (activeGroup := self activeGroup) notNil ifTrue:[

        (mainView := activeGroup mainGroup mainView) notNil ifTrue:[

            ^ mainView application

        ]

    ].

    ^ nil

    "

     WindowGroup activeMainApplication 

    "

!

scheduledWindowGroups

    "return a collection of all windowGroups (possibly for different

     display devices) which are scheduled (i.e. which have a process 

     running, handling events)."

    |set screens|

    screens := Screen allScreens.

    screens size == 0 ifTrue:[^ #()].

    set := IdentitySet new.

    screens do:[:aDevice |

	aDevice allViewsDo:[:aView |

	    |wg|

	    (wg := aView windowGroup) notNil ifTrue:[

		wg process notNil ifTrue:[

		    set add:wg

		]

	    ].

	].

    ].

    ^ set asArray

    "

     WindowGroup scheduledWindowGroups   

    "

    "Modified: 1.9.1995 / 13:43:09 / claus"

    "Modified: 18.8.1997 / 18:44:29 / cg"

!

setActiveGroup:aGroup

    "set the currently active windowGroup.

     Temporary; do not use this interface, it will vanish."

    LastActiveProcess := Processor activeProcess.

    LastActiveGroup := aGroup

! !

!WindowGroup class methodsFor:'focus control support'!

takeFocusFromDevice:aDevice

    |prevFocusView prevFocusGroup prevFocusCameViaTab|

    "/

    "/ take the focus from whichEver view had it previously

    "/

    prevFocusView := aDevice focusView.

    prevFocusView notNil ifTrue:[

        aDevice focusView:nil.

        (prevFocusGroup := prevFocusView windowGroup) notNil ifTrue:[

            prevFocusCameViaTab := prevFocusGroup focusCameByTab.

            prevFocusView showNoFocus:prevFocusCameViaTab. "/ true is bad - see pullDownMenu.

            self sendKeyboardFocusEventTo:prevFocusView withArgument:false.

        ].

    ].

    "Modified: / 08-11-2006 / 12:05:22 / cg"

! !

!WindowGroup class methodsFor:'others'!

sendKeyboardFocusEventTo:aView withArgument:arg

    |sensor ev|

    aView isNil ifTrue:[^ self].

    (sensor := aView sensor) notNil ifTrue:[

        ev := WindowEvent keyboardFocus:arg view:aView.   

        sensor notifyEventListenersAbout:ev.

        sensor pushEvent:ev.

    ] ifFalse:[

        aView hasKeyboardFocus:arg

    ].

! !

!WindowGroup methodsFor:'accessing'!

creatingProcess

    "return the process which created this group or nil.

     Only returns non-nil for modal groups."

    ^ creatingProcess

    "Modified: / 17.8.1998 / 10:21:29 / cg"

!

device

    "return the device, we receive our events from"

    <resource:#obsolete>

    self obsoleteMethodWarning:'use #graphicsDevice'.

    ^ self graphicsDevice

    "Modified: 5.7.1996 / 17:53:58 / cg"

!

graphicsDevice

    "return the device, we receive our events from"

    |dev|

    graphicsDevice notNil ifTrue:[^ graphicsDevice].

    topViews notNil ifTrue:[

	topViews do:[:v |

	    |app|

	    v notNil ifTrue:[

		(app := v application) notNil ifTrue:[

		    "/

		    "/ ok, it has an application;

		    "/ ask it for preferences.

		    "/