"

 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.

"

"{ Package: 'stx:libview2' }"

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 - VW'!

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:[

        bindings isNil ifTrue:[

            bindings := IdentityDictionary new

        ].

        bindings declareAllFrom:moreBindings

    ]

    "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).

     WARNING:

        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).

     WARNING:

         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:[

            MessageNotUnderstood 

                ignoreNotUnderstoodOf:aSymbol

                in:[

                    ^ application aspectFor:aSymbol

                ].

            MessageNotUnderstood 

                ignoreNotUnderstoodOf:aSymbol

                in:[

                    ^ 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|

    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 has 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 masterApplication masterBuilder|

"/

"/        (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.

!

findComponentAt:name

    "recursively search for a component identified by its name in myself

     and all of my subApplications.

    "

    ^ self findComponentAt:name ignoringViews:(IdentitySet new).

!

findComponentAt:name ignoringViews:triedViews

    "recursively search for a component identified by its name in myself

     and all of my subApplications.

     As a builders applications view might be different from the builders view,

     we must be careful to avoid endless recursion if a subview refers to the topviews builder,

     (sigh)

    "

    |comp window app b|

    (comp := self componentAt:name) notNil ifTrue:[^ comp].

    window := self application window.

    (triedViews includes:window) ifTrue:[^ nil].

    triedViews add:window.

    window allSubViewsDo:[:v |

        triedViews add:v.

        ((app := v application) notNil 

        and:[(b := app builder) notNil 

        and:[b ~~ self]])

        ifTrue:[

            comp := b findComponentAt:name ignoringViews:triedViews.

            comp notNil ifTrue:[

                ^ comp

            ]

        ]

    ].

    ^ nil

!

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