"

 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 labels focusSequence

		namedComponents helpKeys componentCreationHook applicationClass

		keyboardProcessor subCanvasSpecs'

	classVariableNames:'StopOnError Verbose'

	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.

    The order of the lookup sequence to access an aspect is defined:

        application

        application class

        additional  class (applicationClass).

    Methods to access any aspect are located in the category

    'spec creation aspect fetch'.

    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 class methodsFor:'debugging'!

stopOnError:aBoolean

    "enable/disable debug halt when aspects are missing.

     Useful during development, to detect missing aspects.

     The default is off."

    StopOnError := aBoolean

    "Modified: / 4.8.1998 / 19:40:09 / cg"

!

verbose:aBoolean

    "enable/disable debug messages on the Transcript.

     Useful during development, to detect missing aspects.

     The default is off."

    Verbose := aBoolean

    "Created: / 4.8.1998 / 19:39:37 / cg"

    "Modified: / 4.8.1998 / 19:40:14 / cg"

! !

!WindowBuilder methodsFor:'Compatibility - ST80'!

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"

! !

!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

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

     This is a private interface for the UIPainter to pass down the app-class

     to the specs when editing."

    ^ applicationClass 

!

applicationClass:something

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

     This is a private interface for the UIPainter to pass down the app-class

     to the specs when editing."

    applicationClass := something.

!

aspectAt:aSymbol

    "return the aspect for a symbol or nil.

    "

    ^ self 

        aspectAt:aSymbol 

        ifAbsent:[self aspectNotFound:aSymbol error:'no aspect for:']

    "Modified: / 4.8.1998 / 19:29:36 / cg"

!

aspectAt:aSymbol ifAbsent:exceptionBlock

    "return the aspect for a symbol or the value from exceptionBlock.

    "

    |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

            ].

            ^ exceptionBlock value.

        ]

    ].

    ^ nil

    "Created: / 4.8.1998 / 19:28:30 / cg"

    "Modified: / 4.8.1998 / 19:37:02 / cg"

!

aspectAt:aSymbol put:aModel

    "store an aspect identified by its symbol and its value

    "

    bindings isNil ifTrue:[

        bindings := IdentityDictionary new

    ].

    ^ bindings at:aSymbol put:aModel

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

!

bindingAt:aSymbol

    "return the binding for a symbol or nil if there is none

    "

    bindings notNil ifTrue:[

        ^ bindings at:aSymbol ifAbsent:nil.

    ].

    ^ nil

!

bindings

    "return my bindings

    "

    ^ bindings

!

bindings:aDictionary

    "set bindings to a dictionary

    "

    bindings := aDictionary

!

componentAt:name

    "return a component identified by its name.

    "

    |widget appBuilder masterApplication masterBuilder|

    namedComponents notNil ifTrue:[

        widget := namedComponents at:name asSymbol ifAbsent:nil.

        widget notNil ifTrue:[^ widget].

    ].

    "/ cg the following code looks in any application-

    "/ or master applications builder for the component.

    "/ This as an effect, if a subcanvases builder is asked for

    "/ a component, which is actually held by the real-apps builder

    "/ (in case they have different builders).

    "/ For now, this code is disabled, since I dont know what effect this

    "/ has to existing code ...

"/    application notNil ifTrue:[

"/        (appBuilder := application builder) notNil ifTrue:[

"/            appBuilder ~~ self ifTrue:[    

"/                ^ appBuilder componentAt:name

"/            ]

"/        ].

"/

"/        (masterApplication := application masterApplication) notNil ifTrue:[

"/            (masterBuilder := masterApplication builder) notNil ifTrue:[

"/                masterBuilder ~~ self ifTrue:[    

"/                    ^ masterBuilder componentAt:name

"/                ]

"/            ]

"/        ]

"/    ].

    ^ nil

!

componentAt:name put:aComponent

    "store a component identified by its name.

    "

    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 

    "return my focus sequence

    "

    focusSequence isNil ifTrue:[

        focusSequence := OrderedCollection new

    ].

    ^ focusSequence

    "Modified: / 12.3.1999 / 00:02:04 / cg"

!

helpKeyFor:aComponent

    "return the helpkey for a component or nil

    "

    |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

    "assign a key for a component which is used to access the help text

     from the application.

    "

    aKey isNil ifTrue:[

        helpKeys isNil ifFalse:[

            helpKeys removeKey:aComponent ifAbsent:nil

        ]

    ] ifFalse:[

        helpKeys isNil ifTrue:[

            helpKeys := IdentityDictionary new

        ].

        helpKeys at:aComponent put:aKey

    ]

!

keyboardProcessor

    "return my keyboard processor

    "

    keyboardProcessor isNil ifTrue:[

        keyboardProcessor := KeyboardProcessor new    

    ].

    ^ keyboardProcessor

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

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

!

keyboardProcessor:aKeyboardProcessor

    "set my keyboard processor

    "

    keyboardProcessor := aKeyboardProcessor

    "Created: / 18.6.1998 / 19:59:38 / cg"

!

labelAt:name

    labels isNil ifTrue:[^ nil].

    ^ labels at:name asSymbol ifAbsent:nil

    "Created: / 27.2.1998 / 13:52:28 / cg"

!

labelAt:name put:aLabelString

    labels isNil ifTrue:[

        labels := IdentityDictionary new.

    ].

    labels at:name asSymbol put:aLabelString

    "Created: / 27.2.1998 / 02:30:54 / cg"

!

menuAt:aKey

    "Find a binding for the menu named aKey, either in the bindings 

     or from the source"

    ^ self menuFor:aKey

!

menuAt:aSymbol put:someMenuOrHolder

    "add someMenuOrHolder as the binding for the menu named aSymbol to the bindings"

    ^ self aspectAt:aSymbol put:someMenuOrHolder

!

namedComponents

    "return list of named components

    "

    ^ namedComponents

!

subCanvasAt:majorKey at:minorKey

    "get the subCanvas or subSpec specification from major and minor key.

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

     which can be filled via #specificationAt:at:put: messages.

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

     #specificationFor: (if majorKey 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 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:[

        ^ self specificationFor:minorKey

    ].

    application notNil ifTrue:[

        "/ look for class in applications namespace ...

        cls := application resolveName:majorKey.

    ] ifFalse:[

        "/ fallBack - use that global, if it exists

        cls := Smalltalk at:majorKey.

        cls isNil ifTrue:[

            Transcript showCR:('WindowBuilder[warning]: missing application when fetching majorKey:' , majorKey).

        ].