Introduction Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 CLOS Intro
Allegro CL version 8.0

Chapter 1: Create the Application

Do not start the tutorial after the final version has been loaded

Before proceeding through the tutorial, make sure that you have not opened or loaded the final version of the tutorial in the current IDE session (as you might have done, say, to see how the final project works). If the final tutorial has been loaded, you will get lot of redefinition warnings and there will be other problems. If you have loaded the final version (or indeed any version beyond where you are), simple restart the IDE (without reopening the tutorial project), and then proceed through the tutorial.

Starting steps

  1. Open a new project using the File | New Project command. You will be prompted for a directory in which to store the project files (and perhaps a directory in which to place project directories). Here is the dialog which prompts you to choose a directory:

new-proj-gui.bmp (650802 bytes)

We suggest naming the directory gui-builder-tutorial, as shown, a subdirectory of the C:\allegro-projects\ on Windows and allegro-projects/ on Linux. (Choose any name and location you like, of course) In the documentation, we will assume you have chosen C:\allegro-projects\gui-builder-tutorial\ on Windows and allegro-projects/gui-builder-tutorial/ on Linux. A new project will be created and become the current project.

  1. View the Project Manager dialog using the View | Project Manager command. In the Project Manager dialog, click on the Options tab. The project name should be gui-builder-tutorial (same as the directory name). The project manager title should be "Gui-builder-tutorial" and the title of the Project Window, the window across the top with the menus and toolbars, should be "Gui-builder-tutorial - International Allegro CL …".
  2. If there is no form, click on File | New Form. This dialog will appear asking for the class (i.e. type) of the form. Accept the default dialog by clicking OK.

new-form.bmp (549702 bytes)

Because this is the first form we have created in this Lisp session, its initial name is form1. The form you create may have that name or perhaps form2 or formN for some other N. We will soon change its name so its initial name is not important.

  1. Click on the Save All button on the standard toolbar (or click File | Save All).

ch1-1-sa.bmp (14262 bytes)

The project file will be automatically saved to gui-builder-tutorial.lpr in the project directory. Save the form to doodler.cl (rather than form1.cl).

  1. In the Project Manager, switch back to General tab.
  2. Click on the Add button in the Project Manager toolbar (it looks like a big +). Choose CODE from the Specify the type of module(s)... dialog that appears (meaning that you are adding source files). In the File Choice dialog, navigate back to the Allegro directory, and the [Allegro directory]\gui-builder-tutorial\ subdirectory (the path is usually C:\Program Files\acl80\gui-builder-tutorial\ on Windows or [Allegro dir]/gui-builder-tutorial/ on Linux) Add the file util.cl. You will be asked if you want to copy it to the project directory. Answer `yes'. Repeat for cycloid.cl. Now add three additional files, again from [Allegro directory]\gui-builder-tutorial\: center.bmp, curve.bmp, and erase.bmp. These are distributed files rather than code files (meaning they are not Lisp source files), so choose DISTRIBUTED FILE from the Specify the type of module(s)... dialog rather than CODE and again copy the files.

Note that order is Important in the Project Manager

The order you list files on the General tab is the load order for the files Lisp will use when running your project. The arrow keys on the Project Manager toolbar can help you change the order if you add them to the project incorrectly or want to rearrange them later.

Here is what the Project Manager general tab should look like now:

ch1-pm-notsav.bmp (439014 bytes)

You can inspect these files using the Project Manager. Click on a file name to select it and click the View Selected Code button

ch1-2-vsc.bmp (16310 bytes)

The file will be opened in the Editor.

  1. Inspect form1 (or whatever number form you have) by double clicking anywhere on the form's body (the gray grid of dots). You can also select the form and use the Tools | Inspect Selected Object command.
  1. In the inspector, change name to :doodler. Change the scrollbars to t and the title to Doodler.

Naming Objects

All windows and controls have names. As you begin to write the event handling code for these objects, you will use their names to refer to them.

Making Changes in the Inspector

The right-hand column of the inspector contains values. The left-hand column contains symbols, (in this case, names of properties). Make the changes requested in this step by clicking on each property's value field and typing a new value in its place. In some cases, you'll be offered a drop-down menu of choices when you click on the value, and you will be able to choose one from the menu.

The changes will commit when you hit ENTER or move the focus to a new location in the inspector. Notice that the title of the form changes. From here on we call it the Doodler form.

  1. Switch to the Project Manager Dialog (the General tab should be visible; change to it if it is not). Select the doodler form and click on the View Selected Code button on the Project Manager's toolbar.

    ch1-2-vsc.bmp (16310 bytes)

Package Statements

You’ll see an (in-package :common-graphics-user) statement in the buffer. In-package statements need to be included in every form you build for Common Lisp applications. common-graphics-user is the default package for a project, and is the one that we are using for this tutorial. Projects in general may use that package or a custom package.

Working with Editor Buffers in the Workbook

Whenever you choose the View Selected Code button, you are placed in the Editor Workbook in a buffer named after the component you've selected from the Project Manager Dialog.

In this case, doodler is the buffer to display. The buffers all have names displayed on their tabs in the Workbook. Clicking on a tab displays the current code for the named component in a buffer. Once you've opened the Editor Workbook, you don't need to keep using the Project Manager dialog to display the current code.

  1. In the doodler.cl editor, type in.
(defclass doodler (non-refreshing-window)
   ())

Creating a New Class: doodler

This new doodler class inherits from non-refreshing-window, a class supplied with Allegro CL. non-refreshing-window determines the behavior of doodler. As the tutorial progresses you will add behaviors to doodler that distinguish it from non-refreshing-window.

You’ve chosen a parent class for doodler that supports certain types of graphic displays. We’ll explain later on why there is an even better choice of a parent class for doodler, and show you how to revise it.

Don’t Change Pre-Supplied Classes

First create a new class that inherits its behavior from a class which you’d like to model, then change the behavior of the new class. You rely on the pre-supplied classes for certain standard behaviors; you don’t want to change those. Changing pre-supplied classes is not supported.

There is a brief discussion of creating new classes and inheritance in Paul Graham’s Chapter 11 of ANSI Common Lisp.

  1. Evaluate the defclass expression by moving the Editor's text cursor so that it is somewhere inside the defclass expression (typically by clicking there). Then invoke the Tools | Incremental Evaluation command to evaluate the expression pointed to by the text cursor.

Mistake-proof Evaluations

The text cursor can also be placed after the last parenthesis. Putting it just after the expression makes the result completely unambiguous; you’ll never get a mistaken evaluation if you choose that location for your request.

The History List

If it evaluates properly, you will see the following display in the history list (the topmost frame, a drop-down combo box) of the Debug Window.

ch1-3-dbw.bmp (180822 bytes)

  1.     In the doodler inspector, change the class property from dialog to doodler.

Protecting the dialog Class: changing the class property

Changing the class property is part of standard preparation for writing events and methods on doodler. We don’t want changes we make to doodler to also be made to its parent class, dialog.

The class property prevents that. Once the doodler’s class is changed from dialog to doodler, dialog is protected from changes.

See Don't Change Pre-Supplied Classes above.

  1.     Click on the Save All button or choose File | Save All to save all changes.
  2.     Click on the Run Project button (or choose Run | Run Project) or choose Run | Run Form after first clicking the Doodler form first to give it focus.

ch1-4-rb.bmp (14262 bytes)

Notice that you now have an empty window containing scrollbars as well as Maximize, Minimize, and Close buttons. The running form will have no grid pattern on it.

  1.     Close the running Doodler window. You can click on the Close button on the running form, click on the Stop button, or choose the Run | Stop command.

ch1-5-sb.bmp (12654 bytes)

  1.         Go to chapter 2. If you wish to, you can stop working on the tutorial now and return to it later. All the work you have done has been saved.

Copyright © 2001-2004 Franz Inc. All rights reserved.

Introduction Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 CLOS Intro
Allegro CL version 8.0