"

 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 namedComponents

		helpKeys componentCreationHook applicationClass keyboardProcessor

		subCanvasSpecs componentToSpecMapping'

	classVariableNames:'StopOnError Verbose'

	poolDictionaries:''

	category:'Interface-Framework'

!

!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 addAll: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: / 04-08-1998 / 19:28:30 / cg"

    "Modified: / 25-07-2011 / 15:29:25 / cg"

!

aspectAt:aSymbol put:aModel

    "store an aspect identified by its symbol and its value.

     Returns the stored aspect !!"

    bindings isNil ifTrue:[

	bindings := IdentityDictionary new

    ].

    bindings at:aSymbol put:aModel.

    ^ aModel

!

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

        bindings := IdentityDictionary new.

    ].

    ^ bindings

    "Modified: / 20-04-2005 / 18:59:28 / janfrog"

!

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.

!

componentToSpecMappingAt:aView

    componentToSpecMapping isNil ifTrue:[^ nil].

    ^ componentToSpecMapping at:aView ifAbsent:nil

!

componentToSpecMappingAt:aView put:aSpec

    "/ self assert:(aSpec isKindOf:UISpecification).

    componentToSpecMapping isNil ifTrue:[

	componentToSpecMapping := IdentityDictionary new.

    ].

    componentToSpecMapping at:aView put:aSpec

!

findComponentAt:name

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

     and all of my subApplications."

    ^ self

	findComponentAt:name

	forWhichViewConformsTo:[:v | true]

	ignoringViews:(IdentitySet new).

!

findComponentAt:name forWhichViewConformsTo:viewCheck ignoringViews:triedViews

    "recursively search for a visible 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 isNil ifTrue:[

	^ self

    ].

    "/ window := self application window.

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

    triedViews add:window.

    window allSubViewsDo:[:v |

	(triedViews includes:v) ifFalse:[

	    triedViews add:v.

	    (viewCheck value:v) ifTrue:[

		((app := v application) notNil

		and:[(b := app builder) notNil

		and:[b ~~ self]])

		ifTrue:[

		    comp := b findComponentAt:name forWhichViewConformsTo:viewCheck ignoringViews:triedViews.

		    comp notNil ifTrue:[

			^ comp

		    ]

		]

	    ]

	]

    ].

    ^ nil

!

findVisibleComponentAt:name

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

     and all of my subApplications.

     Be careful: this also searches for components in unmapped canvases."

    ^ self

	findComponentAt:name

	forWhichViewConformsTo:[:v | v shown]

	ignoringViews:(IdentitySet new).

!

helpKeyFor:aComponent

    "return the helpkey for a component or nil"

    |v key|

    v := aComponent.

    [v notNil] whileTrue:[

	(key := v helpKey) notNil ifTrue:[

	    ^ key

	].

"/        helpKeys notNil ifTrue:[

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

    aComponent helpKey: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

    "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