"

 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.

"

Object subclass:#WindowBuilder

	instanceVariableNames:'window application bindings visuals focusSequence namedComponents

		helpKeys componentCreationHook applicationClass keyboardProcessor

		subCanvasSpecs'

	classVariableNames:'StopOnError'

	poolDictionaries:''

	category:'Interface-Support-UI'

!

!WindowBuilder class methodsFor:'documentation'!

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.

"

!

documentation

"

    a no-op class, for systems which do not use the UIBuilder.

    Concrete subclasses know how to create a view (with components) from

    some interface spec. 

    Currently, an experimantal version of UIBuilder exists,

    and more may be added in the future (for example, to parse different UI

    specs - thinking of motifs UIL specs, Windows DialogSpecs etc.).

    [instance variables:]

        window          <View>

                                the topView into which the components

                                are (have been) created from the specification

        application     <ApplicationModel>

                                the application object (typically an instance

                                of a subclass of ApplicationModel).

                                That one is usually supposed to provide

                                valueHolders for aspects, action methods

                                menuSpecs and possibly more windowSpecs.

                                Usually means, that most of those can also be

                                provided to the builder via a set of bindings,

                                which overrides those.

        bindings        <Dictionary>

                                can be set (or filled) with bindings for

                                aspects to be used when setting up the models

                                for components. Useful either to overwrite

                                corresponding appModel aspects or if the appModel

                                does not want to procide those.

                                (for example, to open a dialog and provide the

                                 bindings in a dictionary - as opposed to

                                 providing them via aspect methods)

        visuals                 not yet used - for compatibility

        focusSequence   <Collection>

                                maintained during the build process;

                                contains tabable components.

                                This will be replaced by a more intelligent

                                mechanism in the near future.

        namedComponents <Dictionary>

                                contains name->component associations for

                                all components which have a non-nil component

                                name. Created during the build process.

        helpKeys                not yet used - for compatibility

        componentCreationHook <BlockOrNil>

                                can be set before the components are built

                                from the spec, to provide an arbitrary

                                callBacks-hook which will be invoked after

                                a component has been created from a spec. 

                                The UIPainter uses this to maintain its

                                component<->spec assiciations.

                                Can be set by the app, to catch creation of

                                components and fiddle around during the

                                creation process (change extents, colors or whatever)

        applicationClass <ClassOrNil>

                                can be set to provide an additional class which

                                is asked for aspects during the build process.

                                If not set, the app is asked, which itself asks

                                its class.

        keyboardProcessor       not yet used - for compatibility

                                Will eventually takeover the functionality

                                of the focusSequence, shortcuts & provide a hook

                                for the app.

        subCanvasSpecs <Dictionary>

                                can be set by the app to provide subcanvas

                                specs (much like the bindings dictionary)

    [author:]

        Claus Gittinger

"

! !

!WindowBuilder methodsFor:'accessing'!

addBindings:moreBindings

    "used with subDialogs, which provide local bindings.

     All bindings from moreBindings overwrite any local bindings."

    moreBindings notNil ifTrue:[

        moreBindings keysAndValuesDo:[:aKey :aValue |

            bindings at:aKey put:aValue

        ]

    ]

    "Created: 28.2.1997 / 14:14:33 / cg"

!

application

    "return the application (an ApplicationModel),

     for which the view is built.

     This one is supposed to provide the aspects, menus etc."

    ^ application

    "Modified: 17.1.1997 / 19:04:40 / cg"

!

application:anApplicationModel

    "set the application (an ApplicationModel),

     for which the view is built.

     This one is supposed to provide the aspects, menus etc."

    application := anApplicationModel

    "Modified: 17.1.1997 / 19:04:47 / cg"

!

applicationClass:something

    "set the value of the instance variable 'applicationClass' (automatically generated)"

    applicationClass := something.!

aspectAt:aSymbol

    |b|

    aSymbol notNil ifTrue:[

        bindings notNil ifTrue:[

            b := bindings at:aSymbol ifAbsent:nil.

            b notNil ifTrue:[^ b].

        ].

        application notNil ifTrue:[

            Object messageNotUnderstoodSignal handle:[:ex |

                ex parameter selector == aSymbol ifFalse:[

                    ex reject

                ]

            ] do:[

                ^ application aspectFor:aSymbol

            ].

            Object messageNotUnderstoodSignal handle:[:ex |

                ex parameter selector == aSymbol ifFalse:[

                    ex reject

                ]

            ] do:[

                ^ application class aspectFor:aSymbol

            ].

            Transcript showCR:'WindowBuilder: no aspect for ' , aSymbol storeString.

            StopOnError == true ifTrue:[self halt].  "/ avoids debugger in end-user apps

        ].

    ].

    ^ nil

    "Modified: / 29.10.1997 / 17:26:16 / cg"

!

aspectAt:aSymbol put:aModel

    bindings isNil ifTrue:[

        bindings := IdentityDictionary new

    ].

    ^ bindings at:aSymbol put:aModel

    "Modified: 17.1.1997 / 19:28:37 / cg"

!

bindingAt:aSymbol

    bindings notNil ifTrue:[

        ^ bindings at:aSymbol ifAbsent:nil.

    ].

    ^ nil

!

bindings

    ^ bindings

!

bindings:aDictionary

    bindings := aDictionary

!

componentAt:name

    namedComponents isNil ifTrue:[^ nil].

    ^ namedComponents at:name asSymbol ifAbsent:nil

!

componentAt:name put:aComponent

    namedComponents isNil ifTrue:[

        namedComponents := IdentityDictionary new.

    ].

    namedComponents at:name asSymbol put:aComponent

!

componentCreationHook:something

    "set the value of the instance variable 'componentCreationHook' (automatically generated)"

    componentCreationHook := something.!

focusSequence 

    ^ focusSequence

!

helpKeyFor:aComponent

    |v key|

    helpKeys isNil ifTrue:[^ nil].

    v := aComponent.

    [v notNil] whileTrue:[

        (key := helpKeys at:v ifAbsent:nil) notNil ifTrue:[

            ^ key

        ].

        v := v superView

    ].

    ^ nil

!

helpKeyFor:aComponent put:aKey

    aKey isNil ifTrue:[

        helpKeys isNil ifFalse:[

            helpKeys removeKey:aComponent ifAbsent:nil

        ]

    ] ifFalse:[

        helpKeys isNil ifTrue:[

            helpKeys := IdentityDictionary new

        ].

        helpKeys at:aComponent put:aKey

    ]

!

keyboardProcessor

    keyboardProcessor isNil ifTrue:[

        keyboardProcessor := KeyboardProcessor new    

    ].

    ^ keyboardProcessor

    "Created: 3.3.1997 / 18:31:37 / cg"

    "Modified: 3.3.1997 / 18:32:27 / cg"

!

namedComponents

    ^ namedComponents

!

source

    "same as #application, for ST-80 compatibility"

    ^ application

    "Created: 17.1.1997 / 19:03:51 / cg"

!

source:anApplicationModel

    "same as #application:, for ST-80 compatibility"

    application := anApplicationModel

    "Modified: 17.1.1997 / 19:03:57 / cg"

!

subCanvasAt:majorKey at:minorKey

    "get the subCanvas specification from major and minor key.

     Here, we first look for a spec in the private subCanvasSpecs dictionary,

     which can be filled via #subCanvasAt:put: messages.

     If not present, or none is found there, we bounce back trying

     #specificationFor:with: (if minorKey is nil) or by sending the minorKey

     message to the class named as majorKey.

     Notice, that the class named majorKey is first searched in the

     application classes namespace - allowing private classes as majorKey.

    "

    |spec cls app dict dkey|

    subCanvasSpecs notNil ifTrue:[

        dkey := majorKey ? #NoMajorKey.

        dict := subCanvasSpecs at:dkey ifAbsent:nil.

        dict notNil ifTrue:[

            spec := dict at:minorKey ifAbsent:nil.

            spec notNil ifTrue:[^ spec].

        ].

    ].

    majorKey isNil ifTrue:[

        spec := self safelyPerform:#specificationFor: with:minorKey.

        spec isNil ifTrue:[

            spec := self safelyPerform:minorKey

        ]

    ] ifFalse:[

        "/ look for class in applications namespace ...

        app := self application.

        app isNil ifTrue:[

            "/ fallBack - use that global, if it exists

            cls := Smalltalk at:majorKey.

            cls isNil ifTrue:[

                Transcript showCR:('missing application when fetching majorKey:' , majorKey).

            ]

        ] ifFalse:[

            cls := app resolveName:majorKey.

        ].

        (cls notNil and:[cls respondsTo:minorKey]) ifTrue:[

            spec := cls perform:minorKey

        ]

    ].

    ^ spec

    "Modified: / 27.1.1998 / 12:17:13 / cg"

!

subCanvasAt:majorKey at:minorKey put:aSpec

    "deposit a subCanvas specification for major and minor key

     in my private subCanvasSpecs dictionary.

     This will be used later, when building subcanvases, to provide

     (or possibly override an application provided subcanvas) the

     spec for a subcanvas. (see #subCanvasAt:at:)."

    |dict key|

    subCanvasSpecs isNil ifTrue:[

        "/ lazyly initialize

        subCanvasSpecs := IdentityDictionary new

    ].

    key := majorKey ? #NoMajorKey.

    dict := subCanvasSpecs at:key ifAbsent:nil.

    dict isNil ifTrue:[

        dict := IdentityDictionary new.

        subCanvasSpecs at:key put:dict

    ].

    dict at:minorKey put:aSpec

    "Modified: / 27.1.1998 / 12:21:27 / cg"

!

visualAt:name

    visuals isNil ifTrue:[^ nil].

    ^ visuals at:name asSymbol ifAbsent:nil

    "Created: 3.3.1997 / 16:24:17 / cg"

!

visualAt:name put:aVisual

    visuals isNil ifTrue:[

        visuals := IdentityDictionary new.

    ].

    visuals at:name asSymbol put:aVisual

    "Created: 3.3.1997 / 16:24:41 / cg"

!

visuals

    ^ visuals

    "Created: 3.3.1997 / 16:24:00 / cg"

!

visuals:aDictionary

    visuals := aDictionary

    "Created: 3.3.1997 / 16:24:06 / cg"

!

window

    "return the top window (view), for which an interface

     is (being) built"

    ^ window

    "Modified: 17.1.1997 / 19:30:00 / cg"

!

window:aView

    "set the top window (view), for which an interface

     is (being) built"

    window := aView

    "Modified: 17.1.1997 / 19:30:22 / cg"

!

windowGroup

    ^ window windowGroup

    "Modified: 17.6.1997 / 18:04:01 / cg"

! !

!WindowBuilder methodsFor:'aspect access support'!

booleanValueAspectFor:aKey

    "helper (common code) to generate a boolean aspect if required.

     If no binding exists for aKey, a valueHolder holding false is

     created and added to the bindings.

     Otherwise, the existing binding is returned."

    ^ self valueAspectFor:aKey initialValue:false

    "Modified: 28.7.1997 / 12:53:57 / cg"

!

nilValueAspectFor:aKey

    "helper (common code) to generate a valueHolder aspect if required.

     If no binding exists for aKey, a valueHolder holding nil is

     created and added to the bindings.

     Otherwise, the existing binding is returned."

    ^ self valueAspectFor:aKey initialValue:nil

    "Modified: 28.7.1997 / 12:54:06 / cg"

!

valueAspectFor:aKey initialValue:initialValue

    "helper (common code) to generate a valueHolder aspect if required.

     If no binding exists for aKey, a valueHolder holding initialValue is

     created and added to the bindings.

     Otherwise, the existing binding is returned."

    |holder|

    (holder := self bindingAt:aKey) isNil ifTrue:[

        self aspectAt:aKey put:(holder :=  initialValue asValue).

    ].

    ^ holder

    "Created: 28.7.1997 / 12:53:45 / cg"

    "Modified: 28.7.1997 / 12:54:13 / cg"

! !

!WindowBuilder methodsFor:'building'!

buildFromSpec:aSpec

    ^ self subclassResponsibility

!

makeTabable:aComponent

    "add a component to the list of tabable components"

    focusSequence isNil ifTrue:[

        focusSequence := OrderedCollection new.

    ].

    focusSequence add:aComponent

    "Modified: / 31.10.1997 / 18:39:30 / cg"

! !

!WindowBuilder methodsFor:'message sending'!

safelyPerform:aSelector

    "send the message aSelector to the receiver self or application;

     the result returned from the send or nil is returned

    "

    |res|

    aSelector isSymbol ifTrue:[