Chapter 2: VisualWorks

The purpose of this chapter is to familiarize the reader with the basic features and capabilities of VisualWorks.

Starting VisualWorks

To start VisualWorks from the command line of a Unix system, use the command


where visual_path is typically /opt/visual (/opt/local/visual at the Computer Science Department at Clemson University). The file is called the image file. It contains the initial VisualWorks environment. The default system image file is typically visual_path/image/ On the Sun Solaris platforms at Clemson, the command


will start up VisualWorks with the default image. To start VisualWorks with an image other than the default, use the command

vw image-file

Enter the appropriate command to start VisualWorks on your system. You should see two windows, the VisualWorks Launcher and the Workspace.

VisualWorks Launcher

The VisualWorks Launcher is the main window in VisualWorks. It is used primarily to access the various tools and resources available. A Launcher window is shown below.


A Workspace is used primarily to test pieces of Smalltalk code. A Workspace window is shown below.

Using the Mouse and the Pop-Up Menus

General familiarity with windowing systems is assumed in this tutorial. Mouse button operations refer to the left ([Select]) mouse button unless otherwise specified.

There are two types of pop-up menus associated with each window in VisualWorks. There is the [Window] menu which is accessed by clicking the right mouse button in the window. The [Window] menu is used for closing, moving, and resizing the current window. The second pop-up menu is the [Operate] menu which is accessed by clicking the middle mouse button in the window. There may be more than one [Operate] menu per window, in which case an area will be specified in which to click the middle mouse button. To select an item from either the [Operate] or [Window] menus the mouse button used to obtain access the menu must be used.

Note: The following conventions are used for one-button and two-button mice:

Two-button mouse

  • The left button is the [Select] button.
  • The right button is the [Operate] button.
  • The [Window] menu is obtained by using the Control key and right ([Operate]) button together.

    One-button mouse

  • The button alone is the [Select] button.
  • The [Operate] menu is accessed using the Option key and the button together.
  • The [Window] menu is accessed using the Command key and the button together.

    In windows that have a menu bar, pulldown menus are accessed by clicking on the word associated with the menu. For example, click on File located on the Launcher's menu bar to obtain the File pulldown menu. Pulldown menu selections will be specified by the menu name followed by an arrow(->) and the menu item. For example, the File->Settings option from the VisualWorks Launcher refers to the Settings option from the File pulldown menu. Many pulldown menu options also have a shortcut button on the tool bar, which will be refer to with its associated icon. For example, the Canvas Tool may be obtained by using either the Tools->New Canvas menu option or by the shortcut button .

    Setting up VisualWorks

    To insure access to Smalltalk source code and VisualWorks On-line Documentation, the proper paths must be set using the Settings window. Open the Settings window by selecting the File->Settings options from the VisualWorks launcher. You should see the window depicted below. Make sure that the correct the path for the VisualWorks source code is displayed (visual_path/image/visual.sou). If you need to correct the path, correct as necessary and click Accept. (Note: No changes should be needed at Clemson.)

    Select the help settings by clicking on the Help tab of the Settings notebook pages (not on the Help button for the Settings window). You should see the following window. Make sure that the path for the online documentation is correct. Click Accept after making any necessary changes.

    Now close the Settings window by selecting close from the Settings [Operate] menu.


    In VisualWorks, a GUI window is created by using the Canvas Tool and placing widgets on the Canvas. A GUI window contains components called widgets. Widgets are control and information structures, and they come in various forms. For example, the Settings window shown in the previous section is composed of the following widgets (left-to-right, top-to-bottom): a notebook, labels, input fields, and action buttons. Here is a list of the widgets available in VisualWorks.

    Action Button
    Check Box
    Radio Button
    Input Field
    Text Editor
    Menu Button
    Combo Box
    Group Box
    Data Set
    View Holder
    Linked Data
    Embedded Data

    More information on each of these widgets is available in the online documentation (which is described below).

    The Canvas, Canvas Tool, and Palette

    A VisualWorks canvas is much like an artist's canvas on which you paint a GUI window using widgets instead of paint. To obtain a canvas you can select Tools->New Canvas from the Launcher, or use the shortcut button on the Tool Bar. An outline of a Canvas window will appear. Move this to a preferred location on the screen and place it by clicking the mouse button. The Palette and Canvas Tool window will appear around the Canvas. Note that most other windows in VisualWorks will first appear in outline form, and you will then be required to place the window on the screen in this manner.

    Bringing up a Canvas should produce three new windows similar to the following:

    To demonstrate how these tools work, click on the action button widget on the Palette. The text "Action Button" will be displayed at the bottom of the Palette. Place an action button on the Canvas by clicking on the Canvas where the action button is to be placed. As you can see, providing a combination of widgets would enable you to create a GUI like the Palette itself. Try placing more widgets on the Canvas if you wish. Now close the Canvas Tool by selecting close from the Canvas [Operate] menu.

    Online Documentation

    Another useful tool in VisualWorks is the online documentation. The online documentation can be accessed from the VisualWorks Launcher via the Help->Open Online Documentation option or the shortcut button . Shown below is the Online Documentation window that lists three manuals that may be used as further references. These three manuals include the following:

    For example, suppose you needed information on how to construct a Smalltalk message. Select the VisualWorks CookBook by clicking on the book title with the mouse button. Now, select Chapter 1: Smalltalk Basics, and then select Constructing a Message. Information on your topic is now displayed in the Online Documentation window. Close the Online Documentation window.

    System Browser

    A System Browser is a useful tool for viewing Smalltalk classes, protocols, and methods. Not only does a Browser provide useful ways to view system and user classes, it also has many features that help the user to quickly and easily develop classes, protocols, and methods.

    To open a System Browser, select Browse->All Classes from the VisualWorks Launcher or use the shortcut button . Notice that a System Browser is divided into four columns across the top half of the window, and the bottom half contains a text area. These are important areas to learn. The columns (left-to-right) are the Category View, the Class View, the Protocol View, and the Method View. The text area that comprises the bottom half of the window is the Code View. These five different views will be referred to frequently in the development portion of this tutorial.

    For example, select the category "Magnitude-General" and the classes associated with that category appear in the Class View. Select the Date class, and the protocols associated with that class are displayed in the Protocol View. Finally, select the accessing protocol and the methods associated with that protocol are displayed in the Method View. The System Browser should now look like the window shown below.

    Notice that the Code View currently contains only a template for the code of a method. Select any method and you will see its code in the Code View. Close the System Browser by selecting close from the System Browser [Window] menu.

    Filing In and Filing Out Components

    To save categories, classes, or even methods you can write ("file out") these components to a file and then remove them from your image. Later you can read ("file in") these components into your image.

    Filing In

    We will illustrate how to "file in" components by adding an application, Calculator Example, to our image. The CalculatorExample class is in the category UIExamples-General, and it is stored in the file visual_path/tutorial/basic/ First note that the category UIExamples-General is not currently in the image by scrolling through the categories in the Category View of a System Browser. Open a File List from the Tools->File List option or the shortcut button of the VisualWorks Launcher. Enter /opt/local/visual/tutorial/basic/* in the first input field, which is called the Pattern View, and Return. (Note: This is for the visual_path at Clemson.) Select /opt/local/visual/tutorial/basic/ from the file list, which is called the Names View. The File List should look like the following window.

    Select file in from the Names View [Operate] menu. Verify that the category UIExamples-General is now in the image by using the System Browser. Close the File List.

    Filing Out

    You can file out a category, class, or even single methods. For example to file out a category, select (with a mouse click) a category from the System Browser (so that the category is highlighted). Select file out as... from the Category View [Operate] menu, enter the file name to which you wish to file the category out, and click OK. A category, class, or method that is filed out can later (for example, in another VisualWorks session) be filed in as illustrated in the previous section.

    Starting an Application

    Once you have developed an application you will want to execute it. To start a completed application, open a Resource Finder using Browse->Resources from the VisualWorks Launcher or the shortcut button . Select View->User Classes from the Resource Finder menu. Select the class you would like to start. To start the Calculator Example that we previously filed in, select the CalculatorExample class and the windowSpec resource as depicted below. (Note that the windowSpec resource is automatically selected because it is the only resource for the CalculatorExample class.) Select Start from the Resource Finder and the Calculator Example will start. When you have finished using the Calculator, close the application by selecting close from the Calculator [Window] menu. Close the Resource Finder.

    A class may have one or more "resources", which are user interfaces. To start an application, we select its class and the appropriate resource for the initial window of the application.

    Saving Your Work

    Doing a "Save" in VisualWorks is a complete save. It actually saves an image of all of the current classes (system and user), active windows, etc. This is a nice feature if it becomes necessary to stop in the middle of your work. Unfortunately, saving your image has drawbacks. An image on a Solaris platform will take up approximately 4 megabytes of disk space. To save an image, select File->Save As from the VisualWorks Launcher. A dialog box will appear. Enter the name for your image file and click OK. VisualWorks will save the file in the current directory unless a different path is specified. The file will be have the extension .im.

    VisualWorks automatically creates a .cha file in the directory from which VisualWorks is started, and VisualWorks periodically records the changes made to the initial image in the .cha file. The .cha files can be useful for change management, and they can sometimes be used for error recovery (e.g., if you mistakenly delete some work that you need or fail to file out some work that you wished to save), but you may wish to delete the .cha files until you use VisualWorks in a large project.

    NOTE: Any work done on the canvas will not be saved when an image is saved, unless the current canvas has been installed on a class.