eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'WindowBuilder':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: WindowBuilder

Inheritance:

   Object
   |
   +--WindowBuilder
      |
      +--UIBuilder
Package:
stx:libview2
Category:
Interface-Framework
Version:
rev: 1.191 date: 2024/02/09 11:44:05
user: stefan
file: WindowBuilder.st directory: libview2
module: stx stc-classLibrary: libview2

Description:


an abstract class, providing general support for window building.
Concrete subclasses know how to create a view (with components) from
some interface spec (i.e. a windowSpec).
More subclasses are possible reading different spec formats (eg. XML based specs).
Also, subclasses may decide to build their view manually (programatically),
by redefining #setupWindowFor:. 

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 'spec creation aspect fetch' category.

Currently, the only well supported subclass is UIBuilder, which builds according an uiSpec,
as typically returned by the #windowSpec method of the application.
This used to be VisualWorks compatible in its format, and many older VW specs can be used
out of the box. However, VW decided to expose the namespace of widgets in the spec,
and thus newer VW specs will need a slight massage to work.

More may be added in the future (for example, to parse different UI
specs - thinking of motif's UIL specs, Windows DialogSpecs, YAML etc.).

[instance variables:]
    window          <View>
                            the view into which the components
                            are (have been) created from the specification.
                            Usually, this is a TopView instance, but might as well be
                            a subView (so apps can be embedded into other apps)

    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.

    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)


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.

Class protocol:

class initialization
o  initialize
(comment from inherited method)
called only once - initialize signals

constants
o  windowTypeDialog

o  windowTypeNormal

o  windowTypePartner

o  windowTypePopUp

o  windowTypePopUpNotModal

o  windowTypePopUpWithFrame

o  windowTypeSlave

o  windowTypeToolDialog

o  windowTypeUndecorated

o  windowTypeUndecoratedResizable

debugging
o  stopOnError: aBoolean
enable/disable debug halt when aspects are missing.
Useful during development, to detect missing aspects.
The default is false.

o  verbose: aBoolean
enable/disable debug messages on the Transcript.
Useful during development, to detect missing aspects.
The default is off.

queries
o  isAbstract
Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

Instance protocol:

Compatibility-VW
o  source
same as #application, for ST-80 compatibility

o  source: anApplicationModel
same as #application:, for ST-80 compatibility

accessing
o  addBindings: moreBindings
used with subDialogs, which provide local bindings.
All bindings from moreBindings overwrite any local bindings.

o  application
return the application (an ApplicationModel),
for which the view is built.
This one is supposed to provide the aspects, menus etc.

o  application: anApplicationModel
set the application (an ApplicationModel),
for which the view is built.
This one is supposed to provide the aspects, menus etc.

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

o  applicationClass: aClass
set the value of the instance variable 'applicationClass'.
WARNING:
This is a private interface for the UIPainter to pass down the app-class
to the specs when editing.

o  aspectAt: aSymbol
return the aspect for a symbol or nil.

o  aspectAt: aSymbol ifAbsent: exceptionBlock
return the aspect for a symbol or the value from exceptionBlock.

o  aspectAt: aSymbol put: aModel
store an aspect identified by its symbol and its value.
Returns the stored aspect !

o  bindingAt: aSymbol
return the binding for a symbol or nil if there is none

o  bindingAt: aSymbol ifAbsentPut: anAspectOrBlock
return the binding for a symbol or nil if there is none

o  bindings
return my bindings

o  bindings: aDictionary
set bindings to a dictionary

o  componentAt: name
return a component identified by its name

Usage example(s): 

^ appBuilder componentAt:name

Usage example(s): 

^ masterBuilder componentAt:name

o  componentAt: name put: aComponent
store a component identified by its name.

o  componentCreationHook: aThreeArgBlock
set the value of the instance variable 'componentCreationHook'

o  componentToSpecMappingAt: aView

o  componentToSpecMappingAt: aView put: aSpec
self assert:(aSpec isKindOf:UISpecification).

o  findComponentAt: name
recursively search for a component identified by its name in myself
and all of my subApplications.

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

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

o  helpKeyFor: aComponent
return the helpkey for a component or nil

o  helpKeyFor: aComponent put: aKey
assign a key for a component which is used to access the help text
from the application.

o  keyboardProcessor
return my keyboard processor

o  keyboardProcessor: aKeyboardProcessor
set my keyboard processor

o  labelAt: name

o  labelAt: name put: aLabelString

o  menuAt: aKey
Find a binding for the menu named aKey, either in the bindings
or from the source

o  menuAt: aSymbol put: someMenuOrHolder
add someMenuOrHolder as the binding for the menu named aSymbol to the bindings

o  namedComponents
return a list of named components

o  namedComponentsDo: aBlock

o  resources
return the application's resources -
that's a ResourcePack containing national language strings

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

o  subCanvasAt: majorKey at: minorKey put: aSpec
deposit an interfaceSpecification for major and minor key
in my private subCanvasSpecs dictionary.
This will be used later, when building,
to provide an interfaceSpec for a subcanvas or subSpecification
(or possibly override an application provided interfaceSpec).
See #subCanvasAt:at:.

o  visualAt: name

o  visualAt: name put: aVisual

o  visuals

o  visuals: aDictionary

o  window
return the window (view), for which an interface is (being) built.
Usually, this is tha application's top window; however, it is also possible
to build components inside a subview (such as a subCanvas)

o  window: aView
set the top window (view), for which an interface
is (being) built

o  windowGroup

o  windowTitle: aString
if the window is already created, change its title.
Otherwise, remember the title to be set when the window is created later

aspect access support
o  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.

o  listAspectFor: aKey
helper (common code) to generate a list model aspect if required.
If no binding exists for aKey, a new List is
created and added to the bindings.
Otherwise, the existing binding is returned.

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

o  valueAspectFor: 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.

o  valueAspectFor: aKey computeInitialValueWith: initialValueBlock
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.
The initial value is computed by evaluating initialValueBlock

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

building
o  buildFromSpec: aSpec

** This method must be redefined in concrete classes (subclassResponsibility) **

o  makeTabable: aComponent
add a component to the list of tabable components

o  setupWindowFor: aWindow

** This method must be redefined in concrete classes (subclassResponsibility) **

error handling
o  aspectNotFound: anAspect error: errorString
show error message on transcript (if Verbose is true)
and/or stop (if StopOnError) is true

message sending
o  safelyPerform: aSelector ifNone: aBlock
send the message aSelector to the application;
the result returned from the send or nil is returned

o  safelyPerform: aSelector with: anArgument ifNone: aBlock
send the one-arg-message aSelector to the application;
the result returned from the send or nil is returned

o  safelyPerform: aSelector with: arg1 with: arg2 ifNone: aBlock
send the two-arg-message aSelector to the application;
the result returned from the send or nil is returned

o  safelyPerform: aSelector with: arg1 with: arg2 with: arg3 ifNone: aBlock
send the 3-arg-message aSelector to the application;
the result returned from the send or nil is returned

o  safelyPerform: aSelector withArguments: arguments ifNone: aBlock
send the one-arg-message aSelector to the application;
the result returned from the send or aBlock is returned

queries
o  isEditing
true if building from a GUI builder resource ( UIPainter, ... ),
false if building for the real thing.
If true, no models or actions should be set (no application is running).
(i.e. the widgets have been built to be shown in the UIPainter, with no app instance)

resolving fonts
o  resolveFont: fontOrSymbolOrStyle
resolve fontOrSymbol to a real font

spec creation aspect fetch
o  actionFor: aKey
return an action for aKey. This is invoked during window building
(by the builder) to ask for an ActionButtons actionBlock.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a block.

o  actionFor: aKey withValue: aValue
return an action for aKey/value combonation.
This is invoked during window building
(by the builder) to ask for an ActionButtons actionBlock if that button
specified an action with an argument value.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a block.

o  actionFor: aKey withValue: arg1 withValue: arg2
return an action for aKey/value combination.
This is invoked during window building
(by the builder) to ask for an ActionButtons actionBlock if that button
specified an action with an argument value.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a block.

o  aspectFor: aKey
return a model for aKey. This is invoked during window building
(by the builder) to ask for an Editfield's, a Toggle's etc. model.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a valueHolder.

o  aspectFor: aKey ifAbsent: exceptionBlock
return a model for aKey. This is invoked during window building
(by the builder) to ask for an Editfield's, a Toggle's etc. model.
Here, first the local bindings are searched, then the application and
finally the application's class is asked for a corresponding action.
The returned object is typically a valueHolder.

o  componentFor: aKey
return a component for aKey. This is invoked during window building
(by the builder) to ask for an ArbitraryComponents view.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a view.

o  labelFor: aKey
return a label for aKey. This is invoked during window building
(by the builder) to ask for a ???'s label.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a string.

o  listFor: aKey
return a list for aKey. This is invoked during window building
(by the builder) to ask for a ???'s label.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically a list.

o  menuFor: aKey
Find a binding for the menu named aKey, either in the bindings
or from the source

o  specificationFor: aKey
return a specification for aKey. This is invoked during window building
(by the builder) to ask for the interfaceSpec for a subCanvas or subSpecification.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding interfaceSPec.
The returned object is typically an interfaceSpec array.

o  visualFor: aKey
return a visual (icon, image) for aKey. This is invoked during window building
(by the builder) to ask for some graphical labels.
Here, first the local bindings are searched, then the application and
finally the applications class is asked for a corresponding action.
The returned object is typically an image or form.

spec creation callbacks
o  createdComponent: aView forSpec: spec named: name
callback from the UISpec after a view has been
created for a spec.
If it has a name, add it to the namedComponents dictionary;
if I have a creationHook (application callBack), evaluate it.

startup
o  closeRequest

o  open
open my topView, as previously created

o  openAt: aPoint
open my topView at some location

o  openDialog
open my topView, as previously created as a modal view,
blocking interaction to the currently active view.

o  openDialogAt: aPoint
open my topView, as previously created as a modal view,
blocking interaction to the currently active view.

o  openDialogAt: aPoint withExtent: ext
open my topView, as previously created as a modal view,
blocking interaction to the currently active view.

o  openDialogWithExtent: ext
open my topView, as previously created as a modal view,
blocking interaction to the currently active view.

o  openModal
open my topView as a modal dialog, as previously created,
blocking interaction to the currently active view.

o  openPopUpAt: aPoint
open my topView, as previously created as a popUp view,
blocking interaction to the currently active view.

o  openPopUpIn: aRectangle
open my topView, as previously created as a popUp view,
blocking interaction to the currently active view.

o  openWindow
open my topView

o  openWindowAt: aPoint
open my topView at some location

o  openWindowAt: origin withExtent: ext andType: type
open my window, as previously created, optionally defining the
windows origin and/or extent.
The type argument may be #dialog or #normal, and specifies if the view
should be opened as a modal view, blocking interaction to the currently
active view, or as a normal view.

o  openWindowCenter
open my topView centered on the screen (dialog & normal only)

o  openWithExtent: aPoint
open my topView, as previously created, but override
the extent.

o  openWithExtent: ext andType: type
open my window, as previously created. The type argument
may be #dialog or #normal, and specifies if the view should
be opened as a modal view, blocking interaction to the currently
active view, or as a normal view.

startup-basic
o  openAt: origin withExtent: ext andType: type
open my window, as previously created, optionally defining the
windows origin and/or extent.
The type argument may be
#normal, #dialog, #popUp,
#toolDialog, #popupWithFrame, #slave, #partner, #popUpNotModal
#undecorated or #undecoratedResizable
and specifies how the view should be opened.
Most common are
#dialog: modal view (blocking interaction to the currently active view),
#popUp: blocking, undecorated
#normal: a standard view

testing
o  isWebPageBuilder

translating
o  translateString: aString
translate aString to the current language.
If there is an application, it knows best what to do


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 21 Dec 2024 15:40:28 GMT