VisualWorks

GUI Developer's Guide

P46-0136-01

Copyright 19932002 by Cincom Systems, Inc.

All rights reserved.
This product contains copyrighted third-party software.

Part Number: P46-0136-01

Software Release 7
This document is subject to change without notice.
RESTRICTED RIGHTS LEGEND:
Use, duplication, or disclosure by the Government is subject to restrictions as
set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013.
Trademark acknowledgments:
CINCOM, CINCOM SYSTEMS, and the Cincom logo are registered trademarks of
Cincom Systems, Inc. ParcPlace and VisualWorks are trademarks of Cincom Systems,
Inc., its subsidiaries, or successors and are registered in the United States and other
countries. ObjectLens, ObjectSupport, ParcPlace Smalltalk, Database Connect, DLL & C
Connect, and COM Connect are trademarks of Cincom Systems, Inc., its subsidiaries, or
successors. ENVY is a registered trademark of Object Technology International, Inc. All
other products or services mentioned herein are trademarks of their respective
companies. Specifications subject to change without notice.
The following copyright notices apply to software that accompanies this
documentation:
VisualWorks is furnished under a license and may not be used, copied, disclosed, and/or
distributed except in accordance with the terms of said license. No class names,
hierarchies, or protocols may be copied for implementation in other systems.
This manual set and online system documentation copyright 19932002 by Cincom
Systems, Inc. All rights reserved. No part of it may be copied, photocopied, reproduced,
translated, or reduced to any electronic medium or machine-readable form without prior
written consent from Cincom.

Cincom Systems, Inc.

55 Merchant Street
Cincinnati, Ohio 45246

Phone: (513) 612-2300

Fax: (513) 612-2000
World Wide Web: http://www.cincom.com

Contents

About This Book

13

Audience ................................................................................................................... 13
Conventions .............................................................................................................. 13
Typographic Conventions ............................................................................. 13
Special Symbols ........................................................................................... 14
Mouse Buttons and Menus .......................................................................... 14
Getting Help .............................................................................................................. 15
Commercial Licensees ................................................................................. 15
Before Contacting Technical Support .............................................. 15
Contacting Technical Support ......................................................... 16
Non-Commercial Licensees ......................................................................... 16
Additional Sources of Information ............................................................................. 17
Smalltalk Tutorial ....................................................................................................... 17
Online Help .................................................................................................. 17
VisualWorks FAQ ......................................................................................... 17
News Groups ............................................................................................... 18
VisualWorks Wiki ......................................................................................... 18
Commercial Publications .............................................................................. 18
Examples ..................................................................................................... 18
Chapter 1

The VisualWorks GUI Environment

19

UI Painter .................................................................................................................. 20
The Canvas .................................................................................................. 20
The Palette ................................................................................................... 21
GUI Painter Tool ........................................................................................... 21
Resource Finder ........................................................................................................ 23
Menu Editor ............................................................................................................... 24
Image Editor .............................................................................................................. 25
Hot Region Editor ...................................................................................................... 26

GUI Developers Guide

Contents

Chapter 2

Building an Applications GUI

27

Loading the UI Painter .............................................................................................. 27

Creating a Graphical User Interface ......................................................................... 28
Painting a Window ..................................................................................... 28
Setting Properties ........................................................................................ 29
Installing the Canvas ................................................................................... 31
Reopening a Canvas ................................................................................... 32
Defining Value Models ................................................................................. 33
Testing the User Interface ............................................................................ 34
Formatting a Canvas ................................................................................................ 34
Setting the Window Size .............................................................................. 34
Setting the Window Opening Position .......................................................... 35
Adding Scrollbars to a Window .................................................................... 36
Adding a Menu Bar ...................................................................................... 36
Setting the UI Colors .................................................................................... 37
Sizing a Widget ............................................................................................ 38
Making a Widgets Size Fixed ......................................................... 39
Making a Widgets Size Relative ..................................................... 39
Applying Explicit Boundaries to an Unbounded Widget .................. 40
Positioning a Widget .................................................................................... 40
Making a Widgets Origin Fixed ...................................................... 40
Making a Widgets Origin Relative .................................................. 41
Giving an Unbounded Widget a Fixed Position ............................... 42
Giving an Unbounded Widget a Relative Position .......................... 42
Grouping Widgets ........................................................................................ 43
Making a Group of Widgets ............................................................ 43
Editing Widgets in Groups .............................................................. 43
Aligning Widgets .......................................................................................... 43
Distributing Widgets ..................................................................................... 44
Changing a Widgets Font ............................................................................ 45
Named Fonts ............................................................................................... 45
Changing the Tabbing Order ........................................................................ 47
Opening and Closing Windows ................................................................................. 47
Opening the Main Window ........................................................................... 48
Opening a Secondary Window .................................................................... 48
Setting the Window Size at Opening ........................................................... 49
Setting the Startup Location of a Window ................................................... 49
Closing Application Windows ....................................................................... 50
Performing Final Actions .............................................................................. 50
Hiding a Window ............................................................................. 51

VisualWorks

Contents

Chapter 3

Controlling the GUI Programmatically

52

Replacing the Builder Interface ................................................................................. 52

Accessor Methods ........................................................................................ 53
Accessing a Window ................................................................................................. 54
Getting an Application Window .................................................................... 54
Getting the Active Window ........................................................................... 54
Getting the Window at a Location ................................................................ 55
Setting Window Properties ........................................................................................ 56
Changing the Window Size .......................................................................... 56
Determining a Windows Dimensions ........................................................... 56
Changing a Windows Label ......................................................................... 56
Adding and Removing Scroll Bars ................................................................ 57
Controlling Window Displays ..................................................................................... 57
Refreshing a Windows Display .................................................................... 57
Expanding and Collapsing a Window ........................................................... 58
Assigning a Window Icon .......................................................................................... 58
Creating an Icon ........................................................................................... 58
Registering an Icon ...................................................................................... 59
Installing an Icon ............................................................................. 59
Slave and Master Windows ....................................................................................... 60
Defining Slave and Master Windows ............................................... 60
Make Windows Equal Partners .................................................................... 60
Choosing the Events That Are Sent ............................................................. 61
Choosing the Events That Are Received ..................................................... 61
Window Events .......................................................................................................... 62
Controlling Widgets ................................................................................................... 66
Accessing a Widget ...................................................................................... 66
Accessing the Widgets Wrapper ................................................................. 67
Setting Widget Properties ............................................................................ 67
Changing a Widgets Size ............................................................... 68
Changing a Widgets Font ............................................................... 68
Hiding a Widget ............................................................................... 69
Disabling a Widget .......................................................................... 70
Changing a Widgets Colors ............................................................ 71
Adding and Removing Dependencies .......................................................... 71
Adding a Dependency ..................................................................... 72
Removing a Dependency by Retracting the Interest ....................... 72
Bypassing All Dependencies ........................................................... 72
Validation Properties .................................................................................... 73
Notification Properties .................................................................................. 74

GUI Developers Guide

Contents

Chapter 4

Adapting Domain Models to Widgets

76

Setting up Simple Value Models (ValueHolder) ........................................................ 77

Defining a Value Holder ............................................................................... 77
Adapting Part of a Domain Model (AspectAdaptor) .................................................. 78
Defining an Adaptor ..................................................................................... 79
Addressing the Subject Directly ................................................................... 80
Accommodating Unusual Accessors ........................................................... 80
Monitoring Programmatic Changes ............................................................. 80
Synchronizing Updates (Buffering) ........................................................................... 81
Adding Synchronized Updates .................................................................... 83
Discarding the Buffered Values ................................................................... 84
Adapting a Collection (SelectionInList) ..................................................................... 85
Adapting a Collection Element ................................................................................. 86
Creating a Custom Adaptor ...................................................................................... 87
Chapter 5

Menus

89

Creating a Menu ....................................................................................................... 89

Creating a Menu using the Menu Editor ...................................................... 90
Creating a Menu Programmatically ............................................................. 91
Adding Menus to the User Interface ......................................................................... 93
Adding a Menu Bar to a Window ................................................................. 94
Adding a Menu Button ................................................................................. 94
Adding a Popup Menu to a Widget .............................................................. 95
Adding a Menu Bar or Pop-Up Menu of Values ........................................... 95
Accessing Menus Programmatically ......................................................................... 96
Modifying a Menu Dynamically ................................................................................. 98
Disabling a Menu Item ................................................................................. 98
Hiding a Menu Item ...................................................................................... 98
Adding an Item to a Menu ............................................................................ 99
Removing an Item from a Menu ................................................................ 100
Substituting a Different Menu .................................................................... 100
Displaying an Icon in a Menu .................................................................................. 101
Adding an Icon to a Menu .......................................................................... 102
Displaying an On/Off Indicator ................................................................... 102
Extending Tools Menus and Toolbars ..................................................................... 103
Setting the Menu Item Position .................................................................. 104
Adding Items to the Launcher .................................................................... 105
Adding Items to a Browser ......................................................................... 105
Menu and Toolbar Events ....................................................................................... 106
Popup Menu Events ................................................................................... 107
Toolbar Events ........................................................................................... 107

VisualWorks

Contents

Chapter 6

Drag and Drop

108

About Drag and Drop .............................................................................................. 108

Drag and Drop Framework Classes ........................................................... 109
Adding a Drop Source ............................................................................................. 110
Dragging Multiple Selections ...................................................................... 112
Adding a Drop Target .............................................................................................. 113
Providing Visual Feedback During a Drag .............................................................. 114
Drop Target Messages ............................................................................... 114
Pointer Shapes ........................................................................................... 115
Changing Color During a Drag ................................................................... 115
Changing a Button Label During a Drag .................................................... 117
Tracking a Targeted List Item ..................................................................... 119
Responding to a Drop ............................................................................................. 121
Adding a Drop Response ........................................................................... 122
Adding Target Emphasis ............................................................................ 123
Examining the Drag Context ................................................................................... 126
Responding to Modifier Keys .................................................................................. 126
Responding to a Modified Drag .................................................................. 127
Chapter 7

Dialogs

131

Standard Dialogs ..................................................................................................... 131

Displaying a Warning ................................................................................. 131
Asking a Yes/No Question .......................................................................... 132
Multiple-Choice Dialog ............................................................................... 133
Requesting a Textual Response ................................................................. 133
Requesting a Filename ............................................................................. 134
Handling a File that Exists or Does Not Exist ................................ 135
Multiple-Selection List Dialog ..................................................................... 136
Prompting for a Password .......................................................................... 137
Supplying Extra Action Buttons Below the List ........................................... 138
Linking a Dialog to a Master Window ...................................................................... 138
Adopting the Look of a Master Window ...................................................... 138
Linking a Dialog to a Window ..................................................................... 139
Creating a Custom Dialog ....................................................................................... 140
Providing a Temporary Model for the Dialog .............................................. 141
Chapter 8

Custom Views

142

Creating a View Class ............................................................................................. 143

Connecting a View to a Domain Model ................................................................... 144
Defining What a View Displays ............................................................................... 145
Updating a View When Its Model Changes ............................................................. 146
GUI Developers Guide

Contents

Connecting a View to a Controller .......................................................................... 147

Creating a Controller Class ........................................................................ 148
Connect the Controller to the Model .......................................................... 149
Connect the Controller to the View ............................................................ 150
Connecting a Composite View to a Controller ........................................... 150
Redisplaying All or Part of a View ........................................................................... 150
Redisplaying a View .................................................................................. 151
Redisplaying Part of a View ....................................................................... 151
Redisplaying Immediately .......................................................................... 151
Integrating a View into an Interface ........................................................................ 152
Chapter 9

Configuring Widgets

153

Buttons ................................................................................................................... 154

Radio Buttons ............................................................................................ 154
Radio Button Events ..................................................................... 155
Check Boxes .............................................................................................. 156
Checkbox Events .......................................................................... 157
Action Buttons ........................................................................................... 158
Action Button Events .................................................................... 159
Button Tab Notebook .............................................................................................. 161
Charts ..................................................................................................................... 162
Adding a Chart ........................................................................................... 162
Charting Multiple Data Series .................................................................... 162
Adding Labels ............................................................................................ 163
Special Requirements for Charts ............................................................... 163
Pareto ........................................................................................... 164
Picture .......................................................................................... 164
XY ................................................................................................. 165
Pie Charts ..................................................................................... 166
Exploding Labels .......................................................................... 166
Doughnut Labels ........................................................................... 166
Click Map ................................................................................................................ 167
Adding a Click Map .................................................................................... 167
Defining the Hot Region Mappings ............................................................ 167
Using Custom Views and Controllers ........................................................ 169
Click Widget Events ................................................................................... 169
Combo Box ............................................................................................................. 170
Adding a ComboBox to a Canvas .............................................................. 170
Listing Arbitrary Objects ............................................................................ 171
Combo Box Events .................................................................................... 172
Datasets ................................................................................................................. 174
Setting up a Dataset .................................................................................. 174

VisualWorks

Contents

Editing Column Properties ........................................................................ 176

Changing Column Widths ............................................................. 176
Changing the Column Order ......................................................... 177
Disabling Column Scrolling ........................................................... 177
Moving the Selection to Another Column ...................................... 177
Scrolling Dataset Columns ............................................................ 177
Formatting Column Labels ............................................................ 178
Adding a Row ............................................................................................. 179
Adding a Row Marker .................................................................... 179
Adding Row Numbering ................................................................ 180
Providing Initial Data .................................................................................. 180
Dataset Events ........................................................................................... 180
Input Fields .............................................................................................................. 184
Creating an Input Field ............................................................................... 184
Restricting Input Type ................................................................................. 185
Formatting Displayed Data ......................................................................... 186
Creating a Custom Format ............................................................ 186
Validating Input ........................................................................................... 187
Validating a Whole Entry ............................................................... 187
Validating Individual Characters .................................................... 188
Modifying a Fields Pop-Up Menu ............................................................... 189
Adding a Command ...................................................................... 189
Overriding a Default Command ..................................................... 190
Disabling a Fields Menu ............................................................... 191
Connecting two Fields ................................................................................ 191
Controlling the Insertion Point .................................................................... 191
Highlighting a Portion of a Field .................................................... 192
Positioning the Insertion Point ....................................................... 192
Input Field Events ....................................................................................... 192
Hierarchical Lists ..................................................................................................... 194
Adding a List .............................................................................................. 194
Create a List for a Natural Tree .................................................................. 194
Building a Tree ........................................................................................... 195
Hierarchical List Events .............................................................................. 196
Labels ...................................................................................................................... 198
Creating a Textual Label ............................................................................. 198
Creating a Graphic Label ........................................................................... 198
Making a Label Mnemonic ......................................................................... 199
Supplying the Label at Run Time ............................................................... 199
Building a Registry of Labels ...................................................................... 200
Label Events .............................................................................................. 201
Lists ......................................................................................................................... 202
Adding a List .............................................................................................. 202

GUI Developers Guide

Contents

Editing the List of Elements ....................................................................... 202

Enabling Multiple Selections ...................................................................... 203
Getting a Selection Contents ..................................................................... 204
Setting a Selection ..................................................................................... 205
Connecting Two Lists ................................................................................. 206
List Events ................................................................................................. 207
Menu Button ........................................................................................................... 210
Adding a Menu Button ............................................................................... 210
Adding a Menu Button with a Menu of Commands .................................... 211
Menu Button Events .................................................................................. 211
Notebook ................................................................................................................ 213
Creating a Notebook .................................................................................. 213
Setting the Starting Page ........................................................................... 215
Getting the Selected Tab ........................................................................... 215
Adding Secondary Tabs (Minor Keys) ....................................................... 216
Connecting Minor Tabs to Major Tabs ....................................................... 218
Changing the Page Layout (Subcanvas) ................................................... 219
Notebook Events ....................................................................................... 221
Percent Done Bar ................................................................................................... 223
Basic Properties ........................................................................................ 223
Aspect ........................................................................................... 223
Orientation .................................................................................... 223
Starting Point ................................................................................ 223
Adding a Percent Done Bar ....................................................................... 224
Percent Done Bar Events .......................................................................... 224
Lines, Boxes, and Ovals ......................................................................................... 225
Adding a Line to a Canvas ......................................................................... 225
Adding a Group Box .................................................................................. 225
Making a Group Box Mnemonic .................................................... 226
Group Box Events ......................................................................... 226
Grouping Widgets with a Region ............................................................... 226
Region Events .............................................................................. 227
Resizing Splitter ...................................................................................................... 228
Adding a Resizing Splitter .......................................................................... 228
Setting Widget Positioning ......................................................................... 228
Resizing Splitter Events ............................................................................. 230
Sliders ..................................................................................................................... 231
Adding a Slider .......................................................................................... 231
Connecting a Slider to a Field .................................................................... 231
Connecting a Slider to a Non-numeric Field ................................. 232
Making a Slider Read-Only ........................................................................ 233
Changing the Slider Range ........................................................................ 233

10

VisualWorks

Contents

Making a Slider Two-Dimensional .............................................................. 235

Slider Events .............................................................................................. 236
Spin Buttons ............................................................................................................ 237
Adding a Spin Button ................................................................................. 238
Spin Button Events ..................................................................................... 238
Subcanvases ........................................................................................................... 241
Inheriting a Subcanvas ............................................................................... 241
Changing the Value of an Inherited Widget ................................... 242
Nesting One Application in Another ........................................................... 242
Setting a Value in an Embedded Widget ....................................... 244
Reusing an Interface Only .......................................................................... 244
Changing Interfaces at Run Time ............................................................... 245
Accessing an Embedded Widget ............................................................... 246
Subcanvas Events ...................................................................................... 247
Tab Control .............................................................................................................. 248
Compatibility with Notebook ....................................................................... 248
Adding a Tab Control .................................................................................. 249
Defining Initial Labels ................................................................................. 250
Placing an Icon on a Tab ............................................................................ 250
Tab Control Events ..................................................................................... 251
Tables ...................................................................................................................... 253
TableInterface ............................................................................................. 253
Adding a Table ............................................................................................ 253
Controlling Column Widths ......................................................................... 254
Connecting a Table to an Input Field .......................................................... 255
Labeling Columns and Rows ...................................................................... 256
Table Events ............................................................................................... 257
Text Editors ............................................................................................................. 259
Adding a Text Editor ................................................................................... 259
Retrieving and Modifying Selected Text ..................................................... 260
Highlighting Text ......................................................................................... 261
Aligning Text ............................................................................................... 261
Text Editor Events ...................................................................................... 262
Tree View ................................................................................................................ 264
Basics ......................................................................................................... 265
Aspect ........................................................................................... 265
Details ........................................................................................................ 265
Minimum Element Height .............................................................. 265
Whole Line Selection .................................................................... 265
Advanced ................................................................................................... 265
Items .......................................................................................................... 265
Display String ................................................................................ 265
Icons .............................................................................................. 266

GUI Developers Guide

11

Contents

Initializing a Tree View ............................................................................... 266

Programmatic Interface ............................................................................. 267
Controller Interface ....................................................................... 267
Model Interface ............................................................................. 267
Adding a Tree View .................................................................................... 268
Adding Text Emphases .............................................................................. 268
Tree View Events ....................................................................................... 269
View Holder ............................................................................................................ 272
Adding a View Holder ................................................................................ 272
View Holder Events ................................................................................... 272

Index

274

Method Index

282

12

VisualWorks

About This Book

This document is designed to help both new and experienced developers

create application programs effectively using the VisualWorks
application frameworks, tools, and facilities.

Audience
This guide assumes that you have at least a beginning familiarity with
object-oriented programming. The description of VisualWorks begins at
an elementary level, with an overview of the system tools and facilities,
and a description of Smalltalk syntax, but does not attempt to be a
tutorial.
For additional help, a large number of books and tutorials are available
from commercial book sellers and on the world-wide web. In addition,
Cincom and some of its partners provide VisualWorks training classes.

Conventions
We have followed a variety of conventions, which are standard in the
VisualWorks documentation.

Typographic Conventions
The following fonts are used to indicate special terms:

GUI Developers Guide

Example

Description

template

Indicates new terms where they are defined,

emphasized words, book titles, and words as words.

cover.doc

Indicates filenames, pathnames, commands, and

other constructs to be entered outside VisualWorks
(for example, at a command line).

filename.xwd

Indicates a variable element for which you must

substitute a value.

13

Chapter - About This Book

Example

Description

windowSpec

Indicates Smalltalk constructs; it also indicates any

other information that you enter through the
VisualWorks graphical user interface.

Edit menu

Indicates VisualWorks user-interface labels for menu

names, dialog-box fields, and buttons; it also
indicates emphasis in Smalltalk code samples.

Special Symbols
This book uses the following symbols to designate certain items or
relationships:
Examples

Description

File ! New

Indicates the name of an item (New) on a menu

(File).

<Return> key
<Select> button
<Operate> menu

Indicates the name of a keyboard key or mouse

button; it also indicates the pop-up menu that is
displayed by pressing the mouse button of the
same name.

<Control>-<g>

Indicates two keys that must be pressed

simultaneously.

<Escape> <c>

Indicates two keys that must be pressed

sequentially.

Integer>>asCharacter Indicates an instance method defined in a class.

Float class>>pi

Indicates a class method defined in a class.

Mouse Buttons and Menus

VisualWorks supports a one-, two-, or three-button mouse common on
various platforms. Smalltalk traditionally expects a three-button mouse,
where the buttons are denoted by the logical names <Select>,
<Operate>, and <Window>:

14

<Select> button

Select (or choose) a window location or a menu

item, position the text cursor, or highlight text.

<Operate> button

Bring up a menu of operations that are

appropriate for the current view or selection. The
menu that is displayed is referred to as the
<Operate> menu.

<Window> button

Bring up the menu of actions that can be

performed on any VisualWorks window (except
dialogs), such as move and close. The menu that is
displayed is referred to as the <Window> menu.

VisualWorks

Getting Help

These buttons correspond to the following mouse buttons or

combinations:

<Select>

3-Button

2-Button

1-Button

Left button

Left button

Button

Right button

<Option>+<Select>

<Operate> Right button

<Window> Middle button <Ctrl> + <Select> <Command>+<Select>

Note: This is a different arrangement from how VisualWorks used

the middle and right buttons prior to 5i.2.
If you want the old arrangement, toggle the Swap Middle and Right Button
checkbox on the UI Feel page of the Settings Tool.

Getting Help
There are many sources of technical help available to users of
VisualWorks. Cincom technical support options are available to users
who have purchased a commercial license. Public support options are
available to both commercial and non-commercial license holders.

Commercial Licensees
If, after reading the documentation, you find that you need additional help,
you can contact Cincom Technical Support. Cincom provides all
customers with help on product installation. For other problems there are
several service plans available. For more information, send email to
[email protected].

Before Contacting Technical Support

When you need to contact a technical support representative, please be
prepared to provide the following information:

GUI Developers Guide

The version id, which indicates the version of the product you are
using. Choose Help ! About VisualWorks in the VisualWorks main
window. The version number can be found in the resulting dialog
under Version Id:.

Any modifications (patch files) distributed by Cincom that you have

imported into the standard image. Choose Help ! About VisualWorks in
the VisualWorks main window. All installed patches can be found in
the resulting dialog under Patches:.

15

Chapter - About This Book

The complete error message and stack trace, if an error notifier is the
symptom of the problem. To do so, select copy stack in the error notifier
window (or in the stack view of the spawned Debugger). Then paste
the text into a file that you can send to technical support.

Contacting Technical Support

Cincom Technical Support provides assistance by:
Electronic Mail
To get technical assistance on VisualWorks products, send email to
[email protected].
Web
In addition to product and company information, technical support
information is available on the Cincom website:
http://supportweb.cincom.com
Telephone
Within North America, you can call Cincom Technical Support at
(800) 727-3525. Operating hours are Monday through Friday from
8:30 a.m. to 5:00 p.m., Eastern time.
Outside North America, you must contact the local authorized
reseller of Cincom products to find out the telephone numbers and
hours for technical support.

Non-Commercial Licensees
VisualWorks Non-Commercial is provided as is, without any technical
support from Cincom. There are, however, on-line sources of help
available on VisualWorks and its add-on components. Be assured, you
are not alone. Many of these resources are valuable to commercial
licensees as well.
The University of Illinois at Urbana-Champaign very kindly provides
several resources on VisualWorks and Smalltalk:

A mailing list for users of VisualWorks Non-Commercial, which

serves a growing community of VisualWorks Non-Commercial users.
To subscribe or unsubscribe, send a message to:
[email protected]
with the SUBJECT of "subscribe" or "unsubscribe".

16

An excellent Smalltalk archive is maintained by faculty and students

at UIUC, who are long-time Smalltalk users and leading lights in the
Smalltalk community, at:

VisualWorks

Additional Sources of Information

http://st-www.cs.uiuc.edu/

A Wiki (a user-editable web site) for discussing any and all things
VisualWorks related at:
http://wiki.cs.uiuc.edu/VisualWorks

A variety of tutorials and other materials specifically on VisualWorks

at:
http://wiki.cs.uiuc.edu/VisualWorks.Tutorials+and+courses

The Usenet Smalltalk news group, comp.lang.smalltalk, carries on active

discussions about Smalltalk and VisualWorks, and is a good source for
advice.

Additional Sources of Information

This is but one manual in the VisualWorks library. The Cincom Smalltalk
publications website:
http://www.cincom.com/smalltalk/documentation
is a resource for the most up to date versions of VisualWorks manuals
and additional information pertaining to Cincom Smalltalk.

Smalltalk Tutorial
A new VisualWorks Smalltalk tutorial is availalbe online at:
http://www.cincom.com/smalltalk/tutorial/
The tutorial information is growing, so revisit this site.

Online Help
VisualWorks includes an online help system. To display the online
documentation browser, open the Help pull-down menu from the
VisualWorks main menu bar and select one of the help options.

VisualWorks FAQ
An accumulating set of answers to frequently asked questions about
VisualWorks is being compiled in the VisualWorks FAQ, which
accompanies this release and is available from the Cincom Smalltalk
documentation site.

GUI Developers Guide

17

Chapter - About This Book

News Groups
The Smalltalk community is actively present on the internet, and willing to
offer helpful advice. A common meeting place is the comp.lang.smalltalk
news group. Discussion of VisualWorks and solutions to programming
issues are common.

VisualWorks Wiki
A wiki server for VisualWorks is running and can be accessed at:
http://wiki.cs.uiuc.edu:8080/VisualWorks
This is becoming an active place for exchanges of information about
VisualWorks. You can ask questions and, in most cases, get a reply in a
couple of days.

Commercial Publications
Smalltalk in general, and VisualWorks in particular, is supported by a
large library of documents published by major publishing houses. Check
your favorite technical bookstore or online book seller.

Examples
There are a number of examples in parcels, installed in the examples
subdirectory, under the VisualWorks install directory. These are referred
to frequently in this document, and provide additional help in
understanding GUI development in VisualWorks.

18

VisualWorks

1
The VisualWorks GUI Environment

The Graphical User Interface (GUI) building framework is what puts the
Visual in VisualWorks. Building a GUI is done by visually selecting,
placing, and arranging widgets on a canvas. We call the process
painting, and the tool you use is the UI Painter. The resulting canvas
specifies the application window.
Once you have designed the GUI, you connect it to your applications
model, so that input to the GUI is passed on to the model, and so that
relevant changes in the model are displayed in the GUI. This connecting
function is handled by a subclass of ApplicationModel specific to your
application. This model is generated by the UI Painter, including stub
methods for many essential aspects of the model, according to attributes
you specify for the GUI elements.
In this document we address the more mechanical aspects of building
and controlling a GUI in VisualWorks. For a lower-level description of how
the application framework works in connection with the rest of your
application, refer to the Application Framework chapter in the
Application Developers Guide.

GUI Developers Guide

19

Chapter 1 - The VisualWorks GUI Environment

UI Painter
The Visual in VisualWorks emphasizes the graphical approach to
Graphical User Interface (GUI) design and development. This is provided
by the UI Painter.

The UIPainter is initially unloaded from the base image. To load it, load
the UIPainter parcel (Tools ! Load Parcel in the Visual Launcher).
The Painter tool is in three parts:

Canvas (lower right) - represents a single window, on which you

place widgets, the graphical components of the GUI.

Palette (top right) - presents a collection of widgets that are

commonly used in a GUI, and some widget arrangement buttons.

GUI Painter Tool (left) - provides a collection of menu commands and

buttons for performing formatting and other operations on the canvas,
a hierarchical view of the widgets on the current canvas, and the
properties of the selected widget.

The Canvas
The Canvas, which starts out blank, is where you place and arrange
widgets to paint your GUI.

20

VisualWorks

UI Painter

The canvas can be resized to define the size of the resulting window, and
settings allow you to specify its initial size when it opens in the
application, and to constrain its maximum and minimum sizes.
The widgets you place on the canvas have a number of properties that
define their appearance and interaction with your applications data
model. Positioning properties determine how the widgets scale or
distribute when the window is resized.
Once you have painted a GUI, you install it in your application. This
writes the canvas definition spec into an interface specification. The
specification is used by the application to open the window. You can also
edit the specification later by reopening it in the UI Painter.
The Canvas <Operate> menu provides configuration commands that are
also available in other parts of the UI Painter, notably those on the GUI
Painter Tool.

The Palette
The Palette has one button for each type of widget. Widgets are the
elements that you can include in a GUI, including simple elements like
labels and buttons, and more complex elements like hierarchical lists and
tables.
To add a component to your canvas, such as an input field, you simply
click on the Input Field icon in the Palette to select it, and then click in the
canvas to place the widget. You can then drag the widget around to
arrange its position relative to other widgets.
To add several copies of the same widget use the sticky widget picker.
Then, each time you click on the canvas you drop another copy of that
widget, without having to return to the canvas each time. To return to
single widget painting, select the not sticky picker.
The Palette also has several buttons for doing some basic widget
organizing, such as aligning and distributing widgets. These operations
are also available on the GUI Painter Tool menus, and in the Canvas
<Operate> menu.

GUI Painter Tool

The GUI Painter Tool is control central for configuring a canvas and its
widgets.

GUI Developers Guide

21

Chapter 1 - The VisualWorks GUI Environment

While you may have several canvases open at any given time, there is
only one GUI Painter Tool, which is focused on the currently selected
canvas. To operate on another canvas, select it to update the GUI Painter
Tool.
The GUI Painter Tool has menus and buttons for configuring the canvas
and its widgets. These are described throughout this document as the
relevant task is discussed.
On the left is a hierarchical Tree View, the components in the current
canvas. The canvas itself is included at the top of the list, as Main Window.
Below it, indented to show inclusion, are any widgets you have placed on
the canvas. Each widget has a default name, which you may rename to
make more descriptive and useful. Composite parts, which are groups of
widgets, are further indented under the composite.
You can select a widget to configure by either clicking on the widget in the
canvas or in the widget list in the GUI Painter Tool. The widget list is
particularly useful in complex canvases, where a hidden widget may be
overlaid with another widget. It also simplifies selecting a nested widget
for configuration.
The widget list also shows the tab order between widgets for which
tabbing is enabled. Tab order is set from top to bottom. Moving a widget
in the list adjusts its place in the tabbing sequence.
The largest section of the GUI Painter tool is the collection of properties
pages. The specific pages and their contents vary from widget to widget,
but every widget has Basics, Details, Color, and Position pages. Additional
pages are added as required by the currently selected widget.
Common properties are described under Setting Properties in Chapter 2,
Building an Applications GUI. Additional properties are described
individually for each widget in Chapter 9, Configuring Widgets.
Once the canvas has been designed, you install it by clicking the Install
button, or by selecting the Edit ! Install menu item.

22

VisualWorks

Resource Finder

Resource Finder
Canvases, menus, and graphical images are stored in VisualWorks as
resources, and saved as specifications in class methods of the
Application Model. To find resources once they are created, select Browser
! Resources to open the Resource Finder.

Application classes are listed in the left-hand view. You can filter the list
to show tool classes, example classes, and other categories. To do so,
use the View ! All Classes submenu.
An application class can support multiple interfaces, each of which may
involve multiple canvases for the VisualWorks main window, secondary
windows, and dialogs. The right-hand view lists all of the resource
methods for the selected class. Double-click or click Edit to open that
resource in its editor.

GUI Developers Guide

23

Chapter 1 - The VisualWorks GUI Environment

Menu Editor
The Menu Editor provides an intuitive, visual way of building a menu. The
menu can be added to the GUI either as a standard, drop-down menu on
the menu bar, added to a menu Button widget, or as a pop-up (right-click)
menu to the window area.

Menu commands and buttons are provided for adding an item, adding a
sub-item, and for rearranging items. Sub-items are accessed as submenus off of the parent menu.
Menu levels are indicated by indenting. To change the level of an item,
select it and click on the left or right arrow button. To change the order of
an item, select it and click the up or down buttons.
There are also three properties pages for each menu item. The Basic
page specifies the displayed String menu label, the lookup key and
catalog, if used, the items return value, and its ID, for programmatically
accessing the item. The Details page specifies any modifier keys needed
for the item, the icon for the item, if any, and its help text. The Defaults
page sets the items initial state.
An application frequently needs to modify a menu or the state of its items
while running, either to indicate state or to activate and deactivate items.
Details on how to create menus and control them during runtime are
provided in Chapter 5, Menus.

24

VisualWorks

Image Editor

Image Editor
Your GUI is often enhanced by the inclusion of icons, simple graphics that
indicate a widgets function. Menu items and buttons, for example, are
often clearer with an icon to suggest visually what they do.
VisualWorks includes an Image Editor that you can use to draw an image
pixel by pixel, and then store it in a resource method. The Image Editor is
best suited for producing small images, such as icons and cursor shapes.
To open an Image Editor, choose Tools ! Image Editor in the GUI Painter
Tool or the VisualWorks main window.

Paint the desired image in the scrollable pixel grid. The controls are pretty
standard for simple paint programs.
To make the graphic available to your application, click the Install button,
then specify your application class as the class into which to install the
graphic, and a method name for the graphic. This installs the graphic as a
resource, which you can access in the resources browser. The method is
installed as a class method in a resource protocol of a selected class.
For more about graphics in VisualWorks, refer to Working With Graphics
and Colors in the Application Developers Guide. Instructions for
incorporating a graphic in your applications GUI are provided at relevant
points throughout the rest of this document.

GUI Developers Guide

25

Chapter 1 - The VisualWorks GUI Environment

Hot Region Editor

Clickable images can give a very modern look to an otherwise dull GUI.
The Click Map widget allows you to add one to your canvase. The Hot
Regions Editor allows you to define clickable regions.
To define hot regions, you load a graphic resource into the Hot Regions
Editor as a back drop. Then, using drawing tools, draw and paint areas to
be included in the region, and specify a message selector to be sent
when the region is clicked.
For detailed instructions, refer to Click Map in Chapter 9, Configuring
Widgets.

26

VisualWorks

2
Building an Applications GUI

This chapter provides an overview of how to build a graphical user

interface (GUI) and link it to the domain model(s) of a VisualWorks
application.
While there must be a domain model to complete the linking, a great deal
of preliminary work can be begun working on the GUI, so it is not
necessary to program the domain model before building the GUI. A fairly
common development approach in object-oriented programming is to
develop, or at least prototype, the GUI before completing the domain
model.
The VisualWorks Painter tool both creates the UI specification and the
application model, so this stage goes a long way to beginning application
development.
In this chapter, we begin with an overview of the basic operations of
building the GUI using the UI Painter tool. From there we move to a more
complete description of building an application view for a domain. Finally,
several approaches to and options for building the adaptors that connect
the GUI and domain are described.

Loading the UI Painter

The UI Painter is a loadable component in VisualWorks. Before you can
begin painting a canvas, you need to load it.
Load the UIPainter parcel using the parcel loading tool, Tools ! Load
Parcel, and enter UIPainter into the prompter.

GUI Developers Guide

27

Chapter 2 - Building an Applications GUI

Creating a Graphical User Interface

To create the visual portion of a graphical user interface, you specify the
contents and layout of each window in your application. These windows
include the applications main window, secondary windows, and dialog
boxes.
Part of the procedure generates stub methods and value holders to link
up with the domain model. Later, you program application-specific
behavior for each of the windows you specified.

Painting a Window
You create windows by creating a visual specification using the UI
Painter. The painter tool provides a canvas, on which you arrange
widgets, a palette containing widgets, and a canvas tool, which gives
quick access to a number of common UI layout commands.
To open the Painter, click on the Canvas button in the Main Window
toolbar.

The UI Painter opens with three windows: the GUI Painter Tool (left), the
widget Palette (top right), and the canvas (bottom right).
The canvas is a work area in which you add and arrange visual
components until it looks like the window you want in your application. If
your application uses several windows, you create a separate canvas for
each window in the application. One window will be the main window, and
the rest will be sub-windows.
28

VisualWorks

Creating a Graphical User Interface

You paint the blank canvas by placing and arranging widgets on it. To
place a widget, click on a widget in the palette, then move the mouse to
the canvas and click once. A representation of the widget is displayed at
the cursor. Move it where you want the widget, then click again to drop
the widget.
If you want to place several of the same widget on the canvas, select the
Sticky Select button before selecting the widget. Every time you drop one
widget, you can drop another, until you select another widget or reselect
the single-place button.

Setting Properties
Every window and widget has an associated collection of properties. A
few properties are common to all windows and widgets, but most vary
from object to object.
Properties define a variety of visual attributes, such as font, color,
borders, and so on. For some widgets, such as input fields, properties
also indicate the nature of the data to be displayed and how that data is to
be referenced by the application.
Properties are initially set using the Properties Pages in the GUI Painter
Tool while you are constructing the GUI.

GUI Developers Guide

29

Chapter 2 - Building an Applications GUI

Most of the properties available for setting are self-explanatory. If you

want to change some characteristic of a window or widget, look in the
property pages, and youll usually find the property setting you need.
Many of the properties are described in other sections of this manual,
either in discussions of general features or of the individual widgets (refer
to Chapter 9, Configuring Widgets).
A few fields need some initial explanation:
String

A string for the label. The label may be supplied programmatically or

by a graphic in many cases, which you indicate by marking a check
box for the option, and the string field is grayed-out.
Message

The name of the class message in the application model providing

the label, if the label is provided by the application (Supplied by
Application checkbox) either as a string or by a graphic (Label is Image
checkbox).
Aspect

The name of the property in the application model that represents the
value model for the widget. An instance variable and stub accessor
method for the aspect are created when you select Define for this
widget. The value model is typically a value holder, if the widget
reflects a property within the application model, or an aspect adaptor,
if the widget reflects a property in a separate domain model.
ID
The name of the widget. A default name is provided for each widget,
so you can easily identify it in the list of widgets. If you need to
access this widget programmatically, you also use this name to
identify the widget to the UIBuilder. You may change the default name
to something more descriptive or keep the default name.
Lookup Key
This is the message catalog lookup key. This field is displayed for
widgets that take a label, such as the label, action button, and radio
button. It is displayed when the Show UI for Globalization option is
activated on the UI Options page of the Settings Tool. For additional
information about message catalogs and their use, refer to the
VisualWorks Internationalization Guide (vwintlg.pdf).
Fly-by Help
The Fly-by Help page allows you to specify a String to display if the
user moves the cursor over the widget and pauses. This allows you to
give a hint to the user about what this widget does.

30

VisualWorks

Creating a Graphical User Interface

Installing the Canvas

At any time in the painting process, you can save the canvas by installing
it in an application model. Installing the canvas creates an interface
specification, which the UI Builder uses to display the UI. The
specification is stored as a class method in the application model.
To install a canvas, either click the Install button in the Canvas Tool, or
select install in the <Operate> menu for the canvas. The Install dialog
allows you to enter the necessary information.

For a new canvas, you need to enter a class name in the Install on Class
field. This can be a new class name or the name of an existing class. For
a new class, you will be asked for the appropriate superclass in a
subsequent dialog.
You must also either enter or select a method selector (message name)
for the specification. The default is windowSpec, which is the standard
name for the main window specification. If you are defining a secondary
window, you should pick another name. Click OK to save the specification.
If you specified a class that does not already exist, you are asked to
select a superclass and a name space for it. For an application, you
typically select ApplicationModel as the superclass. The name space is
typically one created for your application (refer to Name Spaces,
Chapter 6 in the Application Developers Guide, for more information).

GUI Developers Guide

31

Chapter 2 - Building an Applications GUI

The ApplicationModel superclass provides support functions for GUIoriented applications, so it is usually the right choice for an application.
SimpleDialog provides support features for dialogs (see Chapter 7,
Dialogs for more information). On the other hand, if the class must be a
subclass of some other class, select Other and enter its name.
The Category field sets the category for the new class. You can use an
existing category or a new category name that better identifies your work.

Reopening a Canvas
When you save the canvas, its specification is added to the resources for
the application. After youve closed the canvas, you can open it again for
editing using the Resource Browser (Browse ! Resources menu item in the
VisualWorks Main Window). In the Resource Browser, select the class
name containing the canvas, then select the specification for the canvas
and click Edit.
You can also select the specification method in a browser, and pick the
Edit Resource item on the <Operator> menu.

To save any changes you make to a canvas, you must reinstall it.

32

VisualWorks

Creating a Graphical User Interface

Defining Value Models

In the canvas you can also define instance variables and stub methods
for the aspect adaptors you identify in the properties for each widget. For
most widgets, the names of these variables and methods are specified in
the Aspect property. The Action Button widget has only a method (no
instance variable), and its name is specified in the Action property field.
Some widgets dont use variables or methods at all, and so dont have a
corresponding property.
Once you have entered aspect names for one or more widgets, select the
widgets, either individually or as a multiple selection. Then click the Define
button in the canvas tool, or select Define in the <Operate> menu for the
canvas. A confirmation dialog listing the names of aspects and actions
that will be defined is displayed. These aspects and actions are referred
to here as models since they represent the content of the widgets.

In the list of models, each item that will be defined is marked with a check
mark. To remove the check mark, and so skip that method, click on the
item.
Unchecking an item is important in subsequent define operations,
because redefining will usually overwrite any custom changes you make
to the method.
The Add Initialization checkbox gives a little control over how much code is
generated for aspect methods. Without initialization, the instance variable
for the aspect is simply returned. With initialization, the method tests for
whether the variable has a value, and if not it assigns an initial value. The
type of value assigned depends on the widget.
GUI Developers Guide

33

Chapter 2 - Building an Applications GUI

Once the stub methods are generated, you can edit them to provide the
specific processing your application needs. For example, to connect the
UI to its domain model, you must redefine some aspect methods to use
aspect adaptors. Refer to Chapter 4, Adapting Domain Models to
Widgets for more information.

Testing the User Interface

When you have installed the windows canvas in an application model,
you have a minimal application that can be started. At this point, the
widgets in the window exhibit generic behavior, because youve not
added any specific behavior to exhibit or data to display. You can,
however, see how the interface will look under running conditions.
To start the application, with the canvas open, click the Open button in the
Canvas Tool, or select Open in the canvas <Operate> menu. Move the
new window outline to a location on the screen and click.
You can also use this method for starting the application later, as you add
specific behavior to the application.

Formatting a Canvas
The following sections describe operations for formatting and arranging
widgets, to adjust how the window will appear in the application. Most of
the operations are performed in the canvas while assembling the GUI.
Some formatting can be set or changed programmatically, while the
application is running. Instructions are provided for doing this along with
the canvas instructions. For general instructions for accessing widgets
from a running application using the widgets ID, see Chapter 3,
Controlling the GUI Programmatically.

Setting the Window Size

While editing a canvas, you change the size of the window by dragging
the corners of the canvas to any desired size. Generally you select a size
and proportion that accommodates any widgets you use in the GUI. As
you design the canvas, you will likely change the size.
Once you have finished laying out the GUI, you want to ensure that the
window opens at the size you designed. To do this, select the Main Window
item in the GUI Painter Tools widget list, and go to the Position/Size page.

34

VisualWorks

Formatting a Canvas

At the bottom of are three sets of height and width dimensions. The
Specified dimensions give the default opening size. To set this to the
dimensions that you have sized the canvas, simply click the Specified
button, and the current dimensions are filled in. You may enter other
dimensions if you prefer.
It is also frequently useful to constrain a window to a certain size, so that
a user cannot change its size to larger or smaller than certain
dimensions. This is useful when the interface becomes unusable outside
of a range of values. These dimensions are provided by the Minimum and
Maximum dimensions. You can enter precise dimensions, but it is easier to
resize the canvas to the smallest usable size and click the Minimum
button. Similarly, resize the canvas to the largest desireable size, and
click the Maximum button.
If you allow the window to be resized, you will also want to decide how
widgets are sized. Refer to Sizing a Widget on page 38 for directions on
controlling widget sizes.

Setting the Window Opening Position

You can specify in the GUI Painter Tool for a canvas how the window will
be placed when the application is opened. In the GUI Painter Tool, go to
the Position/Size page, and select an opening option for your application
window.
In the top group, the options are:
System Default: Opens the window as specified as the default in the
Settings Tool, which is either user placement or automatic placement.
User Placement: Opens the window by user placement, regardless of
the default.
Advanced: Activates further options (below).
If you select Advanced, the further options are:
System Default: Opens the window as specified as the default in the
Settings Tool.
Screen Center: Opens the window centered on the screen.
Mouse Center: Opens the window centered on the mouse.
Last/Saved Position: If Auto is checked, the window will open where it
was last closed. If Auto is unchecked, the window will open each time in
the same location.

GUI Developers Guide

35

Chapter 2 - Building an Applications GUI

Cascade: Each time the window opens below and to the right of where it
last opened. This is useful especially if several copies of the window can
open in succession.
Specified Position: Opens with the top left corner at the specified
screen coordinate.
After selecting the option, Apply the change and Install the canvas.

Adding Scrollbars to a Window

Scrollbars on a window allow a GUI to contain widgets that might not
always be displayed, depending on window size. If this is a possibility, you
can add horizontal and/or vertical scrollbars to your window.
1

In the windows canvas, make sure no widget is selected, or select

the Main Window item in the widgets list.

On the Details properties page, turn on the desired scroll bars.

Apply the properties and install the canvas.

Adding a Menu Bar

To add a menu to a window, you create the menu using the Menu Editor
(refer to Chapter 5, Menus) and enable the menu in the canvas.
1

In the canvas for the window, make sure no widget is selected, or

select the Main Window item in the widgets list.

On the Basics properties page, turn on the Enable switch for the Menu
Bar property.

In the Menu field, enter the name of the menu-creation method,

defined for the menu in the Menu Editor.

Install the canvas.

You can use the Menu Editor to create the menu either before or after
enabling the canvas. Each first-level entry in the menu appears in the
menu bar, but only if it has a submenu.

36

VisualWorks

Formatting a Canvas

Setting the UI Colors

Setting colors for a window and for widgets within the window use the
same property dialog, and in fact work together.

Windows and widgets have four color zones:

Foreground

Background

Selection foreground

Selection background

On the Color properties page, you can apply a color to any of these zones.
By default, each zone is set to none, which means that the window or
widget inherits its colors. A window inherits the platform window
managers colors, and widgets inherit from either a containing widget or
the window. Unless you specifically want to highlight some feature of the
GUI, you should leave all color selections at their default.
When you do select colors, be sensitive to good taste (unlike the above
example). Also, be aware that some forms of color blindness made
certain combinations useless. For example, many people cannot
distinguish between red and green, so a red foreground on a green
background ought to be avoided.
GUI Developers Guide

37

Chapter 2 - Building an Applications GUI

To change a color:
1

In a canvas, select the window or widget whose color you want to set.

On the Color properties page, select the desired color from the color
chart.

Click on the color zone on the Color page.

To revert to none, click on the zone a second time with the same
color selected.

Apply the properties and install the canvas.

Sizing a Widget

These lists . . .

. . . are sized and

positioned by
these settings
in a Position
Tool

In the canvas, you can set a widgets size by dragging its selection
handles, stretching or shrinking the widgets dimensions.
You can make the widgets in a multiple selection all equal in height,
width, or both, using the Arrange ! Equalize... command in the GUI Painter
Tool menu. There are also buttons on the Palette for doing these
operations.
Widgets appear in their painted size when the window is opened. When
the window size is fixed, nothing more normally needs to be done.
However, when the windows size is variable, you may want to arrange for
the widget to adjust its size in relation to that of the window. You can use
the Layout ! Relative command on the Canvas Tool to arrange for
automatic resizing in both the vertical and the horizontal dimensions.
For more complicated situations, or for more precise control, you can set
properties on the Position properties page, as described in the following
sections.

38

VisualWorks

Formatting a Canvas

Making a Widgets Size Fixed

A widgets origin is controlled by the Left (L) and Top (T) property settings;
its size is controlled by the Right (R) and Bottom (B) property settings. A
fixed size is commonly used for buttons and labels.
Online example: Size1Example
1

In a canvas, select the widget whose size is to be fixed.

On the Position properties page, set the Right Proportion to be equal

to the Left Proportion (in the example, 0 and 0). Since proportions
control scaling, identical left and right proportions keep the right edge
of the widget a fixed distance from the left edge.

Set the Right Offset to the width of the widget added to the Left
Offset.

Set the Bottom Proportion equal to the Top Proportion.

Set the Bottom Offset to the height of the widget added to the Top
Offset.

Apply the properties and install the canvas.

Making a Widgets Size Relative

You can cause a widget to expand or shrink in concert with the window by
setting its Right Proportion to be different from the Left Proportion, or by
setting the Bottom Proportion to be different from the Top Proportion. This
is especially useful for widgets that can use additional space, such as text
editors, lists, and tables. Input fields are often made relative in the
horizontal dimension only.
Online example: Size1Example

GUI Developers Guide

In a canvas, select the widget whose size is to be relative.

On the Position properties page, set the Right Proportion to a value

that is larger than the Left Proportion. (A right proportion of 0.5 keeps
the right edge anchored at the windows midline while the left edge is
anchored to the windows left edge.)

Set the Right Offset to the distance you want between the widgets
right edge and the imaginary line identified by the Right Proportion.

Set the Bottom Proportion to a value that is larger than the Top
Proportion.

Set the Bottom Offset to the distance between the widgets bottom
edge and the imaginary line representing the Bottom Proportion.

39

Chapter 2 - Building an Applications GUI

Apply the properties and install the canvas.

Applying Explicit Boundaries to an Unbounded Widget

Four widgets are inherently variable in size: labels, action buttons, radio
buttons, and check boxes. These widgets change in size to accommodate
their textual labels, which expand and shrink on different platforms
because of font differences. Unlike most widgets, which have four
boundaries, the variable-size widgets are said to be unbounded.
Sometimes it is preferable to convert an unbounded widget so it is
bounded like other widgets. As shown in Size2Example, the advantage is
that you can make a series of buttons have equal dimensions, for
example. There is a slight hazard in converting an unbounded widget,
however; on a different platform, a font change in the widgets label may
cause the label to expand beyond the widgets unyielding boundaries.
Online example: Size2Example
1

In a canvas, select an unbounded widget such as a label.

In the Canvas Tool, select Layout ! Be Bounded.

Alternatively, select the Bounded button

on the Position page.

Apply the properties, if necessary, and install the canvas.

To reverse the operation, select Layout ! Unbounded.

Positioning a Widget
The basic way to set a widgets position is by dragging it to the desired
position in the canvas. This determines the widgets initial position relative
to the windows upper left corner.
Widgets appear in their painted position when the window is opened.
When the window size is fixed, nothing more normally needs to be done.
However, when the windows size is variable, you may want to arrange for
the widget to adjust its position relative to the size of the window. You can
use the Layout ! Relative command on the GUI Painter Tool to arrange for
automatic repositioning in both the vertical and the horizontal dimensions.
Buttons are available on the Palette for the same operation.
For more complicated situations, or for more precise control, use the
settings on the Position properties page.

Making a Widgets Origin Fixed

Making a widget fixed is useful when the windows size is fixed. When the
windows size is variable, this approach works best for a button or other
fixed-size widget that is located along the left or top edges of the window.
40

VisualWorks

Formatting a Canvas

Online example: Size1Example (start it and then resize the window to see
the effect)
1

In a canvas, select the widget whose position is to be fixed.

On the Position properties page, set the Left and Top Proportions to 0.
These proportions control whether a widget moves relative to the
window size. Setting these properties to 0 causes the widgets origin
to remain fixed in place.

Set the Left Offset to the desired distance between the windows left
edge and the widgets left edge (in the example, 50 pixels).

Set the Top Offset to the desired distance between the windows top
edge and the widgets top edge (50).

Apply the properties and install the canvas.

Making a Widgets Origin Relative

A relative origin causes the widget to move farther away from the left and
top edges of the window when the window grows and closer when the
window shrinks. This is useful for keeping an object centered in the
window and for shifting one widget that is placed below or to the right of
another widget that expands and shrinks in size.
You can also make the origin relative in only one dimension. In the
example, the origin shifts horizontally as the window is resized, but it
maintains a stable offset from the windows top edge.
Online example: Size1Example

GUI Developers Guide

In a canvas, select the widget whose position is to be relative.

On the Position properties page, set the Left Proportion to the fraction
of the windows width from which the Left Offset is to be measured.
(In the example, a left proportion of 0.5 causes the widget to remain
anchored at the windows midline.)

Set the Left Offset to the distance you want between the widgets left
edge and the imaginary line identified by the Left Proportion (50
pixels).

Set the Top Proportion to the fraction of the windows height from
which the Top Offset is to be measured. (In the example, a top
proportion of 0 anchors the widgets top edge at the top edge of the
window, which is the same as keeping the origin fixed in the vertical
dimension.)

41

Chapter 2 - Building an Applications GUI

Set the Top Offset to the distance you want between the widgets top
edge and the imaginary line identified by the Top Proportion (50
pixels).

Apply the properties and install the canvas.

Giving an Unbounded Widget a Fixed Position

An unbounded widget has no left, right, top, and bottom sides because its
boundaries are not fixed. However, it does have a reference point that can
be positioned in either a fixed or relative location in the window. By
default, the reference point is the origin of the widget (the top-left corner).
1

In a canvas, select an unbounded widget such as a label.

On the Position properties page, set all of the Proportions to 0.

Set the X and Y Offsets to the coordinates of the widgets top-left

corner relative to the top-left corner of the window.

Apply the properties and install the canvas.

Giving an Unbounded Widget a Relative Position

Online example: Size2Example

42

In a canvas, select an unbounded widget (in the example, select one

of the unbounded buttons on the left to examine its properties).

In the Position properties page, set the X Proportion to the fraction of

the widgets width at which the reference point is to be positioned
(0.5).

Set the Y Proportion to the fraction of the widgets height at which the
reference point is to be positioned (0).

Set the X Proportion to the fraction of the windows width at which the
widgets reference point is to be anchored. (In the example, an X
Proportion of 0.25 keeps the widgets reference point anchored onefourth of the way across the window.)

Set the X Offset to the distance you want between the widgets
reference point and the imaginary line identified by the X proportion
(0).

Set the Y Offset to the fraction of the windows height at which the
widgets reference point is to be anchored. (In the example, a Y
proportion of 0 keeps the widgets reference point a fixed distance
from the windows top edge.)

Apply the properties and install the canvas.

VisualWorks

Formatting a Canvas

Grouping Widgets
Windows frequently have clusters of widgets that work closely together.
Such clusters are usefully dealt with, for formatting purposes, as a single
object. For this purpose, the widgets can be formed into a group.
Once grouped, the whole group can be moved on the canvas, retaining
its arrangement.

Making a Group of Widgets

To make a group out of several widgets:
1

Select the widgets to be grouped, by selecting one widget and then

hold down the <Shift> key while selecting additional widgets.

Select Arrange ! Group either in the <Operate> menu or in the GUI

Painter Tool.

In the widgets list in the GUI Painter Tool, notice that a new pseudowidget, Composite1 (or some higher increment if there are already
composites) is added to the list. The component widgets are listed under
it and indented. The list can be collapsed or expanded as desired, to hide
or show the component widgets.
To ungroup a group of widgets, select Arrange ! Ungroup.

Editing Widgets in Groups

You can edit an individual widget within a group, without ungrouping. To
do so, in the hierarchical widget list in the GUI Painter Tool, select the
desired widget within the group. Then, edit its properties as usual.

Aligning Widgets

When painting a canvas, you frequently need to make several widgets

align along a vertical or horizontal line to give a neat, regular appearance.
For precise control you can use the Align dialog, shown above and
GUI Developers Guide

43

Chapter 2 - Building an Applications GUI

described below. There are also a set of alignment buttons on the Palette,
giving quick access to the alignment functions. You can also use the
Position properties page to precisely position widgets, but would usually
choose to do so only due to scaling consideration
1

In a canvas, select the widgets to be aligned.

In the GUI Painter Tool or the Canvas <Operate> menu, select the
Arrange ! Align command.

In the Align dialog, select on horizontal line when aligning side-by-side

widgets. When aligning widgets in a column, select on vertical line.

In the Align dialog, select first selection when the widgets are to be
aligned with the first widget that was selected. Select merged box to
align the widgets on a line halfway between the two most extreme
positions within the group of widgets.

In the Align dialog, select the edges, or the centers, to be aligned.

Install the canvas.

Distributing Widgets

When painting a canvas, you frequently need to make the spaces

between several widgets equal. For precise control you can use the
Distribute dialog, shown above. You can also use the distribution buttons
on the Palette.

44

In a canvas, select the widgets to be spaced.

In the GUI Painter Tool or Canvas <Operate> menu, select the Arrange
! Distribute command.

In the Distribute dialog, select left to right for widgets that are to be
spaced in a horizontal row. Select top to bottom for columnar
distribution.

VisualWorks

Formatting a Canvas

In the Distribute dialog, select the type of spacing. For constant spacing
between edges, you must specify the number of pixels to place between
each pair of widgets.

Install the canvas.

Changing a Widgets Font

When a widgets default font is not suitable, you can use the Font menu in
the widgets properties to choose an alternative font. The built-in fonts
are:

System, for a font that matches the current platforms system font,
when available. The font varies depending on platform and Look
policy. (Defined in the Look Policy classes.)

Default, for the default font for the widget. The font varies with the Look

Policy and the widget.

Pixel, Small, Medium, Large and Fixed defined in TextAttributes.

Standard, Small, Medium, Large and Fixed defined in

VariableSizeTextAttributes.

The drop-down lists under Pixel and Standard also list any Named Fonts
you have defined.

Named Fonts
VisualWorks does not automatically add all fonts on your system to the
fonts list. However, you can selectively add these fonts and assign them a
name for use by name. Once defined, a named font is added to the fonts
list in the GUI Painter and other utilities.

GUI Developers Guide

45

Chapter 2 - Building an Applications GUI

Open the Named Fonts tool from the GUI Painter Tool, either by clicking
the Define Named Fonts button or selecting Edit ! Define Named Fonts.

To add a named font:

1

Click Add New Named Font, and enter a descriptive name in the
prompter.

With the new name selected, assign attributes to it by selecting the

font (as known to the system) in the drop-down list, size, color, and
other characteristics.

Click Assign To Named Font, and Close the tool.

The named font can now be assigned to a text widget or field by selecting
it on the Details page.
The named font definitions are saved in the image the next time you save
it. You may also either file out the definitions using File ! Named Fonts !
File Out... in the GUI Painter Tool.
More importantly, you can install the named fonts into your application by
selecting File ! Named Fonts ! Install In Application... in the GUI Painter
Tool. This option adds a definedNamedFonts instance method to your
application model. Note that this option is only available when the current
application has already been installed.

46

VisualWorks

Opening and Closing Windows

Changing the Tabbing Order

When an application is running, users can use the <Tab> key to shift the
keyboard focus from one widget to the next in a window, without having to
move the mouse.
More specifically, the <Tab> key moves focus to each widget on the tab
chain. You add a widget to the tab chain by turning on its Can Tab property
on the Details property page. Passive widgets such as labels and dividers
do not have a Can Tab property, so they cannot be put on the tab chain.
Note that you should either turn off the Can Tab property in a text editor or
set the Tab Requires Control Key option, if you want the editor to interpret the
<Tab> key as a literal character to be entered into the text. Otherwise,
<Tab> will advance to the next widget. With Can Tab inactive, the user
cannot tab out of the text editor. With Tab Requires Control Key set,
<Ctrl>+<Tab> tabs out of the text editor.
The order in which the <Tab> key advances the focus is the order in
which the widgets are listed in the GUI Painter Tool widget list. To change
the tab order, select a widget and then click one of the ordering buttons:

Bring to Front (first tab position)

Bring Forward (forward one tab position)

Send Backward (backward one tab position)

Send to Back (last tab position)

Use these buttons to shuffle the widgets to the desired tab order.
For composite parts, arrange the tabbing order within the group. Then,
move the group to the appropriate position.

Opening and Closing Windows

The usual way of opening an interface window for an application is to ask
an application model to open one of its interface specifications. An
application is frequently started by opening its main window in this way.

GUI Developers Guide

47

Chapter 2 - Building an Applications GUI

Opening the Main Window

When the applications main window spec name is #windowSpec, you can
just send open to the application model:
Editor1Example open
If the main windows spec is named other than #windowSpec, send
openWithSpec: to the application class.
Editor1Example openWithSpec: #windowSpec
These expressions can either be incorporated into an application to open
the window at an appropriate time, or evaluated in a workspace to launch
the application.

Opening a Secondary Window

When the same application model serves one or more secondary
canvases in addition to the main canvas, you can open a secondary
canvas. A secondary canvas implies that the application has reached
the proper state, that the instance variables required by the interface
have been initialized.
This example creates a new UIBuilder the first time it is invoked, and it
stores that builder in an instance variable. When your application needs
to access widgets on the secondary canvas later, storing this second
builder assures you will have a means of accessing the widgets.

48

In a method in the application model, create a new UIBuilder.

Tell the builder which object will supply its menus, aspects, and other
resources by sending it a source: message. The argument is typically
the application model itself. (Alternatively, you can send a series of
aspectAt:put: messages to install the resources directly.)

Create the spec object and add the spec to the builder.

Open the window.

VisualWorks

Opening and Closing Windows

openFinder
"Open the Search window. If already open, raise to top."
| bldr |
(self finderBuilder notNil and: [self finderBuilder window isOpen])
ifTrue: [self finderBuilder window raise]
ifFalse: [
self finderBuilder: (bldr := UIBuilder new).
bldr source: self.
bldr add: (self class
interfaceSpecFor: #finderSpec).
bldr window
application: self;
beSlave.
self adjustSearchScope.
self searchStatus value: 0.
(bldr componentAt: #searchStatus) widget
setMarkerLength: 5.
bldr openAt: (self
originFor: bldr window
nextTo: #findButton)].
(self wrapperAt: #listView) takeKeyboardFocus.

Setting the Window Size at Opening

Rather than specify the opening size of a window in the canvas, you can
specify the size when opening.
1

Build an interface up to the point of opening the window, by sending

the allButOpenInterface: to an instance of the application model.

Get the window from the interface builder.

Ask the window to open with a specified size (extent), by sending the
window an openWithExtent: message.
| bldr win |
bldr := Editor2Example new allButOpenInterface: #windowSpec.
win := bldr window.
win openWithExtent: 500@220.

Setting the Startup Location of a Window

GUI Developers Guide

Build the interface up to the point of opening the window.

Get the window from the interface builder.

49

Chapter 2 - Building an Applications GUI

Ask the window to open itself within a specified rectangle, using

screen coordinates, in pixels.
| bldr win |
bldr := Editor2Example new
allButOpenInterface: #windowSpec.
win := bldr window.
win openIn: (50@50 extent: win minimumSize).

Closing Application Windows

The platform window manager provides the user with a means of closing
a window, such as clicking on a close icon. Often it is desirable for an
application to provide a close method in its interface, such as an Exit
option on a menu or a Quit button. An application might also close a
window as a side effect of some conclusive user action, such as clicking
the window managers close icon.
The techniques shown here notify the windows model, so it can take
precautions such as confirming the action.
When an application model is running one or more windows, you can
close it (or all of them at once, if there is more than one) by sending
closeRequest to the application.
Ask the application model to close its associated windows.
| editor |
editor := Editor2Example new.
editor openInterface: #windowSpec.
(Delay forSeconds: 1) wait.
editor closeRequest.

Performing Final Actions

When an application window has been asked to close, it first sends a
changeRequest message to its application model. If the model answers
false, the window wont close; if it answers true, the window proceeds to
close itself. Thus, the model has a chance to verify that no damage will
be done if the window is closed.
For example, as shown below, the Image Editor (UIMaskEditor) uses a
changeRequest method to confirm the users intent to abandon any
unsaved changes in the image.
Implement a changeRequest method in your application model, which
answers true when the window can close and false otherwise.

50

VisualWorks

Opening and Closing Windows

changeRequest
^super changeRequest
ifFalse: [false]
ifTrue: [(self modified or: [self magnifiedBitView controller
updateRequest not])
ifTrue:
[Dialog confirm: 'The image has been altered, but not installed.
Do you wish to discard the changes?']
ifFalse: [true]]
Notice also in the example that the inherited version of changeRequest is
first invoked to preserve any precautions that a parent class may have
implemented.

Hiding a Window
A window is a relatively expensive object, because it holds a visual
component that is often bulky and because it allocates a display surface
using the window manager. When your application needs to open and
close a window repeatedly, it is not necessary to reconstruct it each time.
Instead, you can unmap it, which hides the window without disassembling
it. Then you can simply map it to redisplay it.
| win |
win := (Editor2Example open) window.
win display.
(Delay forSeconds: 1) wait.
win unmap.
(Delay forSeconds: 1) wait.
win map.
All windows also respond to an isMapped message, and keep their
mapped state as a Boolean in their mapped instance variable.

GUI Developers Guide

51

3
Controlling the GUI Programmatically

An application frequently needs to exert control over the appearance and

behavior of its user interface during runtime. This requires exerting
programmatic control over the GUI.
This chapter describes various ways for exerting this control. Methods are
explained for identifying and accessing individual windows, dialogs and
widgets, and for setting their various properties.

Replacing the Builder Interface

When an application model opens an interface specification, it creates an
interface builder, which in turn creates the specified window and its
contents. To access windows and their components, the standard
approach as been through this builder object. The application would send
a self builder message, together with a specific message to access the
desired component, for example:
self builder window .
or
self builder compoentAt: aWidgetID .
This protocol has been replaced by a new, preferred protocol that allows
you to access these objects without first getting the builder. See
Accessor Methods below for the protocol.
The new protocol is preferred because in future releases the builder will
be removed, to be replaced by a new GUI building framework. The old
access approach will then be no longer valid.
While the implementation of the of this new protocol still accesses the
builder, future implementations will not. The new protocol will be
preserved in future releases, though the implementation will change.
52

VisualWorks

Replacing the Builder Interface

Accessor Methods
The following methods allow easy lookup of widgets and widget
components without having to go through the applications builder object.
We suggest using these messgage instead of the self builder messages
commonly used in VisualWorks applications.
wrapperAt: aSymbol
Answer the value of the named component at aSymbol. Typically gets
a SpecWrapper or nil. In the case of a toolbar, it gets the actual ToolBar
instance. This method is the ApplicationModel direct replacement for
messages of the form:
self builder componentAt: aSymbol.
controllerAt: aSymbol
Answers the controller for the component associated with aSymbol.
The answer may be nil or a Controller. In the case of a toolbar, it will
be nil. This method is the ApplicationModel direct replacement for
messages of the form:
(self builder componentAt: aSymbol) controller.
widgetAt: aSymbol
Answer the widget associated with aSymbol. Typically answers a kind
of VisualPart, which may be nil. This method is the ApplicationModel
direct replacement for messages of the form:
(self builder componentAt: aSymbol) widget
mainWindow
Answer the main window associated with this ApplicationModel
instances. Typically answers a ApplicationWindow. May be nil if the
window is not created yet. This method is the ApplicationModel direct
replacement for messages of the form:
self builder window
windowMenuBar
Answers the instance of MenuBar associated with the main window.
May be nil if the window is not mapped and opened, or if there is no
menu bar associated with the main window.

GUI Developers Guide

53

Chapter 3 - Controlling the GUI Programmatically

Accessing a Window
Getting an Application Window
Your application code can manipulate the window programmatically by
obtaining the window from the application model and then sending it
messages. To get the main window, send a mainWindow message to the
application instance. For example, to get an applications window and
change its label, do:
| app win |
app := Editor2Example new.
app open.
win := app mainWindow.
win label: 'Editor'.

Getting the Active Window

ScheduledControllers

The ScheduledControllers object keeps track of all controllers, including the

active controller. You can ask the active controller for its associated
window.
To access a window, ask the active controller for its associated window,
which is the topComponent associated with the controllers view.

54

VisualWorks

Accessing a Window

| win |
win := ScheduledControllers
activeController view topComponent.
win moveTo: 20@20.

Getting the Window at a Location

cursor
location

When your application performs an operation on a window that is pointed

to by the user (using the mouse), you can access the window as shown
here. Drag-and-drop operations, in particular, rely on this technique.
To get a window by its location:
1

Get the cursor location in screen coordinates by sending a

globalCursorPoint message to the controllers sensor.

Get the window at the cursor point by sending a windowAt: message

to the default Screen. The argument is the cursor location. (In the
example, the windows component flashes so you can verify that the
correct window was accessed.)
| sensor pt window |
sensor := ScheduledControllers activeController sensor.
Cursor bull showWhile: [sensor waitButton].
pt := sensor globalCursorPoint.
window := Screen default windowAt: pt.
window component flash.

GUI Developers Guide

55

Chapter 3 - Controlling the GUI Programmatically

Setting Window Properties

Once you have a window, you can set a variety of properties for that
window, overriding any properties set for the window when you created it.
This provides for a great deal of programmatic control over windows.
The following sections describe how to set several properties. For other
property setting options, browse the Window class and its subclasses.

Changing the Window Size

You can set a window size by giving it a new display box, using screen
coordinates. You can also constrain the window size, as shown here.
| win |
win := (Editor2Example new) open; mainWindow.
win displayBox: (100@100 extent: 400@220).

Determining a Windows Dimensions

Several messages are available for determining the dimensions and
constraints on a window. This example shows a few. For more, browse
the Window class and its subclasses.
| win min max box origin width height |
win := (Editor2Example new) open; mainWindow.
min := win minimumSize.
max := win maximumSize.
box := win displayBox.
origin := box origin.
width := box width.
height := box height.

Changing a Windows Label

You can modify an open windows label by sending a label: message to
the window, with the new label as argument.
| win |
win := (Editor2Example new) open; mainWindow.
win label: 'Editor'.

56

VisualWorks

Controlling Window Displays

Adding and Removing Scroll Bars

Programmatically adding and removing scrollbars requires that scrollbars
be initially activated, which is set in the Properties Tool for the window.
Then, to remove scroll bars, send a noVerticalScrollBar or
noHorizontalScrollBar message to the windows BorderDecorator. To add
scrollbars, send a useVerticalScrollBar or useHorizontalScrollBar message:
| win |
win := ApplicationWindow new.
win component: (BorderDecorator
on: Object comment asComposedText).
win open.
win component
noVerticalScrollBar;
noHorizontalScrollBar.
win display.
Cursor wait showWhile: [
(Delay forSeconds: 2) wait].
win component
useVerticalScrollBar;
useHorizontalScrollBar.

Controlling Window Displays

A variety of operations can be performed on windows by their application,
such as refreshing or collapsing (minimizing). For additional control
operations, browse Window and its subclasses.

Refreshing a Windows Display

Under normal conditions, a window redisplays its contents whenever
those contents change or whenever an overlapping window is moved.
Sometimes you need to redisplay a window programmatically, as when
you want to display an intermediate state of the window before a drawing
operation has been completed.
To refresh a window, send it a display message:
| win |
win := (Editor2Example new) open; mainWindow.
5 timesRepeat: [
(Delay forMilliseconds: 400) wait.
win display].

GUI Developers Guide

57

Chapter 3 - Controlling the GUI Programmatically

Expanding and Collapsing a Window

Window managers typically provide a means of collapsing (iconifying) a

window and expanding it back to its normal state. You can also control
that behavior programmatically.
To collapse a window, send a collapse message to the window. To expand
the window, send an expand message to the window.
| win |
win := (Editor2Example new) open; mainWindow.
win display.
(Delay forSeconds: 1) wait.
win collapse.
(Delay forSeconds: 1) wait.
win expand.

Assigning a Window Icon

For window managers that support iconified windows, VisualWorks
provides a default icon to represent a collapsed window. You can assign a
different icon to better represent the window. The icon must be an image
(refer to Graphical Images in the Application Developers Guide).

Creating an Icon
An icon is an instance of Icon, and consists of an image (figure) and a
mask (shape), both of which are instances of CachedImage. The icon may
also be registered in the Icon class IconConstants dictionary.
To create an icon with a mask, send a figure:shape: message to an
instance of Icon, specifying the image and mask:

58

VisualWorks

Assigning a Window Icon

| myIcon |
myIcon := Icon new
figure: VisualLauncher CGHelp24
shape: VisualLauncher CGHelp24Mask.
myIcon cleanFigure.
(The mask does not exist in the example, but can be created easily using
the Image Editor.)
If either the image or mask is an instance of Image, not CachedImage, send
asCachedImage to the image when assigning it to figure or shape.
The cleanFigure message is needed for color icons, to clean up some odd
behavior on Windows systems, and may not be required in all cases.

Registering an Icon
Icons that are reused frequently can be registered with the Icon class,
which stores icons in a dictionary.
To register an icon, send constantNamed:put: to the Icon class, with a
symbol for its name and the icon as arguments:
| myIcon |
myIcon := Icon new
figure: VisualLauncher CGHelp24
shape: VisualLauncher CGHelp24Mask.
myIcon cleanFigure.
Icon constantNamed: #HelpIcon put: myIcon
To later retrieve the icon, send constantNamed: to the Icon class:
| win |
win := ScheduledWindow new.
win icon: ( Icon constantNamed: #HelpIcon).
win open

Installing an Icon
Instances of ScheduledWindow and its subclasses store an icon in their
icon instance variable. To set an icon for a window, send an icon:
message to the window with the icon to use:
| win |
win := ScheduledWindow new.
win icon: ( Icon constantNamed: #HelpIcon).
win open
Windows other than instances of ScheduledWindow or its subclasses do
not hold onto the icon, and must ensure that the icon persists as long as
the window does. Registering the icon is sufficient.

GUI Developers Guide

59

Chapter 3 - Controlling the GUI Programmatically

Slave and Master Windows

In a multiwindow application, it is often helpful to close all secondary
windows automatically when the user closes the main window. In this
situation, the main window is called the master window and the
secondary windows are called slave windows.

Defining Slave and Master Windows

1

Tell the master window which application model to inform of its

events.

Tell the master window to be a master.

Tell the slave window which application model will relay events from
the master window.

Tell the slave window to be a slave.

| masterWin slaveWin |
masterWin := ( Editor1Example new ) openInterface; mainWindow.
masterWin
label: 'Master';
application: app;
beMaster.
slaveWin := (Editor2Example new) open; mainWindow.
slaveWin
label: 'Slave';
application: app;
beSlave.

Make Windows Equal Partners

When you want to be able to close all of your applications windows by
closing any one of them, make them partners instead of master and
slaves.
Tell the windows to be partners.

60

VisualWorks

Slave and Master Windows

| win1 win2|
win1 := ( Editor1Example new ) openInterface; mainWindow.
win1
label: 'Partner 1';
application: app;
bePartner.
win2 := (Editor2Example new) open; mainWindow.
win2
label: 'Partner 2';
application: app;
bePartner.

Choosing the Events That Are Sent

By default, master and partner windows broadcast the following events:
#close, #collapse, and #expand. You can remove any of those events, and
you can add any of the following: #bounds, #enter, #exit, #hibernate, #reopen,
and #release.
Tell the master or partner window which events to broadcast.
| masterWin slaveWin |
masterWin := ( Editor1Example new ) openInterface; mainWindow.
masterWin
label: 'Master';
application: app;
beMaster;
sendWindowEvents: #( #close #collapse
#expand #hibernate #reopen).
slaveWin := (Editor2Example open) window.
slaveWin
label: 'Slave';
application: app;
beSlave.

Choosing the Events That Are Received

By default, slave and partner windows mimic the following events: #close,
#collapse, and #expand. Controlling the events that are received lets each
slave be selective according to its needs.
Tell the slave or partner window which events to receive.

GUI Developers Guide

61

Chapter 3 - Controlling the GUI Programmatically

| masterWin slaveWin |
masterWin := ( Editor1Example new ) openInterface; mainWindow.
masterWin
label: 'Master';
application: app;
beMaster.
slaveWin := (Editor2Example new ) open; mainWindow.
slaveWin
label: 'Slave';
application: app;
beSlave;
receiveWindowEvents: #( #close).

Window Events
Unlike widgets, Windows and Dialogs trigger many events that are
directly related to Platform Operating System window events. Because of
this, not all events are triggered on all platforms. Therefore it is suggested
that you test your windows on all target platforms to assure that the
events you are registering for happen when and how you expect.
Windows and Dialogs also trigger events that are not coming in from the
platform operating system, these VisualWorks based events are available
to all Windows, without regard to the underlying operating system.
Platform based events are marked with the initial tag (Platform) in their
description. VisualWorks based events are marked with the initial tag
(VisualWorks) in their description.
An ApplicationModel can access the Window or Dialog by sending the
new #mainWindow message to itself. Once the window is in hand, the
developer can then set up its when:send:to: registration methods.
#activate
(Platform) When the underlying platform sends an activate
notification event to a VisualWorks window, the window triggers the
#activate event. On some platforms, only the enter event is sent.
#bounds
(Platform) When the underlying platform changes the size of the
VisualWorks window and sends the bounds notification event, the
window triggers the #bounds event.
#close
(Platform) When the underlying platform sends a close notification
event to a VisualWorks window, the window triggers the #close event.
62

VisualWorks

Window Events

#collapse
(Platform) When the underlying platform sends a collapse notification
event to a VisualWorks window, the window triggers the #collapse
event.
#deactivate
(Platform) When the underlying platform sends a deactivate
notification event to a VisualWorks window, the window triggers the
#deactivate event. On some platforms, only the exit event is sent.
#destroy
(Platform) When the underlying platform sends a destroy notification
event to a VisualWorks window, the window triggers the #destroy
event.
#enter
(Platform) When the underlying platform sends an enter notification
event to a VisualWorks window, the window triggers the #enter event.
#expand
(Platform) When the underlying platform sends an expand notification
event to a VisualWorks window, the window triggers the #expand
event.
#expose
(Platform) When the underlying platform sends an expose notification
event to a VisualWorks window, the window triggers the #expose
event.
#exit
(Platform) When the underlying platform sends an exit notification
event to a VisualWorks window, the window triggers the #exit event.
#move
(Platform) After a window is moved, the underlying platform sends a
move notification event to a VisualWorks window, the window in
response triggers the #move event.
#resize
(Platform) When the underlying platform sends a resize notification
event to a VisualWorks window, the window triggers the #resize event.
#unknownEvent
(Platform) There are many raw events that come into a VisualWorks
window from the underlying operating system. Any operating system
event that arrives at a VisualWorks window that VisualWorks does
not otherwise handle, is always sent to the main window as an
UnknownEvent. There are many ways of trapping these otherwise
unhandled events in the GUI framework. This event is triggerd as a

GUI Developers Guide

63

Chapter 3 - Controlling the GUI Programmatically

notification of when one of these events arrives. It is important to note

that the format of the underlying raw operating system event is
different for each platform, and that it is thus up to the developer to
deal with any cross platform issues. Additionally, these events come
in fast and furious.
#closing
(VisualWorks) When a window is in the process of closing, but before
the window is closed and loses focus, the window sends the #closing
event.
#opening
(VisualWorks) This is the very first VisualWorks event that all window
trigger. It occurs before the window is mapped and before it gets
focus.
#mapped
(VisualWorks) This is the second VisualWorks event that all window
trigger. It occurs just after the initial display surface is visually brought
to life. This also is triggered when a window which has been
programmatically unmapped, is remapped.
#unmapped
(VisualWorks) This event is triggered whenever a window is
programmatically unmapped. This event does not occur during the
sequence of closing a window.
#gettingFocus
(VisualWorks) This event is triggered whenever a window that does
not have focus, is given top visual focus, either by clicking in the
window, clicking on one of the windows visual accessories (such as
the title bar or a border), or by using an operating system feature to
bring the window to top focus.
#losingFocus
(VisualWorks) This event is triggered whenever a window that has
top focus is asked to no longer be the main window focus. This may
happen by clicking in or on any another window (without regard to if it
is a VisualWorks window), or by using an operating system feature to
bring another window to top focus. In the case of VisualWorks Dialog
windows, the Dialog window will not loose focus to VisualWorks
windows until it is closed, and therefore will not trigger the
#losingFocus event until that VisualWorks Dialog is closed.
#clicked
(VisualWorks) Previously, a window did not know when it was clicked
on. With this new event, any window which is clicked with the
<Select> mouse button, on in any area where there is not another
64

VisualWorks

Window Events

widget that handles the event, will cause the window to trigger the
#click event. This event is not triggered in the Menubar or Toolbar
areas. Labels and ViewHolders are examples of widgets that do not
handle mouse clicking, and for these, the underlying window will
trigger the #clicked event.
#rightClicked
(VisualWorks) As with the #clicked event, any window which is clicked
with the <Operate> mouse button on any area where there is not
another widget that handles the event, will cause the window to
trigger the #rightClicked event. This event is not triggered in the
Menubar or Toolbar areas. Labels and ViewHolders are examples of
widgets that do not handle mouse clicking, and for these, the
underlying window will trigger the #clicked event.
#doubleClicked
(VisualWorks) As with the #clicked event, any window which is double
clicked with the <Operate> mouse button on any area where there is
not another widget that handles the event, will cause the window to
trigger the #doubleClicked event. This event is not triggered in the
Menubar or Toolbar areas. Labels and ViewHolders are examples of
widgets that do not handle mouse clicking, and for these, the
underlying window will trigger the #doubleClicked event.
#middleClicked
(VisualWorks) As with the #clicked event, any window which is clicked
with the <Window> mouse button on any area where there is not
another widget that handles the event, will cause the window to
trigger the #middleClicked event. This event is not triggered in the
Menubar or Toolbar areas. Labels and ViewHolders are examples of
widgets that do not handle mouse clicking, and for these, the
underlying window will trigger the #middleClicked event. Windows and
Dialogs are the only visual objects in VisualWorks that trigger this
event.
#scrollLeft
(VisualWorks) If a window has horizontal scroll bars, and the window
view is made to scroll to the left, the window triggers the #scrollLeft
event.
#scrollRight
(VisualWorks) If a window has horizontal scroll bars, and the window
view is made to scroll to the right, the window triggers the #scrollRight
event.

GUI Developers Guide

65

Chapter 3 - Controlling the GUI Programmatically

#scrollUp
(VisualWorks) If a window has vertical scroll bars, and the window
view is made to scroll up, the window triggers the #scrollUp event.
#scrollDown
(VisualWorks) If a window has vertical scroll bars, and the window
view is made to scroll down, the window triggers the #scrollDown
event.
#menuBarCreated
(VisualWorks) At the time an ApplicationModel receives the
#postBuildWith: message, no menu bar has been created. This makes
it hard to register to a menu bar's events in the postBuildWith: method.
The developer has two choices, either register to a menu bar's events
in the postOpenWith: message, or register with the window's
#menuBarCreated event and do menu bar event registration at that
time. Once a menu bar is created, it can be access by the new
windowMenuBar method of the ApplicationModel.
#toolBarCreated
(VisualWorks) As with the menu bar, at the time an ApplicationModel
receives the postBuildWith: message, no tool bar has been created.
This makes it hard to register to a tool bar's events in the
postBuildWith: method. The developer has two choices, either register
to a menu bar's events in the postOpenWith: message, or register with
the window's #menuBarCreated event and do menu bar event
registration at that time. Once the tool bar is created, it can be
accessed by the widgetAt: method using the ID of the tool bar as
defined in the window properties page of the UIPainter tool.

Controlling Widgets
It is often useful for an application to be able to access the widgets in its
windows. Depending on the purpose of the access, a widget may be
accessed directly or through its wrapper. In either case, the widget is
identified by its ID, which is set in the Properties Tool in the Canvas.

Accessing a Widget
In a System Browser, edit a method in the application model (in this
example, alignCenter) so that it sends a widgetAt: message to the
application model. The argument is the ID.

66

VisualWorks

Controlling Widgets

alignCenter
| widget style |
widget := self widgetAt: #comment .
style := widget textStyle copy.
style alignment: 2.
widget textStyle: style.
widget invalidate.

Accessing the Widgets Wrapper

Online example: HideExample
In some cases, the application model must send messages to the
wrapper that surrounds the widget. A wrapper is an instance of
WidgetWrapper, which controls various aspects of the widgets
appearance, such as visibility, enablement, and layout.
1

In a canvas, select the widget to be accessed. In the widgets ID

property, enter an identifying name for the widget. Apply the
properties and install the canvas.

In a System Browser, edit a method in the application model (in this

example, changedListVisibility) so that it sends a wrapperAt: message to
the application model. The argument is the ID.
changedListVisibility
| wrapper desiredState |
wrapper := self wrapperAt: #colorList.
desiredState := self listVisibility value.
desiredState == #hidden
ifTrue: [wrapper beInvisible].
desiredState == #disabled
ifTrue: [
wrapper beVisible.
wrapper disable].
desiredState == #normal
ifTrue: [wrapper enable; beVisible].

Setting Widget Properties

The properties that are typically set in the Canvas using the Properties
Tool can also be set or changed during an application run by sending
appropriate messages to the widget or its wrapper. The following sections
explain how to set a number of properties. Additional options are
available, and can be found by browsing the widget classes.

GUI Developers Guide

67

Chapter 3 - Controlling the GUI Programmatically

Changing a Widgets Size

In some circumstances, your application may need to resize a widget
while the application is running. In Size3Example, a colored region is
resized in response to Expand and Shrink buttons.
Online example: Size3Example
1

Get the widgets wrapper from the application model.

Send a bounds message to the wrapper to get the widgets existing

size.

Create a rectangle having the desired origin and extent, using the
widgets bounding rectangle to derive the new values.

Send a newBounds: message to the wrapper. The argument is the

new bounding rectangle.
expandBox
| wrapper oldSize newSize |
wrapper := self wrapperAt: #box.
oldSize := wrapper bounds.
"If the box is bigger than the window already, do nothing."
oldSize origin x < 0
ifTrue: [^nil].
"Expand the bounding rectangle by 10 pixels on each side."
newSize := Rectangle
origin: oldSize origin - 10
corner: oldSize corner + 10.
"Assign the new bounding rectangle to the widget wrapper."
wrapper newBounds: newSize.

Changing a Widgets Font

Online example: Font1Example

68

In a method in the application model, get the widget from the

application model.

Create an instance of TextAttributes corresponding to the new font. If

the font exists in the fonts menu, you can send a styleNamed:
message to the TextAttributes class. The argument is the name of the
font (for example, #large for the systems Large font).

Get the label from the widget by sending a label message; get the text
of the label by sending a text message to it. Then install a blank text

VisualWorks

Controlling Widgets

temporarily as a means of erasing the old label if the new font is

smaller.
4

Install the new font in the widget by sending a textStyle: message to

the widget. The argument is the TextAttributes you created in step 2.

Reinstate the original label by sending a labelString: message to the

widget.
changedFont
| widget newStyle oldLabel |
widget := (self widgetAt: #label) .
newStyle := TextAttributes styleNamed: (self labelFont value).
"Erase the existing label in case its font is larger than the new one."
oldLabel := widget label text.
widget labelString: ''.
"Install the new font."
widget textStyle: newStyle.
"Reinstate the original label."
widget labelString: oldLabel.

Hiding a Widget
Sometimes a widget is useful only under certain conditions and needs to
be hidden at other times to avoid confusing the user of your application.
Action buttons need to be hidden when their actions are not appropriate.
A widget may also be hidden when two alternative widgets are layered on
top of each other. For example, the Online Documentation window uses a
text editor on top of a list editor and hides the view that is unneeded at
any given time.
You can turn on a widgets Initially Invisible property to cause the widget to
be hidden when the window opens. You can also program the application
model to hide and show the widget while the application is running.
Online example: HideExample

GUI Developers Guide

In a method in the application model, get the widgets wrapper from

the application model.

To hide the widget, send a beInvisible message to the wrapper.

To make the widget visible again, send a beVisible message to the

wrapper.

69

Chapter 3 - Controlling the GUI Programmatically

changedListVisibility
| wrapper desiredState |
wrapper := self wrapperAt: #colorList.
desiredState := self listVisibility value.
desiredState == #hidden
ifTrue: [wrapper beInvisible].
desiredState == #disabled
ifTrue: [
wrapper beVisible.
wrapper disable].
desiredState == #normal
ifTrue: [
wrapper enable.
wrapper beVisible].

Disabling a Widget
Sometimes a widget is useful only under certain conditions, but making it
invisible would be confusing to the user of your application. You can
disable a widget, causing it to be displayed in gray. In addition, its
controller is inactivated so the widget does not respond to user input.
Action buttons are frequently grayed out when not needed.
You can turn on a widgets Initially Disabled property to cause the widget to
be disabled when the window opens. You can also program the
application model to disable and enable the widget while the application
is running.
Online example: HideExample

70

In a method in the application model, get the widgets wrapper.

To disable the widget, send a disable message to the wrapper.

To make the widget active again, send an enable message to the

wrapper.

VisualWorks

Controlling Widgets

changedListVisibility
| wrapper desiredState |
wrapper := self wrapperAt: #colorList.
desiredState := self listVisibility value.
desiredState == #hidden
ifTrue: [wrapper beInvisible].
desiredState == #disabled
ifTrue: [
wrapper beVisible.
wrapper disable].
desiredState == #normal
ifTrue: [
wrapper enable.
wrapper beVisible].

Changing a Widgets Colors

Online example: ColorExample
1

In a method in the application model, get the widgets wrapper.

Get the LookPreferences from the wrapper and create a copy with the
desired color. The copy is created when a color-zone message is
sent: foregroundColor:, backgroundColor:, selectionForegroundColor:, or
selectionBackgroundColor:. The argument is the desired new color.

Install the new LookPreferences by sending a lookPreferences: message

to the wrapper. The argument is the new LookPreferences.
foregroundColor: aColor
"For each sample widget, change the indicated color layer."
| wrapper lookPref |
self sampleWidgets do: [ :widgetID |
wrapper := (self wrapperAt: widgetID).
lookPref := wrapper
lookPreferences foregroundColor: aColor.
wrapper lookPreferences: lookPref].

Adding and Removing Dependencies

When a widgets value is changed, such as when an item is selected from
a list, the application often needs to react in some way. A common
reaction is to update other widgets based on the new value. You can
arrange for such a reaction, typically as part of the initialization process.
This is known as setting up a dependency or registering an interest.

GUI Developers Guide

71

Chapter 3 - Controlling the GUI Programmatically

You can also bypass the dependency when unusual circumstances arise.
For example, when two widgets depend on each other, one of them must
bypass the dependency mechanism to avoid infinite recursion.

Adding a Dependency
Online example: DependencyExample
In the application models initialize method (typically), send an
onChangeSend:to: message to the widgets value holder. The first argument
is a message, which will be sent to the second argument. The second
argument is typically the application model itself.
initialize
colorNames := SelectionInList with: ColorValue constantNames.
selectedColor := String new asValue.
fieldIsDependent := false asValue.
"Arrange for the application model to take action when the
check box is turned on or off."
fieldIsDependent
onChangeSend: #changedDependency to: self.

Removing a Dependency by Retracting the Interest

Online example: DependencyExample
1

Send a retractInterestsFor: message to the widgets value holder. The

argument is the object that registered the interest, typically the
application model itself.

After the value has been changed, register the interest again.
changedDependency
"Turn on or off the dependency link between the list and
the input field, depending on the value of the check box."
| valueModel |
valueModel := self colorNames selectionIndexHolder.
self fieldIsDependent value
ifTrue:
[valueModel onChangeSend: #changedSelection to: self]
ifFalse:
[valueModel retractInterestsFor: self].

Bypassing All Dependencies

Online example: FieldConnectionExample

72

VisualWorks

Controlling Widgets

Send a setValue: message to the widgets value holder instead of the

usual value: message. The argument is the widgets new value.

Get the widget from the application model and ask the widget to
update itself with the new value.
changedB
"Use setValue: to bypass dependents, thus avoiding circularity."
self bSquared setValue: (self b value raisedTo: 2).
"Since dependents were bypassed when the model was updated,
update the view manually."
(self widgetAt: #b2) update: #value.

Validation Properties
Frequently, only certain entries are valid for a particular widget. For
example, you might want to restrict input accepted by an input field to a
numeric range from 0 to 999, or check for incompatible checkbox
selections.
Validation properties specify messages a widget sends to its application
model asking for permission to proceed. In this way, validation provides
input flow control, for example, to prevent the user from entering invalid
data into an input field, or to prevent the user from entering a field before
filling in other prerequisite fields.

GUI Developers Guide

73

Chapter 3 - Controlling the GUI Programmatically

Property

Description

Entry

Specifies the message the widget sends to its application

model when it prepares to accept focus. If the method
returns true, the widget takes focus; otherwise, focus is
refused.

Change

Specifies the method the widget sends to its application

model after the user changes the widgets value and
attempts to exit the widget before the widget writes the
input value to its value model. The method should
determine whether the input value is acceptable. If the
method returns true, the widgets controller writes the
input value to the value model; otherwise, the value model
remains unchanged.

Exit

Specifies the method the widget sends to its application

model when it prepares to give up focus. The message is
sent any time the user attempts to exit the widget. The
method should determine whether the widget can actually
give up focus. If the method returns true, the widget gives
up focus; otherwise, focus is retained.

D. Click

Specifies the method the widget sends to its application

model when preparing to respond to a double-click.

Validation methods, which you add to the application model, return either
true or false. On true, the widget proceeds with its action; on false, the
widget waits for new, valid input. You can implement the validation
method to redirect input focus or to disable and enable input widgets.
To create a validation method that inspects the widgets value, specify a
selector with a colon (selector:). The widget passes its controller object as
the argument to the method. The method can then ask the controller for
the widgets value. For certain widgets (input fields, text editors, and
combo boxes), you use statements such as the following to get and set
values through the controller:
input := aController editValue

Notification Properties
You specify Notification properties when you want a widget to inform its
application model that certain actions have taken place, namely, that the
widget has taken focus, changed internal state, or given up focus.
Notification properties are useful for facilitating complex flow of user
input.
Each notification property specifies the symbolic name of a notification
callback, which is the message you want the widget to immediately send
after the relevant action. For each notification callback you specify, you
74

VisualWorks

Controlling Widgets

must program the application model to contain a corresponding method.

You implement this method to provide the desired response to the
widgets action. You can implement the notification method to activate
other widgets in the interface.

GUI Developers Guide

Property

Description

Entry

Specifies the symbolic name for the widgets entry

notification callback. The widget sends this message to its
application model immediately after taking focus. You must
implement a corresponding method in the application
model that provides the desired response to this event.

Change

Specifies the symbolic name for the widgets change

notification callback. The widget sends this message to its
application model immediately after the widget sends its
input value to its value model. You must implement a
corresponding method in the application model to provide
the desired response to this event. Note that specifying a
change notification callback is similar to registering an
interest in a value model via onChangeSend:to:, in that both
cause a message to be sent after the value in the value
model has changed.
However, the two techniques also differ in important ways:
The change notification callback is sent only to the
application model. The message specified by
onChangeSend:to: is sent to the specified receiver, which
may, but need not be the application model. If both
techniques are used together, the message sent by
onChangeSend:to: is sent first, and the change notification
callback is sent second.

Exit

Specifies the symbolic name for the widgets exit

notification callback. The widget sends this message to its
application model immediately after it gives up focus. You
must implement a corresponding method in the application
model to provide the desired response to this event.

D. Click

Specifies the symbolic name for the widgets double-click

notification callback. This callback is the message that the
widget sends to its application model in response to a
double-click. You must implement a corresponding method
in the application model to provide the desired response to
this event.
This property appears with the List and Table widgets only.

75

4
Adapting Domain Models to Widgets

Value models are a powerful device for establishing dependencies

between objects, so that when a change occurs to one object, another is
automatically notified. While this mechanism is useful between any
objects, it is used most to establish dependencies between domain
models and widgets. This mechanism is a fundamental feature of the
VisualWorks application framework.
The Define operation in the UI Painter creates a simple value model for
each widget, typically a ValueHolder. This object is sufficient for very small
applications for which the domain is modeled within the application
model. For applications that separate the domain model from the
application model, more connecting logic needs to be defined.
This chapter describes some standard approaches to configuring value
models.
The trigger-event system, which is not described in this chapter, provides
a powerful, additional approach to defining dependencies. All windows,
dialogs, and widgets trigger events in specified conditions. These events
are described at appropriate places in this document. For a general
description of the trigger-event system, refer to the Application
Developers Guide, chapter 6, Event System.

76

VisualWorks

Setting up Simple Value Models (ValueHolder)

Setting up Simple Value Models (ValueHolder)

This input field is a

dependent of the
value holder in the
name variable

A widget that presents data (such as an input field) relies on an auxiliary

object called a value model to manage the data it presents. That is,
instead of holding onto the data directly, a data widget delegates this task
to its value model. Thus, when a data widget accepts input from a user, it
sends this data to its value model for storage. When a data widget needs
to update its display, it asks its value model for the data to be displayed.
A value model provides a uniform set of messages for accessing the data
to be presented, allowing all data widgets to store and refresh their data
in a standard way. Use a value message to get the data from the value
model. Use a value: message to set data in the value model and update
the widgets display. Other objects, such as the application model, can
also send these messages to a value model to obtain or change a
widgets data programmatically.
A data widget is a dependent of its value model in that the widget
depends on its value model to notify it when the relevant data has
changed. The widget responds to such notification by asking the value
model for the new data and displaying it. This keeps the widgets display
synchronized with changes made programmatically to the data.
A ValueHolder is the most basic type of value model. As its name implies,
a value holder holds onto the relevant data in an instance variable. A
value holder is most useful for widgets that accept temporary pieces of
information that the interface must hold onto until they can be further
processed.

Defining a Value Holder

Online example: Adaptor1Example
Send an asValue message to the data object that is to be contained (in the
example, the number 0 is asked to return a value holder containing itself).

GUI Developers Guide

77

Chapter 4 - Adapting Domain Models to Widgets

initializeID
accountID := 0 asValue.
accountID onChangeSend: #changedID to: self.
Send a newString message to the ValueHolder class. This is equivalent to
the expression String new asValue, and the choice of which to use is a
matter of personal preference.
initializeName
name := ValueHolder newString.
name onChangeSend: #changedName to: self.
Send a newBoolean message to the ValueHolder class. This is equivalent to
the expression false asValue.
Send a newFraction message to the ValueHolder class. This is equivalent to
the expression 0.0 asValue.

Adapting Part of a Domain Model (AspectAdaptor)

Name (input field)
Customer (domain model)
subject
AspectAdaptor
Name (variable)

aspect

Data widgets are commonly used for presenting data that is held by some
object in the application, such as a domain model. In such cases, the
appropriate value model is an AspectAdaptor, which is conceptually a
pointer to the remote data. An aspect adaptor has a subject, which is the
relevant domain model, and an aspect, which is the name of the instance
variable that holds the relevant data. An aspect adapter translates the
value and value: messages it receives into accessor and mutator
messages that are understood by its subject.
Subject channel: You can set up an aspect adaptor so that it obtains its
subject from a value holder, called a subject channel. A subject channel
provides indirect access to the subject, allowing you to programmatically
introduce a new subject for an existing aspect adaptor. This is useful
when you want particular data widget to display data held by successive
domain model instances.

78

VisualWorks

Adapting Part of a Domain Model (AspectAdaptor)

Unusual accessors: By default, an aspect adaptor assumes that the

domain model has accessing messages for getting and setting the value
of the variable, and that those messages can be derived from the
variables namein the example, the domain model is a
Customer1Example, and it provides name and name: methods for accessing
the value of its name variable.
Programmatic changes to data: By default, an aspect adaptor notices
programmatic changes to the data only upon receiving a value: message.
However, a domain model normally changes its data without sending any
messages to the aspect adaptor.

Defining an Adaptor
Online example: Adaptor2Example
This example shows how to set up an aspect adaptor with a subject
channela value holder from which the aspect adaptor will obtain its
subject.
1

In an initialize method in the application model, initialize an instance

variable (selectedCustomer) with a value holder that holds the domain
model (a Customer1Example).

In an aspect method (accountID), send a subjectChannel: message to

the AspectAdaptor class. The argument is the value holder you created
in step 1.

Tell the aspect adaptor which aspect of the domain model to monitor
by sending a forAspect: message to the adaptor. The argument is a
Symbol, typically the name of the desired instance variable (accountID)
in the domain model.
initialize
customers := SelectionInList new.
customers selectionIndexHolder
onChangeSend: #changedCustomer to self.
selectedCustomer := Customer1Example new asValue
accountID
| adaptor |
adaptor := AspectAdaptor subjectChannel: self selectedCustomer.
adaptor forAspect: #accountID.
adaptor onChangeSend: #redisplayList to: self.
^adaptor

GUI Developers Guide

79

Chapter 4 - Adapting Domain Models to Widgets

Addressing the Subject Directly

If the subject does not change during a run, you do not need go the
indirect route illustrated above of holding the domain model object in a
ValueHolder, but can hold the domain model object itself.
In step 1 above, assign the domain model instance itself to the instance
variable.
In step 2 above, send a subject: message to the AspectAdaptor class
instead of a subjectChannel: message. The argument is now the domain
model, instead of a value holder containing the domain model.

Accommodating Unusual Accessors

Use these steps when a domain model provides accessor methods
whose names are different from the instance variable they accessfor
example, when the aspect is an instance variable called income, and its
accessors are getIncome and putIncome:.
Online example: Adaptor2Example
After creating the adaptor, send an accessWith:assignWith: message to it.
The first argument is the name of the domain models method that
accesses the desired value. The second argument is the name of the
method that assigns a new value. (In the example, the message names
are address and address:, and they access an instance variable named
address, so the same effect can be achieved via forAspect: #address).
address
| adaptor |
adaptor := AspectAdaptor subjectChannel: self selectedCustomer.
^adaptor
accessWith: #address
assignWith: #address:

Monitoring Programmatic Changes

Online example: Adaptor2Example and Customer1Example

80

Send a subjectSendsUpdates: message to the adaptor with the

argument is true. This causes the adaptor to register itself as a
dependent of the subject (in the example, a Customer1Example).

In the domain model class (Customer1Example), edit every method that

alters the data value directly (that is, without going through the
adaptor), so that it sends a changed: message to self. The argument is
the aspect that has been changed (#phoneNumber). This causes the

VisualWorks

Synchronizing Updates (Buffering)

dependent adaptor to be notified when the domain model makes the

relevant change.
phoneNumber
| adaptor |
adaptor := AspectAdaptor subjectChannel: self selectedCustomer.
adaptor forAspect: #phoneNumber.
adaptor subjectSendsUpdates: true.
^adaptor
formatUSPhoneNumber
| rawPhone rawSize areaCode prefix suffix separator |
rawPhone := self phoneNumber select: [ :ch | ch isDigit].
rawSize := rawPhone size.
areaCode := ''.
prefix := ''.
suffix := ''.
separator := '-'.
rawSize > 0 ifTrue: [areaCode :=
rawPhone copyFrom: 1 to: (3 min: rawSize)].
rawSize > 3 ifTrue: [prefix :=
separator,
(rawPhone copyFrom: (4 min: rawSize) to: (6 min: rawSize))].
rawSize > 6 ifTrue: [suffix :=
separator,
(rawPhone copyFrom: (7 min: rawSize) to: (rawSize min: 10))].
self phoneNumber: areaCode, prefix, suffix.
self changed: #phoneNumber.

Synchronizing Updates (Buffering)

These input fields all

pass their values to
the model at the same
time (when the OK
button is clicked)

GUI Developers Guide

81

Chapter 4 - Adapting Domain Models to Widgets

Frequently, it is useful to delay updating a particular widgets value until

other widgets in the same series are ready to be updated. This is
especially true in applications that make use of a database, because a
row is updated only after all changes to the fields in that row have been
made. Using BufferedValueHolders enables you to arrange a trigger
channel that is monitored by all of the widgets in the series.
The trigger channel is a value holder that contains true or falseputting
true in the trigger channel causes all of the dependent adaptors to update
the model. Putting false in the trigger channel discards the buffered
values, canceling the update.
Adaptor3Example provides an OK button that you press after you enter
customer information in the input fields. When you press the OK button,
the values are assigned to the selected customer.

82

VisualWorks

Synchronizing Updates (Buffering)

Adding Synchronized Updates

Online example: Adaptor3Example
1

In the application model, create an instance variable (in the example,

updateTrigger) to contain the true/false value that triggers updates.

Create an accessing method for the variable.

updateTrigger
^updateTrigger

Initialize the variable to a value holder containing false.

initialize
customers := SelectionInList new.
customers selectionIndexHolder
onChangeSend: #changedCustomer to: self.
selectedCustomer := Customer1Example new asValue.
updateTrigger := false asValue.

For each widget in the series, place the widgets value model in a
BufferedValueHolder by sending a subject:triggerChannel: message to the
BufferedValueHolder class. The first argument is the widgets value
model (in the example, an AspectAdaptor). The second argument is
the trigger channel (updateTrigger). This is typically done when the
widgets value model is initialized. Note that the buffered value holder
does not replace the widgets value modelrather, it contains that
value model.
accountID
| adaptor bufferedAdaptor |
adaptor:= AspectAdaptorsubjectChannel:self selectedCustomer.
adaptor forAspect: #accountID.
bufferedAdaptor := BufferedValueHolder
subject: adaptor
triggerChannel: self updateTrigger.
^bufferedAdaptor

GUI Developers Guide

Provide a button, a menu command, or other device with which the

user can indicate that the series of values have all been edited as
much as necessary (in the example, completion is indicated using an
OK button that triggers an accept action).

In the action method (accept), send a value: message to the trigger

channel (updateTrigger). The argument is true.

83

Chapter 4 - Adapting Domain Models to Widgets

accept
self updateTrigger value: true.
self redisplayList.

Discarding the Buffered Values

Online example: Adaptor3Example
Send a value: message to the trigger channel (updateChannel). The
argument is false. This is typically done after confirming that the user
wants to abandon the edited data.
changedCustomer
| chosenCustomer selector |
chosenCustomer := self customers selection.
chosenCustomer isNil
ifTrue: [
self selectedCustomer value: Customer1Example new.
selector := #disable]
ifFalse: [
self selectedCustomer value: chosenCustomer.
selector := #enable].
"Discard changes that were not OK'd."
self updateTrigger value: false.
"Enable/disable selection-sensitive widgets."
#( #accountID #name #address #phoneNumber #ok)
do: [ :componentName
(self wrapperAt: componentName)
perform: selector].

84

VisualWorks

Adapting a Collection (SelectionInList)

Adapting a Collection (SelectionInList)

customers (list widget)

Collection of customers

SelectionInList

A list or notebook widget is designed to work with a SelectionInList, which

contains a value holder for holding the collection to be displayed. When
the domain model supplies a simple collection, you can set up a
SelectionInList to adapt to it.
Online examples: Adaptor4Example and Customer2Example
In this example, the application model is Adaptor4Example, and the domain
model is a Customer2Example, which holds an OrderedCollection of
customers.
Put the domain models collection in a SelectionInList by sending an
adapt:aspect:list:selection: message to the SelectionInList class. The adapt:
argument is the domain model (in the example, collectionModel). The
aspect: argument is typically the name of the domain models collection
variable. The list: argument is the name of the domain models method
that returns the collection. The selection: argument is the name of the
domain models method that sets the selection in the collection.
initialize
collectionModel := Customer2Example new.
customers := SelectionInList
adapt: collectionModel
aspect: #customers
list: #customers
selection: #selectedCustomer:.
customers selectionIndexHolder
onChangeSend: #changedCustomer to: self.
selectedCustomer := Customer1Example new asValue.

GUI Developers Guide

85

Chapter 4 - Adapting Domain Models to Widgets

Adapting a Collection Element

Each of these fields monitors one

of three elements in an array

Sometimes a widget is used to display a single element in a collection.

This situation arises when an array or other collection is used to gather a
set of related attributes that would normally be separate instance
variables in a domain model.
In the example, the domain model has a vector that consists of an array
of three numbers, representing the x, y, and z axes. If the vector were an
instance of a hypothetical Vector class and could respond to vector-like
accessing messages, you could use an AspectAdaptor to hold its three
axis values. Because the vector is a simple array that cannot respond to
such messages, you must use an IndexedAdaptor.
An IndexedAdaptor has a subject (the collection) or subject channel (when
the collection is in a value holder) and an index number (the position of
the desired element in the collection).
Online example: Adaptor5Example
1

Send a subjectChannel: message to the IndexedAdaptor class, with the

value holder containing the collection as the argument. If the
collection is not contained in a value holder, send a subject: message
instead, with the collection as the argument.

Send a forIndex: message to the adaptor. The argument is the

position of the desired element in the collection.
xAxis
| adaptor |
adaptor := IndexedAdaptor subjectChannel: self vector.
^adaptor forIndex: 1

86

VisualWorks

Creating a Custom Adaptor

Creating a Custom Adaptor

This input field uses a PluggableAdaptor
to translate from a number to a zero-padded
string and back again

Occasionally it is convenient to use a custom adaptor that performs a

block of actions each time its value is accessed or changed. A
PluggableAdaptor provides this flexibility. In the example, a PluggableAdaptor
is used to translate an integer such as 342 into a string containing
prefixed zeroes ('000342'), saving the user the trouble of entering the
leading zeroes.
A PluggableAdaptor takes three blocks, which enable it to perform custom
actions at three junctures in the flow of communications between the
widget and the domain model:

The getBlock: controls what happens when a value is fetched from the
model by the widget. In the example, the block translates the models
account number into a zero-padded string.

The putBlock: controls what happens when a value is sent to the

model by the widget. In the example, the zero-padded string is
converted back into a number.

The updateBlock: controls when the widget updates itself based on an

update message sent by the model. When the widget is the only
source of changes to the data value, this block can simply return false.
When the data value can be changed by other objects, the block
performs a test to determine whether the widget should refetch the
data value. Typically this test uses the update blocks second
argument, the aspect, to find out whether the aspect that it cares
about has changed.

Online example: Adaptor6Example

GUI Developers Guide

Create the custom adaptor by sending an on: message to the

PluggableAdaptor class. The argument is the domain model.

Send a getBlock:putBlock:updateBlock: message to the adaptor. The

first block takes one argument: the domain model. The second block
takes two arguments: the model and the value to be assigned. The
third block takes three arguments: the model, the aspect of the model

87

Chapter 4 - Adapting Domain Models to Widgets

that was changed, and a parameter that corresponds to the argument

of a changed:with: message, when applicable.
initialize
accountID := 1.
paddedID := PluggableAdaptor on: self.
paddedID
getBlock: [ :model |
| paddedString |
paddedString := model accountID printString.
6 - paddedString size
timesRepeat: [paddedString := '0', paddedString].
paddedString]
putBlock: [ :model :value |
model accountID: value asNumber]
updateBlock: [ :model :aspect :parameter | false]

88

VisualWorks

5
Menus

VisualWorks provides menu bars, menu buttons, and pop-up menus as

GUI elements for presenting lists of options. All three elements use an
underlying instance of Menu for their options. The Menu Editor provides
an easy-to-use tool for creating a menu, or you can assemble a menu
programmatically.
Menu bar and pop-up menus by default send a message to the
application model, while a menu button by default places a value in its
aspect value holder. Building a menu for these different behaviors affects
what you assign to each menu item while building the menu.
To override the default behavior for a type of menu, you can define the
value of a menu item in an action block. In this way, you can cause a
menu bar or pop-up menu item to place a value in a value holder, or a
menu button item to execute a command. This makes the VisualWorks
menu support extremely flexible while at the same time providing a
powerful framework for menu implementation.

Creating a Menu
You can create a menu either using the Menu Editor, or programmatically.
With the Menu Editor, you can create menus of messages or values. If a
more complex action is required, such as a compound message or an
action block, you can assemble the menu programmatically.
Complex actions are necessary, for example, for assigning a value to a
value holder from a menu bar or pop-up menu, or executing a command
from a button menu.

GUI Developers Guide

89

Chapter 5 - Menus

Creating a Menu using the Menu Editor

The Menu Editor provides both menu selections and buttons for several
design operations. In the following instructions, we refer to the menu
selections, but the button equivalent can be used.
Online example: MenuEditorExample
1

Open a Menu Editor by selecting Tools ! Menu Editor in the main

window.

Add a top-level menu by selecting Edit ! New Item, and edit its
properties.
When you add a menu item, it is displayed as <new item>. Edit this
label in the Label Default property, giving the menu item the label you
want displayed.
To include a mnemonic for the menu item, insert an ampersand (&)
character in the label before the letter to use as the mnemonic. For
example, I&tem makes t the mnemonic letter for the item, and is
indicated in the menu by underlining the letter.
Subsequent uses of Edit ! New Item add items at the same level as
the selected item.

Add a submenu by selecting a label and choosing Edit ! New Submenu

Item.

The new item is placed below and indented from the selected item.

90

VisualWorks

Creating a Menu

In each items Value property, either:

enter a message selector

leave blank, if the item has submenu items

A message selector is sent to the application model by menu bar and

pop-up menus. For a button menu, the selector should be the
widgets aspect accessor method, which updates the aspect value
holder.
A value property is not needed if the item has subitems, since
selecting the item only displays the submenu.
5

Specify the shortcut character, if desired.

A shortcut character allows the user to select this menu item by
pressing the character key while holding down one or more modifier
keys (<Ctrl>, <Alt>, or <Shift>). To specify a character, enter it in the
Shortcut character: field on the Details page, and check the desired
modifier key check boxes. The shortcut will be displayed in the menu.

Adjust any menu item levels and locations as needed.

Move ! Left and Move ! Right change the menu level of an item. Move
! Up and Move ! Down change the order of items.

Choose Menu ! Install... to install a specification for the menu in a

resource method of the application model.

Create any methods required by message names entered in a menu

items Value property.

Creating a Menu Programmatically

When building a menu programmatically, each menu label is associated
with its action, which may be a value, a command, or an action block.
Since value and command menus can be created using the Menu Editor,
we illustrate the programmatic approach with an action block example
(but see the MenuCommandExample and MenuValueExample online
examples).
Action blocks are typically used in menu bar and pop-up menus that
place values in value holders (as illustrated), or in button menus that
execute a command. To execute a command, you configure the value
holder for the button menu to send perform: with its value holder value as
argument when its value is changed.

GUI Developers Guide

91

Chapter 5 - Menus

A menu typically is created by a method in a resources protocol on the

class side of an application model. The resource method can also be an
instance method, which is necessary when it relies on data supplied by a
running application.
Online example: MenuValueExample
1

In a menu-creating instance method, create a menu builder by

sending a new message to the MenuBuilder class.
An instance method is used in the example
(templatesMenuForMenuBar) because information is needed from the
application model instance. If this is not required, the menu creation
method can be a class method (see the MenuValueExample class
resource methods).

For each menu item, send an add: message to the menu builder with
an association as the argument.
The association relates the menu items label string and the block
that performs the required action. For value and command menus,
the value holder or message selector occur, as symbols, in place of
the block.
To include a mnemonic for the menu item, insert an ampersand (&)
character in the label before the letter to use as the mnemonic. For
example, I&tem makes t the mnemonic letter for the item, and is
indicated in the menu by underlining the letter.

To add a shortcut key sequence for the menu item, which displays on
the menu, specify the character key and the modifier key or keys.
(Note that this is not illustrated in the example code.)
For example, to specify <Ctrl>+<Shift>+A as the shortcut, add these
lines:
menuItem shortcutKeyCharacter: $A.
menuItem shortcutModifiers:
(InputState ctrlMask bitOr: InputState shiftMask).
The modifier keys can be specified individually (ctrlMask, shiftMask, or
altMask), or combined using bitOr: as shown above.

To insert a submenu, send a beginSubMenuLabeled: message to the

menu builder with the submenu label as argument.
This begins a submenu definition. Add submenu items by sending an
add: message to the menu builder, as before.

92

VisualWorks

Adding Menus to the User Interface

At the end of the submenu definition, send an endSubMenu message

to the menu builder.
5

Get the menu from the menu builder using a menu message and
return it as the result of the menu-creating method.

In this example, all menu items are added within a submenu. This is
necessary here because the menu is being added to the menu bar. The
submenu label is displayed in the menu bar.
The example also illustrates adding graphics and color programmatically.
templatesMenuForMenuBar
| mb menu submenu |
mb := MenuBuilder new.
mb
beginSubMenuLabeled: 'Templates';
add: ' ' -> [self letter value: self class firstNotice];
add: ' ' -> [self letter value: self class secondNotice];
add: ' ' -> [self letter value: self class finalNotice];
endSubMenu.
"Add graphic labels."
menu := mb menu.
submenu := (menu menuItemLabeled: 'Templates')
submenu.
(submenu menuItemAt: 1)
labelImage: (self class oneImage).
(submenu menuItemAt: 2)
labelImage: (self class twoImage).
(submenu menuItemAt: 3)
labelImage: (self class threeImage).
"Set the background color."
submenu backgroundColor: ColorValue chartreuse.
^menu

Adding Menus to the User Interface

You add a menu to your applications GUI either by adding a menu bar to
the window, adding a menu button widget, or by specifying the pop-up
menu for a widget. These are all defined in the canvas and Properties
Tool by specifying a menu you have defined in the Menu Editor or in a
menu creating method.

GUI Developers Guide

93

Chapter 5 - Menus

Adding a Menu Bar to a Window

A menu bar appears to the user as a set of separate menus across the
top edge of a window. The menus and submenus are actually
implemented by a single menu object. The menu labels displayed across
the menu bar are top-level menu items in the menu object and their
contents are the submenus associated with the top-level menu items.
Online example: MenuCommandExample
1

In the canvas for the window, make sure no widget is selected.

In a Properties Tool, turn on the Enable switch for the Menu Bar
property.

In the Menu field, enter the name of the menu-creation resource

method (fileMenu).

Create the menu definition resource method that you named in step
3, and any action methods that are invoked by the menu items.

Adding a Menu Button

menu button

A menu button is a widget that allows you to place a drop-down menu

anywhere in the canvas. Also, its label typically changes to reflect the
current selection. By default, selecting an item in a button menu places
the value of the menu item in the button menu widgets aspect value
holder.
For information about configuing the Menu Button widget, refer to Menu
Button in Chapter 9, Configuring Widgets.
Online example: MenuValueExample

94

VisualWorks

Adding Menus to the User Interface

Adding a Popup Menu to a Widget

pop-up menu

Several widgets, notably lists and text editors, provide a pop-up menu in
response to the <Operate> mouse button.
The underlying menu is typically a menu of commands, sending the
associated symbol as a message to the application model.
Online example: MenuCommandExample
1

In the Menu property of the widget, enter the name of the menu
creation resource method (fileMenu).

Create the menu creation resource method (fileMenu), and any action
methods named in the menu of commands.

Adding a Menu Bar or Pop-Up Menu of Values

Menu bars and pop-up menus can be used to set the value of a value
holder as the result of the command they execute. You can either create a
method for each message selector, defining it to set the value holder
value, or enter a complex message in the menu definition. The example
illustrates one way of doing the latter.
Online example: MenuValueExample
1

In the Menu property of the widget, enter the name of the method that
returns a menu of values (templatesMenuForPopUp).

Use a Menu Editor or System Browser to create the menu method

(templatesMenuForPopUp). In the menu, each item label is paired with a
block in which the widgets aspect variable (letter) is updated with the
desired value.
templatesMenuForPopUp

GUI Developers Guide

95

Chapter 5 - Menus

| mb |
mb := MenuBuilder new.
mb
add: 'First Notice' -> [self letter value: self class firstNotice];
add: 'Second Notice' -> [self letter value: self class
secondNotice];
add: 'Final Notice' -> [self letter value: self class finalNotice].
^mb menu

Accessing Menus Programmatically

It is useful to be able to access a menu or menu items in order to modify
the menu in some way. The most common use is to enable or disable
(gray out) menu items.
For a menu defined using the Menu Editor, you can access an item by its
ID property. For a menu defined either way, you can access an item by its
label.
Online examples: MenuCommandExample, MenuEditorExample
In the method that is to access the menu, do the following:
1

Get the menu by sending a menuAt: message to the builder, with the
name of the menus resource method as argument.

Get a menu item, either by:

label, by sending menuItemLabeled: to the menu with the label

string as the argument, or

name key (ID), by sending atNameKey: to the menu with the name
key as a symbol as the argument.

Get a submenu by sending a submenu message to the menu item that

is the submenu.

Get a submenu item by sending menuItemLabeled: or atNameKey: to the

submenu, as in step 2.

MenuCommandExample accesses menu items this way to disable and

enable menu items in its configureMenu method:

96

VisualWorks

Accessing Menus Programmatically

configureMenu
"Disable or enable the menu items depending on whether
a file is selected."
| menu submenu |
menu := self builder menuAt: #fileMenu.
submenu := (menu menuItemLabeled: 'File') submenu.
self files selection isNil
ifTrue: [
(submenu menuItemLabeled: 'Open') disable.
(submenu menuItemLabeled: 'Delete') disable]
ifFalse: [
(submenu menuItemLabeled: 'Open') enable.
(submenu menuItemLabeled: 'Delete') enable]
It is simple to create its interface using the Menu Editor and assign ID
properties to the File menu and its items. The equivalent configureMenu
method could then be written (assuming the ID properties are the same
as the labels):
configureMenu
"Disable or enable the menu items depending on whether
a file is selected."
| menu submenu |
menu := self builder menuAt: #fileMenu.
submenu := (menu atNameKey: #File) submenu.
self files selection isNil
ifTrue: [
(submenu atNameKey: #Open) disable.
(submenu atNameKey: #Delete) disable]
ifFalse: [
(submenu atNameKey: #Open) enable.
(submenu atNameKey: #Delete) enable]
As a variation on this theme, you can operate on a collection of menu
items. In MenuEditorExample, the disableDarkColors method gets the menus
collection of menu items by sending a menuItems message to the menu. It
then sends a nameKey message to each menu item to obtain its name key,
and disables each menu item whose name key is in the darkColors array.

GUI Developers Guide

97

Chapter 5 - Menus

Modifying a Menu Dynamically

Sometimes a menu needs to change depending on conditions within the

application. The most common change is to simply disable, or gray out
an option. More extreme, but also common, is to have different sets of
menu items available depending on the state of the application.
For example, in a document editing program, there might be only options
for opening documents and closing the application if no document is
open, but several menus with many editing options available when a
document is open.
The following sections describe several useful modifications.

Disabling a Menu Item

Applications frequently disable, or gray out, menu items when the
selection in inappropriate for the current state. This is typically done after
testing some condition in the application.
To disable a menu item, send a disable message to the menu item.
Similarly, to enable a menu item, send an enable message to it.
See MenuCommandExample and the example code in the previous section.

Hiding a Menu Item

Hiding a menu item is sometimes better than disabling it. A disabled item
may frustrate a user if it is not clear why it is disabled, while hiding it
removes the temptation to use it. This is an interface design decision.
Online example: MenuModifyExample

98

VisualWorks

Modifying a Menu Dynamically

Get the menu and menu item.

Refer to Accessing Menus Programmatically above. You may need
to get a submenu to get to the menu item.

To hide the item, send a hideItem: message to the menu, with the
menu item as the argument.

To reveal an item, send an unhideItem: message to the menu, with the

menu item as the argument.
adjustBenefitList
"Hide benefit items that are not available to the currently
selected job title."
| bMenu item |
bMenu := self builder menuAt: #benefitsMenu.
item := bMenu menuItemLabeled: 'Golden Parachute'.
"Only the President gets the Golden Parachute."
self jobTitle value == #President
ifTrue: [bMenu unhideItem: item]
ifFalse: [bMenu hideItem: item].

Adding an Item to a Menu

You can add a new menu item to the end of a menu.
Online example: MenuModifyExample
1

Get the menu by sending a menuAt: message to the application

models builder, with the menu creation resource method as
argument.

Send an addItemLabel:value: message to the menu. The first argument

is the label string and the second argument is a command, a value,
or an action block.
addTitle
"Prompt for a new job title and add it to the list."
| newTitle jMenu |
newTitle := Dialog request: 'New title?'.
newTitle isEmpty ifTrue: [^self].
jMenu := self builder menuAt: #jobTitlesMenu.
jMenu addItemLabel: newTitle value: newTitle asSymbol.
self jobTitle value: newTitle asSymbol.

GUI Developers Guide

99

Chapter 5 - Menus

Removing an Item from a Menu

Online example: MenuModifyExample
1

Get the menu and the menu item to be removed.

Refer to Accessing Menus Programmatically above. You may need
to get a submenu to get to the menu item.

Send a removeItem: message to the menu, with the menu item to

delete as the argument.

In the case of a menu button in which the current selection is

displayed (that is, a menu button whose Label property is blank),
make sure the buttons value holder has a valid value.
deleteTitle
"Prompt for a title and remove it from the list."
| jMenu removableTitles title item |
jMenu := self builder menuAt: #jobTitlesMenu.
"Don't permit the president to be overthrown."
removableTitles := jMenu labels
reject: [ :nextTitle | nextTitle = 'President'].
title := Dialog
choose: 'Delete Title'
fromList: removableTitles
values: removableTitles
lines: 8
cancel: [^nil]
for: ScheduledControllers activeController view.
item := jMenu menuItemLabeled: title.
jMenu removeItem: item.
"If the deleted title is showing, pick the first title."
self jobTitle value == title asSymbol
ifTrue: [self jobTitle value: #President].

Substituting a Different Menu

The MenuSwapExample swaps menus depending on the application state.
This is useful for large changes.
Online example: MenuSwapExample
1

100

In the Menu property of the widget, enter the name of a method that
returns a value holder containing a menu (menuHolder).
VisualWorks

Displaying an Icon in a Menu

In the application model, create an instance variable to hold the menu

in a value holder (menuHolder).

Create a method (menuHolder) that returns the value of the instance

variable.
menuHolder
^menuHolder

Create the starting menu (nothingSelectedMenu) and the alternate

menu (colorSelectedMenu).

In the initialize method, get the starting menu, put it in a value holder,
and assign the holder to the instance variable.
initialize
colors := SelectionInList with: ColorValue constantNames.
colors selectionIndexHolder onChangeSend: #selectionChanged to:
self.
menuHolder := self nothingSelectedMenu asValue.

Create a method (selectionChanged) that tests to see which menu

should be used and then puts the correct menu in the menu holder.
selectionChanged
self colors selection isNil
ifTrue: [self menuHolder value: self nothingSelectedMenu]
ifFalse: [self menuHolder value: self colorSelectedMenu]

Arrange for the menu-changing method to be invoked when the

relevant condition changes in the application. (In the example, the
onChangeSend:to: message in the initialize method accomplishes this.)

Displaying an Icon in a Menu

graphic labels

on/off indicator

Menu items can have a textual or graphical label.

GUI Developers Guide

101

Chapter 5 - Menus

Adding an Icon to a Menu

Online example: MenuValueExample
It is often useful to substitute a graphic label for a textual label or combine
the two.
Send a labelImage: message to the menu item. The argument is any visual
component, but typically it is a graphic image. The label string will be
displaced to the right to make room for the image. The label string must
have at least one character (even just a space).
templatesMenuForMenuBar
| mb menu submenu |
mb := MenuBuilder new.
mb
beginSubMenuLabeled: 'Templates';
add: ' ' -> [self letter value: self class firstNotice];
add: ' ' -> [self letter value: self class secondNotice];
add: ' ' -> [self letter value: self class finalNotice];
endSubMenu.
"Add graphic labels."
menu := mb menu.
submenu := (menu menuItemLabeled: 'Templates') submenu.
(submenu menuItemAt: 1)
labelImage: (self class oneImage).
(submenu menuItemAt: 2)
labelImage: (self class twoImage).
(submenu menuItemAt: 3)
labelImage: (self class threeImage).
"Set the background color."
submenu backgroundColor: ColorValue chartreuse.
^menu

Displaying an On/Off Indicator

Online example: MenuValueExample
This procedure prefixes a check mark or check box to the textual label as
a toggle indicator. This technique is frequently used with a menu item that
represents a setting to indicate whether the condition is on or off. You can
also use it to simulate a set of radio buttons in a menu, as
MenuValueExample does.

102

VisualWorks

Extending Tools Menus and Toolbars

To display an on indicator, send a beOn message to the menu item.

The indicator is a check mark in some looks and a box in others.

To display an off indicator, send a beOff message. In some looks,

beOff simply removes the on indicator; in others it displays a
different image.
setCheckMark
"In the pop-up menu, set the check box to indicate the currently
displayed template."
| menu item |
menu := self builder menuAt: #templatesMenuForPopUp.
item := menu menuItemAt: 1.
self letter value = self class firstNotice
ifTrue: [item beOn]
ifFalse: [item beOff].
item := menu menuItemAt: 2.
self letter value = self class secondNotice
ifTrue: [item beOn]
ifFalse: [item beOff].
item := menu menuItemAt: 3.
self letter value = self class finalNotice
ifTrue: [item beOn]
ifFalse: [item beOff].

Extending Tools Menus and Toolbars

VisualWorks tools are designed to allow you to easily extend their menus
and tool bars. This is done by adding methods that invoke a special menu
item definition pragma. This is useful especially for developers who are
enhancing the standard tool set, or adding new tools.
The menu pragma is a special syntactical element that can be placed a in
method definition:
< pragmaName: ...
>
where ... is a series of menu property specifications. The set of pragmas
is defined in Menu class method pragmas. Browse senders of these
pragmas for the full set of examples.

GUI Developers Guide

103

Chapter 5 - Menus

Within VisualWorks, extending menus is done by a variety of system

parcels. For example, the UIPainter parcel adds menus and tool buttons
to the Visual Launcher when it is loaded. Using the system browser to
browse the #actions category in the VisualLauncher class, you will find
methods like:
browseApplications
"Open a new UIFinder."
<menuItem: '&Resources'
icon: #finderIcon
nameKey: nil
menu: #(#menuBar browse)
position: 10.01>
<menuItem: 'Browse Applications'
icon: #finderIcon
nameKey: nil
menu: #(#launcherToolBar)
position: 20.02>
self openApplicationForClassNamed: #UIFinderVW2
The first pragma adds the Resources action to the Browse menu (#menuBar
browse) on the Launcher's menu bar. The second pragma adds the finder
button to the Launcher's tool bar (#launcherToolBar). Both assign the
named icon, but neither assigns a nameKey, which would be used to
access the item programmatically.
Following any menu item pragma label, the pragma specifies the actions
to be performed when the item is selected, as a normal Smalltalk
expression.
See senders of Menu>>#augmentFrom:to: and Menu>>#augmentFrom:to:for:
to see how the menus are extended.

Setting the Menu Item Position

The position: argument specifies the location of the menu or toobar item
as a floating-point constant that sets the ordering and grouping of items.
Menu items are originally numbered, so the first group is numbered 10
and successor groups increment by 10. Similarly, the first item in a group
is at position .01, and the count ascends by 0.01. So a menu with two
groups of three items each has its items numbered 10.01, 10.02, 10.03,
20.01, 20.02, 20.03.
To define a new group, assign a new integer part. For example, using 15
would insert a new group between the two existing groups.

104

VisualWorks

Extending Tools Menus and Toolbars

To insert a new item between existing items, use a fractional part. For
example, using 10.025 would insert a new menu item between the
existing second and third items. Using 10.04 would append an item to the
group.

Adding Items to the Launcher

As illustrated above, methods for adding menu and toolbar items to the
VisualLauncher are added to the VisualLauncher class, in the actions
protocol. The launcher updates its button displays immediately and
automatically.
For adding a menu item, specify that the change is in the menu bar, and
which submenu the addition goes in, in an array:
menu: #(#menuBar browse)
Here, #menuBar specifies the method name that defines the menu bar,
and browse is the name key of the Browse menu. Examine menuBar
method for other name keys.
For adding a tool bar button, specify the class method that returns the
appropriate icon. This may be an image resource method, but may be an
intermediate method. For example, the Resource Finder method tests for
the color depth, and returns the resource method for the appropriate icon:
finderIcon
^Screen default colorDepth == 1
ifTrue: [self BWAppFinder24]
ifFalse: [self CGAppFinder24]

Adding Items to a Browser

A similar approach is used for extending the menu bar operations and
<Operate> menus corresponding to specific panes in browsers. For each
pane in the browsers, there is a subclass of BrowserHelper, in which you
can make any required additions. For example, the ClassesBrowserHelper
class defines various features of a classes pane.
By simply adding a method specifying a menu pragma (in the actions
protocol), you can add an item to the menu bar menu and to the
<Operate> menu for the pane controlled by that help class. For example,
add this method to ClassesBrowserHelper, and test the change to a new
instance of a browser with a classes pane:

GUI Developers Guide

105

Chapter 5 - Menus

myMenuItem
<menuItem: My new action
nameKey: nil
menu: #(#listMenu)
position 40.1>
Since no icons are involved, this shorter version of the menu item pragma
can be used.

Menu and Toolbar Events

Unlike other triggered events sent by the system, the menu and tool bar
events are the only ones that pass along arguments. In all cases, the
argument is the ID (also known as the menuKey) of the menu, toolbar
button or menu item. If there is no ID for the menu, toolbar button or
menu item then nil is sent.
#menuOpened:
When a main menu item is opened because of navigation by the
keyboard or the mouse, the menu bar triggers the #menuOpened:
event. The ID (menuKey) of the menu is sent as a parameter of this
event if it is defined. If no ID (menuKey) is defined, then nil is sent as
the parameter.
#menuClosed:
When a main menu item is closed because of navigation by the
keyboard or the mouse, or a menu item being selected, the menu bar
triggers the #menuOpened: event. The ID (menuKey) of the menu is
sent as a parameter of this event if it is defined. If no ID (menuKey) is
defined, then nil is sent as the parameter.
#menuItemSelected:
When any menu item is selected, without regard to if the menu item
is on a main menu or a sub-menu off of one of the main menus, the
menu bar triggers the #menuItemSelected: event. If the menu item has
no action associated with it, then this event is not triggered. The ID
(menuKey) of the menu item is sent as a parameter of this event if it is
defined. If no ID (menuKey) is defined, then nil is sent as the
parameter.
#submenuOpened:
When a menu item has a sub-menu, and that sub-menu is opened
because of navigation by the keyboard or mouse, the menu bar
triggers the #submenuOpened: event. The ID (menuKey) of the menu is
sent as a parameter of this event if it is defined. If no ID (menuKey) is
defined, then nil is sent as the parameter.

106

VisualWorks

Menu and Toolbar Events

#submenuClosed:
When a menu item has a sub-menu, and that sub-menu is closed
because of navigation by the keyboard or mouse, or a sub-menu item
being selected, the menu bar triggers the #submenuOpened: event.
The ID (menuKey) of the menu is sent as a parameter of this event if it
is defined. If no ID (menuKey) is defined, then nil is sent as the
parameter.

Popup Menu Events

Individual widgets are allowed to have local popup / operate menus.
These events are triggered by the underlying widget when one of those
popup menus is created, and if one of the menu items is selected.
#popupMenuCreated
When a widget creates a popup (<Operate>) menu, the widget
triggers the #popupMenuCreated event.
#popupMenuItemSelected:
When a menu item on a popup menu is selected, the widget triggers
the #popupMenuItemSelected: event. If the menu item has no action
associated with it, then this event is not triggered. The ID (menuKey)
of the menu item is sent as a parameter of this event if it is defined. If
no ID (menuKey) is defined, then nil is sent as the parameter.

Toolbar Events
Toolbars have a simple event interface, that only triggers when one of the
tool bar buttons is pressed.
#toolBarButtonSelected:
When a toolbar button is pressed, the tool bar triggers the
#toolBarButtonSelected: event. If the toolbar button has no action
associated with it, then this event is not triggered. The ID (menuKey)
of the toolbar button is sent as a parameter of this event if it is
defined. If no ID (menuKey) is defined, then nil is sent as the
parameter.

GUI Developers Guide

107

6
Drag and Drop

About Drag and Drop

aDropSource

aDragDropManager

aDragDropData

aConfigurableDropTarget
aDragDropContext

Drag and drop technology allows a user to select an object using the
mouse pointer, drag that object to another location on the screen, and
drop it. This is useful, for instance, for moving or copying items from one
list to another. This operation is common in some environments for
moving files (items) from one directory (a list) to another.
In VisualWorks, you implement drag and drop by setting one or more
widgets as drop sources and others as drop targets. Currently, only list
widgets can be a drop source, while a drop target can be any widget
except a linked or embedded dataform. Drop sources and drop targets
may be in the same interface, or they may be in the interfaces of different
applications.
You set up drop sources and drop targets by specifying various message
names in their properties, and then programming the relevant application
model(s) to respond to these messages.

108

VisualWorks

About Drag and Drop

Drag and Drop Framework Classes

In a running application, a drag-and-drop interaction is carried out by
instances of several framework classes. Some of these instances are
created as a result of the code you write, while others are created
automatically when the interface is built or when drag and drop is
underway. Each drag-and-drop interaction involves an instance of these
classes:
DragDropData
Holds the data to be transferred, plus information about where the
drag originated (the widgets controller, containing window, and
application model).
DropSource
Defines the shapes that the pointer can have during a drag, based on
the drop source. The default pointer shapes indicates whether a
move, a copy, or no transfer would take place.
DragDropManager
Tracks the mouse pointer throughout the drag, and is responsible for
setting the pointers shape based on location. When a drop occurs in
a drop target, the DragDropManager sends a message to process the
transferred data.
ConfigurableDropTarget
Instances identify the widgets that are potential drop targets.
DragDropContext
Combines the DragDropData, the DropSource, and the
ConfigurableDropTarget in a convenient object for passing as an
argument in various messages.

GUI Developers Guide

109

Chapter 6 - Drag and Drop

Adding a Drop Source

drop source

drop data

"no-drop" pointer

A drop source is a widget from which a drag can originate, and holding
the data to be transferred. Currently, only the List and Table widgets can
serve as a drop source.
You enable a list as a drop source by providing values for the Drag OK and
Drag Start properties on the Drop Source page of the Properties Tool. These
properties specify the messages that the widget sends when the user
starts a drag operation, by pressing a mouse button and moving the
mouse.
You program the widgets application model to respond to these
messages as follows:

The drag-ok method must return a Boolean to indicate whether drag

and drop is appropriate from this drop source.

The drag-start method creates DragDropData, DropSource, and

DragDropManager instances.

Online example: ColorDDExample

1

110

Add a list widget to the canvas, set its Aspect and ID properties, install
the canvas and define its aspect instance variable and accessor
method, and initialize the SelectionInList, as usual for a list (refer to
Lists in Chapter 9, Configuring Widgets).

VisualWorks

Adding a Drop Source

In the lists Drag OK property, enter the name of the method that will
determine whether a drag can proceed from this list
(colorWantToDrag:).
The selector must end with a colon, because the widget sends this
message with its controller as argument. This is true even if the
controller isnt used.

In the lists Drag Start property, enter the name of the method that will
initiate drag and drop (colorDrag:)
This selector must also end with a colon, for the same reason.

Leave the Select On Down property selected.

This causes a selection to occur when the mouse is pressed down to
start the drag, which is the normal drag and drop behavior, rather
than waiting for the mouse to be released. Apply the properties and
install the canvas.

Create the drag-ok method (colorWantToDrag:).

This method must return a Boolean (true to permit drag and drop,
false to prevent it), and must accept a Controller as its argument, even
if that controller isnt used.
colorWantToDrag: aController
"Determine whether to permit a drag to start from this widget. In
this case, make sure that there is data to drag and that the drag
starts a selection."
^self color list size > 0 and: [self color selection notNil]

Create the drag-start method (colorDrag:) in the drag source protocol.

This method also must accept a Controller as its argument. In the
method:

GUI Developers Guide

Create a DragDropData instance.

Ssend a key: message to the DragDropData instance to specify a

symbol (#colorChoice) that identifies the kind of data being stored.
(A drop target can use this key to filter out inappropriate kinds of
data).

Ssend messages to the DragDropData instance to specify any

further information that a drop target might use when evaluating
this drag. Typically, you send a contextWindow: message
specifying the containing window, a contextWidget: message
specifying the list widget, and a contextApplication: message

111

Chapter 6 - Drag and Drop

specifying the application model.

Send a clientData: message to the DragDropData instance to store

the object to be transferred (in the example, the color that is
currently selected). Notice that the color choice is stored in an
IdentityDictionary, which is a general technique for storing multiple
related pieces of data.

Create an instance of DropSource to make predefined kinds of

visual feedback available during the drag.

Create an instance of DragDropManager and initialize it with the

DropSource and DragDropData instances.

Send a doDragDrop message to the DragDropManager to start the

drag and drop.
colorDrag: aController
"Drag the currently selected color. Provide all available
information about the context of the color so that the drop
target can use whatever it needs."
| ds dm data |
data := DragDropData new.
data key: #colorChoice.
data contextWindow: self builder window.
data contextWidget: aController view.
data contextApplication: self.
data clientData: IdentityDictionary new.
data clientData at: #colorChoice put: self color selection.
ds := DropSource new.
dm := DragDropManager
withDropSource: ds
withData: data.
dm doDragDrop

Note that when the drag and drop completes, the doDragDrop message
returns a symbol which can be stored in a temporary variable and then
used to trigger further actions (such as cutting the dragged data out of
the drop source list). This symbol is ignored in the colorDrag: method.

Dragging Multiple Selections

A multiple-selection list can be the source of several drag options. You set
up a multiple-selection list the same way as a single-selection list, except
that:

112

VisualWorks

Adding a Drop Target

In the Properties Tool for the List widget, click the lists Multi Select
property.

Initialize the lists aspect variable with a MultiSelectionInList instead of

a SelectionInList.

Send the selections message (instead of selection) to obtain the

selected data to store in the DragDropData instance.
The selections message returns an ordered collection of objects.

Adding a Drop Target

A drop target is a widget in which data can potentially be dropped. You
can set up any window or widget as a drop target except a linked or
embedded dataform.
In general, you set up a drop target by filling in one or more of its
properties on the Drop Target page of the Properties Tool, and then
implementing corresponding methods in the application model. Each of a
widgets DropTarget properties specifies the name of a message that the
DragDropManager sends at various points after the drag encounters this
widget.
At a minimum, you must fill in the widgets Drop property to specify the
name of a method that implements the desired response when a drop
occurs in that widget. Filling in the Drop property causes the builder to set
up the widget with a ConfigurableDropTarget instance so that the
DragDropManager can recognize the widget as a drop target.
In addition, you normally fill in the widgets Entry, Over, and Exit properties
to specify the names of methods that provide visual feedback when the
pointer is dragged across the widget. Typically, these methods specify the
pointers shape and adjust the drop targets appearance to signal whether
the drop target can accept a drop from this particular drag. Strictly
speaking, these properties are optional, in that drag and drop can
function without them. However, providing visual feedback is normally
required by user interface design guidelines.

GUI Developers Guide

113

Chapter 6 - Drag and Drop

Providing Visual Feedback During a Drag

As part of adding a drop target, you normally arrange for visual feedback
to be given to users when they drag the pointer over it. The purpose of
this feedback is to let users know whether a drop can be accepted from
this particular drag, and, if so, what kind of transfer may result. Visual
feedback typically includes changing the pointers shape and adjusting
the drop targets appearancefor example, by highlighting a button,
changing a label, or scrolling a list to track the pointers movement over it.

Drop Target Messages

You arrange for visual feedback by filling in the drop targets Entry, Over,
and Exit properties with the names of messages to be sent by the
DragDropManager at various points during a drag. You then implement
methods in the application model to respond to these messages:

The entry message is sent as soon as the pointer enters the widgets
bounds. The method typically saves the drop targets visual state for
restoring later, and/or toggles simple visual characteristics such as
highlighting.

The over message is sent immediately after the entry message, and
then every time the pointer moves within the widgets bounds. The
method typically adjusts the drop targets appearance in response to
pointer location or a modifier key press.

The exit message is sent wherever the pointer is dragged out of the
widgets bounds before the mouse button is released. The method
typically restores the widgets original appearance.

Each method has access to the dragged data through the

DragDropContext instance that is passed to it by the DragDropManager. The
methods query the DragDropContext to decide what kind of visual feedback
to provide. Furthermore, these methods use the DragDropContext to save
and restore drop target characteristics.
Note that no changes are made to a drop targets appearance unless you
implement them in these methods. Programmatic techniques for
changing widget appearance are described in Chapter 9, Configuring
Widgets.

114

VisualWorks

Providing Visual Feedback During a Drag

Pointer Shapes
Each of the entry, over, and exit methods control the pointer shape by
returning an effect symbol. The DragDropManager passes each effect
symbol to the operations DropSource instance, which sets the pointer
shape accordingly. A standard DropSource recognizes these basic effect
symbols:
#dropEffectNone
Produces a pointer shaped like a circle with a slash through it; usually
indicates that no transfer is possible in the pointers current location.
#dropEffectMove
Produces an arrow-shaped pointer with an open box below it; usually
indicates a simple transfer such as a move (data is cut from the
source after the transfer).
#dropEffectCopy
Produces the same pointer as #dropEffectMove, but with a plus sign;
usually indicates a modified transfer such as a copy (data is left in the
source after the transfer).

Changing Color During a Drag

Online example: ColorDDExample
This example highlights the Apply Color button and changes the pointers
shape while the pointer is in the button.

GUI Developers Guide

In the canvas, select the Apply Color button, and set its ID property (in
this case, enter #applyColorButton).

On the Drop Target page of a Properties Tool, fill in the widgets Entry,
Over, and Exit properties with the names of the messages to be sent
during the drag (applyColorEnter:, applyColorOver:, and applyColorExit:,
respectively). Each selector must end with a colon. Apply the
properties and install the canvas.

In a System Browser, add an entry method (applyColorEnter:) in an

appropriate protocol (in this case, drop target - button1). The method
must accept a DragDropContext instance as an argument.

In the entry method, test the dragged data to determine what kind of
feedback to provide (positive feedback if the data is a color choice,
and negative feedback otherwise). Send a key message to the
DragDropContext instance to obtain the identifying symbol that was
assigned when the drag started. If the datas key is not #colorChoice,
return an effect symbol (#dropEffectNone) to signal that a drop is not
allowed.
115

Chapter 6 - Drag and Drop

If the dragged data is acceptable, highlight the button as if it were

pressed and return an effect symbol (#dropEffectMove) that signals
permission to drop.
applyColorEnter: aDragContext
"A drag has entered the bounds of the Apply Color button. Test whether a drop
would be permitted here with this data. If so, cause the button to be
highlighted as if it were pressed, and return a symbol that indicates the
feedback to be given to the user."
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
(self widgetAt: #applyColorButton)
isInTransition: true.
^#dropEffectMove.

Add an over method (applyColorOver:) that accepts a DragDropContext

instance as an argument.

In the over method, test the dragged data and return the appropriate
effect symbols. No other processing is necessary in this method
because the buttons highlighting does not vary with the pointers
movement.
applyColorOver: aDragContext
"A drag is over the Apply Color button. Test whether a drop would be
permitted here with this data. If so, return a symbol that indicates the
feedback to be given to the user. The DragDropManager uses this symbol
to determine the pointer shape."
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
^#dropEffectMove

Add an exit method (applyColorExit:) that accepts a DragDropContext

instance as an argument.

In the exit method, test the dragged data and return #dropEffectNone if
the dragged data is not a color choice.

10 If the dragged data is acceptable, reverse any visual effect that was
set in the entry method (in this case, unhighlight the button).
11 Return #dropEffectNone, to signal that no drop has occurred (this
method executes only if the pointer leaves the widget without
dropping).

116

VisualWorks

Providing Visual Feedback During a Drag

applyColorExit: aDragContext
"A drag has exited the Apply Color button without dropping. Test whether a
drop would have been permitted here with this data. If so, restore the
button to its former state, and return a symbol that indicates the feedback
to be given to the user."
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
(self widgetAt: #applyColorButton)
isInTransition: false.
^#dropEffectNone

Changing a Button Label During a Drag

Online example: ColorDDExample
This example saves and changes the label of the Apply More Color button
when the pointer enters the button, restoring the original label when the
pointer exits.
1

In the canvas, select the Apply More Color button, and set its ID property
(in this case, enter #applyMoreColorButton).

On the Drop Target page of a Properties Tool, set the widgets Entry,
Over, and Exit properties (enter applyMoreColorEnter:, applyMoreColorOver:,
and applyMoreColorExit:).

In an entry method (applyMoreColorEnter:), create an IdentityDictionary

in which to save the drop targets original state.

Save any button characteristics in the IdentityDictionary that are to be

restored later. In this case, store the widget and its label. (Storing the
widget is a stylistic option that enables the widget to be accessed
later through the DragDropContext rather than through the builder.)

Get the widgets ConfigurableDropTarget instance from the

DragDropContext, and set the IdentityDictionary as its client data.

Change the buttons label by sending the labelString: message to the

button. The message argument is the string to be displayed. Note
that a different string is specified depending on the state of the shift
key.
applyMoreColorEnter: aDragContext
"A drag has entered the bounds of the Apply More Color button. Test whether
a drop would be permitted here with this data. If so, store the current label
of the button. Then test whether the shift key is down. Based on this test,

GUI Developers Guide

117

Chapter 6 - Drag and Drop

change the button's label and return a symbol that indicates the feedback to
be given to the user."
| widget dict |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
widget := self widgetAt: #applyMoreColorButton .
dict := IdentityDictionary new.
dict at: #widget put: widget.
dict at: #label put: widget label.
aDragContext dropTarget clientData: dict.
aDragContext shiftDown
ifTrue:
[widget labelString: 'Background'.
^#dropEffectCopy].
widget labelString: 'Foreground'.
^#dropEffectMove.
7

In an exit method (applyMoreColorExit:), get the drop targets

IdentityDictionary from the DragDropContext.

Retrieve the button from the IdentityDictionary. (Alternatively, you could

obtain the button from the builder.)

Retrieve the original label from the IdentityDictionary and put it back on
the button. (Note that argument of the label: message is a label
object, not a string.)

10 Remove the drop target data from the DragDropContext. This prepares
the DragDropContext for the next drop target the pointer may
encounter.
applyMoreColorExit: aDragContext
"A drag has exited the Apply More Color button without dropping. Test
whether a drop would have been permitted here with this data. If so, restore
the button to its former state, and return a symbol that indicates the

118

VisualWorks

Providing Visual Feedback During a Drag

feedback to be given to the user."

| dict widget |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
dict := aDragContext dropTarget clientData.
widget := dict at: #widget.
widget label: (dict at: #label).
aDragContext dropTarget clientData: nil.
^#dropEffectNone.

Tracking a Targeted List Item

Online example: ColorDDExample
This example provides visual feedback for a list in which a drop is
intended for a particular item rather than the list as a whole. The steps
cause the pointers location to be indicated by target emphasis, a
rectangular border around the item containing the pointer. The target
emphasis tracks the pointer, scrolling if necessary. (Target emphasis is
also used in keyboard traversal of lists to indicate the target for selection.)
1

In the canvas, select the list of color layers and set its ID property (in
this case, enter #colorLayerList).

On the Drop Target page of a Properties Tool, set the widgets Entry,
Over, and Exit properties (enter colorLayerEnter:, colorLayerOver:, and
colorLayerExit:).

In an entry method (colorLayerEnter:), create an IdentityDictionary in

which to save the drop targets original state.

Save any characteristics into the IdentityDictionary that are to be

restored later. In this case, store the widget, the location of any target
emphasis resulting from keyboard traversal, and a Boolean indicating
whether the list has focus.

Get the widgets ConfigurableDropTarget instance from the

DragDropContext. Store the IdentityDictionary as its client data.

Give focus to the list to prepare it for tracking the pointer with target
emphasis.
colorLayerEnter: aDragContext
"A drag has entered the bounds of the list of color layers. Test whether a drop
would be permitted here with this data. If so, save the initial state of the
color layer list, give focus to the list, and return a symbol that indicates the

GUI Developers Guide

119

Chapter 6 - Drag and Drop

feedback to be given to the user."

| dict widget |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
widget := self widgetAt: #colorLayerList .
dict := IdentityDictionary new.
dict at: #widget put: widget.
dict at: #targetIndex put: widget targetIndex.
dict at: #hasFocus put: widget hasFocus.
aDragContext dropTarget clientData: dict.
widget hasFocus: true.
^#dropEffectMove
7

In an over method (colorLayerOver:), retrieve the list widget from the

DragDropContext.

Send the showDropFeedbackIn:allowScrolling: message to the list to

display target emphasis at the pointers current position, scrolling if
necessary. (Remember, this message gets sent each time the pointer
moves in the list).
colorLayerOver: aDragContext
"A drag is over the list of color layers. Test whether a drop would be permitted
here with this data. If so, tell the list to scroll the target emphasis when the
pointer moves. Return a symbol that indicates the feedback to be given to
the user. The DragDropManager uses this symbol to determine the pointer
shape."
| list |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
list := aDragContext dropTarget clientData at: #widget.
list
showDropFeedbackIn: aDragContext
allowScrolling: true.
^#dropEffectMove

In an exit method (colorLayerExit:), get the drop targets

IdentityDictionary from the DragDropContext and retrieve the list widget.

10 Restore the lists original target emphasis and focus state.

120

VisualWorks

Responding to a Drop

11 Remove the drop target data from the DragDropContext. This prepares
the DragDropContext for the next drop target the pointer may
encounter.
colorLayerExit: aDragContext
"A drag has exited the list of color layers without dropping. Test whether a
drop would have been permitted here with this data. If so, restore the initial
state of the color layer list, and return a symbol that indicates the feedback
to be given to the user."
| dict widget |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
dict := aDragContext dropTarget clientData.
widget := dict at: #widget.
widget targetIndex: (dict at: #targetIndex).
widget hasFocus: (dict at: #hasFocus).
aDragContext dropTarget clientData: nil.
^#dropEffectNone

Responding to a Drop

Dropping a color
here . . .

. . . changes the
background color
of the demonstration widgets

A central part of creating a drop target is to implement the action to be

taken whenever a drop occurs in it. A typical action is to verify that the
dragged data is acceptable to this drop target, and then process that data
accordingly. You arrange for this by filling in the widgets Drop property on

GUI Developers Guide

121

Chapter 6 - Drag and Drop

the Drop Target page of the Property Tool. This property specifies the name
of the message that the DragDropManager will send when a drop occurs in
the widget. You then create a corresponding method in the application
model to implement the response.
Like the entry, over, and exit methods, a drop method receives a
DragDropContext instance as an argument from the DragDropManager. The
method can examine this instance to determine whether to accept the
dragged data and, if so, how to process it.
A typical drop method adjusts the appearance of the drop target widget to
reverse any visual feedback caused by the enter or over method or to
provide visual evidence of the completed drop. The drop method may
also need to clean up any drop target data that was created by the entry
method.
A drop method returns an effect symbol for the DragDropManager to return
to the drag-start method that initiated the drag.
The example sets up the Apply Color button in ColorDDExample so that
dropping a color on this button applies that color to the foreground layer
of the demonstration widgets.

Adding a Drop Response

Online example: ColorDDExample

122

In the canvas, select the widget you want to use as a drop target. In
this case, select the Apply Color button.

On the Drop Target page of a Properties Tool, set the widgets Drop
property (applyColorDrop:). The selector must end with a colon. Apply
properties and install the canvas.

In a System Browser, add a drop method (applyColorDrop:) in an

appropriate protocol (in this case, drop target - button 1). The method
must accept a DragDropContext instance as an argument.

In the drop method, determine whether the dragged data should be

accepted for processing (that is, whether it is a color choice). To do
this, send a key message to the DragDropContext instance to obtain the
identifying symbol that was assigned when the drag started. If the key
is not #colorChoice, return an effect symbol (#dropEffectNone) to signal
that no drop is allowed.

If the dragged data is acceptable, perform the processing that is to

result from the drop. In this example, send a sourceData message to
the DragDropContext to obtain the DragDropData; then send this object a

VisualWorks

Responding to a Drop

clientData message to obtain the selected color. Turn the selected

color into a color value and set it as the foreground color of the
demonstration widgets.
6

Restore the widgets original appearance (turn off the highlighting

that was turned on by the applyColorEnter: method).

Return an effect symbol indicating the result of the drop. This symbol
is passed to the drag-start method (colorDrag:), where it can be used
to trigger further actions at the drop source.
applyColorDrop: aDragContext
"A drop has occurred in the Apply Color button. If the drop is permitted, set
the foreground color of the demonstration widgets to be the dragged color
choice. Restore the button to its former visual state and return an effect
symbol for possible use in the colorDrag method."
| dict aColor |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
dict := aDragContext sourceData clientData.
aColor := ColorValue perform: (dict at: #colorChoice).
(self widgetAt: #applyColorButton)
isInTransition: false.
self foregroundColor: aColor.
^#dropEffectMove.

Adding Target Emphasis

Dropping data on a particular list item requires that you enable target
emphasis in the list through the entry and over methods. Target emphasis
tracks the location of the pointer, displaying a rectangular border around
the currently targeted list item.
Online example: ColorDDExample
1

In the canvas, select the list of color layers and set its ID property (in
this case, enter #colorLayerList).

On the Drop Target page of a Properties Tool, set the widgets Entry, Over
and Drop properties (colorLayerEnter:, colorLayerOver:, and
colorLayerDrop:).

In an entry method (colorLayerEnter:), give focus to the list to prepare it

for displaying target emphasis.
colorLayerEnter: aDragContext
"A drag has entered the bounds of the list of color layers. Test whether a drop
would be permitted here with this data. If so, save the initial state of the
color layer list, give focus to the list, and return a symbol that indicates the

GUI Developers Guide

123

Chapter 6 - Drag and Drop

feedback to be given to the user."

| dict widget |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
widget := self widgetAt: #colorLayerList .
dict := IdentityDictionary new.
dict at: #widget put: widget.
dict at: #targetIndex put: widget targetIndex.
dict at: #hasFocus put: widget hasFocus.
aDragContext dropTarget clientData: dict.
widget hasFocus: true.
^#dropEffectMove
4

In an over method (colorLayerOver:), retrieve the list widget from the

DragDropContext and send it the showDropFeedbackIn:allowScrolling:
message to display target emphasis at the pointers current position.
colorLayerOver: aDragContext
"A drag is over the list of color layers. Test whether a drop would be permitted
here with this data. If so, tell the list to scroll the target emphasis when the
pointer moves. Return a symbol that indicates the feedback to be given to
the user. The DragDropManager uses this symbol to determine the pointer
shape."
| list |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
list := aDragContext dropTarget clientData at: #widget.
list
showDropFeedbackIn: aDragContext
allowScrolling: true.
^#dropEffectMove

124

In a drop method (colorLayerDrop:), test whether the dragged data is a

color choice; if so, obtain the selected color from the dragged data
and turn it into a color value.

Send a targetIndex message to the list to get the index of the targeted
list item (the item containing the pointer when the drop occurs).

Get the color layer that is shown in the list at the targeted index.

Give visual feedback to indicate a successful drop. In this case,

cause the targeted list item to appear selected (set the lists selection

VisualWorks

Responding to a Drop

index to be the targeted index). Alternatively, you could restore the list
to its original visual state, as is done in the colorLayerExit: method.
9

Use the targeted color layer to choose the appropriate message for
changing the color of the demonstration widgets.
colorLayerDrop: aDragContext
"A drop has occur in the list of color layers. If the drop is permitted, combine
the dragged color choice and the targeted color layer to change the color of
the appropriate parts of the demonstration widgets. Return an effect
symbol for possible use in the colorDrag method."
| dict aColor widget idx aLayer |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
dict := aDragContext sourceData clientData.
aColor := ColorValue perform: (dict at: #colorChoice).
widget := aDragContext dropTarget clientData at: #widget.
idx := widget targetIndex.
idx = 0 ifTrue: [^#dropEffectNone].
aLayer := self colorLayer listHolder value at: idx.
self colorLayer selectionIndexHolder value: idx.
aDragContext dropTarget clientData: nil.
aLayer = 'Foreground'
ifTrue: [self foregroundColor: aColor].
aLayer = 'Background'
ifTrue: [self backgroundColor: aColor].
aLayer = 'Selection Foreground'
ifTrue: [self selectionForegroundColor: aColor].
aLayer = 'Selection Background'
ifTrue: [self selectionBackgroundColor: aColor].
^#dropEffectMove.

GUI Developers Guide

125

Chapter 6 - Drag and Drop

Examining the Drag Context

Drop target methods can examine a variety of information by querying the
DragDropContext instance that is passed to them by the DragDropManager.
Among other things, the DragDropContext instance contains the
DragDropData you created in the Drag Start method, plus the current pointer
location and modifier key states. This information can be useful for
determining the appropriate drop response.
In a drop target method, obtain information about the drag from the
DragDropContext instance that is passed to the method (assume the
argument name is aDragContext).
"Get the key that was assigned to the dragged data."
aDragContext key.
"Get the application model from which the drag originated."
aDragContext sourceData contextApplication.
"Get the window from which the drag originated."
aDragContext sourceData contextWindow.
"Get the current pointer location."
aDragContext mousePoint.

Responding to Modifier Keys

You can make drag and drop sensitive to the state of the <Control>,
<Shift>, <Alt>, and <Meta> modifier keys. For example, in many
applications, a user can move a file by dragging it and copy a file by
<Shift>-dragging it.
Making drag and drop sensitive to modifier keys involves:

Providing the appropriate visual feedback in the drop targets entry,

over, and exit methods.

Providing appropriate processing in the drop targets drop method.

The example sets up the Apply More Color button in ColorDDExample so that
dragging changes the foreground color of the demonstration widgets,
while <Shift>-dragging changes the background color.

126

VisualWorks

Responding to Modifier Keys

Responding to a Modified Drag

Online example: ColorDDExample
1

In the canvas, select the list of color layers and set its ID property (in
this case, enter #applyMoreColorButton).

On the Drop Target page of a Properties Tool, set the widgets Entry,
Over, Exit and Drop properties (applyMoreColorEnter:, applyMoreColorOver:,
applyMoreColorExit:, and applyMoreColorDrop:). Apply properties and
install the canvas.

In an entry method (applyMoreColorEnter:), send a shiftDown message

to the DragDropContext instance to find out whether the user is
pressing the <Shift> key down.

If the <Shift> key is down, provide appropriate visual feedback. In this

case, change the buttons label to indicate that background colors will
be set, and return an effect symbol (#dropEffectCopy) to signal a
modified transfer.

If the <Shift> key is not down, change the buttons label to indicate
that foreground colors will be set, and return an effect symbol
(#dropEffectMove) to signal a regular transfer.
applyMoreColorEnter: aDragContext
"A drag has entered the bounds of the Apply More Color button. Test whether
a drop would be permitted here with this data. If so, store the current label
of the button. Then test whether the shift key is down. Based on this test,
change the button's label and return a symbol that indicates the feedback to
be given to the user."
| widget dict |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
widget := self widgetAt: #applyMoreColorButton .
dict := IdentityDictionary new.
dict at: #widget put: widget.
dict at: #label put: widget label.
aDragContext dropTarget clientData: dict.
aDragContext shiftDown
ifTrue:
[widget labelString: 'Background'.
^#dropEffectCopy].
widget labelString: 'Foreground'.
^#dropEffectMove.

GUI Developers Guide

127

Chapter 6 - Drag and Drop

In an over method (applyMoreColorOver:), find out whether the user

has changed the <Shift> key state while dragging the pointer within
the widget. (Remember, this method executes each time the pointer
moves in the widget.) If the <Shift> key is down, test whether the
buttons label needs to change; if so, change it. Return the
#dropEffectCopy symbol.

If the <Shift> key is not down, test whether the buttons label needs to
change; if so, change it. Return the #dropEffectMove symbol.
applyMoreColorOver: aDragContext
"A drag is over the Apply More Color button. Test whether a drop would be
permitted here with this data. If so, test whether the shift key is down.
Based on this test, return a symbol that indicates the feedback to be given
to the user. The DragDropManager uses this symbol to determine the
pointer shape."
| widget |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
widget := aDragContext dropTarget clientData at: #widget.
aDragContext shiftDown
ifTrue:
[widget label text string = 'Background'
ifFalse: [widget labelString: 'Background'].
^#dropEffectCopy].
widget label text string = 'Foreground
ifFalse: [widget labelString: 'Foreground'].
^#dropEffectMove.

In an exit method (applyMoreColorExit:), restore the buttons original

label. In this example, the same label is restored, regardless of the
<Shift> keys state.
applyMoreColorExit: aDragContext
"A drag has exited the Apply More Color button without dropping. Test
whether a drop would have been permitted here with this data. If so, restore
the button to its former state, and return a symbol that indicates the

128

VisualWorks

Responding to Modifier Keys

feedback to be given to the user."

| dict widget |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
dict := aDragContext dropTarget clientData.
widget := dict at: #widget.
widget label: (dict at: #label).
aDragContext dropTarget clientData: nil.
^#dropEffectNone.
9

In a drop method (applyMoreColorDrop:), test whether the <Shift> key

is down.

10 If the <Shift> key is down, apply the dragged color choice to the
background color layer of the demonstration widgets. Return
#dropEffectCopy to signal a modified transfer.
11 If the <Shift> key is not down, apply the dragged color choice to the
foreground color layer. Return #dropEffectMove to signal a regular
transfer. Note that a drag-start method could respond differently
depending on which symbol is returned.
applyMoreColorDrop: aDragContext
"A drop has occured in the Apply More Color button. If the drop is permitted,
obtain the dragged color. Then test whether the shift key is down. If so, set
the background color of the demonstration widgets. If not, set their
foreground color. Restore the button to its former visual state and return an

GUI Developers Guide

129

Chapter 6 - Drag and Drop

effect symbol for possible use in the colorDrag method."

| dict widget aColor |
aDragContext key == #colorChoice
ifFalse: [^#dropEffectNone].
dict := aDragContext sourceData clientData.
aColor := ColorValue perform: (dict at: #colorChoice).
dict := aDragContext dropTarget clientData.
widget := dict at: #widget.
widget label: (dict at: #label).
aDragContext dropTarget clientData: nil.
aDragContext shiftDown
ifTrue:
[self backgroundColor: aColor.
^#dropEffectCopy].
self foregroundColor: aColor.
^#dropEffectMove

130

VisualWorks

7
Dialogs

Dialogs are special purpose windows, typically used to display notices or

to prompt for specific information required by an application. VisualWorks
provides a simple method for displaying many forms of common dialogs,
as well as a full capability for creating custom dialogs.
A variety of dialogs can be constucted quite simply by sending various
class methods to the Dialog class. For more complex and custom dialogs,
SimpleDialog provides a variety of utility methods to simplify dialog
creation.

Standard Dialogs
The standard dialogs provided in VisualWorks make it simple to display
commonly used dialogs from within an application. Typically, all you need
to do is send a message to the Dialog class that identifies the kind of
dialog and any specific information required, such as text.
The standard dialogs are demonstrated in the example DialogExample.

Displaying a Warning

A warning dialog is frequently used when an action cannot be completed,

such as if a search command cannot find a user-specified string.

GUI Developers Guide

131

Chapter 7 - Dialogs

A warning dialog generally displays a simple textual message, which can

have embedded carriage returns and text styles.
A warning dialog is displayed by sending a warn: message to the Dialog
class. When the user clicks OK, the message returns the value nil.
warn
| returnVal |
returnVal := Dialog
warn: 'The memory named\''FirstKiss''\was not found.\'
withCRs.
self returnedValue value: returnVal printString.

Asking a Yes/No Question

Frequently an application needs to ask the user a yes/no question, such

as to request verification when the user has initiated an action that may
have unintended side effects. A yes/no dialog is often referred to as a
confirmer.
By convention, the question is phrased in such a way that a Yes answer
causes the action to proceed.
A confirmer dialog is displayed by sending a confirm: message to the
Dialog class, with a string containing the question.
Dialog confirm: 'Really erase all memories\of adolescent period?\'
withCRs.
If the user clicks Yes, the dialog returns true, and if the user clicks No, the
dialog returns false.
The default answer is Yes. In hazardous situations, this might not be a
good default. To change the default response, send a confirm:initialAnswer:
message to Dialog. The second argument is either true or false.
Dialog
confirm: 'Really erase all memories\of adolescent period?'
withCRs
initialAnswer: false

132

VisualWorks

Standard Dialogs

Multiple-Choice Dialog

Frequently more choices than Yes/No, or other choices are required, but
still only a small number. The multiple-choice dialog provides this
capability. The choices are arrayed as a horizontal row of buttons.
The message that creates a multiple-choice dialog assigns a symbol to
each choice. When the user clicks a choice, the message returns the
corresponding symbol to the application.
To display a multiple-choice dialog, send a choose:labels:values:default:
message to the Dialog class. The choose argument is the question. The
labels argument is an array of strings to be displayed on the answer
buttons. The values argument is an array of Symbols to be used as return
values by the answer buttons. The default argument is the Symbol that is
associated with the desired default answer.
Dialog
choose: 'Which memory would you like to review first?'
labels: #( 'Swimming the Channel'
'Triumph at the Coliseum'
'Love & War #47')
values: #(#swim #triumph #love47)
default: #triumph

Requesting a Textual Response

To prompt for a short, textual response, use the request dialog, which
displays a fill-in-the-blank input field and a label.
To open a request dialog, send request: to the Dialog class, with text
describing what is being requested:
Dialog request: 'Find all memories associated with...'

GUI Developers Guide

133

Chapter 7 - Dialogs

When the user enters a string and clicks OK, the dialog returns the userspecified string. If the user clicks Cancel, the default is to return an empty
string.
By default, an empty string appears in the input field. To specify a default
response, send request:initialAnswer: to Dialog, with the default answer as a
string:
Dialog
request: 'Find all memories associated with...'
initialAnswer: 'friend'
If an empty string is not an appropriate response to Cancel, you can
specify an alternate action or value. Send request:initialAnswer:onCancel: to
Dialog, with a block containing the action to be taken or the value to be
returned:
getText
| returnVal |
returnVal := Dialog
request: 'Find all memories associated with...'
initialAnswer: 'friend'
onCancel: [self defaultRuminationTopic].
"Update the text field in the main window."
self returnedValue value: returnVal printString.

Requesting a Filename

A filename dialog is a special case for a fill-in-the-blank dialog that

prompts the user for a pattern and displays a list of file names matching
that pattern. The dialog accepts * and # as wildcard characters.
When the user clicks Cancel, an empty string is returned by default. The
final variant shows how to arrange for a different value to be returned, an
action to be taken, or both.
To open a file request dialog, send requestFileName: to the Dialog class,
with a string for the label:
Dialog requestFileName: 'Open memory file named...'

134

VisualWorks

Standard Dialogs

In some situations, there may be a natural default file name, as when

saving a file that has been edited. To provide a default filename, send
requestFileName:default: to Dialog, with a string containing the file name:
Dialog
requestFileName: 'Open memory file named...'
default: 'hero01.mem'

Handling a File that Exists or Does Not Exist

By default, the dialog accepts any filename that is accepted by the
operating system. In some circumstances, confirmation may be required
if the specified file either already exists or does not exist.
If you expect the file to exist, you will want confirmation if it does not. In
this case, send requestFileName:default:version: to Dialog, with the symbol
#new as argument:
Dialog
requestFileName: 'Open memory file named...'
default: 'hero01.mem'
version: #new
On the other hand, if you expect the file to be new, you want confirmation
if the file already exists. In this case, send requestFileName:default:version:
with the symbol #old.
In other cases, it may be preferable to cancel the operation if the file
either exists or does not exist. To cancel if the file does exist, send
requestFileName:default:version: with the symbol #mustBeNew.
Dialog
requestFileName: 'Open memory file named...'
default: 'hero01.mem'
version: #mustBeNew
To cancel if the file does not exist, send requestFileName:default:version: with
the symbol #mustBeOld.
Further cancellation processing can be specified by sending a
requestFileName:default:version:ifFail: message to Dialog. The final argument
is a block containing the action to be taken or the value to be returned:

GUI Developers Guide

135

Chapter 7 - Dialogs

getFilename
| returnVal |
returnVal := Dialog
requestFileName: 'Open memory file named...'
default: 'hero01.mem'
version: #mustBeOld
ifFail: [Transcript show: 'Memory file access canceled'. ''].
"Update the text field in the main window."
self returnedValue value: returnVal printString.

Multiple-Selection List Dialog

A multiple-selection list dialog displays a list of selectable items. This

dialog is similar to a multiple-selection list widget, but is displayed only
when needed, separately from the main window. Each item in the list is
associated with a value, like a menu item, and your application can either
insert the selected value in a value holder or trigger an action.
By default, the dialog contains a list of items, an OK button, and a Cancel
button, but additional buttons can be added.
To open a multiple-selection dialog, send
choose:fromList:values:lines:cancel: to the Dialog class. The choose: argument
is a prompt string. The fromList: argument is a collection of strings, the list
item labels. The values: argument is a collection of the same size as the
fromList: collection, containing the values to be associated with the list
items. The lines: argument is an integer indicating the maximum number
of list items to display (for a long list). The cancel: argument is a block
containing the action to take when the Cancel button is pressed.

136

VisualWorks

Standard Dialogs

| files response |
files := Filename defaultDirectory directoryContents
reject: [ :name | name asFilename isDirectory].
response := Dialog
choose: 'Edit which file?'
fromList: files
values: files
lines: 8
cancel: [^nil].
response asFilename edit.

Prompting for a Password

The following is an example of using SimpleDialog interface construction
methods to assemble and format this dialog. Notice the use of the
#password type, which masks the password when entered as a string of
asterisks.

| user pass |
(SimpleDialog initializedFor: nil)
setInitialGap;
addMessage: 'Username' textLine: (user := '' asValue) boundary: 0.4;
addGap;
addMessage: 'Password' textLine: (pass := '' asValue)
type: #password boundary: 0.4;
addGap;
addOK: [true];
openDialog.
user value -> pass value

GUI Developers Guide

137

Chapter 7 - Dialogs

Supplying Extra Action Buttons Below the List

It the two default buttons are not enough or not the correct buttons for
your application, you can change them. For example, when you enter a
wildcard pattern in a file pathname dialog, a list dialog shows the files that
match your pattern and offers a Try again button in case you want to try a
different pattern.
To configure buttons, send choose:fromList:values:buttons:values:lines:cancel:
to the Dialog class. The buttons: argument is a collection of strings to be
used as button labels. The values: argument is a collection of values to be
associated with the button labels.
| files response |
files := Filename defaultDirectory directoryContents
reject: [ :name | name asFilename isDirectory].
response := Dialog
choose: 'Edit which file?'
fromList: files
values: files
buttons: #('Count Files')
values: #(#count)
lines: 12
cancel: [^nil].
response == #count
ifTrue: [Dialog warn: files size printString]
ifFalse: [response asFilename edit]

Linking a Dialog to a Master Window

By default, the built-in dialogs use system settings for their colors and UI
Look. If your application employs a special set of settings, you can
arrange for dialogs to mimic the colors and UI Look of a master window.
In addition, some window systems create a visual connection between a
dialog and its master window.

Adopting the Look of a Master Window

To integrate well with an application, it is often necessary for dialogs to
adopt the look of its master window. The standard dialogs have variant
opening message forms ending with a for: keyword. The argument is a
window, typically the current window, which is given as shown in the
example:

138

VisualWorks

Linking a Dialog to a Master Window

confirm
| returnVal |
returnVal := Dialog
confirm: 'Really erase all memories\of adolescent period?'
withCRs
initialAnswer: false
for: ScheduledControllers activeController view.
"Update the text field in the main window."
self returnedValue value: returnVal printString.

Linking a Dialog to a Window

You can link a dialog to the currently active window with a warn:for:
message. The master window is typically the main application window,
which an application model can access through self builder window.
To link a dialog to a window, send a useColorOveridesFromParent: message
to the SimpleDialog class. The argument true causes subsequently opened
dialogs to adopt the colors of their master window, in addition to the UI
look. (Note that Overides is misspelled in the method name and must
therefore be misspelled here.)
Then send the for: keyword form of the dialog opening message to the
Dialog class, with the master window as the argument for the for: keyword.
| masterWindow |
SimpleDialog useColorOveridesFromParent: true.
masterWindow := ScheduledWindow new.
masterWindow background: ColorValue yellow.
masterWindow open.
Dialog
warn: 'This dialog has a yellow background, too.'
for: masterWindow.
masterWindow sensor eventQuit: nil.
To reset the SimpleDialog class to its default behavior, send the
useColorOveridesFromParent: message with the argument false.

GUI Developers Guide

139

Chapter 7 - Dialogs

Creating a Custom Dialog

These
buttons . . .

. . . display this dialog

When a standard dialog is not sufficient, you can create your own using
the canvas tool. You can then open the interface specification in a dialog
window.
The basic technique is send an openDialogInterface: message to the
application model, with the symbolic name of the dialogs interface
specification.
openDialogCanvas
| returnVal |
returnVal := self openDialogInterface: #memoryZonesDialog.
"Update the text field in the main window."
self returnedValue value: returnVal printString.
The dialog is created as an instance of SimpleDialog, which provides its
own interface builder for setting up the dialogs widgets. The dialog
builder obtains any needed value models, actions, and resources for its
widgets from the application model.
Note, however, that buttons whose Action properties are #accept or #cancel
obtain their actions from the SimpleDialog instance instead. These
predefined actions are useful for OK and Cancel buttons on the dialog.
Consequently, if you define methods named accept or cancel in the
application model, they will be ignored.

140

VisualWorks

Creating a Custom Dialog

An alternative technique for creating a custom dialog (not illustrated here)

is to create a separate model for the dialog (typically, a subclass of
SimpleDialog). You install the dialogs canvas in this subclass and then
program the subclass to provide the value models, actions, and
resources needed by the dialogs widgets. This technique enables you to
reuse the dialog more easily in further applications.

Providing a Temporary Model for the Dialog

You can create a dynamic dialog by programming the application model
to create an instance of SimpleDialog and configure its interface builder.
This creates a temporary model for the dialog, which is useful when the
value models for the dialogs widgets are only needed during the lifetime
of the dialog. For example, a file-finding dialog might employ several
widgets, each requiring a value model, but only the ultimate filename is of
interest to the application.
In the example, the properties for the dialogs list widget tell the dialogs
builder that the list widget needs a MultiSelectionInList for its value holders.
1

In the method that is to open the dialog, create an instance of

SimpleDialog.

Get the builder from the SimpleModel and preload it with one binding
for each active widget. The aspectAt: argument is the symbol you
specified in the widgets Aspect property. The put: argument is an
appropriate value model.

Ask the SimpleDialog to open the interface.

openTempModelDialog
| returnVal dialogModel list |
dialogModel := SimpleDialog new.
dialogBuilder := dialogModel builder.
"Since the simple model does not respond to a #memoryZones message,
its builder must be preloaded with a multilist."
list := MultiSelectionInList new
list: self memoryZones list copy.
dialogBuilder aspectAt: #memoryZones put: list.
"Open the interface."
returnVal := dialogModel
openFor: self
interface: #memoryZonesDialog.
"Update the text field in the main window."
self returnedValue value: returnVal printString.

GUI Developers Guide

141

8
Custom Views

A view displays text or graphics representing all or part of a data model.

Each of the widgets uses a view to display a data model. When an
existing widget does not serve your purpose, you can create a custom
view.
A custom view is like a small application. It typically has a domain model,
a controller, and a view, which is similar to an application model. You
begin that process by creating the view class, and then add its UI
specification and connect it to its domain model.
Building a custom view is described in the context of an example,
CustomViewExample, a simple sketch pad. It uses four classes that
demonstrate the interactions among a domain model (Sketch), a custom
view (SketchView), a custom controller (SketchController), and an
application model (CustomViewExample). SketchView uses a Sketch as its
model, which has a name and a collection of points representing a series
of sketched strokes. SketchView uses a SketchController to handle mouse
and keyboard input.
These examples classes are all in the CustomView-Example parcel.

142

VisualWorks

Creating a View Class

Creating a View Class

custom view for sketching

The new view requires a class, which you create as a subclass of View or
one of its subclasses.
Online example: SketchView
1

In a System Browser, select Class ! Add Class ! Fixed Size to display

the class-definition template.

In the template, specify the name space, class name, and superclass
name. The superclass is typically either View (as in the example, or a
subclass of View).

Supply variable names, if any, and then Accept the definition.

Smalltalk.Examples defineClass: #SketchView
superclass: #{UI.View}
indexedType: #none
private: false
instanceVariableNames: ''
classInstanceVariableNames: ''
imports: ''
category: 'Examples-Help'

GUI Developers Guide

143

Chapter 8 - Custom Views

Connecting a View to a Domain Model

When a different
domain model
is selected . . .

. . . the custom view is given the

new model and displays it

A view displays text or graphics that communicate the state of its domain
model, or at least a portion of its domain model. Since a view must
communicate frequently with the domain model, it needs a way of
accessing that object. As a subclass of DependentPart, every view inherits
an instance variable for storing its model. Sending a model: message to
the view, typically when the view is created, stores the model in this
instance variable, where it can be accessed easily.
A side effect of the model: message is that the view is registered as a
dependent of the model. This link sets the stage for the view to update its
display when the model changes.
About the example: Although some views have the same domain model
for their whole lifetimes, SketchView changes its model each time the user
selects a different Sketch. For that reason, SketchView reimplements the
model: method so it can update its display after storing the new model.
Online example: CustomViewExample, SketchView
1

Tell the view which object to use as its domain model. This is done in
an initialization method or, as in the example, the application model
(CustomViewExample) can notify the view whenever the domain model
changes.
changedSketch
self sketchView model: self sketches selection.

144

VisualWorks

Defining What a View Displays

If the view needs to take action when its model is changed, such as
redisplaying itself, override the inherited model: method (as in
SketchView).
model: aModel
super model: aModel.
self invalidate.
"Tell the controller where to send menu messages."
self controller performer: aModel.

Defining What a View Displays

The view gets a collection

of points from the model
and displays the points as
line segments

A views purpose is to display text or graphics. It does so in a method

named displayOn:, which is sent to the view whenever circumstances
require that it update its display.
The view decides what to display based on the state of its domain model.
It displays the text and/or graphics on a GraphicsContext, which is an object
that windows and other display surfaces use for rendering objects.
Online example: SketchView
In CustomViewExample, a SketchView is used to display the line segments
that are stored in its domain model, a Sketch.

GUI Developers Guide

In a displaying protocol, add a displayOn: method to the view. The

argument is a GraphicsContext.

In the displayOn: method, get the required data from the model (in the
example, a set of line segments, each represented as a collection of
points).

145

Chapter 8 - Custom Views

In the displayOn: method, display the appropriate text or graphics,

based on the data from step 2 (in the example, each collection of
points is displayed as a Polyline).
displayOn: aGraphicsContext
self model isNil ifTrue: [^self].
self model strokes do: [ :stroke |
aGraphicsContext displayPolyline: stroke].

Updating a View When Its Model Changes

update

dependents

self

changed

aModel

update

view1

view2

Since the purpose of a view is to display some aspect of its domain

model, it must be prepared to change its display when the model is
changed.
When the domain model changes its state, it is responsible for notifying
all of its dependents. It does so by sending a variant of the changed:with:
message to itself. The first argument is a Symbol indicating what was
changed, and the second argument is the new value.
Shorter versions of the changed:with: message, changed: and changed, can
be used when less information needs to be sent. Read their comments in
a code browser for more information.
The changed:with: message is inherited, and it sends an update:with:
message to each dependent, passing along the same two arguments.
Thus, the view must implement an update:with: method in which it gets the
new data from the model and displays it.
Online example: Sketch, SketchView
1

146

In any method in the domain model that changes the model in a way
that affects the view, send a variant of the changed:with: message to
the model. (In the example, Sketch sends three such messages, one
VisualWorks

Connecting a View to a Controller

when it adds a point and the others when it erases some or all of its
contents.)
add: aPoint
"Add aPoint to the current stroke."
self strokes last add: aPoint.
self changed: #stroke with: self currentLineSegment.
eraseLine
"Erase the last stroke that was drawn."
self strokes isEmpty
ifFalse: [
self strokes removeLast.
self changed: #erase with: nil].
eraseAll
"Erase my contents."
self strokes removeAll: self strokes copy.
self changed: #erase with: nil.
2

In the view, implement a variant of the update:with: method to take the

appropriate action in response to a change in the model. (In the
example, the same update:with: method responds to either of the
changed:with: messages sent by the model.)
update: anAspect with: anObject
"When a point is added to the model..."
anAspect == #stroke
ifTrue: [anObject asStroker displayOn: self graphicsContext].
"When the model erases its contents..."
anAspect == #erase
ifTrue: [self invalidate].

Connecting a View to a Controller

If a view responds to mouse or keyboard input, it needs a controller to
process mouse and keyboard input. Such a view is called active. A view
is often closely allied with its controller, so an inherited mechanism
installs the desired controller when the view is created.

GUI Developers Guide

147

Chapter 8 - Custom Views

Controllers are event-driven in VisualWorks, meaning that they capture

mouse and keyboard events passed into VisualWorks from the operating
system. An views controller identifies which events it responds to, and
how it responds.
SketchView uses a SketchController, which changes the cursor to a
crosshair, notifies the model when the user draws with the <Select>
button, and provides a menu when the <Operate> button is pressed.

Creating a Controller Class

Because an input controller defines the interactive character of a view,
changing the controller can have a dramatic impact on the operation of a
view. When an existing controller class does not serve your purposes,
you can create a custom controller class.
An event-driven controller that responds to keyboard input needs to have
an instance variable named keyboardProcessor, and accessor methods for
that variable (keyboardProcessor and keyboardProcessor:). The controller
should not initialize the variable, however, because a KeyboardProcessor
will be supplied by the window using a keyboardProcessor: message.
By default, an event-driven controller does not accept keyboard focus.
When it handles keyboard input, it must respond true to a desiresFocus
message.
To create the basic controller class:
1

In a System Browser, define a new controller class.

In the template, specify the name space, the class name, and the
superclass. The superclass is some class in the Controller hierarchy.
For this example it is ControllerWithMenu.

Supply variable names, if any, and then Accept the definition.

In our example, a variable named strokeInProgress is created to
store a true/false indication of whether the user is actively sketching,
and a keyboardProcessor variable to specify whether it accepts
keyboard input
SketchControllers definition is:

148

VisualWorks

Connecting a View to a Controller

Smalltalk.Examples defineClass: #SketchController

superclass: #{UI.ControllerWithMenu}
indexedType: #none
private: false
instanceVariableNames: 'strokeInProgress keyboardProcessor '
classInstanceVariableNames: ''
imports: ''
category: 'Examples-Help'
3

Add an initialize method to assign an initial value to the instance

variables. Remember that we do not initialize keyboardProcessor.
initialize
super initialize.
strokeInProgress := false.

Add accessor methods for the instance variables. The methods are
responsible for getting and setting the value of each instance
variable.
strokeInProgress
^strokeInProgress
strokeInProgress: aBoolean
strokeInProgress := aBoolean
keyboardProcessor
^keyboardProcessor
keyboardProcessor: kp
keyboardProcessor := kp

When keyboard input is to be handled, add a desiresFocus message

to the controller. The method simply returns true, overriding the
inherited method, which returns false.
desiresFocus
^true

Connect the Controller to the Model

A controllers purpose is to respond to input events. Frequently, the
response involves sending a message to the views domain model.
A controller inherits a model instance variable (from Controller) for storing
the model so it can easily access that object. Also, by default, a view
sends a model: message to its controller when it receives a model:
message itself, effectively installing the model in both the view and its
controller.
GUI Developers Guide

149

Chapter 8 - Custom Views

It the default behavior is not appropriate, you can also set the controllers
model explicitly. This is not necessary for our example. If it is necessary
for your application, simply send a model: message to the controller. The
argument is the model.

Connect the Controller to the View

Online example: SketchView, SketchController
An application model sometimes needs to access a views controller. The
usual way of accessing the controller is to ask the view for it. Thus, the
view must itself be able to access its controller.
A view inherits an instance variable for storing its controller. By default,
this instance variable is initialized automatically, when a view is opened,
according to the value returned by its defaultControllerClass method.
defaultControllerClass
^SketchController
To make a view passive, return NoController from the defaultControllerClass
method.
Alternatively, you can install a controller in a view directly, by sending a
controller: message to the view, with the controller class name as
argument.

Connecting a Composite View to a Controller

When multiple views inhabit the same window, normally they have
separate controllers. In some situations, the composite object that groups
them needs its own controller, either instead of the individual controllers
or in addition to them. A CompositeView is intended for grouping views that
need a common controller. To initialize its controller:
Send a controller: message to the composite that groups the views. The
argument is an instance of the desired type of controller (not the class
name as with defaultControllerClass).

Redisplaying All or Part of a View

A view can redisplay its entire contents or just a portion of them. For
example, when one window overlaps another, the overlap region is all
that needs to be redisplayed when the lower window is no longer
obscured by the upper window. This overlap region is called a damage
rectangle, because it is a rectangular region that was damaged by an
overlapping window.
150

VisualWorks

Redisplaying All or Part of a View

The windows sensor keeps track of such damage rectangles and repairs
them in a batch to avoid repairing the same region twice. Sending
invalidate to a view causes the entire view to be treated as a damage
rectangle. Alternatively, you can limit the damage rectangle to a portion of
the window.
By default, damage rectangles are accumulated until the windows
controller reaches a certain point in its cycle of activity. That is sufficient
in most situations. However, when a competing process is monopolizing
the processor, the delay can be significant. In this case, you can force the
damage to be repaired immediately.
Invalidating a view is done in a view method, when the view updates its
model. It can also be done by an application model that has changed a
widgets data model in a way that bypasses the normal dependencies.

Redisplaying a View
Online example: SketchView
Send invalidate to the view. This is typically done in a view method that
changes the model (as in the example).
model: aModel
super model: aModel.
self invalidate.
"Tell the controller where to send menu messages."
self controller performer: aModel.

Redisplaying Part of a View

Send invalidateRectangle: to the view. The argument is a rectangle that
represents all or part of the views bounding box. The bounding box can
be accessed by sending bounds to the view.

Redisplaying Immediately
Send invalidateRectangle:repairNow: to the view. The first argument is a
rectangle that represents all or part of a views bounding box. The second
argument is true when immediate redisplay is desired, and false for the
default behavior.

GUI Developers Guide

151

Chapter 8 - Custom Views

Integrating a View into an Interface

A View Holder widget is provided on the UI Painter Palette for integrating
a custom view into a canvas. This view holder enables you to treat your
custom view like a standard widget in that you can paint its layout and
apply borders and scroll bars. However, your application is responsible for
connecting the view to a domain model.
Online example: CustomViewExample, SketchView
1

Select a View Holder from the Palette and place it on the canvas.

In the view holders View property, enter the name of the applicationmodel method that supplies an instance of the desired view
(sketchView).

If the application model will need to access the custom view while the
application is running, use a System Browser to create an instance
variable (sketchView) in which to store the custom view.

Use a System Browser to create the application-model method that

you named in step 2 (sketchView). This method typically answers the
contents of the instance variable that you created in step 3.
sketchView
^sketchView

In an initialize method in the application model, create an instance of

the custom view. If appropriate, connect the custom view to a data
model. (In the example, there is no model to be connected until the
user adds the first Sketch object.)
initialize
sketches := SelectionInList with: OrderedCollection new.
sketches selectionIndexHolder
onChangeSend: #changedSketch to: self.
sketchView := SketchView new.

152

VisualWorks

9
Configuring Widgets

VisualWorks provides a rich set of widgets for building the GUI for your
application. The widgets are shown in the canvass palette and can be
selected and added to design a window, as described in Chapter 2,
Building an Applications GUI.
This chapter describes the widgets and how to connect them to your
application.

GUI Developers Guide

153

Chapter 9 - Configuring Widgets

Buttons
Online example: ButtonExample
Radio button, checkboxes, and action buttons are common GUI elements
for setting standard parameters and starting actions. Radio buttons and
checkboxes are used to select one or more options. Action buttons
frequently begin an operation or invoke another window.

Radio Buttons

radio buttons

A group of radio buttons allows a user to select a single item from a

limited list of choices. Selecting a radio button causes any other button in
its group to be deselected. This characteristic makes radio buttons useful
only where an exclusive selection is appropriate.
Radio buttons are typically used only for a very brief and static set of
choices. If you want your application to reconfigure the list of choices
programmatically, you use a list widget instead. A list is also scrollable,
making it more suitable for a long list of options.
To allow users to select more than one choice, use either a group of
check boxes or a list widget with the multi-select property turned on.
To add a group of radio buttons:
1

Add a radio button to the canvas for each selectable option.

For each button, change the Label property to name the choice.

Enter the same Aspect property for each button in the group.
The common aspect is what makes a group.

For each button, enter a different Select property.

This symbol is stored in the Aspect value holder whenever the button
is selected.

154

Apply the properties and install the canvas, and use define to add an
instance variable and accessor method for the aspect.

VisualWorks

Buttons

Create an initialize method, in which you initialize the aspect variable

to hold a value holder containing one of the valid Select symbols.
The default symbol determines which radio button is the default.
initialize
super initialize.
outputMode := #dialog asValue.
showMinutes := true asValue.
showHours := true asValue.
showSeconds := true asValue.

Radio Button Events

A Radio Button triggers events when its label is changing, when it gains
and looses focus, and when the selection is turned on or off.
Radio Buttons send the #labelChanging, #labelChanged, #turnedOn and
#turnedOff events only after the Radio Button has been created and
displayed on the canvas. Thus, a Radio Button that has its value initially
set to be turned on or off, will not trigger that event, since that value is
assigned before the Radio Button is initially displayed on the canvas.
#labelChanging
When a radio button's label is about to change, the radio button
triggers the #labelChanging event.
#labelChanged
After a radio button's label has changed, the radio button triggers the
#labelChanged event.
#clicked
When a radio button is clicked on by the mouse, without regard to the
on or off state of the radio button, the radio button triggers the #clicked
event.
#gettingFocus
When a radio button receives focus, either by being tabbed to or
clicking on, the radio button triggers the #gettingFocus event.
#losingFocus
When a radio button loses focus, either by being tabbed away from or
by another widget on the canvas gaining focus, the radio button
triggers the #losingFocus event.
#tabbed
When a radio button has focus, and the Tab key is pressed causing
the focus to move to the next widget in the tab order, the radio button
triggers the #tabbed event.

GUI Developers Guide

155

Chapter 9 - Configuring Widgets

#backTabbed
When a radio button has focus and the Back-Tab (Shift-Tab) key is
pressed causing focus move to the previous widget in the tab order,
the radio button triggers the #backTabbed event.
#turnedOn
After a radio button has its state changed from being not selected to
being selected, the radio button triggers the #turnedOn event.
#turnedOff
After a radio button has its state changed from being selected to not
being selected, the radio button triggers the #turnedOff event.

Check Boxes

check boxes

A check box is like a toggle button that allows the user to turn on or turn
off an attribute. Check boxes are often used in a group to represent a set
of related attributes.
Selecting one check box has no effect on others in the set, so users can
select as many as they want. When you want only one attribute to be
selected at a time, use radio buttons instead.
To add an check box:
1

Add a check box to the canvas for each selectable option.

In its Label property, enter a description for the check box.

Enter an Aspect property for the check box.

The value holder for the check box will contain true when the check
box is selected and false when it is not selected.

156

Apply the properties and install the canvas, and use define to create
an instance variable and aspect accessor method.

Create or edit the initialize method to initialize the variable to a value

holder containing true if you want the check box to be selected by
default and false otherwise.

VisualWorks

Buttons

initialize
super initialize.
outputMode := #dialog asValue.
showHours := true asValue.
showMinutes := true asValue.
showSeconds := true asValue.

Checkbox Events
A Check Box triggers events when its label is changing, when it gains and
looses focus and when the selection is checked or unchecked.
Check Boxes send the #labelChanging, #labelChanged, #checked and
#unchecked events only after the Check Box has been created and
displayed on the canvas. Thus, a Check Box that has its value initially set
to be checked or unchecked, will not trigger that event, since that value is
assigned before the Check Box is initially displayed on the canvas.
#labelChanging
When a check box's label is about to change, the check box triggers
the #labelChanging event.
#labelChanged
After a check box's label has changed, the check box triggers the
#labelChanged event.
#clicked
When a check box is clicked on by the mouse, without regard to the
checked or unchecked the check box, the check box triggers the
#clicked event.
#gettingFocus
When a check box receives focus, either by being tabbed to or by
clicking on by the mouse, the check box triggers the #gettingFocus
event.
#losingFocus
When a check box loses focus, either by being tabbed away from, or
by having another widget on the canvas gain focus, the check box
triggers the #losingFocus event.
#tabbed
When a check box has focus, and the Tab key is pressed in request
to have the focus to move to the next widget in the tab order, the
check box triggers the #tabbed event.
#backTabbed
When a check box has focus, and the Back-Tab (Shift-Tab) key is
pressed in request to have the focus move to the previous widget in
the tab order, the check box triggers the #backTabbed event.
GUI Developers Guide

157

Chapter 9 - Configuring Widgets

#checked
After a check box has had its state changed from being unchecked to
being checked, the check box triggers the #checked event.
#unchecked
After a check box has its state changed from being checked to being
unchecked, the check box triggers the #unchecked event.

Action Buttons
action button

An action button triggers an action, such as opening a dialog window. If

you want to save space in an interface, consider using a menu instead of
multiple buttons.
To add an action button:

158

Add an action button to the canvas. In the buttons Label property,

enter a descriptive label.

In the buttons Action property, enter the message selector that

performs the action.

Apply the properties and install the canvas.

Create the method for the button in the actions protocol.

VisualWorks

Buttons

tellTime
| t tString |
t := Time now.
tString := String new.
"Assemble the time string based on the check boxes."
self showHours value
ifTrue: [tString := tString, t hours printString].
self showMinutes value
ifTrue: [tString := tString, ':', t minutes printString, ':']
ifFalse: [tString := tString, '::'].
self showSeconds value
ifTrue: [tString := tString, t seconds printString].
"Send the time string to the output channel set by the radio
buttons."
self outputMode value == #transcript
ifTrue: [Transcript show: tString; cr]
ifFalse: [DialogView warn: tString]

Action Button Events

An Action Button triggers events when its label is changing, when it is
pressed, and when it gains and looses focus.
Action Buttons send the #labelChanging and #labelChanged events only after
the Action Button has been created and displayed on the canvas. Thus,
an Action Button does not trigger these events when it gets its initial label,
since that value is assigned before the Action Button is initially displayed
on the canvas.
#labelChanging
When a button's label is about to change, the button triggers the
#labelChanging event.
#labelChanged
After a button's label has changed, the button triggers the
#labelChanged event.
#clicked
When a button is clicked on by the mouse, the button triggers the
#clicked event.
#pressed
When a button is pressed either by keyboard interaction or by being
clicked on by the mouse, the button triggers the #pressed event.
#gettingFocus
When a button receives focus, either by being tabbed to or by clicking
on by the mouse, the button trigger the #gettingFocus event.
GUI Developers Guide

159

Chapter 9 - Configuring Widgets

#losingFocus
When a button loses focus, either by being tabbed away from, or by
having another widget on the canvas gain focus, the button triggers
the #losingFocus event.
#tabbed
When a button has focus, and the Tab key is pressed in request to
have the focus to move to the next widget in the tab order, the button
triggers the #tabbed event.
#backTabbed
When a button has focus, and the Back-Tab (Shift-Tab) key is
pressed in request to have the focus move to the previous widget in
the tab order, the button triggers the #backTabbed event.

160

VisualWorks

Button Tab Notebook

Button Tab Notebook

The Button Tab Notebook widget was soft deprecated in 5i.4, and is no
longer on the Palette. The supporting classes are still present in the
system, but will be removed in a subsequent release. Please consider
using Tab Control in its place.

GUI Developers Guide

161

Chapter 9 - Configuring Widgets

Charts
The Chart widget supports a large variety of graphical representations
that are commonly used in business applications to represent numerical
data. The style and appearance of the chart are set by widget properties.
The application model provides the chart data in the form of a collection
of numerical data. A simple chart presents a single set or series of
values. A more complex chart, comparing two or more sets of data,
requires two or more collections of values, called a data series.

Adding a Chart
To add a bar chart to an application:
1

Select the Chart widget in the Palette, and drop it on a canvas.

On the Basics property page, specify the charts Aspect, which is the
the name of the instance variable and accessor method that supplies
the data to the chart.
In the case of a simple chart with a single series of values, the aspect
returns a collection. For charts that compare multiple series of
values, you set up one or more data series, as described in Charting
Multiple Data Series.

Select the chart type and click Apply

Install the canvas.

Create a definition for the chart widgets aspect and edit it to return a
value holder on the collection containing the chart data.

Charting Multiple Data Series

A more complex chart, such as one that compares performance of two or
more entities over time, needs to plot more than a single series of data
points. To do this, you declare the multiple data series.
The Aspect for your chart declared on the Basics property page is still the
instance variable for your chart data, but it now is a collection of items
with some additional structure.
The simplest case is that it is a collection of simple collections of
numbers, such as the following array of arrays:
#(#(60 40) #(20 55) #(35 10) #(75 50))
The data series can be identified by index within the subcollections. (See
BG_EzChart for an example of this approach.)
162

VisualWorks

Charts

More typically, the collection will consist of structured objects, such as an

Employee object, defined in a class other than the application model. In
this case the data series will require accessor methods defined in the
relevant class to return the collections required for charting. (See
BG_Company for an example of this approach.)
In either case, you must specify the data series for the chart.
1

Add a Chart widget to a canvas.

On the Basics property page for the chart, specify the Aspect for the
Chart.

On the Data Series page, click New to add a new data series, and

In the Name field, enter a descriptive name for the first set.

In the Aspect field, enter either the accessor method for the items
making up this data series, or the index of this item in the
subcollection.

Repeat step 3 for each additional data series.

Apply your changes.

Using a source browser, ensure that the chart widgets aspect

instance variable is initialized to the collection, and that its accessor
method returns the collection as a value holder.

Adding Labels
You add labels to your chart by including the label strings as another data
series.
To add labels:
1

On the Data Series property page, add a new data series with an
appropriate name. For the Aspect, enter the index for the labels in the
collection, or the name of the accessor method that returns the label
from the collection members.

Apply your changes.

Edit the application code as necessary to include the label in the

collection stored in the chart widgets aspect instance variable.

Special Requirements for Charts

Most of the charts are configured as described in the preceding sections.
A few charts have special requirements for formatting their data, and are
described here.
GUI Developers Guide

163

Chapter 9 - Configuring Widgets

Pareto

A Pareto chart consists of a bar chart in descending order of item

magnitude, with the overlay graph of cumulative percentages. Used with
multiple data series, it is useful for pinpointing the data series that
accounts for the greatest number.
The Pareto chart can take either a single or multiple data series, as
described previously.
A Pareto chart does not accept labels.

Picture

A picture chart represents the unit of a numeric item with a meaningful

picture or symbol. A picture chart can represent only a single data series,
but may include the labels:
#(#(60 'Jan') #(20 'Feb') #(35 'Mar') #(75 'Apr'))
164

VisualWorks

Charts

For the labels to display, define two data series, and check the Label
checkbox for the series holding the labels.
To replace the default picture, enter the name of the graphic into the
Aspect field on the Picture section on the Options property page.

By default, the picture represents a unit of 20. To change the unit amount,
enter the desired amount in the Unit field under the Picture section of the
Options Properties.

XY

An XY chart indicates any correlations between two characteristics

derived from the scattering status of points plotted in the chart.
The XY chart expects points as its data. For example, an XY chart with
two data series could be set up as follows:
dataPointXY
| array1 array2 array3|
array1 := Array with: 20@60 with: 20@40.
array2 := Array with: 40@40 with: 40@10.
array3 := Array with: 60@75 with: 60@35.
^(Array with: array1 with: array2 with: array3) asValue

GUI Developers Guide

165

Chapter 9 - Configuring Widgets

Pie Charts

A pie chart can only represent one data series, but may include labels:
#(#(25 'Jan') #(15 'Feb') #(40 'Mar') #(20 'Apr'))

Exploding Labels
In a pie chart, a slice can be designated to be exploded. For example,
enter Jan in the Labels to Explode field on the Options page. Only one label
can be exploded at a time.

Doughnut Labels
A doughnut label appears inside a circle in the center of a pie chart. To
create a doughnut label, enter the label name in the Doughnut Label field on
the Options page.

166

VisualWorks

Click Map

Click Map
The Click Map widget allows you to define areas of a graphic image and
specify the action to invoke if the user clicks on each area.
Using a Click Maps for a button bar makes it possible to use any graphic
image to represent the row of buttons. The image may include text,
graphics, and a variety of colors. All of the buttons may be part of a single
image, guaranteeing their relative layout.

Adding a Click Map

To add a click map widget to a canvas:
1

Choose the click map widget

canvas.

in the Palette and place it on a

Set the following Basic properties and Apply them:

ID: A unique identifier for the widget, which will be used to access the
widget.
Visual Message: The message selector that returns the image, which is

typically an image resource method.

Mappings Selector : The message that returns the mapping between an
area and the action for that location. You define mapping using the
Hot Regions Editor.
Default Click Message: (optional) Specifies the action to be invoked when

the user clicks in an area for which no other action is specified. If left
empty, no action is taken.
3

In the canvas, resize the click map widget so that it closely outlines
the graphic image.

Install the canvas, and provide a class name and method name in

which to install the canvas when prompted.

Defining the Hot Region Mappings

1

GUI Developers Guide

Select the click map widget in the canvas.

167

Chapter 9 - Configuring Widgets

In the GUI Painter Tool, choose Tools ! Hot Regions Editor.

Choose Regions ! Read to display the selected click widgets image as

the background in the Hot Regions Editor. Resize the window to
display the entire image.

Choose Edit ! New Slice to begin defining a region.

A slice is comprised of one or more areas that invoke the same action
when clicked. The areas in a slice do not need to be contiguous.
Identify areas in the Hot Regions Editor using tools similar to other
bitmap editors:

The four colors or patterns of ink allow you to select a color that
shows well when selecting a region. The color does not show in
the final click map.

Six brush sizes and shapes. The first four draw lines, the next
draws an ellipse, and the sixth draws a rectangle.

A fill-mode bucket that fills the entire image.

In the Selector input field, enter a method selector for the action to be
invoked when this slice is clicked and press <Return>.
The selector is added to the menu button in the middle of the Hot
Regions Editor. You can use the menu to switch between different
slices of the same hot region resource.

168

Repeat steps 4 and 5 to define all the slices for this hot region.

Choose Regions ! Apply to:

VisualWorks

Click Map

Install the hot region resource. You are prompted for the class
name and selector for the resource method that stores the hot
region mappings.

Insert the resources selector into the Mapping Selector property of

the click map widget that is selected in the canvas.

Close the Hot Regions Editor.

Install the canvas.

Using Custom Views and Controllers

If you have an application that uses custom views and controllers, you
can make it work as a VisualWave application:
1

Make the custom view a subclass of ClickWidget.

In the custom view, implement a mouseReleaseAt: method that

specifies what to do when the user clicks in the custom view.

Disconnect the custom controller from your application. Move any

custom behavior to the custom views mouseReleaseAt: method.

Note that interaction with the user is more limited in web applications than
in other applications. In particular, the only mouse events transmitted to
the application from the web browser are mouse clicks. Events based on
entry, mouse movement, and exit are ignored.

Click Widget Events

A Click Widget triggers events when its view is clicked on.
#clicked
When a click widget is clicked on by the mouse, without regard to if a
mapped region is hit or not, the click widget triggers the #clicked
event.
#hitMappedRegion
When a click widget is clicked on by the mouse, and at least one of
the mapped regions of the click widget has been hit, the click widget
triggers the #hitMappedRegion event.
#missedMappedRegion
When a click widget is clicked on by the mouse, and none of the
mapped regions of the click widget has been hit, the click widget
triggers the #missedMappedRegion event. If a click widget has a Default
Click selector defined, then the click widget will never trigger the
#missedMappedRegion event.

GUI Developers Guide

169

Chapter 9 - Configuring Widgets

Combo Box

It is frequently useful for an input field to restrict the valid entries. This can
be done with validation methods, but the ComboBox is often informative
to a user.

Adding a ComboBox to a Canvas

Online example: ComboBoxExample
1

Add a combo-box widget to the canvas.

On the Basics property page, in the Aspect field, enter a name for the
aspect accessor method (in the example, shipper).

In the Choices property, enter the name of the method that returns a
collection of entry choices (shipperChoices).

Apply the properties and install the canvas, and use Define to create
the aspect instance variable and accessing method.

Create the ComboBox choices method in the application model.

The method returns a value holder containing the list of valid entries.
The value holder can be held in an instance variable (as in the
example).
shipperChoices
^shipperChoices

170

Initialize the fields aspect variable with a value model containing data
of the type specified in the Type property for the widget.

Initialize the choices variable with a value holder containing the list of
valid entries.

VisualWorks

Combo Box

initialize
| list |
shipper := 'Courier' asValue.
list := List new.
list add: 'Courier';
add: 'FedEx';
add: 'UPS';
add: 'USPS'.
shipperChoices := list asValue.

Listing Arbitrary Objects

You can arrange for a combo box to display a list of choices that are
arbitrary objects (for example, a list of Employee objects). You do this by
supplying a print method and a read method that translate the relevant
objects into displayable elements (for example, Strings or graphical
images) and back. For example, in ComboCoversionExample, the print
method enables the combo box to display Employee names in the pulldown list and, when an Employee is selected, to display that employees
name in the field. The read method enables the combo box to interpret
the users input as an Employee name, which can be matched with an
existing Employee, or used to create a new one.
Online example: ComboConversionExample

GUI Developers Guide

On the Basics property page, set the Type property of the combo box
to Object.

Fill in the Print property with the name of a method for converting the
relevant objects to strings (in this example, employeeToString:). The
name must end with a colon.

Fill in the Read property with the name of a method for converting
strings to objects of the desired type (in this example,
stringToEmployee:). The name must end with a colon.

In the application model, create a print method with the name you
specified in step 2 (employeeToString:). This method accepts an object
from the choices list as an argument (in this case, an instance of
Employee).

In the print method, return a String that represents the object from the
choices list. In this example, display the name of the Employee. The
string is displayed in the combo boxs pull-down list and also in the
combo boxs field when the choice is selected.

171

Chapter 9 - Configuring Widgets

employeeToString: anEmployee
"Return a String for representing the Employee in the combo boxs list
and field."
^anEmployee name.
6

Create a read method with the name you specified in step 3

(stringToEmployee:). This method accepts a String argument.

In the read method, return an object for the given String. In this
example, determine whether the String is the name of an Employee in
the choices list; if so return that Employee. Otherwise, create a new
Employee and add it to the choices list.
stringToEmployee: aString
"Return an Employee corresponding to the given String. If the String
corresponds to the name of an Employee on the choices list, return that
Employee. Otherwise, create a new Employee and add it to the list."
| theEmp |
theEmp := self employeeChoices value
detect: [:each | each name = aString]
ifNone: [nil].
theEmp isNil
ifTrue:
[theEmp := Employee new name: aString.
self employeeChoices value addLast: theEmp].
^theEmp

Combo Box Events

A Combo Box triggers events when a selection is changing, when it gains
and looses focus, when it gets clicks from the mouse, and when its list is
exposed and closed. The biggest difference between a Menu Button and
a ComboBox in terms of events triggered, is that a Menu Button does not
trigger the #rightClicked or #doubleClicked events.
#changing
When a selection in the list of a combo box is made, or in the case of
an editable combo box, the value has been edited, but before the
value is accepted, the combo box triggers the #changing event.
#changed
After a selection in the list of a combo box is made, or in the case of
an editable combo box, the value has been edited, when the value is
accepted, the combo box triggers the #changed event.
172

VisualWorks

Combo Box

#clicked
When a combo box is clicked on with the <Select> mouse button, the
combo box triggers the #clicked event.
#rightClicked
When a combo box is right clicked on with the <Operate> mouse
button, the combo box triggers the #rightClicked event. This event will
occur without regard to whether there is a popup menu associated
with the combo box.
#doubleClicked
When a combo box is double clicked on with the <Select> mouse
button, the combo box triggers the #doubleClicked event. This event is
always immediately preceded by a #clicked event. Read-only combo
boxes do not respond to the double clicked event, but rather consider
the double click to be two separate clicks that open and immediately
close the combo box, and thus do not trigger the #doubleClicked event.
#gettingFocus
When a list box receives focus, either by being tabbed to or by
clicking on by the mouse, the list box triggers the #gettingFocus event.
#losingFocus
When a combo box loses focus, either by being tabbed away from, or
by having another widget on the canvas gain focus, the combo box
triggers the #losingFocus event.
#tabbed
When a combo box has focus, and the Tab key is pressed moving the
focus to the next widget in the tab order, the combo box triggers the
#tabbed event.
#backTabbed
When a combo box has focus, and the Back-Tab (Shift-Tab) key is
pressed moving the focus to the previous widget in the tab order, the
combo box triggers the #backTabbed event.
#listExposed
When a combo box has its selection list exposed, either by clicking
on the combo box or using the down arrow key to open the list, the
combo box triggers the #listExposed event.
#listClosed
When a combo box has its selection list closed, either by clicking on
another widget on the canvas, by clicking on the combo box when the
list is already exposed, or by selecting a new value in an exposed list,
the combo box triggers the #listClosed event.

GUI Developers Guide

173

Chapter 9 - Configuring Widgets

Datasets

row labels

dataset widget

A dataset presents a list of similar objects for a user to edit. Datasets are
similar to tables, but cells in a dataset can be edited directly. Datasets are
best suited for presenting similar kinds of data.
A dataset uses a SelectionInList to hold the list of objects to be displayed,
along with information about the current selection. Each object in the list
is displayed in its own row, with individual aspects of the object displayed
in their own columns. The property pages specify the means by which
each column presents its data, whether using cells that contain read-only
fields, editable fields, combo boxes, or checkboxes.

Setting up a Dataset
Online example: Dataset1Example
The example displays instances of Employee, which consist of three
objects (name, empNo, and citizen), in three dataset columns.
1

Add the dataset widget to the canvas.

On the Basics property page, in the datasets Aspect property, enter the
aspect name (dsvList). Apply the property and install the canvas.

Use define to add the dsvList instance variable and accessor method
to the application model.
The dsvList method returns a SelectionInList object that will hold the list
to be displayed. This method also sets up the SelectionInList so it will
cause a users selection to be put in a separate value holder
(selectedRow).

174

In the datasets properties, click the New Column button for each
column you want in the dataset.

VisualWorks

Datasets

In the example, three columns are added to the canvas.

5

In the canvas, <Control>-click in the leftmost column to select it.

Display the datasets Column property page. The properties you set on
this page will apply to the currently selected column.

On the Column page, enter Name as the Label property. This creates a
visual label above the selected column, which is to display employee
names.

On the Column page, enter selectedRow name in the Aspect field.

selectedRow refers to the value holder that will hold the object (the
Employee) selected by the user. name refers to the aspect of Employee
that is displayed in this column.

On the Column page, select Input Field as the Type. This causes each
cell in the selected column to display its data in an editable input field.
Note that you can optionally specify nondefault characteristics for
these input fields by filling in properties on the Column Type page.

10 <Control>-click on the middle column to select it.

11 On the Column page, enter Employee Number as the Label and
selectedRow empNo as the Aspect. Select Input Field as the Type.
12 <Control>-click on the rightmost column to select it.
13 On the Column page, enter U.S. Citizen as the Label and selectedRow
citizen as the Aspect. Select Check Box as the Type.
14 When the all properties have been applied, install the canvas.
15 Use the define command to add the selectedRow instance variable to
the application model and to create the selectedRow method in the
aspects protocol.
The selectedRow method returns a value holder for holding the userselected Employee object from the SelectionInList.
16 Use a browser to initialize the dataset (in an initialize method in an
initialize-release protocol).
initialize
| aList |
aList := List new.
aList add: Employee new initialize.
self dsvList list: aList.

GUI Developers Guide

175

Chapter 9 - Configuring Widgets

When you open the application, the dataset contains one empty row. You
can type a name and number in the Name and Employee Number columns,
and select the U.S. Citizen check box.
Note that the first part of the Aspect setting for each column must be the
same as the message sent by the SelectionInList to obtain a value holder
for storing the selected object. You used selectedRow in steps 8, 11, and
13, because that name is used in the generated dsvList method that sets
up the SelectionInList (step 3). To use a name other than selectedRow, you
must replace selectedRow with the desired name in each Aspect field and in
the code generated for dsvList in step 3. Use the define command (as in
step 15) to generate an instance variable and method with the new name.

Editing Column Properties

selected column

You must select a column before you can set its properties. To select a
column:
1

Select the dataset on the canvas.

Place the cursor inside one of the columns of the dataset.

Hold down the <Control> key while clicking the <Select> mouse
button.

Changing Column Widths

By default, all columns have a width of 80 pixels. You can set specific
widths in the datasets Column properties. You can also change the column
widths by editing the dataset in the canvas. For example, to resize the
Employee Number column:

176

In the canvas, <Control>-click in the Employee Number column to select

it.

Place the cursor near the top right or top left margin of the column.

VisualWorks

Datasets

Click and hold the mouse button. The cursor changes to indicate a
column width change operation when properly selected. If necessary,
move the pointer nearer the corner of the selected column until the
cursor changes appearance.

Drag the cursor to widen or narrow the column.

Install the canvas.

Changing the Column Order

You can switch the order of a datasets columns by editing it in the
canvas. For example, to switch the order of the Employee Number and U.S.
Citizen columns:
1

In the canvas, <Control>-click in the Employee Number column to select

it.

Place the cursor on the drag handle within the selected column.

Click and hold on the handle, and drag it toward the U.S. Citizen
column. The cursor changes to indicate the move operation when
properly selected.

Install the canvas.

Disabling Column Scrolling

You can set a datasets columns so that they cannot be scrolled
horizontally. This is useful if you want to keep one or more columns
displayed on the dataset at all times, while the others continue to scroll.
1

To disable scrolling for a column (and all columns to the left of it),
select that column and click the Fixed check box in the Column
properties.

Apply the property and install the canvas.

Moving the Selection to Another Column

1

Select a column in the dataset using the basic steps.

Click the <Select> mouse button for subsequent column selections.

If you then select another widget on the canvas, you must repeat the
basic steps to reselect a dataset column.

Scrolling Dataset Columns

You can scroll the columns in the dataset you are painting:
1

GUI Developers Guide

Select a column in the dataset.

177

Chapter 9 - Configuring Widgets

Press <Control> while using the mouse to move the scroll bars on the
dataset.

Formatting Column Labels

When you specify a column label by entering a string in the Label
property, you have no formatting control. You can add formatting to a
label by using a ComposedText, which is a graphic, to set the label. (Refer
to Working with Text, Chapter 15 in the Application Developers Guide.)
For example, to split a long label onto two lines, you provide a composed
text that contains the appropriate carriage returns. (See Dataset4Example
in the online examples.) To split the Employee Number column label:
1

Create a class method (number) in a resources protocol of the

application model. This method returns a composed text that is to
appear as the label.
number
^('Employee Number' asText allBold) asComposedText

In the canvas, select the Employee Number column of the dataset.

On the Basics property page, enter number as the Label in the Column
properties.

Select the Image check box next to Label. This specifies that the
column label will come from the resource method named in the Label
property.

Apply the properties and install the canvas.

Similarly, to change the color of the column label, set the text color in the
number method:
number
^('Employee Number' asText emphasizeAllWith:
(Array with: #bold with: #color->ColorValue red))
asComposedText

178

VisualWorks

Datasets

Adding a Row
Online example: Dataset2Example

row marker

When the number of rows needed for a dataset is not predetermined, you
can program your application to add rows while it is running.
1

Use the Palette to add an Action Button to a canvas containing a

dataset. Leave the button selected.

On the Basics property page, enter Add Row as the buttons Label
property and addRow as the buttons Action property. Apply the
properties and install the canvas.

Using the define command or a System Browser, add the instance

method addRow in the actions protocol. This method adds a new
object to the list displayed by the dataset. This, in turn, adds a new
row to the dataset.
addRow
(dsvList list) add: Employee new

Adding a Row Marker

A row marker indicates which row is selected within a dataset. It is used
in place of row highlighting. To add a row marker, check Row Selector on
the datasets Details properties. The marker appears as the first column
within the dataset.
To make the row selector appear as a button, which may be useful to
make it more obviously a clickable option, check , also. Both check boxes
must be checked for this option to be active.

GUI Developers Guide

179

Chapter 9 - Configuring Widgets

Adding Row Numbering

Rows can be automatically numbered by checking the Show Line Numbers
property on the Details page. Numbers show in the same column with the
row selection indicator.

Providing Initial Data

Online example: Dataset3Example
An initially empty dataset is sufficient if you want users to input the data
after the application is open. However, some applications require their
datasets to display data initially.
In the application model, create an initialize method that provides the data
for your dataset.
initialize
| aList anEmp |
aList := List new.
"The aspect for the dataset should be a list of Employee
instances. Create an employee to put in the list."
anEmp := Employee new initialize.
anEmp name: 'Tami Hayes'; empNo: '341-2'; citizen: true.
aList add: anEmp.
"Create an employee to put in the list."
anEmp := Employee new initialize.
anEmp name: 'Leo Mazon'; empNo: '786-9'; citizen: false.
aList add: anEmp.
"Set the list for the dataset aspect. This list appears when you
start."
self dsvList list: aList.
super initialize.

Dataset Events
A Dataset triggers events when a selection is changing, when it gains
and looses focus, when it gets clicks from the mouse, and when it's view
scrolls.
#rightClicked
When a dataset is right clicked on with the <Operate> mouse button,
the dataset triggers the #rightClicked event. This event will occur
without regard to whether there is a popup menu associated with the
dataset.

180

VisualWorks

Datasets

#doubleClicked
When a dataset is double clicked on with the <Select> mouse button,
the dataset triggers the #doubleClicked event. This event is always
immediately preceded by a #clicked event.
#gettingFocus
When a dataset receives focus, either by being tabbed to or by
clicking on by the mouse, the dataset triggers the #gettingFocus event.
#losingFocus
When a dataset loses focus, either by being tabbed away from, or by
having another widget on the canvas gain focus, the dataset triggers
the #losingFocus event.
#tabbed
When a dataset has focus and the last cell in the dataset has focus,
and the Tab key is pressed to the focus to the next widget in the tab
order, and the dataset has its wrapping policy that allows it to tab out
to another widget, the dataset triggers the #tabbed event.
#backTabbed
When a dataset has focus and the first cell in the dataset has focus,
and the Back-Tab (Shift-Tab) key is pressed to movethe focus to the
previous widget in the tab order, and the dataset has its wrapping
policy that allows it to tab out to another widget, the dataset triggers
the #backTabbed event.
#scrollLeft
If while navigating with the keyboard or mouse, or manipulating a
horizontal scroll bar in a dataset, the dataset scrolls to the left, the
dataset triggers the #scrollLeft event.
#scrollRight
If while navigating with the keyboard or mouse, or manipulating a
horizontal scroll bar in a dataset, the dataset scrolls to the right, the
dataset triggers the #scrollRight event.
#scrollUp
If while navigating with the keyboard or mouse, or manipulating a
vertical scroll bar in a dataset, the dataset scrolls up, the dataset
triggers the #scrollUp event.
#scrollDown
If while navigating with the keyboard or mouse, or manipulating a
vertical scroll bar in a dataset, the dataset scrolls down, the dataset
triggers the #scrollDown event.

GUI Developers Guide

181

Chapter 9 - Configuring Widgets

#cellGettingFocus
When an individual cell in a dataset receives focus, either by being
tabbed to or by clicking on by the mouse, the dataset triggers the
#cellGettingFocus event.
#cellLosingFocus
When an individual cell in a dataset loses focus, either by being
tabbed away from, or by having another widget on the canvas gain
focus, the dataset triggers the #cellLosingFocus event.
#cellTabbed
When an individual cell in a dataset has focus, and the and the Tab
key is pressed to move the focus either the next cell in the dataset or
to the next widget in the tab order, the dataset trigger the #cellTabbed
event.
#cellBackTabbed
When an individual call in a dataset has focus, and the Back-Tab
(Shift-Tab) key is pressed in request to mov the focus to either the
previous cell in the dataset or the previous widget in the tab order, the
dataset triggers the #cellBackTabbed event.
#cellValueChanged
If a cell is editable, and its value is changed, once the new value has
been accepted the dataset triggers the #cellValueChanged event. This
occurs when a the value of the underlying input field changes, the
selection of the underlying combo box changes, or the check or
unchecked value of the underlying check box changes.
#columnLabelClicked
If a dataset has column labels, and that column label is clicked on
with the mouse, then the dataset triggers the #columnLabelClicked
event.
#rowLabelClicked
If a dataset has row labels, and the row label is clicked on with the
mouse, then the dataset triggers the #rowLabelClicked event.
#rowSelectionsChanging
If a dataset has row labels and a row label is selected or unselected,
or in the case of multiple select datasets the selections change, or in
the case of a dataset where there are no row labels and the focus
changes from one row to another, then prior to the selection change
taking effect, the dataset triggers the #rowSelectionsChanging event.
#rowSelectionsChanged
If a dataset has row labels and a row label is selected or unselected,
or in the case of multiple select datasets the selections change, or in
the case of a dataset where there are no row labels and the focus
182

VisualWorks

Datasets

changes from one row to another, then after the to the selection
change has occured, the dataset triggers the #rowSelectionsChanged
event.

GUI Developers Guide

183

Chapter 9 - Configuring Widgets

Input Fields
An input field is used for both entering and displaying data. You can also
use a field in read-only mode when you just want to display data.
When a field has a short list of valid entries, consider using a menu
button or a combo box instead.
A field uses a value model to manage its data (see Chapter 4, Adapting
Domain Models to Widgets). When the field accepts input from a user, it
sends this data to the value model for storage; when the field needs to
update its display, it asks its value model for the data to be displayed.

Creating an Input Field

input field

Online example: Slider2Example

1

From the Palette, add a field to the canvas.

On the Basics property page, in the fields Aspect property, enter the
name of the get method for the fields value model.

On the Details page, select or assign values for the fields properties.
The size property takes an integer value for the maximum number of
characters allowed.
The following subsections describe other properties.

184

Apply the properties and install the canvas.

Use the define command to add the instance variable to the

application model and define the aspect accessor method.

Define an initialize method for the aspect instance variable, or add

initialization to the aspect accessor method, and evaluate the method
to initialize the variable.

VisualWorks

Input Fields

In this example, the variable is initialized to the desired month using an

initialize method.
initialize
month := (Date nameOfMonth: 1) asValue.
year := 1900 asValue.
dateRange := (0@1) asValue.
dateRange onChangeSend: #changedDate to: self.

Restricting Input Type

You specify the type of input that a field is to accept by setting its Type
property. This property converts the input string into an appropriate kind
of object before sending it to the value model. If the conversion cannot be
performed, the field flashes and continues to display the unaccepted
string without storing it in its value model.
Note: Ensure that the field is initialized with the appropriate type of
data.
You can choose from the following data types. If none of these types are
appropriate, you can add your own type testing.

GUI Developers Guide

Data Type

Description

String

Input is stored as a ByteString. (Default)

Symbol

Input is stored as a Symbol. Useful for applications that

manipulate method selectors.

Text

Input is stored as an instance of Text, and supports

formatting.

Number

Input is stored as an appropriate subclass of Number.

Password

Input is stored as a string, with an asterisk (*) displayed

for each character the user enters. (The actual
characters are sent to the fields value model.)

Date

Input is converted into an instance of Date.

Time

Input is converted into an instance of Time.

Timestamp

Input is converted into an instance of Timestamp.

FixedPoint(2)

Input is converted to a FixedPoint with two decimal

places. Useful for applications that manipulate
monetary amounts.

Boolean

Input is stored as an instance of Boolean. Accepts true

and false only.

185

Chapter 9 - Configuring Widgets

Data Type

Description

ByteArray

Input is stored as an instance of ByteArray.

Object

Input is evaluated as a Smalltalk expression, and the

resulting object is stored as the fields value. The field
redisplays this object using the objects printString
method. Note that the VisualWorks compiler is required
to run an application with Object as the data type for an
input field. This is permitted by the license, and the
compiler is not automatically removed by
RuntimePackager.

Formatting Displayed Data

For some data types, the displayed string can be formatted in various
ways. For example, numbers can be formatted as phone numbers,
monetary units, percentages, and so on.
Predefined data type formats are provided by drop-down lists on the
Basics properties page. The fields Type property setting determines the
kinds of available formats, if any.
For a description of the format conventions, browse the class comments
for the NumberPrintPolicy, TimestampPrintPolicy, and StringPrintPolicy
classes.

Creating a Custom Format

Online example: FieldTypeExample
A TypeConverter enables a field to display a number in a special format,
such as a monetary format. You define the format as a string that uses
the same conventions as the predefined formats.
Edit the aspect accessor method to initialize the value to a TypeConverter,
and specify the format string. This example shows how to create a format
for a monetary amount.
price
^price isNil
ifTrue: [price := (TypeConverter
onNumberValue: 0 asValue
format: '$###,###,###.##')]
ifFalse: [price]

186

VisualWorks

Input Fields

Validating Input
Frequently, only certain entries are valid for a particular field. For
example, you might want to restrict input to a numeric range such as 0 to
999 or check for undesirable characters.
For a general description of the Validation properties, refer to Validation
Properties in Chapter 3.
Data can be validated either a whole-field at a time, or character by
character. The following subsections describe a few variations on these
options.

Validating a Whole Entry

Online example: FieldValidInputExample
Most often you only need to validate an entire entry in a field. To do this,
you need to specify and define the validation message which is sent
when appropriate based on the users actions.
1

On the Validation page of the GUI Painter Tool, enter the names of
validation methods for one or more of the validation points.
In the example, we use:

the Change property, to determine whether to accept input into the

fields value model

the Exit property, to determine whether the field can give up focus

Both send validateUsername:.

2

On the Basics property page, enter the aspect name (username).

Apply properties and install the canvas, and use define to add the
aspect instance variable (username) and aspect method (username) to
the application model. Initialize the instance variable with a value
model.

Create the validation method (validateUsername:) entered in the

validation fields.

Because the Change validation needs to validate the data before it is sent
to the fields value holder, the validation method needs to get the entered
value from the widgets controller. By naming the method so its selector
ends in a colon, the widget sends the controller as an argument, which
the method can then use.

GUI Developers Guide

187

Chapter 9 - Configuring Widgets

In the validation method, send an editValue message to the fields

Controller to obtain the users entry. The entry must be obtained from the
controller instead of the value model, because validation occurs before
the entry has been passed to the value model.
The validation in the example consists of checking the entrys length.
If the entry is valid, the validation method returns true, allowing the field to
pass the entry to the value model and, if requested, give up focus. If the
entry is not valid, the method must return false. In the example, a warning
is also returned, telling the user to correct the entry.
validateUsername: aController
"Check the length of the entered username. Warn the user if the
entered input is too long."
| entry lengthLimit |
lengthLimit := 6.
entry := aController editValue.
"If the username is too long, warn the user (and reject
the input)."
^entry size <= lengthLimit
ifTrue: [true]
ifFalse: [Dialog warn: Please enter only , lengthLimit
printString ,
characters..
false]

Validating Individual Characters

Online example: FieldValidation1Example
In some cases, it is more useful to verify the users entry at each
keystroke. This approach requires more constant monitoring of the
widget.
1

On the Basics property page, in the ID field, enter an identifier for the
field (codeField). Apply the property and install the canvas.

Define a postBuildWith: instance method in the application model

(FieldValidation1Example).
In this method, the first task is to get the controller from the field.
Next, it sends a keyboardHook: message to the controller. The
argument to keyboardHook: is a two-argument block that takes the
keyboard event and the controller as arguments.
Inside the block, invoke the validation method (keyPress:).
Alternatively, you can put the validation code directly inside the block.

188

VisualWorks

Input Fields

postBuildWith: aBuilder
| ctrlr |
ctrlr := (self controllerAt: #codeField).
ctrlr keyboardHook: [ :ev :c |
self keyPress: ev].
3

Define the validation method (keyPress:).

This method takes the keyboard event as its argument, extracts a
character, and validates it.
As the last step in the keyPress: method, return the event when you
want to forward the keyboard event for normal processing. Return nil
to bypass normal processing.
keyPress: ev
"Validate the character."
| ch ascii |
ch := ev keyValue.
"Allow tab and cr."
ascii := ch asInteger.
(ascii == 9 or: [ascii == 13])
ifTrue: [^ev].
ch isAlphaNumeric
ifFalse: [
Dialog warn: 'Please enter only letters and digits'.
^nil].
^ev

Modifying a Fields Pop-Up Menu

Online example: FieldMenuExample
By default, a field has a menu of text-editing commands. You can add or
omit commands, override the action that is associated with a command,
or disable the menu entirely.
A fields menu is usually oriented toward commands. Although you can
arrange for a fields menu to contain a list of valid entries, this is properly
the job of a menu button.

Adding a Command
1

GUI Developers Guide

In the fields Menu property, enter the name of the method that you will
create to supply a custom menu (expandedMenu).

189

Chapter 9 - Configuring Widgets

Define the menu-creating method (expandedMenu) in the application

model, in a menu messages protocol.
expandedMenu
"Add a command to the default text-editing menu."
| mb |
mb := MenuBuilder new.
mb
add: 'capitalize'->#capitalize;
line;
addDefaultTextMenu.
^mb menu

Define the method (capitalize) that is invoked by the newly added

command. Put the method in the menu messages protocol.
capitalize
"Capitalize the field's contents."
self field1 value: (self field1 value
collect: [ :ch | ch asUppercase]).

Overriding a Default Command

You can override a default command by building the menu from its parts.
For the command that you want to override, provide the name of your
overriding method as the value (#newAccept).
newAcceptMenu
"Redefine the 'accept' command by invoking a local alternate."
| mb |
mb := MenuBuilder new.
mb
addFindReplaceUndo;
line;
addCopyCutPaste;
line;
add: 'accept'->#newAccept;
add: 'cancel'->#cancel.
^mb menu
Then define the overriding method (newAccept).
newAccept
Transcript show: self field3 value; cr.

190

VisualWorks

Input Fields

Disabling a Fields Menu

To disable the menu, build a menu creation method that returns a block
containing nil. When asked for its menu, the field will evaluate this block,
and no menu is displayed.
noMenu
^[nil]

Connecting two Fields

Online example: FieldConnectionExample
When the value in a field depends on the value in another field, you can
link them using the built-in dependency mechanism. The connection can
be either one-way or two-way, depending on the needs of your
application.
To define the dependency, you must register an interest between the
fields. Create a postBuildWith: method in the application model, in an
interface opening protocol, and register the interest in the field that
originates updates. In the onChangeSend:to: method, name a method to be
invoked when that field is changed (changedA).
postBuildWith: aBuilder
self a onChangeSend: #changedA to: self.
Then define the change method (changedA) in the application model in a
change messages protocol. That method updates the dependent fields
model.
changedA
self aSquared value: (self a value raisedTo: 2).

Controlling the Insertion Point

You can control the position of the insertion point in a field

programmatically. For example, the data in a field might have a prefix that
rarely changesyou could highlight the suffix for convenient editing. In
that case, the insertion point is actually a portion of the fields text,
which will be replaced by the users entry.
When the suffix has yet to be filled in, you can simply position the
insertion point at the end of the prefix.
GUI Developers Guide

191

Chapter 9 - Configuring Widgets

Highlighting a Portion of a Field

Online example: FieldSelectionExample
1

In a method in the application model, ask the fields wrapper to

takeKeyboardFocus.

Tell the fields controller the indices (character positions) of the

substring that is to be highlighted.
addPart
"Put a template in the partID field, then highlight the suffix."
| wrapper |
self partID value: 'MW-0000'.
wrapper := self wrapperAt: #part1.
wrapper takeKeyboardFocus.
wrapper widget controller selectFrom: 4 to: 7.

Positioning the Insertion Point

1

In a method in the application model, ask the fields wrapper to

takeKeyboardFocus.

Tell the fields controller the character position at which to place the
insertion point.
addPart2
"Put a template in the partID2 field, then position the insertion
point."
| wrapper |
self partID2 value: 'MW-'.
wrapper := self wraooerAt: #part2.
wrapper takeKeyboardFocus.
wrapper widget controller selectAt: 4.

Input Field Events

An Input Field triggers events when its value is changing, when it gains
and looses focus, when it gets clicks from the mouse, and when it's view
scrolls to the left or right.
#changing
When the value of an input field is about to be accepted after directly
editing the value and exiting the input field, the input field triggers the
#changing event.

192

VisualWorks

Input Fields

#changed
After the value of the input field has been accepted, the input field
triggers the #changed event.
#clicked
When a input field is clicked on with the <Select> mouse button, the
input field triggers the #clicked event.
#rightClicked
When a input field is right clicked on with the <Operate> mouse
button, the input field triggers the #rightClicked event. This event will
occur without regard to whether there is a popup menu associated
with the input field.
#doubleClicked
When a input field is double clicked on with the <Select> mouse
button, the input field will trigger the #doubleClicked event. This event
is always immediately preceded by a #clicked event.
#gettingFocus
When a input field receives focus, either by being tabbed to or by
clicking on by the mouse, the input field triggers the #gettingFocus
event.
#losingFocus
When a input field loses focus, either by being tabbed away from, or
by having another widget on the canvas gain focus, the input field
triggers the #losingFocus event.
#tabbed
When a input field has focus, and the Tab key is pressed in request to
have the focus to move to the next widget in the tab order, the input
field triggers the #tabbed event.
#backTabbed
When a input field has focus, and the Back-Tab (Shift-Tab) key is
pressed to move the focus to the previous widget in the tab order, the
input field triggers the #backTabbed event.
#scrollLeft
If while editing, navigating with the keyboard, or selecting text with the
keyboard or mouse in an input field, the view scrolls to the left, the
input field triggers the #scrollLeft event.
#scrollRight
If while editing, navigating with the keyboard or selecting text with the
keyboard or mouse in an input field, the view scrolls to the right, the
input field triggers the #scrollRight event.

GUI Developers Guide

193

Chapter 9 - Configuring Widgets

Hierarchical Lists
Note: The Hierarchical List widget will be deprecated in a future
release, in favor of the Tree View widget. Unless you need
functionality in the Hierarchical List that is not currently provided by
Tree View, please use Tree View. The missing functionality will be
added to Tree View before Hierarchical List is deprecated.
A Hierarchical List widget is similar to a List widget, but its primary
component is an IndentedTreeSelectionInList. This object holds a tree object
representing the hierarchy.
For cases where the hierarchical list is displaying a natural hierarchy,
such as the class hierarchy, IndentedTreeSelectionInList provides instance
creation methods to create the tree. Otherwise, create the tree using
instances of AssociationTreeWithParent.
Retrieving the index and contents of a list item uses the same methods
as for a List widgets SelectionInList.

Adding a List
1

Use a Palette to add a Hierarchical List widget to the canvas. Leave

the list selected.

On the Basics property page, fill in the lists Aspect property with the
name of the method that will return an instance of
IndentedTreeSelectionInList.

Apply the change, install the canvas, and use define to add an instance

variable and aspect accessor method to the application model. This

instance variable will hold the SelectionInList.
4

Write an initialize method to initialize the IndentedTreeSelectionInList.

Create a List for a Natural Tree

The IndentedTreeSelectionInList class has a few instance creation methods
that make it easy to create a tree out of an object with a natural hierarchy.
For instance, the class method
#listObjectHierarchy:childAccessor:childNameAccessor: can create an
appropriate list object as follows:

194

VisualWorks

Hierarchical Lists

initialize
theList := IndentedTreeSelectionInList
listObjectHierarchy: Object
childAccessor: #allSubclasses
childNameAccessor: #name.
^self
For other instance creation convenience methods, browse the instance
creation protocol.

Building a Tree
You can build a hierarchy of arbitrary objects using instances of
AssociationTree or AssociationTreeWithParent. Then use the tree as the
source of the hierarchy for the Hierarchical List widget.
This version of the initialize method creates a hierarchy:
initialize
tree := (AssociationTreeWithParent key: 'first' value: #first).
tree addChild:
((AssociationTreeWithParent
key: 'second'
value: #second)
addChild: (AssociationTreeWithParent
key: 'third'
value: #third);
addChild: (AssociationTreeWithParent
key: 'fourth'
value: #fourth));
addChild: ((AssociationTreeWithParent
key: 'fifth'
value: #fifth)
addChild: (AssociationTreeWithParent
key: 'sixth'
value: #sixth);
addChild: (AssociationTreeWithParent
key: 'seventh'
value: #seventh)).
myList := IndentedTreeSelectionInList
listObjectHierarchy: tree
childAccessor: #children
childNameAccessor: #displayString.
^self

GUI Developers Guide

195

Chapter 9 - Configuring Widgets

Hierarchical List Events

A Hierarchical List triggers events when a selection is changing, when the
underlying list itself is changing, when it gains and looses focus, when it
gets clicks from the mouse, when a node is expanded or collapsed, and
when it's view scrolls.
#clicked
When a hierarchical list is clicked on with the <Select> mouse button,
the hierarchical list triggers the #clicked event.
#rightClicked
When a hierarchical list is right clicked on with the <Operate> mouse
button, the hierarchical list triggers the #rightClicked event. This event
will occur without regard to whether there is a popup menu
associated with the hierarchical list.
#doubleClicked
When a hierarchical list is double clicked on with the <Select> mouse
button, the hierarchical list triggers the #doubleClicked event. This
event is always immediately preceded by a #clicked event.
#gettingFocus
When a hierarchical list receives focus, either by being tabbed to or
by clicking on by the mouse, the hierarchical list triggers the
#gettingFocus event.
#losingFocus
When a hierarchical list loses focus, either by being tabbed away
from, or by having another widget on the canvas gain focus, the
hierarchical list triggers the #losingFocus event.
#tabbed
When a hierarchical list has focus, and the Tab key is pressed to
move the focus to the next widget in the tab order, the hierarchical list
triggers the #tabbed event.
#backTabbed
When a hierarchical list has focus, and the Back-Tab (Shift-Tab) key
is pressed to move the focus to the previous widget in the tab order,
the hierarchical list triggers the #backTabbed event.
#scrollLeft
If while navigating with the keyboard or manipulating a horizontal
scroll bar in a hierarchical list, the hierarchical list scrolls to the left,
the hierarchical list triggers the #scrollLeft event.

196

VisualWorks

Hierarchical Lists

#scrollRight
If while navigating with the keyboard or manipulating a horizontal
scroll bar in a hierarchical list, the hierarchical list scrolls to the right,
the hierarchical list triggers the #scrollRight event.
#scrollUp
If while navigating with the keyboard or manipulating a vertical scroll
bar in a hierarchical list, the hierarchical list scrolls up, the
hierarchical list triggers the #scrollUp event.
#scrollDown
If while navigating with the keyboard or manipulating a vertical scroll
bar in a hierarchical list, the hierarchical list scrolls down, the
hierarchical list triggers the #scrollDown event.
#selectionChanging
When an item in a hierarchical list is selected or unselected, before
the change is applied, the hierarchical list triggers the
#selectionChanging event.
#selectionChanged
After an item in a hierarchical list is selected or unselected, the
hierarchical list triggers the #selectionChanged event.
#selectionListChanged
Whenever the list underlying a hierarchical list is manipulated, either
by changing a value, reordering, adding or removing items, or
changing the list as a whole, the hierarchical list triggers the
#selectionListChanged event.
#itemExpanded
When an item in the hierarchical list is visually toggled from its
collapsed view to its expanded view, the hierarchical list triggers the
#itemExpanded event.
#itemCollapsed
When an item in the hierarchical list is visually toggled from its
expanded view to its collapsed view, the hierarchical list triggers the
#itemCollapsed event.

GUI Developers Guide

197

Chapter 9 - Configuring Widgets

Labels
Online example: LogoExample
A label is used as a title or a description for another widget or group of
widgets, such as a field. Since the text of a label can be changed while
the application is running, a label can also be used for read-only display.
A label accommodates only a single line of text. For a multiline label, use
a separate label for each line or use a read-only text widget.

Creating a Textual Label

To add a text label, select the Label widget and place it on the canvas.
On the Basics properties page, enter the text in the labels Label property
field. Then Apply the properties and Install the canvas.
The label size automatically adjusts to accommodate your text.

Creating a Graphic Label

Use a graphic label when you want to add a pictorial element to an
interface. The graphic can be changed while the application is running, so
you can also use a graphic label to represent a changing aspect of the
model pictorially.
A graphic label is passive. If you need the graphic to respond to a mouse
click, use a graphic button instead.
For a large graphic that requires scroll bars, insert the graphic in a view
holder instead.
To add a graphic label:
1

Use a Palette to place a label widget on the canvas

On the Basics property page, in the labels Label property, enter the
name of the method that will supply the graphic image (in the
example, logo).
The method must be a class method, and by convention is placed in
the resources protocol.

Turn on the Label is Image property.

The Supplied by Application property is turned on as well, because the
graphic will be supplied by the method named in step 2.

198

Apply the properties and install the canvas.

VisualWorks

Labels

You can use the Image Editor to create the graphic image and install it in
the application model, using the method name from step 2. You can also
draw the image using graphics classes in VisualWorks, and create the
class method to return it in the application model.

Making a Label Mnemonic

Adding a mnemonic to a label causes the cursor to jump to the selected
widget when <Alt><key> is pressed.
The <key> is specified by including an ampersand (&) in the label string
before the mnemonic letter. For example, if the label is Label, you could
make L the mnemonic by changing the label string to '$Label' in the labels
String: field. The label will show with the L underscored.
To associate the mnemonic with a widget, enter the widget ID in the
labels Details page, in the Mnemonic: field.

Supplying the Label at Run Time

An application can change the content of a label while it is running. This
is useful for using a label as a read-only display field.
Because the label changes size dynamically, be careful selecting text to
avoid overlapping neighboring widgets.
To change the label, get the widget from the application models builder.
Then, set the label by sending a labelString: message to it with a string
argument, or by sending a label: message to it with a composed text or
graphic as the argument.
The following example updates a label before the canvas is opened, but
you can change the label string at any time after the interface has been
built.

GUI Developers Guide

199

Chapter 9 - Configuring Widgets

postBuildWith: aBuilder
"Update the slogan's text, and make the company name bold and red."
| slogan txt emph label |
"Insert the years-in-business into the slogan."
slogan := 'Serving Shrimps For '
, (Date today year - 1869) printString, ' Years'.
( self wrapperAt: #slogan ) labelString: slogan.
"Make the company name bold and red."
txt := 'Many Hands Shrimppickers' asText
emph := Array
with: #bold
with: #color->ColorValue red.
txt emphasizeFrom: 1 to: 10 with: emph.
label := Label
with: txt
attributes: (TextAttributes styleNamed: #large).
(self wrapperAt: #textLogo) label: label.

Building a Registry of Labels

When you plan to use a label, such as a company name or logo, in
multiple interfaces, you can store it in a central registry. The system will
look for the label in the registry when it does not find the usual resource
method. Two system registries are available, one for graphics and the
other for strings.
Registering a label is usually done in a class-initialization method, so the
registration will occur whenever the class loaded into an image.
Note: Use registries sparingly, especially for graphic images,
because each entry occupies memory until it is explicitly removed.
For a non-registry alternative, consider using a preBuildWith:
message, as done in NamedFontSelector.
To register a graphic image, send visualAt:put: to ApplicationModel. To
register a string label, send labelAt:put: to ApplicationModel. The first
argument is the name of the label, as defined in the Label property of the
widget. The second argument is the graphic or string.

200

VisualWorks

Labels

initialize
"LogoExample initialize"
"Register the graphic image for the trademark symbol."
ApplicationModel
visualAt: #trademark
put: self trademark.
"Register the textual version of the trademark symbol."
ApplicationModel
labelAt: #tm
put: '(TM)'.
Execute the initialization method to make the label available.
To remove a label from the registry, get the appropriate registry by
sending a visuals message to the ApplicationModel class for the graphics
registry, or a labels message for the string registry. Then send the
removeKey:ifAbsent: to the registry specifying the name of the label as the
first argument. The second argument is a block specifying the action to
be take if the label is not found, and can be empty.
"Visual registry"
| registry |
registry := ApplicationModel visuals.
registry removeKey: #trademark ifAbsent: [].
"Labels registry"
registry := ApplicationModel labels.
registry removeKey: #tm ifAbsent: [].

Label Events
Labels and Group Boxes trigger events only when their labels are
changing.
#labelChanging
When a label or group box's label is about to change, the widget
triggers the #labelChanging event.
#labelChanged
After a label or group box's label has changed, the widget triggers the
#labelChanged event.

GUI Developers Guide

201

Chapter 9 - Configuring Widgets

Lists
Online example: List1Example
A list widget is useful for displaying a collection of objects or as an input
device, allowing the user to select one or more elements in the list.
A list widget depends on two value models, one to hold the collection of
objects to be displayed, and the other to hold the index of the current
selection. A SelectionInList is a complex object that contains both of the
required value holders.
The List collection is particularly well suited for use with the List widget,
rather than other sequenced collections. It is extensible, and propagates
change messages to its dependents.
The elements in the collection can be any objects, provided that they can
display themselves textually.

Adding a List
1

Use a Palette to add a list widget to the canvas. Leave the list
selected.

On the Basics property page, fill in the lists Aspect property with the
name of the method that will return an instance of SelectionInList.

Use define to add an instance variable and aspect accessor method to

the application model. This instance variable will hold the
SelectionInList.

Write an initialize method to initialize the instance variable. You

initialize the variable with an instance of SelectionInList that is itself
initialized with a list of Smalltalk class names.
initialize
super initialize.
classes := SelectionInList with: Smalltalk classNames.
classes selectionIndexHolder onChangeSend: #changedClass
to: self.
methodNames := MultiSelectionInList new.
instances := SelectionInList new.

Editing the List of Elements

The contents of a list often change frequently. In List1Example, both the
Selectors view and the Instances view change whenever the selection in
the Classes view is changed.
202

VisualWorks

Lists

Changing the list is accomplished by giving the SelectionInList a new

collection of elements. Note that this is not the same as installing an
entirely new SelectionInList, which would break the link with the list widget.
In the method that is responsible for updating the list, get the
SelectionInList from the application model and send a list: message to it,
with the new List as the argument.
changedClass
| cls |
self classes selection isNil
"No class is selected -- empty the selector list."
ifTrue: [
self methodNames list: List new.
self instances list: List new]
"A class is selected"
ifFalse: [
cls := Smalltalk at: self classes selection.
"Update the selectors list."
self methodNames list: cls selectors asList.
"Update the instances list."
self instances list: cls allInstances].

Enabling Multiple Selections

Sometimes it is appropriate for the user to select more than one item in a
list as targets for an action. A list allows multiple selections when its Multi
Select property is turned on.
A second property, Use Modifier Keys For Multi Select, determines how
selections are to be made. When this property is turned on (the default),
the user:

Clicks the <Select> mouse button to select a single item on the list

<Shift>-clicks to select additional contiguous items

<Control>-clicks to select additional noncontiguous items

Both properties are typically turned on or off together.

1

GUI Developers Guide

On the Details property page, check List widgets Multi Select property,
and make sure the Use Modifier Keys For Multi Select property is also
checked. Apply properties and install the canvas.

203

Chapter 9 - Configuring Widgets

In the application models initialize method, initialize the list widgets

aspect variable to hold a MultiSelectionInList (instead of a
SelectionInList).
initialize
super initialize.
classes := SelectionInList with: Smalltalk classNames.
classes selectionIndexHolder onChangeSend: #changedClass
to: self.
methodNames := MultiSelectionInList new.
instances := SelectionInList new.

Getting a Selection Contents

When a list widget serves as an input device, your application needs to
be able to find out which object is selected. You can ask a SelectionInList
for the selected object or for the index of the selected object in the list.
You can also set the selection programmatically.
For a multiselect list, there may be multiple selections or selection
indexes, so your application model must be prepared to handle a
collection of objects rather than a single selection or index.
When nothing is selected, a SelectionInList returns a nil object as the
selection and zero as the index; a MultiSelectionInList returns an empty
collection for either the selections or the indexes.
In the method that needs to know the current selection in the list, get the
SelectionInList from the application model and send a selection message to
it. To get the index only, send selectionIndex. For a MultiSelectionInList, use
a selections or selectionIndexes message.

204

VisualWorks

Lists

changedClass
| cls |
self classes selection isNil
"No class is selected -- empty the selector list."
ifTrue: [
self methodNames list: List new.
self instances list: List new]
"A class is selected"
ifFalse: [
cls := Smalltalk at: self classes selection.
"Update the selectors list."
self methodNames list: cls selectors asSortedCollection.
"Update the instances list."
self instances list: cls allInstances].

Setting a Selection
It is sometimes useful for a program to set the selection.
To set a list selection, in the method that is to change the selection, get
the SelectionInList from the application model and send it a selectionIndex:
message with the desired index number as the argument. Alternatively,
send a selection: message with the desired object itself as the argument.
postOpenWith: aBuilder
super postOpenWith: aBuilder.
"Uncomment the line below to auto-select the first class."
self classes selectionIndex: 1.
"Uncomment the lines below to auto-select the last class."
"self classes selection: self classes list last.
(self controllerAt: #classes) cursorPointWithScrolling."
"In the classes list, use boxed highlighting instead of
reverse-video."
(self widgetAt: #classes) strokedSelection.
Note that, for a MultiSelectionInList, send selectionIndexes: or selections:,
supplying as argument a collection of indexes or a collection of objects in
the list.
To select all objects in a multiple-selection list, get the MultiSelectionInList
from the application model and send a selectAll message to it.
GUI Developers Guide

205

Chapter 9 - Configuring Widgets

selectAll
self methodNames selectAll.
Similarly, to clear all selections, get the MultiSelectionInList from the
application model and send a clearAll message to it.
clearAll
self methodNames clearAll.

Connecting Two Lists

A list widget frequently interacts with another list, for example if one list
contains items in a selection and the other list contains items that are
out.
To connect two lists, you register an interest between them. In the
application models initialize method, arrange for a change message to be
sent to the application model whenever the selection is changed in the
first list.
initialize
super initialize.
classes := SelectionInList with: Smalltalk classNames.
classes selectionIndexHolder
onChangeSend: #changedClass to: self.
methodNames := MultiSelectionInList new.
instances := SelectionInList new.
Then define the change method in the application model. This method
tests whether anything is selected in the first list (classes) and then
updates the second list (methodNames) appropriately.
changedClass
| cls |
self classes selection isNil
"No class is selected -- empty the selector list."
ifTrue: [
self methodNames list: List new.
self instances list: List new]
"A class is selected"
ifFalse: [
cls := Smalltalk at: self classes selection.

206

VisualWorks

Lists

"Update the selectors list."

self methodNames list: cls selectors asSortedCollection.
"Update the instances list."
self instances list: cls allInstances].

List Events
A List Box triggers events when a selection is changing, when the
underlying list itself is changing, when it gains and looses focus, when it
gets clicks from the mouse, and when it's view scrolls.
#clicked
When a list box is clicked on with the <Select> mouse button, the list
box triggers the #clicked event.
#rightClicked
When a list box is right clicked on with the <Operate> mouse button,
the list box triggers the #rightClicked event. This event will occur
without regard to whether there is a popup menu associated with the
list box.
#doubleClicked
When a list box is double clicked on with the <Select> mouse button,
the list box triggers the #doubleClicked event. This event is always
immediately preceded by a #clicked event.
#gettingFocus
When a list box receives focus, either by being tabbed to or by
clicking on by the mouse, the list box trigger the #gettingFocus event.
#losingFocus
When a list box loses focus, either by being tabbed away from, or by
having another widget on the canvas gain focus, the list box triggers
the #losingFocus event.
#tabbed
When a list box has focus, and the Tab key is pressed in request to
have the focus to move to the next widget in the tab order, the list box
triggers the #tabbed event.
#backTabbed
When a list box has focus, and the Back-Tab (Shift-Tab) key is
pressed to move the focus to the previous widget in the tab order, the
list box triggers the #backTabbed event.

GUI Developers Guide

207

Chapter 9 - Configuring Widgets

#scrollLeft
If while navigating with the keyboard or manipulating a horizontal
scroll bar in a list box, the list box scrolls to the left, the list box
triggers the #scrollLeft event.
#scrollRight
If while navigating with the keyboard or manipulating a horizontal
scroll bar in a list box, the list box scrolls to the right, the list box
triggers the #scrollRight event.
#scrollUp
If while navigating with the keyboard or manipulating a vertical scroll
bar in a list box, the list box scrolls up, the list box triggers the
#scrollUp event.
#scrollDown
If while navigating with the keyboard or manipulating a vertical scroll
bar in a list box, the list box scrolls down, the list box triggers the
#scrollDown event.
#selectionChanging
When an item in a list box is selected or unselected, or in the case of
a multiple select list box, the selections change, before the change is
applied, the list box triggers the #selectionChanging event.
#selectionChanged
After an item in a list box is selected or unselected, or in the case of a
multiple select list box, the selections have changed, the list box
triggers the #selectionChanged event.
#selectionListChanged
Whenever the list underlying a list box is manipulated, either by
changing a value, reordering, adding or removing items, or changing
the list as a whole, the list box triggers the #selectionListChanged event.

208

VisualWorks

Lists

GUI Developers Guide

209

Chapter -

Menu Button

menu button

A menu button allows you to place a drop-down menu anywhere in the

canvas. Also, its label typically changes to reflect the current selection. By
default, selecting an item in a button menu places the value of the menu
item in the button menu widgets aspect value holder.

Adding a Menu Button

Online example: MenuValueExample
1

Add a menu button widget to the canvas and open the Properties
Tool.

In the menu buttons Menu property, enter the name of the menu
creation resource method (templatesMenuForMenuButton).

In the buttons Aspect property, enter a name for the aspect (letter).
Leave the buttons Label property blank. You can enter a label, but it
will always be displayed in the menu. Leaving the Label blank displays
the current selection on the menu button while the application is
running. The initial (default) selection is set by initializing the aspect
variable, typically in the initialize method.

Use the define command to add the aspect instance variable and
accessor method (letter) to the application model.

Create or edit the initialize method to initialize the aspect variable to a

value holder.
Initializing the aspect variable also sets the initial item displayed on
the menu button. This example also illustrates setting a check mark
on the currently selected item.
initialize
letter := self class firstNotice asValue.
letter onChangeSend: #setCheckMark to: self.

210

VisualWorks

Menu Button

Create the menu resource method that you named in step 2, and any
action methods that are invoked by the menu items.

Adding a Menu Button with a Menu of Commands

Online example: MenuCommandExample
Adding a Button Menu that executes a command, such as an action
block, differs from a Button Menu that stores a value in the initialization of
the value holder. The value holder must be configured to perform its value
whenever it is changed. This is typically done in an initialize method:
initialize
files := SelectionInList new.
files selectionIndexHolder onChangeSend: #configureMenu
to: self.
action := nil asValue.
action onChangeSend: #performAction to: self.
You also must define a method that performs the currently selected
action:
performAction
self perform: self action value.

Menu Button Events

A Menu Button triggers events when its value is changing, when it gains
and looses focus, when it gets clicks from the mouse, and when its list is
exposed and closed.
#changing
When a selection in the list of a menu button is made, but before the
value is accepted, the menu button triggers the #changing event.
#changed
After a selection in the list of a menu button is made and the value is
accepted, the menu button triggers the #changed event.
#clicked
When a menu button is clicked on with the <Select> mouse button,
the menu button triggers the #clicked event.
#gettingFocus
When a menu button receives focus, either by being tabbed to or by
clicking on by the mouse, the menu button triggers the #gettingFocus
event.

GUI Developers Guide

211

Chapter -

#losingFocus
When a menu button loses focus, either by being tabbed away from,
or by having another widget on the canvas gain focus, the menu
button triggers the #losingFocus event.
#tabbed
When a menu button has focus, and the Tab key is pressed in
request to have the focus to move to the next widget in the tab order,
the menu button triggers the #tabbed event.
#backTabbed
When a menu button has focus, and the Back-Tab (Shift-Tab) key is
pressed to move the focus to the previous widget in the tab order, the
menu button triggers the #backTabbed event.
#listExposed
When a menu button has its selection list exposed, either by clicking
on the menu button or using the down arrow key to open the list, the
menu button triggers the #listExposed event.
#listClosed
When a menu button has its selection list closed, either by clicking on
another widget on the canvas, by clicking on the menu button when
the list is already exposed, or by selecting a new value in an exposed
list, the menu button triggers the #listClosed event.

212

VisualWorks

Notebook

Notebook

Selecting a tab
causes a different page
of the notebook to be
displayed

A notebook is a powerful navigational widget. At its simplest, it provides a

list in the form of index tabs. When the user selects an index tab, the
effect is the same as selecting an item in a conventional list. A notebook
can be used in many of the same situations in which a list or a menu
might be used, but its richer set of capabilities (such as minor keys)
extend its range of uses.
A notebook also contains a subcanvas which can be used to display a
different interface for each index tab or, as in this simple example, the
same interface.
In Notebook1Example, the subcanvas contains a list widget, and the list is
changed each time an index tab is selected.

Creating a Notebook
Online example: Notebook1Example

GUI Developers Guide

Add a notebook widget to the canvas.

On the Basics page, enter the:

Major property aspect name, the aspect that returns a

SelectionInList containing major index tab labels

Minor property aspect name, the aspect that returns a

SelectionInList containing minor index tab labels (optional)

ID property, then identifying name for the notebook (pageHolder)

213

Chapter 9 - Configuring Widgets

Apply the properties and install the canvas, and define the instance
variables and accessing methods for the notebooks major and minor
index labels.

Initialize the major and minor variable, either in the accessing method
or in an initialize method (as in the example), with a SelectionInList
containing either strings or associations.

Create one or more additional canvases for the interface to display

inside the notebook.
Install this canvas in its own resource method (listSpec), but in the
same application model as the notebook, and define any variables
and methods needed by the subcanvas. (In the example, these are
the classNames variable, the classNames method, and the initialize
method.)
For a notebook that uses different interfaces for each page, you will
create several of these canvases.

Edit the initialize method to send an onChangeSend:to: message to

send a changed message (changedLetter) to the application model
when the user selects an index tab.
initialize
| letters |
letters := #( ' A' ' B' ' C' ' D' ' E' ' F' ' G' ' H' ' I' ' J' ' K' ' L' ' M'
' N' ' O' ' P' ' Q' ' R' ' S' ' T' ' U' ' V' ' W' ' X' ' Y' ' Z' ).
majorKeys := SelectionInList with: letters.
majorKeys selectionIndexHolder
onChangeSend: #changedLetter to: self.
classNames := SelectionInList new.

Create the change message (changedLetter) to update the subcanvas.

changedLetter
| chosenLetter list |
chosenLetter := self majorKeys selection last.
list := Smalltalk classNames
select: [ :name | name first == chosenLetter].
self classNames list: list.

Create a postOpenWith: method to install the subcanvas.

In this method, get the notebook from the application models builder,
using the notebooks ID (pageHolder). Then install the subcanvas by
sending a client:spec: message to the notebook. The first argument is
the subcanvass application model (self), and the second argument is
the subcanvass spec method (listSpec).

214

VisualWorks

Notebook

postOpenWith: aBuilder
(self widgetAt: #pageHolder)
client: self
spec: #listSpec.
majorKeys selectionIndex: 1.

Setting the Starting Page

Online example: Notebook1Example
By default, a notebook opens on a blank page, but another page provides
better visual clues to the user as to the nature of the notebook. You can
select the opening page either by setting the selection indexes of the
major and minor SelectionInLists, or by specifying the list element itself.
In an instance method (such as postOpenWith:), send a selectionIndex:
message to the SelectionInList that holds the major keys. The argument is
the index of the desired tab.
postOpenWith: aBuilder
(self widgetAt: #pageHolder)
client: self
spec: #listSpec.
majorKeys selectionIndex: 1.
If the notebook has minor keys, also set the selection index for that
SelectionInList.
Alternatively, to set the page by specifying the list element, send a
selection: message to the SelectionInList that holds the major keys and, if
applicable, another such message to the minor list. The argument is the
desired element in the list.

Getting the Selected Tab

When the user selects an index tab on a notebook widget, the selection
changes in the underlying SelectionInList. Accessing that selection is a
fundamental operation because the application model must know which
tab is selected before it can take the appropriate action.
In a method in the application model, get the selected index tabs string or
association by sending a selection message to the notebooks major
SelectionInList. (In the example, the resulting string contains a leading
space, so a last message is sent to get the index letter that follows the
space).

GUI Developers Guide

215

Chapter 9 - Configuring Widgets

changedLetter
| chosenLetter list |
chosenLetter := self majorKeys selection last.
list := Smalltalk classNames
select: [ :name | name first == chosenLetter].
self classNames list: list.

Adding Secondary Tabs (Minor Keys)

The side tabs control

the first letter of the
displayed classes

The bottom tabs control

whether all classes are
displayed or only
example classes

Online example: Notebook2Example

In addition to the first set of index tabs, a second row of tabs can be
added along another edge of the notebook. This second set of tabs is
referred to as the minor keys. The minor keys can be used either to refine
the subdivisions implied by the major keys or to filter the content of the
notebook along a separate dimension.
In Notebook2Example, which lists the classes in the system, two minor keys
are used to control whether the page shows all classes beginning with
the selected letter or just the example classes.

216

On the Basics property page, fill in the notebooks Minor property with
the name of the method that returns a SelectionInList containing the
labels for the secondary tabs (in the example, minorKeys).

Use a System Browser or the canvass define command to create the

instance variable (minorKeys) and accessing method (minorKeys) for
the notebooks list of index labels.

VisualWorks

Notebook

minorKeys
^minorKeys
3

Initialize the variable, either in the accessing method or in an initialize

method (as in the example), with a SelectionInList containing either
strings or associations (the example uses associations).

In the initialize method, use an onChangeSend:to: message to arrange

for the notebook to send a message (changedPage) to the application
model when the user selects a secondary tab. (In the example, both
the major and minor tabs trigger the same message: changedPage.)
initialize
| letters |
letters := #( ' A' ' B' ' C' ' D' ' E' ' F' ' G' ' H' ' I' ' J' ' K' ' L' ' M'
' N' ' O' ' P' ' Q' ' R' ' S' ' T' ' U' ' V' ' W' ' X' ' Y' ' Z' ).
majorKeys := SelectionInList with: letters.
majorKeys selectionIndexHolder
onChangeSend: #changedPage to: self.
minorKeys := SelectionInList with: (Array
with: 'All classes'-> #all
with: 'Examples only' -> #examples).
minorKeys selectionIndexHolder
onChangeSend: #changedPage to: self.
classNames := SelectionInList new.

Create the change message (changedPage) in which the subcanvas is

updated based on the selected index tab. (In the example, the
classNames list is updated with all class names or only example
classes, based on the minor key.)
changedPage
| chosenLetter list filter filteredList |
"Major key."
chosenLetter := self majorKeys selection last.
list := Smalltalk classNames
select: [ :name | name first == chosenLetter].
list addAll: (Examples classNames select:
[ :name | name first == chosenLetter]).

GUI Developers Guide

217

Chapter 9 - Configuring Widgets

"Minor key."
filter := self minorKeys selection value.
filter == #all
ifTrue: [filteredList := list]
ifFalse: [filteredList := list
select: [ :name | '*Example' match: name]].
self classNames list: filteredList.

Connecting Minor Tabs to Major Tabs

Online example: Notebook3Example
The major and minor keys of a notebook can be used to navigate through
a two-tiered hierarchy of information. The minor keys can depend on the
major keys so that when the user selects a major key, a different set of
minor keys is presented.
1

In the application models initialize method, set the two SelectionInLists

to send onChangeSend:to: messages to notify the application model
when their selections are changed.
initialize
self initializeDepartments.
self initializeEmployees.
majorKeys := SelectionInList with: departments keys asArray.
majorKeys selectionIndexHolder
onChangeSend: #changedDepartment
to: self.
minorKeys := SelectionInList new.
minorKeys selectionIndexHolder
onChangeSend: #changedSubdepartment
to: self.
employeeList := SelectionInList new.

Create the change message (changedDepartment) for the major keys.

This method gets the selection from the major SelectionInList, and
uses that selection for choosing the new labels for the minor tabs.
The minor key selection is reset to display the first subpage.

218

VisualWorks

Notebook

changedDepartment
| subdepts sel |
sel := self majorKeys selection.
sel isNil ifTrue: [^self].
"Display the appropriate subdepartments as minor keys."
subdepts := self departments at: sel.
self minorKeys list: subdepts.
self minorKeys selectionIndex: 1.
3

Create the change message (changedSubdepartment) for the minor

keys.
This method gets the minor selection and uses that selection for
updating the canvas in the notebook.
changedSubdepartment
"Display the appropriate employees in the list."
| emps sel |
sel := self minorKeys selection.
sel isNil ifTrue: [^self].
emps := self employees at: sel.
self employeeList list: emps.

Changing the Page Layout (Subcanvas)

Each page represents
a different interface or
even a different
application

GUI Developers Guide

219

Chapter 9 - Configuring Widgets

Online example: Notebook4Example

It is often useful for a notebook to present a different interface on each
page. This is the basis of, for example, wizards.
In Notebook4Example, each index tab represents an example application.
Selecting a tab causes a working instance of that application to be
contained in the notebook.
1

In the application models initialize method, set the major keys

SelectionInList to notify the application model when a tab is selected.
initialize
| exampleClasses |
exampleClasses := OrderedCollection new.
exampleClasses := Examples keys select: [ :c |
(('*Example' match: c)
and: [(Smalltalk at: c) isVisualStartable])
and: [('Notebook*' match: c) not]].
majorKeys := SelectionInList
with: exampleClasses asSortedCollection.
majorKeys selectionIndexHolder
onChangeSend: #changedExample to: self.

In the change method (changedExample), get the notebook widget and

send it a client:spec: message to the notebook.
The first argument is the application model (in the example,
exampleClass). The second argument is the spec for the desired
canvas (in the example, each example classs windowSpec is used).
changedExample
| sel exampleClass |
sel := self majorKeys selection.
sel isNil ifTrue: [^self].
exampleClass := Examples at: sel value.
(self widgetAt: #pageHolder)
client: exampleClass new
spec: #windowSpec.

220

VisualWorks

Notebook

Notebook Events
A Notebook triggers events when a tab selection is changing, when one
of its tabs gains or looses focus, and when it's tabs scroll.
#gettingFocus
When any of a notbook's tab groups (either horizontal or vertical)
receives focus by being clicked on by the mouse, or tabbed into by
the keyboard, when none of that group of tabs have had focus, the
notebook triggers the #gettingFocus event.
#losingFocus
When any of a notebook's tabs groups (either horizontal or vertical)
lose focus, by being clicked or tabbed away from, to anything except
another of the tabs in the same group, the notebook triggers the
#losingFocus event.
#tabbed
When a notebook tab group (either horizontal or vertical) has focus,
and the and the Tab key is pressed to move the focus to the next
widget in the tab order or another tab group on the notebook, the
notebook triggers the #tabbed event.
#backTabbed
When a notebook tab group (either horizontal or vertical) has focus,
and the Back-Tab (Shift-Tab) key is pressed to move the focus to the
previous widget in the tab order or another tab group on the
notebook, the notebook triggers the #backTabbed event.
#scrollLeft
If all of the tabs in a horizontal tab group of a notebook are not visible,
and the left double arrow icon is pressed to scroll additional
horizontal tabs into view, then the notebook triggers the #scrollLeft
event.
#scrollRight
If all tabs in a horizontal tab group of a notebook are not visible, and
the right double arrow icon is pressed to scroll additional horizontal
tabs into view, then the notebook triggers the #scrollRight event.
#scrollUp
If all tabs in a vertical tab group of a notebook are not visible, and the
up double arrow icon is pressed to scroll additional vertical tabs into
view, then the notebook trigger the #scrollUp event.
#scrollDown
If all tabs in a vertical tab group of a notebook are not visible, and the
down double arrow icon is pressed to scroll additional vertical tabs
into view, then the notebook triggers the #scrollDown event.
GUI Developers Guide

221

Chapter 9 - Configuring Widgets

#horizontalTabChanging
When a new tab within a horizontal tab group is selected, either by
selection using the mouse or by keyboard navigation, before the view
changes to the newly selected tab the notebook triggers the
#horizontalTabChanging event.
#horizontalTabChanged
After a new tab within a horizontal tab group is selected, either by
selection using the mouse or by keyboard navigation, the notebook
triggers the #horizontalTabChanged event.
#verticalTabChanging
When a new tab within a vertical tab group is selected, either by
selection using the mouse or by keyboard navigation, before the view
changes to the newly selected tab the notebook triggers the
#verticalTabChanging event.
#verticalTabChanged
After a new tab within a vertical tab group is selected, either by
selection using the mouse or by keyboard navigation, the notebook
triggers the #verticalTabChanged event.

222

VisualWorks

Percent Done Bar

Percent Done Bar

Also sometimes called a Progress Bar, this widget gives a visual

indication of how far a process has advanced. Its commonly used for file
copy procedures, but can be useful for any number of lengthy processes
to give the user an indication of how much work has been done and how
much more there is to go.

Basic Properties
Only the Basic properties are specific to this widget.

Aspect
The instance variable that determines the percentage. The value is a
numeric value between 0 and 1.

Orientation
Horizontal indicates progress horizontally.
Vertical indicates progress vertically.
Both indicates progress both vertically and horizontally.
Area shows percentage in terms of area covered, rather than linearly.
Reverse reverses the horizontal and/or vertical direction.

Starting Point
The grid with five radio buttons sets the starting point: top, bottom, left,
right, or center. If Both is selected for the orientation, then the starting
point is either a corner or the center.

GUI Developers Guide

223

Chapter 9 - Configuring Widgets

Adding a Percent Done Bar

1

Add a Percent Done Bar widget to the canvas and select it.

In the Aspect property, enter a name for the aspect.

Set the progress orientation: Horizontal, Vertical, or Both.

Optionally, select Reverse, to reverse the direction of progress
indication. Select Area to indicate progress as the percentage of area
filled.

Select a starting point radio button.

Apply the properties and install the canvas. Use define to add the
aspect instance variable and accessor method.

Percent Done Bar Events

A Percent Done Bar triggers events when its value has changed.
#changed
When a percent done bar is given a new percentage value, it triggers
the #changed event. The percent done bar, unlike other widgets that
trigger #changed events, does not have a matching a #changing event.

224

VisualWorks

Lines, Boxes, and Ovals

Lines, Boxes, and Ovals

region

divider

Lines, group boxes, and regions (rectangles and ellipses) are used to
provide visual separation between sets of interface components. Using
appropriate dividers can greatly improve the usability of an interface.

Adding a Line to a Canvas

Online example: LineExample
1

Use a Palette to add a divider to the canvas.

On the Basics property page, select either Horizontal or Vertical for the
lines orientation property. Apply the property.

Use the widget handles to size and position the divider.

Install the canvas.

Lines are one pixel thick. For a thicker line, use a rectangular region and
set its Thick border property.

Adding a Group Box

When an interface begins to appear cluttered, the user of your application
may have trouble understanding how the widgets relate to one another.
As a visual aid, cluster the widgets in logical groups. Spacing is one way
to group widgets; another way is to surround some groups with boxes.
A box can have a label embedded in its top border. Its line thickness is
one pixel. For a thicker line, use a region as described below.
GUI Developers Guide

225

Chapter -

Use a Palette to add a box to the canvas. Leave the box selected.

Use the widget handles to size and position the box.

Fill in the Label property, if desired.

Choose the labels font.

Apply the properties and install the canvas.

A box line thickness is one pixel. For a thicker line, use a rectangular
region and set its border property to Thick. Also use a region if you want to
use color.

Making a Group Box Mnemonic

Adding a mnemonic to a Group Box label causes the cursor to jump to
the selected widget when <Alt><key> is pressed.
The <key> is specified by including an ampersand (&) in the Group Box
label string before the mnemonic letter. For example, if the label is Label,
you could make L the mnemonic by changing the label string to '$Label' in
the Group Boxs String: field. The label will show with the L underscored.
To associate the mnemonic with a widget, enter the widget ID in the
Group Boxs Details page, in the Mnemonic: field.

Group Box Events

A Group Box triggers events only when its label is changing.
#labelChanging
When a label or group box's label is about to change, the widget
triggers the #labelChanging event.
#labelChanged
After a label or group box's label has changed, the widget triggers the
#labelChanged event.

Grouping Widgets with a Region

For visual variety, you can use a region. A region can be rectangular or
elliptical, and supports colors.

226

Use a Palette to add a region to the canvas. Leave the region

selected.

Set the regions Rectangle or Ellipse property, as desired, and apply the
properties.

Use the widget handles to size and position the region.

VisualWorks

Lines, Boxes, and Ovals

If desired, use the Color property page to apply color to the foreground
(border) and/or background (interior).

Apply the properties and install the canvas.

Region Events
A Region triggers events when one of its visible properties is changed
programmatically.
#changing
When a region is about to change its size, inside color, border color
or border size, before the change is applied the region triggers the
#changing event.
#changed
After a region has had its size, inside color, border color or border
size changed, the region triggers the #changed event.

GUI Developers Guide

227

Chapter 9 - Configuring Widgets

Resizing Splitter
The Resizing Splitter widget allows users to resize widgets in the GUI.
For example, in the GUI Painter Tool, a Resizing Splitter is between the
hierarchical list of widgets and the tabbed notebook.
You can change the relative size of both by selecting and dragging the
area between them. The cursor shape changes while it is passing over a
Resizing Splitter, indicating that the border is movable.
Because this widget is really only intended for direct user manipulation,
no programmatic interface is described in this section.
Typically, the Resizing Splitter will be one of the last widgets you add to
the canvas, since you add it between other widgets whose size you want
to allow the user to control.

Adding a Resizing Splitter

1

Select the Resizing Splitter and drop it on the canvas between the
widgets you want to resize.

Initially the widget is proportioned horizontally, and the the Horizontal

check box is marked, for separating widgets top to bottom. To
separate widgets left to right, uncheck the Horizontal check box and
resize the widget accordingly.

In the Left/top widgets: properties field, enter the IDs of the widgets to
the left of or above the widget. Similarly, in the Right/bottom widgets:
field, enter the IDs of the widgets to the right or below the Resizing
Splitter.
Since there may be (frequently are) more than one widget on one
side of a widget, these fields take space-separated widget ID names.
Only widgets in the lists are resized as the Resizer Splitter is moved.
IDs can be listed either simply as identifiers (TreeView1 TextEditor2) or as
symbols (#TreeView1 #TextEditor2).

Accept and install the canvas.

Setting Widget Positioning

To make sure the widgets resize appropriately as the ResizIng Splitter is
moved, you will need to set the widget positions carefully. Use the Position
pages for the affected widgets properties for precise control.

228

VisualWorks

Resizing Splitter

The Resizing Splitter can either have a border or be borderless. With a

border it can double as a separator line, and so enhance the look of your
GUI. Without a border it is invisible, and so simply serves as an area to
grab for resizing. Even if you want it to be invisible in the final product,
leaving it with a border can be useful while arranging your GUI.
For example, lets set position settings for a GUI with a Tree View in the
top left and a group of Check Boxes on the lower left, separated by a
bordered Resizing Splitter, and a Text Editor on the right separated by an
unbordered Resizing Splitter. The GUI looks like this:

Set the positions as shown below (placement of the check boxes is left as
an exercise for the reader):
Position

Offset

Left (L)

Top (T)

Right (R)

0.5

-3

Bottom (B)

0.5

-7

Left (L)

0.5

Top (T)

Right (R)

-3

Bottom (B)

-3

Left (L)

Top (T)

TreeView (top left)

TextEditor (right)

GroupBox (bottom left)

GUI Developers Guide

229

Chapter 9 - Configuring Widgets

Position

Offset

Right (R)

0.5

-3

Bottom (B)

0.5

-7

Left (L)

26

Top (T)

0.5

-2

Right (R)

0.5

-26

Bottom (B)

0.5

Left (L)

0.5

-2

Top (T)

Right (R)

0.5

Bottom (B)

ResizingSplitter (horizontal)

RisizingSplitter (vertical)

For clarity, the positions are all given as relative either to a line shared by
a Resizing Splitter, or to an edge, but that is not necessary. The affected
widgets are identified in the Resizing Splitters Left/top widgets: and
Right/bottom widgets: lists.

Resizing Splitter Events

A Resizing Splitter triggers events when it is clicked on and when its
position on the canvas has changed.
#clicked
When a resizing splitter is clicked on by the mouse, without regard to
if the splitter is moved, the resizing splitter triggers the #clicked event.
#moved
When a resizing splitter has finished being moved and then the
mouse button has been released, the resizing splitter triggers the
#moved event.

230

VisualWorks

Sliders

Sliders
A slider simulates the sliding switch that some electronic devices use for
controlling volume, bass level, and other properties. A slider enables you
as the designer of an application to define a specific range of legal
values, and it enables the user to conveniently select a value within that
range.

Adding a Slider
Online example: Slider1Example
1

Add a slider widget to the canvas.

On the Basics property page, in the sliders Aspect property, enter a

name for the aspect (destination).

(Optional) Set the Start, Stop, and Step properties

These properties set the range and increment for the slider. The
default Start is 0 and Stop is 1. The default Step is nil, providing
continuous motion.

Apply the properties and install the canvas, and use define to add the
aspect instance variable and accessor method (destination).

Create or edit the initialize method to initialize the variable with a value
holder and an initial value.
initialize
"Destination"
destination := Date today year asValue.
"Current year"
currentYear := Date today year asValue.
"Trip meter"
tripRange := RangeAdaptor
on: currentYear
stop: 4000
grid: 1.

Connecting a Slider to a Field

Although a slider is both an input and an output device, it gives only a
rough idea of the current value. A field is commonly used to display the
precise value.

GUI Developers Guide

231

Chapter 9 - Configuring Widgets

Slider1Example uses a field to display the destination year, because the

slider covers such a large range (zero to 4000) that the user can only
guess at its current value.
1

Add a field to the canvas.

In the fields Aspect property, enter the same aspect name as for the
slider.

In the fields Type property, select Number.

Apply the properties and install the canvas.

Connecting a Slider to a Non-numeric Field

Online example: Slider2Example
By its nature, a slider always manipulates a numeric value. You can make
it appear to manipulate a nonnumeric value, however, by using a field to
display the transformed value. The example translates numeric values to
months.
1

Add a field to the canvas.

In the fields Aspect property, enter a different method name than the
sliders Aspect (month).

In the fields Type property, select the type that corresponds to the
transformed value (the example uses a String type).

Apply the properties and install the canvas, and use define to create
the aspect instance variable and accessing method.

In a method in the application model (typically initialize), initialize the

fields variable.

Edit the initialize method so a change message (changedDate) is sent

to the application model when the sliders value changes.
initialize
month :=(Date nameOfMonth: 1) asValue.
year := 1900 asValue.
dateRange := (0@1) asValue.
dateRange onChangeSend: #changedDate to: self.

Create the change method (changedDate) in the application model.

This method is responsible for changing the fields value based on
the sliders new value.

232

VisualWorks

Sliders

changedDate
"Convert the y-axis value to a month."
|yx|
y := self dateRange value y.
y := (12 - (y * 12) asInteger) max: 1."(12 months)"
self month value: (Date nameOfMonth: y).
"Convert the x-axis value to a year."
x := self dateRange value x.
x := 1900 + (x * 100) asInteger."(100 years)"
self year value: x.

Making a Slider Read-Only

Although it is normally an input device, a slider can be used purely as an
output device. In Slider1Example, we use a read-only slider as a meter to
display the progress of the users time-traveling adventure.
1

On the Basics properties page, assign the sliders ID property with an

identifying name (tripRange).

In a method in the application model (typically postBuildWith:), get the

slider component from the builder and disable it.
postBuildWith: aBuilder
"Disable the trip meter, making it read-only."
(self wrapperAt: #tripRange) disable.

Changing the Slider Range

When the sliders range is unchanging, you can use the sliders Start, Stop,
and Step properties to set the range and the step value. When the range
or step varies, however, you need to adjust the range within the
application.
A RangeAdaptor is a specialized value model that also keeps track of the
range and step values. You can change those values by sending
messages to the adaptor.
Online example: Slider1Example (the Trip Meter slider)
1

Edit the sliders initialization (typically in an initialize method) to

initialize the sliders aspect variable with a RangeAdaptor by sending
the instance creation message (on:start:stop:grid:).
The on: argument is a value holder containing the number that the
slider manipulates. When a field is connected to the slider, as in the
example, this argument is the fields aspect variable. The grid:
argument is the step value.

GUI Developers Guide

233

Chapter 9 - Configuring Widgets

initialize
"Destination"
destination := Date today year asValue.
"Current year"
currentYear := Date today year asValue.
"Trip meter"
tripRange := RangeAdaptor
on: currentYear
start: 0
stop: 4000
grid: 1.
2

Whenever the range or step must change, send a rangeStart:,

rangeStop:, or grid: message to the adaptor. (In the example, this is
done in the engage method.)
engage
"Start the time trip."
| startingYear destinationYear direction |
startingYear := self currentYear value.
destinationYear := self destination value.
destinationYear == startingYear
ifTrue: [^Dialog warn: 'Please select a new destination.'].
"Set the endpoints on the trip meter."
self tripRange
rangeStart: startingYear;
rangeStop: destinationYear;
grid: 1.
"Reset the meter to the starting position."
currentYear value: startingYear.
"Set up a step value for the loop that follows (-1 = backward in
time)."
destinationYear > startingYear
ifTrue: [direction := 1]
ifFalse: [direction := -1].
"For each year of time travel, update the current year."
startingYear to: destinationYear by: direction do: [ :yr |
currentYear value: yr].

234

VisualWorks

Sliders

Making a Slider Two-Dimensional

2D marker controls
two aspects of the
model

You can make a slider manipulate a point in two dimensions and then use
the x-axis and y-axis components of that point to control two separate
parameters.
In Slider2Example, a two-dimensional slider is used to alter two fields
simultaneously. The first field uses the y component to display one of the
12 months. The second field uses the x component to arrive at a year
between 1900 and 2000.
Online example: Slider2Example
1

In an instance method (typically initialize), initialize the sliders variable

to an instance of Point that is held by a value holder, and arrange for a
change message (changedDate) to be sent to the application model
when the sliders value changes.
initialize
month := (Date nameOfMonth: 1) asValue.
year := 1900 asValue.
dateRange := (0@1) asValue.
dateRange onChangeSend: #changedDate to: self

In a postBuildWith: method, get the slider from the application and ask
it to beTwoDimensional.
postBuildWith: aBuilder
(self widgetAt: #dateRange)
beTwoDimensional;
setMarkerLength: 10.

Create the change method (changedDate) in the application model.

This method splits the sliders value into its x-axis and y-axis
components. Each component is a value between 0 and 1 and is

GUI Developers Guide

235

Chapter 9 - Configuring Widgets

transformed as needed to produce a suitable value for the related

field.
changedDate
"Convert the y-axis value to a month."
|yx|
y := self dateRange value y.
y := (12 - (y * 12) asInteger) max: 1."12 months"
self month value: (Date nameOfMonth: y).
"Convert the x-axis value to a year."
x := self dateRange value x.
x := 1900 + (x * 100) asInteger."(100 years)"
self year value: x.

Slider Events
A Slider triggers events when its value has changed or folded in half and
eaten whole (without regard to cheese). Unlike other widgets that interact
with the mouse, a Slider never gets focus and thus does not trigger focus
or mouse click events.
#changing
When a slider is about to change its value, the slider triggers the
#changing event.
#changed
After a slider has changed its value, the slider triggers the #changed
event.

236

VisualWorks

Spin Buttons

Spin Buttons
A spin button allows a user to select a value from a determined range.
The selected value is returned as a selectable object type and format.
A spin button model must represent a number, whenever its Type
property is set to either String, Text, or Symbol. In these cases the model
must respond to asNumber and not answer zero unless the model itself
represents 0.
For example, model values for a spin button, listed by Type, might be:
Type

Example model value

String

'774.3'

Text

'12e-03' asText

Symbol

#'12'

The Low Value is the minimum setting the button will spin to, and the High
Value is the maximum setting. The spin button range is unbounded
unless these values are set.
The Interval is the amount each button press increments or decrements
the spin button value. Any number may be entered for the Interval, but
only positive numbers make sense. The default Interval value is 1.
For all spin button Types other than Date, Time, and Timestamp, the Low
Value and High Value properties expect only numeric entries; no nonnumeric symbols should appear in the entry.
If the Type property is set to Date, enter Low Value and High Value entries
as dates, such as 12/20/1988 or Sep 30 1990. The Interval expects values as
a number of days.
When Type is set to Time, format Low Value and High Value entries as
times, such as 12:34:23 pm. Do not set a High Value of 12:00:00 am, unless
you have the wrap around property set. The Interval entries are in units of
seconds.
If Type is a Timestamp, enter Low and High Values in Timestamp format,
such as 01/03/1999 0:00:00.000. Interval entries are in units of milliseconds.

GUI Developers Guide

237

Chapter 9 - Configuring Widgets

The table below summarizes the acceptable spin button property values
for Date, Time, and Timestamp type.
Type

Low/High Value Entry Example

Interval Units

Date

12/20/1988, Sep 30 1990

Days

Time

12:34:23 pm, 18:00:00

Seconds

Timestamp

01/03/1999 0:00:00.000

Milliseconds

Adding a Spin Button

1

Add a spin button widget to the canvas.

In the Aspect property, enter a name for the aspect.

(Optional) Set the Type, Format, Low Value, High Value, and Intervale
properties
These properties set the returned object type and format, and the
range and increment for the presented values.

Apply the properties and install the canvas, and use define to add the
aspect instance variable and accessor method.

Create or edit the initialize method to initialize the aspect variable with
a value holder and an initial value.

Spin Button Events

A Spin Button triggers events when its value is changing, when it gains
and looses focus, when it gets clicks from the mouse, when it spins up or
down and it reaches the end of its value range.
#changing
When the value of the spin button is about to be accepted, either by
spinning the button, or after directly editing the value and exiting the
spin button, the spin button triggers the #changing event.
#changed
After the value of the spin button has been accepted, the spin button
triggers the #changed event.
#clicked
When a spin button is clicked on with the <Select> mouse button, the
spin button triggers the #clicked event.

238

VisualWorks

Spin Buttons

#rightClicked
When a spin button is right clicked on with the <Operate> mouse
button, the spin button triggers the #rightClicked event. This event will
occur without regard to whether there is a popup menu associated
with the spin button.
#doubleClicked
When a spin button is double clicked on with the <Select> mouse
button, the spin button will triggers the #doubleClicked event. This
event is always immediately preceded by a #clicked event.
#gettingFocus
When a spin button receives focus, either by being tabbed to or by
clicking on by the mouse, the spin button triggers the #gettingFocus
event.
#losingFocus
When a spin button loses focus, either by being tabbed away from, or
by having another widget on the canvas gain focus, the spin button
triggers the #losingFocus event.
#tabbed
When a spin button has focus, and the Tab key is pressed in request
to have the focus to move to the next widget in the tab order, the spin
button triggers the #tabbed event.
#backTabbed
When a spin button has focus, and the Back-Tab (Shift-Tab) key is
pressed in request to have the focus move to the previous widget in
the tab order, the spin button triggers the #backTabbed event.
#spinUp
When the up arrow button is pressed on a spin button, prior to
changing the value of the spin button, the spin button triggers the
#spinUp event. If the value of the spin button is changed, the #spinUp
event is always immediately followed by #changing, #changed and
#spunUp events. If the value of the spin button is not changed, the
#spinUp event may be followed by a #bounceTop event, depending on
the settings of the spin button.
#spunUp
After the up arrow button is pressed on a spin button, after changing
the value of the spin button, the spin button triggers the #spunUp
event. The #spunUp event is always immediately preceded by a
#changed event.

GUI Developers Guide

239

Chapter 9 - Configuring Widgets

#spinDown
When the down arrow button is pressed on a spin button, prior to
changing the value of the spin button, the spin button triggers the
#spinDown event. If the value of the spin button is changed, the
#spinDown event is always immediately followed by #changing,
#changed and #spunDown events. If the value of the spin button is not
changed, the #spinDown event may be followed by a #bounceTop
event, depending on the settings of the spin button.
#spunDown
After the down arrow button is pressed on a spin button, after
changing the value of the spin button, the spin button triggers the
#spunDown event. The #spunDown event is always immediately
preceded by a #changed event.
#wrapAroundBottom
If a spin button has a low value set in its properties, and has the wrap
around property set, then when the spin button is asked to spin below
the lowest value, after the #spinDown, #changing, #changed and
#spunDown events are triggered, the spin button triggers the
#wrapAroundBottom event.
#wrapAroundTop
If a spin button has a high value set in its properties, and has the
wrap around property set, then when the spin button is asked to spin
above the highest value, after the #spinUp, #changing, #changed and
#spunUp events are triggered, the spin button triggers the
#wrapAroundTop event.
#bounceBottom
If a spin button has a low value set in its properties, and does not
have the wrap around property set, then when the spin button is
asked to spin below the lowest value, after the #spinDown event is
triggered, the spin button triggers the #bounceBottom event. Because
the value has not changed, the #changing, #changed and #spunDown
events will not trigger.
#bounceTop
If a spin button has a high value set in its properties, and does not
have the wrap around property set, then when the spin button is
asked to spin above the highest value, after the #spinUp event is
triggered, the spin button triggers the #bounceTop event. Because the
value has not changed, the #changing, #changed and #spunUp events
will not trigger.

240

VisualWorks

Subcanvases

Subcanvases
A subcanvas is a widget for displaying another canvas in the canvas you
are building. It is an effective way to build an application interface that
incorporates another application interface, or an entire application, into
itself.
There are three primary uses for subcanvases:
Inheriting an application
Within a hierarchy of application models, you can inherit an interface
and its value models.
Nesting an application
By placing an application in a subcanvas, you make its interface part
of your own applications interface, and effectively incorporate its
domain model into your application as well.
Reusing an interface only
You can incorporate another applications interface, but supply your
own domain model for it.
All three of these methods promote various levels of reuse. Using
subcanvases in these ways allow you to build a collection of reusable
interfaces.

Inheriting a Subcanvas
Subcanvases provide a way to extend the inheritance mechanism in
Smalltalk to building a user interface. By building an application model as
a subclass of another application model, the subclass will inherit standard
interface modules, value holders, and action methods.
For example, Subcanvas1Example is a subclass of List2Example, so it can
reuse the List2Example interface, value holders, and actions.
A subclass need not reimplement anything that the parent class has
implemented, but it can override an inherited action.
Note: A limitation of the inheritance approach is that if you use the
same inherited interface twice in a canvas, both will display the same
thing. This is because both reference the same value holder.
Online example: List2Example (parent) and Subcanvas1Example
1

GUI Developers Guide

Create a new application model (Subcanvas1Example) as a subclass of

the application model from which it is to inherit (List2Example).

241

Chapter 9 - Configuring Widgets

Place a subcanvas widget on the inheriting canvas (the canvas for

Subcanvas1Example).

In the subcanvass Canvas property, enter the name of the inherited

interface specification to be used by the subcanvas (listSpec).
This spec name must be unique within the inheritance chain. For
example, you could not embed an inherited canvas named
windowSpec in a local canvas named windowSpec.
The Name and Class properties are not needed for inheriting a canvas.

Apply the property and install the inheriting canvas in its application
model (Subcanvas1Example).

Changing the Value of an Inherited Widget

The power of reuse is fully realized when you provide local values for the
inherited widgets. For example, List2Example initializes its list to display a
collection of color names. The inheriting application, Subcanvas1Example,
provides its own collection, causing the reused list to display cursor
names instead.
1

Create or edit the initialize method in the inheriting application model

(Subcanvas1Example).

In the initialize method, invoke the inherited initialize method.

In the initialize method, use the inherited aspect message

(selectionInList) to access the desired valued model. Then send an
accessing message (in this case, list:) to the value model to install the
desired value (cursorNames).
initialize
"Install a different list (cursor names) than
the inherited default (color names)."
| cursorNames |
super initialize.
cursorNames := Cursor class organization
listAtCategoryNamed: #constants.
self selectionInList list: cursorNames.

Nesting One Application in Another

Using the subcanvas, you can embed (or nest) one application in another.
This is useful, for example, for creating a set of reusable application
modules that can be plugged into larger applications as needed. This
approach can help avoid duplication of effort for generic modules and
enforce interface design standards.

242

VisualWorks

Subcanvases

The embedded application supplies its own value models and action
methods. Because the applications are not generally related by
inheritance, you cannot override an embedded applications action
methods.
You can embed the same application any number of times in the same
canvas. For example, you could reuse List2Example four times in creating
a System Browsers four list views.
Online example: List2Example embedded in Subcanvas2Example
1

Add a subcanvas widget in the reusing canvas.

Specify these properties for the subcanvas:

Name, the name of the method that returns an instance of the

embedded application (classNames).

Class, the name of the application that you are embedding
(List2Example).
Canvas, the name of the interface specification for the embedded

application (listSpec).
3

Apply the properties and install the reusing canvas in its application
model (Subcanvas2Example).

Add an instance variable (classNames) in the reusing application

model for holding onto the embedded application.

Add an accessor method for the instance variable:

classNames
^classNames

Create or edit the initialize method in the reusing application model, so

it creates the embedded application and assigns it to the instance
variable:
initialize
"Reusing List2Example's interface only -- initialize the list
holder."
selectionInList := SelectionInList with: Smalltalk classNames.
"Reusing List2Example application -- initialize the application
instance."
classNames := List2Example new.
classNames list: Smalltalk classNames.

GUI Developers Guide

243

Chapter 9 - Configuring Widgets

Setting a Value in an Embedded Widget

An embedded widget uses the value with which its host application
initializes it.
1

In the initialize method, send a message (list:) to the embedded

application, installing the desired value.
initialize
"Reusing List2Example's interface only -- initialize the list
holder."
selectionInList := SelectionInList with: Smalltalk classNames.
"Reusing List2Example application -- initialize the application
instance."
classNames := List2Example new.
classNames list: Smalltalk classNames.

If necessary, as in the example, you may need to add a method (list:)

to the embedded application model that allows an outside application
to supply a new value.
list: aCollection
"Install aCollection in the list. This message is provided so
reuserscan install a list that is different than the default list
(color names)."
self selectionInList list: aCollection.

Reusing an Interface Only

You can use a subcanvas to embed one canvas inside another. This is
similar to embedding an entire subapplication, except that the reusing
application must supply all value models and methods for the interface.
Because you are reusing only the interface, you have to reimplement all
of the supporting value holders and methods. You also have to supply
actions for any buttons in the embedded interface.
Online example: Subcanvas2Example (which reuses List2Examples listSpec)
1

Add a subcanvas in the reusing canvas.

Specify these properties for the subcanvas:

Class, the name of the application that defines the interface to be
embedded (List2Example).
Canvas, the name of the interface specification to be embedded

(listSpec).
The Name property is not needed for reusing the interface only.
244

VisualWorks

Subcanvases

Apply the properties and install the reusing canvas in its application
model (Subcanvas2Example).

Edit the reusing application model, adding instance variables and

methods to support the embedded interface.
These instance variables and methods must have the same names
as the corresponding variables and methods in the reused class.
Modify values and action methods as desired.

Changing Interfaces at Run Time

Using a subcanvas makes it easy to change the UI in response to the
current context of the application. In Subcanvas3Example, a subcanvas is
used to hold either a text editor or a list view, depending on whether the
user wants to see textual or listed material related to a selected class.
Online example: Subcanvas3Example

GUI Developers Guide

In the subcanvass Name property, enter the name of the method that
supplies the initial embedded application (embeddedApplication).

Apply the properties and install the reusing canvas.

Create the method (embeddedApplication) that you named in step 1.

Create a change method which:

a

Creates and initializes an instance of the application model to

swap (Editor2Example)

Gets the specification for the new interface, by sending an

interfaceSpecFor: message to the embedded application models
class (Editor2Example). The argument is the name of the interface
specification (#windowSpec).

Gets the subcanvas from the builder and send a client:spec:

message to it. The first argument is the application you created in
step 4a. The second argument is the spec object you obtained in
step 4b.

245

Chapter 9 - Configuring Widgets

showComment
| selectedClass subcanvas spec application |
selectedClass := Smalltalk at: self classNames selection.
"Create the subapplication and initialize it."
application := Editor2Example new.
application text value: selectedClass comment.
"Get the spec object for the embedded canvas."
spec := Editor2Example interfaceSpecFor: #windowSpec.
"Get the subcanvas and install the editing application."
subcanvas := self widgetAt: #subcanvas.
subcanvas client: application spec: spec.

Accessing an Embedded Widget

You may need to access a widget within an embedded interface. For
example, when an embedded action button is not appropriate in the local
application, you may want to make it invisible or disable it.
Online example: Subcanvas3Example
1

Before installing a subapplication using client:spec:, initialize the

subapplications builder to nil.
This causes the subapplication to release its old builder.

Ask the subapplication for widgets wrapper by sending wrapperAt:,

with the ID of the desired widget.
showMethods
| selectedClass subcanvas spec |
selectedClass := Smalltalk at: self classNames selection.
spec := List2Example interfaceSpecFor: #listSpec.
"Install the method names as the collection in the list
application."
self listApplication list: selectedClass selectors asSortedCollection.
"Set the subbuilder to nil to discard the old builder. This is only
necessary when the application uses the builder later to access
widgets."
listApplication builder: nil.
"Get the subcanvas and install the list application."
subcanvas := self widgetAt: #subcanvas.
subcanvas client: listApplication spec: spec.

246

VisualWorks

Subcanvases

"Disable the embedded buttons (just to show that we can)."

(listApplication wrapperAt: #addButton) disable.
(listApplication wrapperAt: #deleteButton) disable.

Subcanvas Events
A Subcanvas triggers events when its view scrolls due to activity via its
scroll bars or the Subcanvas builds and displays a new subcanvas.
#changing
When a subcanvas is sent a client:, client:spec:, or client:spec:builder:
message to have it host a new canvas, prior to the work of building
and displaying the new view, the subcanvas triggers the #changing
event. This event is only triggered once a subcanvas has been built
and displayed the first time. Thus the #changing event is not triggered
upon the initial creation of a subcanvas.
#changed
After a subcanvas is sent a client:, client:spec:, or client:spec:builder:
message to have it host a new canvas, and the new view is
completed being built and displayed, the subcanvas triggers the
#changed event. This event is only triggered once a subcanvas has
been built and displayed the first time. Thus the #changed event is not
triggered upon the initial creation of a subcanvas.
#scrollLeft
If while manipulating a horizontal scroll bar in a subcanvas, the
subcanvas to the left, the subcanvas triggers the #scrollLeft event.
#scrollRight
If while manipulating a horizontal scroll bar in a subcanvas, the
subcanvas scrolls to the right, the subcanvas triggers the #scrollRight
event.
#scrollUp
If while manipulating a vertical scroll bar in a subcanvas, the
subcanvas scrolls up, the subcanvas triggers the #scrollUp event.
#scrollDown
If while manipulating a vertical scroll bar in a subcanvas, the
subcanvas scrolls down, the subcanvas triggers the #scrollDown
event.

GUI Developers Guide

247

Chapter 9 - Configuring Widgets

Tab Control

Online example: TabControlExample

The TabControl is an alternative to the Notebook widget, providing a
tabbed folder look. To change the contents of the subpane below the row
of tabs, click a tab, or select the tab using cursor keys and press Enter.
The Tab Control shows two scroller buttons, if there are more tabs than
can be displayed in the available header space. Press the buttons to
scroll the tabs.

Compatibility with Notebook

The Tab Control is largely, but not completely, protocol-compatible with
the Notebook widget.
In many cases, you can change from a Notebook to a Tab Control simply
by editing the applications windowSpec, replacing the #NoteBookSpec
symbol to #TabControlSpec. This conversion method works, for example,
with Notebook1Example, Notebook4Example, and Notebook5Example.
One limitation is that Tab Control does not support secondary tabs, as
does Notebook. For this reason, the above conversion does not work for
Notebook2Example or Notebook3Example.
For an example specifically using the Tab Control, load the
TabControlExample parcel.

248

VisualWorks

Tab Control

Adding a Tab Control

1

Select the Tab Control on the Palette and drop it on the canvas.

In its Aspect property, enter an aspect name. Also enter an ID, or keep
the default. You will need the ID to identify the selected tab.

Define the accessor method for the aspect.

The model should be a SelectionInList on either Strings, which make up
textual tab labels, or Associations of a VisualComponent to a (optional)
String. In TabControlExample, this is handled in two methods:
tabs
tabs isNil
ifTrue:
[(tabs := SelectionInList with: self labelArray)
selectionIndex: 1.
tabs selectionIndexHolder
onChangeSend: #tabsChanged
to: self].
^tabs
labelArray
"Private - The list of tab names (and/or icons). See also #specArray."
^Array
with: 'Appearance'
with: self class colorsImage -> 'Colors'
with: self class printerImage -> ''

Paint subcanvases for each page (See the appearanceSpec, colorsSpec,

and fontsSpec class methods in TabControlExample for examples.)
So the canvas can be identified by an index, which will be retrieved
from labelArray, TabControlExample defines a specArray method:
specArray
"Private - The list of associated sub canvaes. See also #labelArray."
^#(#appearanceSpec #fontsSpec #colorsSpec)

GUI Developers Guide

Define a method that will respond by changing subcanvases when

the tab selection has changed. This message is sent when the
SelectionInList changes, as is defined in the tabs method.

249

Chapter 9 - Configuring Widgets

tabsChanged
"Every time, a tab is changed, a new sub canvas gets installed."
| index |
index := self tabs selectionIndex.
(self widgetAt: #tabbing)
client: self
spec: (self specArray at: index)
The change is made by the client:spec: message sent to the Tab
Control widget, which is retrieved from the builder.
For additional options and approaches, see Notebook above.

Defining Initial Labels

The above example defines the set of tab labels in code. You have the
option of defining labels directly in the Details property page. This can be
convenient, especially when there is no need to add pages dynamically.
To add a label, enter it into the Entry Field below the List and click Add. To
change a label, select it, edit it in the Entry Field, and click Change. To
delete, click Delete. To change the order of lables, select a label and drag
it to its new position in the list.
When you click Apply, your labels are shown in the canvas, unlike when
you provide labels in code.
You access the label by index as before, and so can change subcanvases
in the same way. So, within the Application Model, for a Tab Control with
aspect name tabs, send:
self tabs selectionIndex
returns the index of the currently selected tab.

Placing an Icon on a Tab

Each tab label can be a string, an icon, or an icon and a string. To use an
icon, the SelectionInList must be an Association. The tabs method invokes
labelArray to provide the labels, as follows:
labelArray
"Private - The list of tab names (and/or icons). See also #specArray."
^Array
with: 'Appearance'
with: self class colorsImage -> 'Colors'
with: self class printerImage -> ''

250

VisualWorks

Tab Control

If the label is only a string, then it is provided simply as a String, as in the

case with the first tab, Appearance.
If the label includes an icon, then the label is specified by an Association
between the icon and a String. The second tab label is an Association
between the graphic returned by self colorsImage and the String Colors.
The third tab is an icon without a String, so the String is empty.

Tab Control Events

A Tab Control triggers events when a tab selection is changing, when one
of its tabs gains or looses focus, and when its tabs scroll.
#gettingFocus
When a tab control receives focus to one of its tabs, by being clicked
on by the mouse, or tabbed into by the keyboard, when none of the
tabs have had focus, the tab control triggers the #gettingFocus event.
#losingFocus
When a tab control loses focus from one of its tabs, by being clicked
or tabbed away from, to anything except another of its tabs, the tab
control triggers the #losingFocus event.
#tabbed
When a tab control's tabs have focus, and the and the Tab key is
pressed in request to have the focus to move to the next widget in the
tab order, the tab control triggers the #tabbed event.
#backTabbed
When a tab control's tabs have focus, and the Back-Tab (Shift-Tab)
key is pressed in request to have the focus move to the previous
widget in the tab, the tab control triggers the #backTabbed event.
#scrollLeft
If all of the tabs in a tab control are not visible, and the left arrow
button is pressed to scroll additional tabs into view, then the tab
control triggers the #scrollLeft event.
#scrollRight
If all of the tabs in a tab control are not visible, and the right arrow
button is pressed to scroll additional tabs into view, then the tab
control triggers the #scrollRight event.
#pageLeft
If all of the tabs in a tab control are not visible, and the left arrow
button is pressed to scroll additional tabs into view while the Shift key
is pressed, then the tab control triggers the #pageLeft event.

GUI Developers Guide

251

Chapter 9 - Configuring Widgets

#pageRight
If all of the tabs in a tab control are not visible, and the right arrow
button is pressed to scroll additional tabs into view while the Shift key
is pressed, then the tab control triggers the #pageRight event.
#tabChanging
When a new tab is selected in a tab control, either by selection using
the mouse or by keyboard navigation, before the view changes to the
newly selected tab, the tab control triggers the #tabChanging event.
#tabChanged
After a new tab is selected in a tab control, either by selection using
the mouse or by keyboard navigation, the tab control triggers the
#tabChanged event.

252

VisualWorks

Tables

Tables
A table displays data in a rows-and-columns structure. In appearance,
tables are similar to dataset widgets, except that tables do not support
direct editing, and tables can display dissimilar kinds of data. Data must
be stored in a collection that allows two-dimensional access.

TableInterface
A table requires a relatively complex auxiliary object as its value model,
which is provided by TableInterface. A TableInterface holds information about
row and column labeling and formatting, in addition to the table data itself.
Within a TableInterface, the table data is held by a composite object, an
instance of SelectionInTable, which stores the collection of cell contents
and the selection index. The collection is expected to be a TwoDList (twodimensional list), which converts a flat collection such as an array into a
matrix of rows and columns. Alternatively, you can use a TableAdaptor to
adapt a collection.
All of this interface machinery can be held by a single instance variable in
the application model, and you can simply send messages to that object
to fetch the table or the selection or any other aspect of it. However, you
may find it economical to create instance variables to hold onto various
aspects of the table interface. For example, the SelectionInTable is useful
when your application model will need to access the contents of the table
at run time.

Adding a Table
Online example: Table1Example
1

Add a table widget to the canvas.

On the Basics property page, in the Aspect property, enter a name for
the aspect (e.g., tableInterface).
Set other property checkboxes as desired.

Apply the properties and install the canvas, and use define to add the
instance variable and accessor method for the aspect (tableInterface).
Initialization is done in an initialize method (step 5), rather than by
checking the include initialization option.

Use a code browser to add other instance variables, as appropriate.

Because TableInterface is a complex object, it is useful to create
additional instance variables for some of its components. In the

GUI Developers Guide

253

Chapter 9 - Configuring Widgets

example we create one additional variable, sightingsTable and an

accessor for it.
5

Create an initialize method to initialize the TableInterface.

A new TableInterface takes a SelectionInTable object, which can be
initialized in the same method. In the example we set it as the value
of sightingsTable.
Normally you wouldnt initialize the table with a hard-coded collection,
but would gather the table data from a database or some other
source.
initialize
| list |
super initialize.
"Create a collection of sightings data."
list := TwoDList
on: #('Vulcans' 188 173 192 'Romulans' 26 26 452) copy
columns: 4
rows: 2.
sightingsTable := SelectionInTable with: list.
"Create a table interface and load it with the sightings."
tableInterface := TableInterface new
selectionInTable: sightingsTable.

Controlling Column Widths

All columns initially have an equal width that is determined by the space
available in the table. If the table expands with the window, the column
widths will also expand.
To set specific widths for the columns, send a columnWidths: message to
the table interface. The argument is an array containing one number for
each column. The number is the width in pixels. Any column for which no
width is specified gets the width of the last entry in the array.
Reset the widths at any time by adding to the initialize method.
tableInterface columnWidths: #(100 40).
This expression changes the first column so that it is wide enough to
show the entire name of the alien race. These widths will remain in effect
even if the window is expanded.

254

VisualWorks

Tables

Connecting a Table to an Input Field

changed cell

input field

A read-only table is sufficient for some applications, but in many

situations the user needs a way to change the contents of a cell in the
table. This can be arranged indirectly by placing an input field near the
table and connecting it to the highlighted cell. This technique relies on a
single cell being selected.
Online example: Table2Example
1

Add an input field to the canvas.

On the Basics property page. in the fields Aspect property, enter a

name for its aspect (e.g., cellContents).

Apply the change and install the canvas, and use define to add an
instance variable and accessor method for the aspect.

Add an instance method to update the table when the entry field
changes.
In the example we add changedCell in a change messages protocol:
changedCell
| cellLocation |
"Get the coordinates of the highlighted cell."
cellLocation := self sightingsTable selectionIndex.
"If a cell is selected, update its contents from the input field."
cellLocation = Point zero
ifFalse: [self sightingsTable table
at: cellLocation
put: self cellContents value]

GUI Developers Guide

In the application models initialize method, initialize the input field so it

sends the changed message.

255

Chapter 9 - Configuring Widgets

initialize
| list |
super initialize.
"Create a collection of sightings data."
list := TwoDList
on: #('Vulcans' 188 173 192 'Romulans' 26 26 452) copy
columns: 4
rows: 2.
sightingsTable := SelectionInTable with: list.
"Create a table interface and load it with the sightings."
tableInterface := TableInterface new
selectionInTable: sightingsTable.
cellContents := String new asValue.
self cellContents onChangeSend: #changedCell to: self.
The application adds the input data into the selected cell.
Notice that when you select a new cell, its contents are not shown in the
input field. To make the field update its contents when the table selection
changes, you must register interest in the table selection with
onChangeSend: and trigger an update in the input field.

Labeling Columns and Rows

column labels

row labels

You can label one or more columns by sending an array of labels to the
table interface. For row labels, you need to send an array of labels and
also an indication of the width of those labels.
Online example: Table3Example
This example adds code to the end of Table2Examples initialize method that
initializes the row and column labels.

256

VisualWorks

Tables

tableInterface
columnLabelsArray: #('Visiting Race' '1992' '1993' '1994');
rowLabelsArray: #(1 2);
rowLabelsWidth: 20.
By default, all cells display their contents beginning at the left margin, and
all labels are centered. You can align data and labels using any of three
symbols: #left, #right, #centered, or #leftWrapped. Using these symbols, you
can control the alignment of a columns data, a columns labels, or a rows
labels.
Add code to the initialize method that initializes the label alignments.
tableInterface
elementFormats: #(#left #right #right #right);
columnLabelsFormats: #(#left #right #right #right);
rowLabelsFormat: #right.
As the example shows, you can set row labels to the same alignment by
passing a single symbol as argument, and the same applies to the
column alignments. For column data and labels, however, you also have
the option of setting each columns alignment individually, as we have
done, by passing an array of symbols.

Table Events
A Table triggers events when a selection is changing, when it gains and
looses focus, when it gets clicks from the mouse, and when it's view
scrolls.
#clicked
When a table is clicked on with the <Select> mouse button, the table
triggers the #clicked event.
#rightClicked
When a table is right clicked on with the <Operate> mouse button,
the table triggers the #rightClicked event. This event will occur without
regard to whether there is a popup menu associated with the table.
#doubleClicked
When a table is double clicked on with the <Select> mouse button,
the table triggers the #doubleClicked event. This event is always
immediately preceded by a #clicked event.
#gettingFocus
When a table receives focus, either by being tabbed to or by clicking
on by the mouse, the table triggers the #gettingFocus event.

GUI Developers Guide

257

Chapter 9 - Configuring Widgets

#losingFocus
When a table loses focus, either by being tabbed away from, or by
having another widget on the canvas gain focus, the table trigger the
#losingFocus event.
#tabbed
When a table has focus, and the and the Tab key is pressed to move
the focus to the next widget in the tab order, the table triggers the
#tabbed event.
#backTabbed
When a table has focus, and the Back-Tab (Shift-Tab) key is pressed
to move the focus to the previous widget in the tab order, the table
triggers the #backTabbed event.
#scrollLeft
If while navigating with the keyboard or mouse, or manipulating a
horizontal scroll bar in a table, the table scrolls to the left, the table
triggers the #scrollLeft event.
#scrollRight
If while navigating with the keyboard or mouse, or manipulating a
horizontal scroll bar in a table, the table scrolls to the right, the table
triggers the #scrollRight event.
#scrollUp
If while navigating with the keyboard or mouse, or manipulating a
vertical scroll bar in a table, the table scrolls up, the table triggers the
#scrollUp event.
#scrollDown
If while navigating with the keyboard or mouse, or manipulating a
vertical scroll bar in a table, the table scrolls down, the table triggers
the #scrollDown event.
#rowSelectionChanged
If a table has its selection mode set to Row, and while navigating with
the mouse or keyboard, the selected row changes, the table triggers
the #rowSelectionChanged event.
#columnSelectionChanged
If a table has its selection mode set to Column, and while navigating
with the mouse or keyboard, the selected column changes, the table
triggers the #columnSelectionChanged event.
#cellSelectionChanged
If a table has its selection mode set to Cell, and while navigating with
the mouse or keyboard, the selected cell changes, the table triggers
the #cellSelectionChanged event.

258

VisualWorks

Text Editors

Text Editors
A text editor is useful for displaying and editing text that does not fit
comfortably within a field, especially when the text is expected to have
multiple lines. The text editor has built-in facilities for:

Line wrapping

Changing the text style

Cutting, copying, and pasting

Undoing and reverting

Searching and replacing

Printing

Executing Smalltalk expressions

Adding a Text Editor

Online example: Editor1Example
1

Add a text editor to the canvas.

On the Basics property page, in the Aspect field, enter a name for the
aspect.

Install the canvas, and use define to add an instance variable and
aspect accessor method to the application model.

Create or edit the initialize method to set the aspect variable to a value
holder containing the initial text to be displayed (usually an empty
string).
initialize
super initialize.
comment := '' asValue.
classes := SelectionInList with: Smalltalk classNames.
classes selectionIndexHolder
onChangeSend: #changedClass to: self.
textStyle := #plain asValue.
textStyle onChangeSend: #changedStyle to: self.
readOnly := false asValue.
readOnly onChangeSend: #changedReadOnly to: self

GUI Developers Guide

259

Chapter 9 - Configuring Widgets

Retrieving and Modifying Selected Text

When the user highlights a portion of the text in an editor, your application
can retrieve the highlighted text. Text editors frequently modify selected
text in some way, such as to change the font, and then insert the revised
text into the main text.
1

In an instance method, get the controller from the text editor widget,
and ask the controller for the selected text.

Make any modifications to the text.

Ask the controller to replace the selection with a new text.

Ask the controllers view to reset its selections (to adjust for a
possible width change in the selection).

Ask the view to redisplay itself.

changedStyle
"A text style was selected -- apply it to the current selection in
the comment."
| c selectedText style |
"Get the selected text."
c := self controllerAt: #comment.
selectedText := c selection.
"If nothing is selected, take no action."
selectedText isEmpty ifTrue: [^self].
"If 'Plain' was selected, remove all emphases;
otherwise add the new emphasis."
style := self textStyle value.
style == #plain
ifTrue: [selectedText emphasizeAllWith: nil]
ifFalse: [
selectedText addEmphasis: (Array with: style)
removeEmphasis: nil
allowDuplicates: false].
"Ask the controller to insert the modified text, then update the
view."
c replaceSelectionWith: selectedText.
c view resetSelections.
c view invalidate.

260

VisualWorks

Text Editors

Highlighting Text
It is occasionally useful for the application to highlight a text selection, for
example to indicate the result of a search.
To highlight text:
1

Write a method in the application model that gets the controller from
the widget.

Ask the controller to select the text between two endpoints (and ask it
to scroll the selection into view if necessary).

Ask the builders component to take the keyboard focus, so the

highlighting will be displayed.
changedClass
"When the list selection changes, update the comment view."
| selectedClass txt start wrapper |
selectedClass := self classes selection.
selectedClass isNil
ifTrue: [self comment value: '' asText]
ifFalse: [
txt := (selectedClass asQualifiedReference value) comment.
self comment
value: txt.
"Find and highlight the class name in the text."
start := txt
indexOfSubCollection: selectedClass asString
startingAt: 1.
start > 0 ifTrue: [
wrapper := (self wrapperAt: #comment).
wrapper widget controller
selectAndScrollFrom: start
to: start + selectedClass asString size - 1.
wrapper takeKeyboardFocus]].

Aligning Text
By default, text in an editor is aligned at the left margin. For wordprocessing applications, you may want to center the text or align it at the
right margin. You can change the alignment by setting the text editors
Align property.

GUI Developers Guide

261

Chapter 9 - Configuring Widgets

For the initial alignment setting, use the Details property page and set the
editors Align property to Left, Center, or Right.
Note: Alignment applies to the entire text. It cannot be applied
selectively to a portion of the text.
To change the alignment for the text editor widget programmatically:
1

In a method in the application model, get the widget from the builder.

Get a copy of the widgets text style. (Do not modify the widgets text
style directly, because that object is shared by many text editors in
the system.)

Set the alignment of the text style to 0, 1, or 2 (0 is flush left, 1 is flush

right, and 2 is centered).

Install the new text style in the widget.

Ask the widget to redisplay itself.

alignRight
| widget style |
widget := self widgetAt: #comment .
style := widget textStyle copy.
style alignment: 1.
widget textStyle: style.
widget invalidate.

Text Editor Events

A Text Editor triggers events when its value is changing, when it gains
and looses focus, when it gets clicks from the mouse, and when it's view
scrolls.
#changing
When the value of a text editor is about to be accepted after directly
editing the value and exiting the input field, the text editor triggers the
#changing event.
#changed
After the value of the text editor has been accepted, the text editor
triggers the #changed event.
#clicked
When a text editor is clicked on with the <Select> mouse button, the
text editor triggers the #clicked event.

262

VisualWorks

Text Editors

#rightClicked
When a text editor is right clicked on with the <Operate> mouse
button, the text editor triggers the #rightClicked event. This event will
occur without regard to whether there is a popup menu associated
with the text editor.
#doubleClicked
When a text editor is double clicked on with the <Select> mouse
button, the text editor will trigger the #doubleClicked event. This event
is always immediately preceded by a #clicked event.
#gettingFocus
When a text editor receives focus, either by being tabbed to or by
clicking on by the mouse, the text editor triggers the #gettingFocus
event.
#losingFocus
When a text editor looses focus, either by being tabbed away from, or
by having another widget on the canvas gain focus, the text editor
triggers the #losingFocus event.
#tabbed
When a text editor has focus, and the Control-Tab key is pressed to
move the focus to the next widget in the tab order, the text editor
triggers the #tabbed event.
#scrollLeft
If while editing, navigating with the keyboard, selecting text with the
keyboard or mouse, or manipulating a horizontal scroll bar in a text
editor, the view scrolls to the left, the text editor triggers the #scrollLeft
event.
#scrollRight
If while editing, navigating with the keyboard, selecting text with the
keyboard or mouse, or manipulating a horizontal scroll bar in a text
editor, the view scrolls to the right, the text editor triggers the
#scrollRight event.
#scrollUp
If while editing, navigating with the keyboard, selecting text with the
keyboard or mouse, or manipulating a vertical scroll bar in a text
editor, the view scrolls up, the text editor triggers the #scrollUp event.
#scrollDown
If while editing, navigating with the keyboard, selecting text with the
keyboard or mouse, or manipulating a vertical scroll bar in a text
editor, the view scrolls down, the text editor triggers the #scrollDown
event.

GUI Developers Guide

263

Chapter 9 - Configuring Widgets

Tree View

Online Examples: TreeViewExample, AdvancedTreeViewExample

A Tree View provides and expandable list view on a hierarchy of items,
such as a file directory system or an object hierarchy. The tree is
expandable either by menu selection, mouse click, or key command,
depending on its configuration.
Keyboard control is described in the following table:
Key command

Description

Home

Select first item

PageUp

Move selection one page up

Up

Select previous item

Ctrl+Up

SelectionInTree: Select previous item at same level

MultiSelectionInTree: Add previous item to selection list

Down

Select next item

Ctrl+Down

SelectionInTree: Select next item at same level

MultiSelectionInTree: Add next item to selection list

264

PageDown

Move selection one page down

End

Select the last item

Left

Contract item

Contract item

Right

Expand item

Shift+Right

Expand item and sub items

VisualWorks

Tree View

Key command

Description

Ctrl+Right

Expand (invisible) root and all sub items

Expand item

Expand item and sub items

Ctrl+W

Reset buffer for string serach

any

Do string search

Basics
The properties on the Basics page are the usual ones.

Aspect
The name of the aspect instance variable and accessors. The aspect
must be either a SelectionInTree or a MultiSelectionInTree.

Details
The properties on the Details page are the same as for List, and are
mostly self-explanatory.

Minimum Element Height

By default, the spacing of the lines in the tree list is determined by the
font height. You can specify a minimum height as an Integer number of
pixels. This may be necessary, for example, if you use an icon that is
taller than the font, which would otherwise get cut off in display.

Whole Line Selection

By default, only the text is highlighted when an item in the Tree View is
selected. To select the whole line, including the icon, if any, check the
Whole Line Selection property.

Advanced
The Item Text Emphasis items specify method selectors to specify text
formatting of a node label when the node is opened, closed, or a leaf
node.

Items
The Items page is specific to Tree View.

Display String
This property sets the selector to be sent to an item in order to retrieve its
textual representation.
GUI Developers Guide

265

Chapter 9 - Configuring Widgets

Icons
None: Items will be displayed using the textual representation only.
Folders: Folder icons will be used.
User Defined: The selector that returns an items iconic representation.
Show Child Images: If checked, the TreeView will have a [+] image next
to child items, if expandable. If unchecked (the default), it will not have a
[+] next to the root item.
Show Root Image: If checked, the TreeView will have a [+] image next to
the Root item. If unchecked (the default), it will not have a [+] next to the
root item. Note that without the image, it is the applications responsibility
to show the root expanded.
Show Lines: If checked, includes connecting lines between parent and
child nodes.
In-Place Edited Selector: The selector that is used to notify an item
about a successful in-place edit. The corresponding method must take
one argument, which will be bound to the editing result (a String).

Initializing a Tree View

A TreeView's model is a SelectionInList on a TreeModel. The TreeModel is
initialized during the interface building process.
There are basically two ways to initialize a TreeView's model. You can
assign a proper model. For example:
initialize
self treeView list: (TreeModel on: TreeTestNode example1)
Alternatively, you can send a root:displayIt:childrenBlock: message to an
initialized TreeModel (see the example1 class method in TreeViewExample):
| app |
app := self new.
self openOn: app.
app treeView list
root: Object
displayIt: true
childrenBlock: [:cls | cls subclasses select: [:ea | ea isMeta not]]
For variations, refer to the initialize-release and instance creation method
categories in TreeModel.

266

VisualWorks

Tree View

Programmatic Interface
Controller Interface
The TreeController supports these local menu items: expand, expandFully,
contractFully, and inplaceEdit.
The expand/contract methods operate on the currently selected item, the
current selectionIndex.
Also, Tree Views do not automatically expand upon opening. To expand
fully on open, define a postOpenWith: method in the application, such as
this:
postOpenWith: aBuilder
| treeWidget |
treeWidget := self widgetAt: #TreeView1.
treeWidget selectionIndex: 1.
treeWidget controller expandFully.
This opens the view with the first item selected. If you do not want to
leave an item selected, append this line:
treeWidget selectionIndex: 0
If the aspect is a MultiSelectionInTree, the expand/contract message is
applied to the first element in its OrderedCollection of elements. The order
of the elements is the order in which the elements were selected.

Model Interface
The widgets model is a TreeModel. The public interface consists of the
following methods to specify the root of a tree and its children. Both
instance methods and instance creation methods are provided.
Instance methods:
root: anObject
Set the root node and display it
root: anObject displayIt: aBoolean
Set the root node and determine whether the root itself should be
displayed or not
root: anObject displayIt: aBoolean childrenBlock: aBlock
Set the childrenBlock and the root node and determine whether the
root itself should be displayed or not
Class methods:
on: root
Provide a new instance initialized with the given root.
GUI Developers Guide

267

Chapter 9 - Configuring Widgets

on: root displayRoot: displayIt

Provide a new instance initialized with the given root. The second
parameter determines whether the root will be displayed.
on: root displayRoot: displayIt childrenWith: childBlock
Provide a new instance initialized with the given root and childBlock.
The second parameter determines whether the root will be displayed.

Adding a Tree View

1

Use a Palette to add a Tree View widget to the canvas. Leave the list
selected.

On the Basics property page, fill in the lists Aspect property with the
name of the method that will return an instance of SelectionInTree.

Apply the change, install the canvas, and use define to add an instance

variable and aspect accessor method to the application model. This

instance variable will hold the SelectionInTree.
4

Write an initialize method to initialize the SelectionInTree (see

Initializing a Tree View above).

Adding Text Emphases

To add text formatting to tree node labels, do the following:
1

Select the TreeView widget on the canvas.

On the Advanced page in the GUI Painter Tool, enter a selector name
for each of the node conditions that you want to specify an emphasis
for. For example, to specify formatting for a closed node, enter a
selector name in the Opened Selector field. The selectors may be either
unary or single-argument keyword method names.

Install the canvas, and use Define to generate the new selectors.

Browse your application models tree view emphasis method category,

and edit the stub methods.

The methods must return an Array of text emphases. For example, if the
unary selector is closedNode, and the emphasis is #italic, the method
would be:
closedNode
^#(#italic)
Standard text emphases are #bold, #italic, #serif, #underline, #strikeout,
#large, and #small.

268

VisualWorks

Tree View

To specify a color, include in the Array an association with #color as the

key and a ColorValue as value:
closedNode
^Array with: #italic with: #color->ColorValue blue
If the selector is a single-argument keyword, the TreeView instance is
passed into the method, and is available for testing. For example:
leafEmphasis: aTreeValue
aTreeValue == VisualBlock ifTrue:
[^Array with: #bold with: #color->ColorValue blue].
^#(#normal)

Tree View Events

A Tree View triggers events when a selection is changing, when the
underlying list itself is changing, when it gains and loses focus, when it
gets clicks from the mouse, when a node is expanded or collapsed, when
an item in its list is edited in place, and when it's view scrolls.
#clicked
When a tree view is clicked on with the <Select> mouse button, the
tree view triggers the #clicked event.
#rightClicked
When a tree view is right clicked on with the <Operate> mouse
button, the tree view triggers the #rightClicked event. This event will
occur without regard to whether there is a popup menu associated
with the tree view.
#doubleClicked
When a tree view is double clicked on with the <Select> mouse
button, the tree view triggers the #doubleClicked event. This event is
always immediately preceded by a #clicked event.
#gettingFocus
When a tree view receives focus, either by being tabbed to or by
clicking on by the mouse, the tree view triggers the #gettingFocus
event.
#losingFocus
When a tree view loses focus, either by being tabbed away from, or
by having another widget on the canvas gain focus, the tree view
triggers the #losingFocus event.

GUI Developers Guide

269

Chapter 9 - Configuring Widgets

#tabbed
When a tree view has focus, and the Tab key is pressed to move the
focus to the next widget in the tab order, the tree view triggers the
#tabbed event.
#backTabbed
When a tree view has focus, and the Back-Tab (Shift-Tab) key is
pressed in request to have the focus move to the previous widget in
the tab order, the tree view triggers the #backTabbed event.
#scrollLeft
If while navigating with the keyboard or manipulating a horizontal
scroll bar in a tree view, the tree view scrolls to the left, the tree view
triggers the #scrollLeft event.
#scrollRight
If while navigating with the keyboard or manipulating a horizontal
scroll bar in a tree view, the tree view scrolls to the right, the tree view
triggers the #scrollRight event.
#scrollUp
If while navigating with the keyboard or manipulating a vertical scroll
bar in a tree view, the tree view scrolls up, the tree view triggers the
#scrollUp event.
#scrollDown
If while navigating with the keyboard or manipulating a vertical scroll
bar in a tree view, the tree view scrolls down, the tree view triggers
the #scrollDown event.
#selectionChanging
When an item in a tree view is selected or unselected, or in the case
of a multiple select tree view, when the selections change, before the
change is applied, the tree view triggers the #selectionChanging event.
#selectionChanged
After an item in a tree view is selected or unselected, or in the case of
a multiple select tree view, when the selections have changed, the
tree view triggers the #selectionChanged event.
#selectionListChanged
Whenever the list underlying a tree view is manipulated, either by
changing a value, reordering, adding or removing items, or changing
the list as a whole, the tree view trigger the #selectionListChanged
event.

270

VisualWorks

Tree View

#itemExpanded
When an item in the tree view is visually toggled from its collapsed
view to its expanded view, the tree view triggers the #itemExpanded
event.
#itemCollapsed
When an item in the tree view is visually toggled from its expanded
view to its collapsed view, the tree view triggers the #itemCollapsed
event.
#itemEdited
If an item in a tree view has an in place editor defined, and that item
is edited, once the editing is completed the tree view triggers the
#itemEdited event.

GUI Developers Guide

271

Chapter 9 - Configuring Widgets

View Holder
The View Holder widget places a custom view on the canvas. While the
interface to the View Holder widget is very simple, defining the custom
view can be quite complex. See Chapter 8, Custom Views, for more
information.

SketchView custom view

Adding a View Holder

Adding a view to a canvas simple:
1

Add a View Holder widget to the canvas.

In the View Holders View: field, enter the selector for method that
returns an instance of the view, for example, #myView. Accept the
change and install the canvas.

In your application model, define the method you entered in step 2.

The method returns an instance of the custom view. For example:
myView
^MyViewClass new.

View Holder Events

A View Holder triggers events when its view scrolls due to activity via its
scroll bars.
#scrollLeft
If while manipulating a horizontal scroll bar in a view holder, the tree
view holder to the left, the view holder triggers the #scrollLeft event.

272

VisualWorks

View Holder

#scrollRight
If while manipulating a horizontal scroll bar in a view holder, the view
holder scrolls to the right, the view holder triggers the #scrollRight
event.
#scrollUp
If while manipulating a vertical scroll bar in a view holder, the view
holder scrolls up, the view holder triggers the #scrollUp event.
#scrollDown
If while manipulating a vertical scroll bar in a view holder, the view
holder scrolls down, the view holder triggers the #scrollDown event.

GUI Developers Guide

273

Index
Symbols
& (menu mnemonic) 90, 92
<Operate> button 14
<Select> button 14
<Window> button 14

A
accessor method
adapting 78
widget aspect 30
action button 158
active window, accessing 54
adaptor
aspect of a model 78
buffered 81
custom 87
on a collection 85
on a collection element 86
value holder 77
Adaptor1Example 77
Adaptor2Example 79, 80
Adaptor3Example 83, 84
Adaptor4Example 85
Adaptor5Example 86
Adaptor6Example 87
adding
widgets to a canvas 29
AdvancedTreeViewExample class 264
aligning
widgets 43
application
model 31
nesting 242
Arrange menu
Align 44
Distribute 44
aspect adaptor 78

B
boolean
in a field 185
bordering a widget 29
bounded widget 40
BufferedValueHolder class 82

274

buffering model updates 81

business graphics, See chart widget 162
Button Tab Notebook widget 161
ButtonExample 154
buttons
See also menu button
action 158
check box 156
mouse 14
radio 154
bypassing a dependency 72
ByteArray
in a field 186

C
canvas
installing 31
opening an existing 32
tab order 47
Change Validation property 187
chart widget 162
check box
adding to UI 156
in menu 102
circle
See also ellipse
Click Map widget 167
closing a window 50
collapsing a window 58
collection
See also list widget 194, 202
adapting 85
adapting an element 86
color
label widget 198
ColorDDExample 110, 115, 117, 119, 122,
127
ColorExample 71
column widths
dataset 176
table 254
ComboBoxExample 170
ComboConversionExample 171
component, See widget
composite widget 43

VisualWorks

Index

ConfigurableDropTarget class 109, 113

confirmer dialog 132
connecting
field to field 191
view to controller 147
controller
connecting a composite view 150
connecting view 147
getting for a widget 150
conventions
typographic 13
creating
application model 31
icon 58
current window, See active window
custom
adaptor 87
dialog 140
view 143
Customer1Example 80
Customer2Example 85
CustomViewExample 144, 152

D
damage
rectangle 150
window 57
data
formatting 186
types in input field 185
data series 162
labels 163
dataset columns
order 177
scrolling 177
widths 176
dataset widget
adding a row 179
row marker 179
Dataset1Example 174
Dataset2Example 179
Dataset3Example 180
date
in a field 185
dependency
adding 72
between widgets 71
bypassing 72
removing 72
DependencyExample 72
desiresFocus message 148

GUI Developers Guide

dialog
custom 140
get file name 134
textual 133
warning 131
yes-no 132
dimension
of a window 56
disabling
menus 98
widgets 70
displaying
in a view 145
domain model
adapting an aspect 78
connecting to view 144
updating view 146
doughnut labels 166
drag and drop 108130
adding 110
dropping on a list item 123
effect symbol 115
examining dragged data 126
framework classes 109
modifier keys 126
multiple selections 112
responding to a drop 121
visual feedback 114
Drag OK property 110
Drag Start property 110
DragDropContext class 109, 114
DragDropData class 109, 111
DragDropManager class 109, 112, 113, 122
Drop property 113, 121
drop source 108, 110
adding 110
setting up 108
drop target 108, 113
button 117
changing button label 117
examining dragged data 126
list item 119, 123
messages 114
providing visual feedback 114
responding to a drop 121
setting up 108
tracking a specific list item 119
using modifier keys 126
DropSource class 109, 112

275

Index

E
editing
a list 202
editor widget 259
Editor1Example 259
effect symbol 115, 122
See also target emphasis
electronic mail 16
elements
adapting 86
ellipse
grouping widgets 226
Ellipse property 226
embedded canvas
See subcanvas
Entry property 113, 114
events
activate 62
and dependents 76
backTabbed 156, 157, 160, 173, 181,
193, 196, 207, 212, 221, 239, 251, 258,
270
bounceBottom 240
bounceTop 240
bounds 62
cellBackTabbed 182
cellGettingFocus 182
cellLosingFocus 182
cellSelectionChanged 258
cellTabbed 182
cellValueChanged 182
changed 172, 193, 211, 224, 227, 236,
238, 247, 262
changing 172, 192, 211, 227, 236, 238,
247, 262
checked 158
clicked 64, 155, 157, 159, 169, 173, 193,
196, 207, 211, 230, 238, 257, 262, 269
close 62
closing 64
collapse 63
columnLabelClicked 182
columnSelectionChanged 258
deactivate 63
destroy 63
doubleClicked 65, 173, 181, 193, 196,
207, 239, 257, 263, 269
enter 63
exit 63
expand 63
expose 63

276

gettingFocus 64, 155, 157, 159, 173,

181, 193, 196, 207, 211, 221, 239, 251,
257, 263, 269
hitMappedRegion 169
horizontalTabChanged 222
horizontalTabChanging 222
itemCollapsed 197, 271
itemEdited 271
itemExpanded 197, 271
labelChanged 155, 157, 159, 201
labelChanging 155, 157, 159, 201
listClosed 173, 212
listExposed 173, 212
losingFocus 64, 155, 157, 160, 173, 181,
193, 196, 207, 212, 221, 239, 251, 258,
263, 269
mapped 64
menuBarCreated 66
menuClosed: 106
menuItemSelected: 106
menuOpened: 106
middleClicked 65
missedMappedRegion 169
move 63
moved 230
opening 64
pageLeft 251
pageRight 252
popupMenuCreated 107
popupMenuItemSelected: 107
pressed 159
resize 63
rightClicked 65, 173, 180, 193, 196, 207,
239, 257, 263, 269
rowLabelClicked 182
rowSelectionChanged 258
rowSelectionsChanged 182
rowSelectionsChanging 182
scrollDown 66, 181, 197, 208, 221, 247,
258, 263, 270, 273
scrollLeft 65, 181, 193, 196, 208, 221,
247, 251, 258, 263, 270, 272
scrollRight 65, 181, 193, 197, 208, 221,
247, 251, 258, 263, 270, 273
scrollUp 66, 181, 197, 208, 221, 247,
258, 263, 270, 273
selectionChanged 197, 208, 270
selectionChanging 197, 208, 270
selectionListChanged 197, 208, 270
spinDown 240
spinUp 239
spunDown 240
VisualWorks

Index

spunUp 239
submenuClosed: 107
submenuOpened: 106
tabbed 155, 157, 160, 173, 181, 193,
196, 207, 212, 221, 239, 251, 258, 263,
270
tabChanged 252
tabChanging 252
toolBarButtonSelected: 107
toolBarCreated 66
turnedOff 156
turnedOn 156
unchecked 158
unknownEvent 63
unmapped 64
verticalTabChanged 222
verticalTabChanging 222
window 61
wrapAroundBottom 240
wrapAroundTop 240
examples 18
Exit property 113
Exit Validation property 187
expanding
windows 58
exploding labels 166

F
field
connecting to a field 191
creating 184
dialog 133
filtering and validating 187
formatting numbers 186
highlighting 192
menu 189
type restriction 185
widget, connecting to a slider 231
FieldConnectionExample 191
FieldMenuExample 189
FieldSelectionExample 192
FieldTypeExample 186
FieldValidation1Example 188
FieldValidInputExample 187
file name
dialog 134
fill-in-the-blank dialog 133
filtering
field input 187
resource list 23
fixed-point number
in a field 185
GUI Developers Guide

fly-by help 30
font
changing widgets 45
label 198
Font1Example 68
fonts 13
formatting
displayed data 186
numeric field 186

G
globalization 30
graphic image
in menu 101
graphic label 198
graphical user interface 2875
GraphicsContext class 145
graying out, See disabling

H
help
fly-by help 30
HideExample 69, 70
hiding
widgets 69
windows 51
Hierarchical List 194
highlighting
in a field 192
in a list 206
holder, See value holder

I
icon
assign to window 59
creating 58
in a menu 101
registering 59
iconifying a window 58
IdentityDictionary class 112
IndentedTreeSelectionInList class 194
IndexedAdaptor class 86
Initially Disabled property 70
Initially Invisible property 69
input field, See field
installing a canvas 31
instance
used in drag and drop 109
interface
integrating a custom view 152
reusing 244
interface component, See widget
interface specification 31
277

Index

internationalization 30
invalidateRectangle 151
invalidating a view 150

K
KeyboardProcessor 148

L
label
table columns 256
table rows 256
window 56
label widget
changing at runtime 199
color 198
creating 198
font 198
graphic 198
registry of labels 200
labels
adding to a chart 163
doughnut 166
exploding 166
Layout commands
Be Bounded 40
Relative 38, 40
Unbounded 40
LineExample 225
List class 202
list widget
adding 194, 202
connecting two lists 206
controlling textual representation 202
editing the list 202
highlighting style 206
List1Example 202
List2Example 241, 243, 244
LogoExample 198
LookPreferences class 71
lookup key 30

M
mail
electronic 16
marker in a slider 235
menu
check box in 102
creating 91
icon 101
in a field 189
item label 101
mnemonics 90, 92
modifying at runtime 98
278

pragma 103
shortcut character 91
menu bar 93
Menu Bar property 36, 94
menu button widget 94, 210
Menu Editor 89
MenuCommandExample 94, 95, 96, 98, 211
MenuEditorExample 90, 96, 97
MenuModifyExample 98, 99, 100
MenuSwapExample 100
MenuValueExample 92, 94, 95, 102, 210
message catalog 30
mnemonic 199, 226
model: message 150
mouse buttons 14
<Operate> button 14
<Select> button 14
<Window> button 14
Multi Select property 113
MultiSelectionInList class 113, 204
MultiSelectionInTree class 267

N
nesting applications 242
NoController class 150
nontextual collection 202
notational conventions 13
notebook widget
changing the page 219
index tabs 215
minor keys 216, 218
secondary tabs 216
starting page 161, 215
tab selection 215
Notebook1Example 213, 215
Notebook2Example 216
Notebook3Example 218
Notebook4Example 220
notification properties 7475
notifier
dialog 131
number
field formatting 186
in a field 185
NumberPrintPolicy class 186

O
object
in a field 186
opening
canvases 48

VisualWorks

Index

specs 48
windows 47
options
doughnut labels 166
exploding labels 166
order of tabbing 47
Over property 113, 114

P
page in a notebook 161, 215
pane, See view
Pareto chart 164
partner windows 60
password in a field 185
picture chart 164
sample data 164
pie chart 166
definition 166
doughnut labels 166
exploding labels 166
PluggableAdaptor class 87
pointer shape, See effect symbol
positioning a widget 40
Print property 171
properties of windows and widgets 29

R
radio button 154
range
in a slider 233
Read property 171
redisplaying a view 150
refreshing a window 57
region widget 225
registering an interest 71
registry
of labels 200
relative sizing of widget 39
Resource Finder 23
reuse techniques 241247
reusing an interface 244
row selector in a dataset 179

S
sample data
picture chart 164
XY chart 165
ScheduledControllers object 54
Screen 55
SelectionInList class 85, 174, 202, 213
SelectionInTable class 253
SelectionInTree class 268
SimpleDialog class 141
GUI Developers Guide

Size1Example 39, 41
Size2Example 40, 42
Size3Example 68
sizing widgets 38
Sketch 142, 146
SketchController 142, 150
SketchView 144, 145, 146, 150, 151, 152
slider widget
adding 231
connecting to field 231
marker length 235
modifying range 233
read-only 231
two-dimensional 235
Slider1Example 231, 233
Slider2Example 184, 232, 235
spacing
a group of widgets 44
special symbols 13
spin button widget
adding 238
StringPrintPolicy class 186
subcanvas
accessing embedded widget 246
in a notebook 219
Subcanvas1Example 241
Subcanvas2Example 243, 244
Subcanvas3Example 245, 246
subject of an adaptor 78
substituting a menu 100
support, technical
electronic mail 16
World Wide Web 16
symbol in a field 185
symbols used in documentation 13
synchronizing updates 81

T
tab order 47
tabbing
Can Tab property 47
order 47
TabControlExample 248
table widget
connecting to input field 255
labeling 256
updating 255
Table1Example 253
Table2Example 255
Table3Example 256
TableInterface class 253
target emphasis 119, 123
279

Index

technical support
electonic mail 16
World Wide Web 16
text
editor, See editor widget
in a field 185
TextAttributes 68
textual dialog 133
time
in a field 185
time stamp
in a field 185
TimestampPrintPolicy class 186
title, See window label
tools
Resource Finder 23
UIBuilder 48
traverse UI 47
TreeViewExample class 264
true-false dialog 132
two-dimensional slider 235
Type property 185
TypeConverter 186
typographic conventions 13

U
UIBuilder 48
unbounded widget 40, 42
updating
a table 255
a view 146
an aspect adaptor 79
buffered 81

V
validating field input 187
validation properties 73, 187
value holder 77
view
connecting to controller 147
connecting to model 144
creating 143
displaying 145
integrating in interface 152
invalidating 150
redisplaying 150
updating 146
with no controller 150
View Holder widget 152
visibility of a widget 69
visual component, See widget

280

W
warning dialog 131
widget
accessing programmatically 66
aligning 43, 44
border 29
bounding 40
disable 70
drop source, See drop source
drop target, See drop target
embedded in subcanvas 246
font 45
groups 43
hiding 69
notification property 74
positioning 40
region 225
sizing 38
spacing 44
tab order 47
unbounded 42
validating actions 73
validation property 73
widgets
composite 43
group 43
WidgetWrapper 67
width
of dataset columns 176
of table columns 254
window
active 54
at a location 55
closing 50
creating 28
events 61
expanding and collapsing 58
get dimensions 56
hiding 51
label 56
menu bar 93
opening 47
position 35
refreshing 57
set initial size 34
specification 48
World Wide Web 16
wrapper 67

VisualWorks

Index

X
XY chart 165
sample data 165

Y
yes-no dialog 132

GUI Developers Guide

281

Method Index
A

contextWidget: 111
contextWindow: 111
controller: 150
controllerAt: 53

accessWith:assignWith: 80
adapt:aspect:list:selection: 85
addItemLabel:value: 99
alignment: 262
applyColorDrop: 122
applyColorEnter: 115
applyColorExit: 115, 116
applyColorOver: 115, 116
applyMoreColorEnter: 117
applyMoreColorExit: 117
applyMoreColorOver: 117
asValue 77
atNameKey: 96

definedNamedFonts 46
disable 70
display 57
displayBox: 56
displayOn: 145
doDragDrop 112
drag-ok 110
drag-start 110
drop 122

backgroundColor: 71
beginSubMenuLabeled: 92
beInvisible 69
beMaster 60
beOff 103
beOn 103
bePartner 60
beSlave 60
beTwoDimensional 235
beVisible 69
bounds 68

C
changed: 80, 146
changed:with: 88, 146
changeRequest 50
choose:fromList:values:lines:cancel: 136
choose:labels:values:default: 133
clearAll 206
client:spec: 220, 245
clientData 123
closeRequest 50
collapse 58
colorDrag: 111, 123
colorLayerEnter: 119
colorLayerExit: 119
colorLayerOver: 119
colorWantToDrag: 111
contextApplication: 111

282

enable 70, 98
endSubMenu 93
expand 58
expandedMenu 190

F
forAspect: 79
foregroundColor: 71
forIndex: 86

G
getBlock:putBlock:updateBlock: 87
globalCursorPoint 55
grid: 234

H
hideItem: 99

I
icon: 59
interfaceSpecFor: 245
invalidate 260, 262
invalidateRectangle: 151
invalidateRectangle:repairNow: 151

K
key: 111
keyboardHook: 188

VisualWorks

Method Index

L
label: 56, 199
labelAt:put: 200
labelImage: 102
labelString: 69, 117, 199

subject: 80, 86
subject:triggerChannel: 83
subjectChannel: 79, 86
subjectSendsUpdates: 80
submenu 96

mainWindow 53
menuAt: 96
menuItems 97
model: 145

takeKeyboardFocus 192, 261

textStyle: 69, 262
topComponent 54

unhideItem: 99
update:with: 147

nameKey 97
newBoolean 78
newBounds: 68
newFraction 78
newString 78

O
onChangeSend:to: 72
openDialogInterface: 140
openIn: 50
openWithExtent: 49
openWithSpec: 48

U
V
visualAt:put: 200
visuals 201

W
widgetAt: 53, 66
windowAt: 55
windowMenuBar 53
windowSpec 48
wrapperAt: 53, 67

P
postBuildWith: 188, 191

R
rangeStart: 234
rangeStop: 234
removeItem: 100
replaceSelectionWith: 260
requestFileName: 134
resetSelections 260
retractInterestsFor: 72

S
selectAll 205
selectAndScrollFrom:to: 261
selection: 215
selectionBackgroundColor: 71
selectionForegroundColor: 71
selectionIndex: 215
selectionIndexes: 205
selections 113
selections: 205
setValue: 73
showDropFeedbackIn:allowScrolling: 120
source: 48
sourceData 122
styleNamed: 68

GUI Developers Guide

283

Reader Comment Sheet

Name:
Job title/function:
Company name:
Address:
Telephone number:

Date:

How often do you use this product?

Is the information easy to understand?

Please comment.

# Months

FAX
IT!

Can you find the information you need?

Please comment.

# Weekly # Monthly

# Daily

How long have you been using this product?

# No

# Yes

# No

# Yes

# Less

# Years

# Yes

Is the information adequate to perform your task?

# No

Please comment.

General comment:

WE STRIVE FOR QUALITY

To respond, please fax to Larry Fasse at (513) 612-2000.

P46-0136-01