1. Amulet V3.0 Overview

This section provides an overview of Amulet, and contains retrieval and installation instructions.

1.1 Introduction

The Amulet research project in the School of Computer Science at Carnegie Mellon University is creating a comprehensive set of tools which make it significantly easier to create graphical, highly-interactive user interfaces. The lower levels of Amulet are called the `Amulet Toolkit,' and these provide mechanisms that allow programmers to code user interfaces much more easily. Amulet stands for Automatic Manufacture of Usable and Learnable Editors and Toolkits.

This manual describes version 3.0 of Amulet.

The Amulet version 3 release notes describe the differences between Amulet v3 and previous versions of Amulet. Code written for Amulet v2 will need to be edited before it will compile and run properly with Amulet v3.

The Amulet Toolkit is a portable toolkit designed for the creation of 2D direct manipulation grapical user interfaces. It is written in C++ and can be used with Unix systems running X Windows, PC's running Microsoft Windows NT or `95, or Macintosh systems running MacOS.

Amulet has been successfully installed on several platforms. Some of these are at CMU, and some installations are at other users' sites:

Unix

OS: SunOS, Solaris, HP/UX, IBM AIX, SGI, Linux, SCO, digital unix, NetBSD
Compilers: gcc 2.7.2 and 2.7.2.1, ObjectCenter 2.1, AIX xlc, SGI CC, SCO 2.1 C++, Sun C++ 3.0.1 and 4.1
PC OS: Windows NT 3.51 and 4.0 and Windows 95 Compilers: Visual C++ 4.0, 4.2 or 5.0
Mac

Compilers: Metrowerks CodeWarrior 10 or CodeWarrior Pro 1 (not CodeWarrior 11)
Other

OS: OpenVMS, QNX/X-Windows
Compilers: DEC CXX 5.4, Watcom 10.6

We are running SunOS and HP/UX using gcc and ObjectCenter, Windows NT 4.0 and Windows 95 using Visual C++, and Macintosh System 7.6 using Codewarrior, so we'll be best able to help you if you're using one of these systems.

We have found that most users who try to use a vendor specific C++ compiler on a Unix workstation (for example, SGI's CC) run into too many language inconsistencies to successfully build Amulet. We will do what we can to help you install Amulet, but sometimes it's easier to install a new compiler (gcc is free) than to try to get Amulet to work on a native compiler.

There is a known bug in the gcc 2.5.8 compiler involving premature destruction of local variables that prevents it from being able to compile Amulet.

Amulet provides support for color and gray-scale displays. Amulet runs on X/11 R5 and R6, using any window manager such as mwm, uwm, twm, etc. It does not use any X toolkit (such as Xtk or TCL). It has been implemented using the native Windows graphics system on the PC, and standard QuickDraw on the Macintosh. Because of stack-size limitations on the 16-bit Windows operating system, Amulet requires PC users to run Windows NT or Windows 95.

More details about Amulet are available in the Amulet home page on the World Wide Web:

http://www.cs.cmu.edu/~amulet

A previous project named Garnet was developed by the same group who is now writing Amulet. It has features similar to those in Amulet, but is implemented in Lisp. For information about Garnet, please refer to the Garnet home page:

http://www.cs.cmu.edu/~garnet

1.2 Amulet Email Addresses

There is a mailing list called amulet-users@cs.cmu.edu where users and developers exchange information about Amulet. Topics include user questions and software releases. To be added to the list, please send your request to amulet-users-request@cs.cmu.edu.

Please send questions about installing Amulet to amulet@cs.cmu.edu.

You can also send bug reports directly to amulet-bugs@cs.cmu.edu. This mail is read only by the Amulet developers.

Another mailing list, amulet-interest@cs.cmu.edu, is available for people who are interested in learning only about new releases of Amulet.

1.3 Using Amulet in Products: Copyright and Licensing

Amulet is available for free by anonymous FTP or WWW. Amulet has been put into the public domain. This means that anyone can use Amulet for whatever they want. In particular, Amulet can be used for commercial development without any license or fees. The resulting binaries and libraries can also be distributed commercially or for free without payments or licenses to Carnegie Mellon University (CMU). You can even include portions of the Amulet source code in your projects or products. The only restriction is that the documentation for Amulet is copyrighted, so you cannot distribute the Amulet manual or papers without permission from CMU. In return, CMU assumes no responsibility for how well Amulet works, and will not guarantee to provide any support. If you need more formal legal language, see Section 1.12 below. If you need this formally signed, then replace your company's name for COMPANY and send it back to us.

Of course, the Amulet research group would appreciate any corporate grants or donations to support the further development and maintenance of Amulet. We would also be interested in discussing grants to support adding specific features to the system that would make it more useful for your needs. Please contact Brad Myers at bam@cs.cmu.edu to discuss this.

If you decide to use Amulet, we would like to be able to mention this in our publicity and reports to our sponsors. (We get recognition for having users, both commercial and research projects.) Please send mail to amulet@cs.cmu.edu with the name of your project or product. We also like to receive screenshots. If you write papers or advertisements about systems built with Amulet, we would appreciate if you included a mention that you used Amulet, and a reference to this manual, and we would like a copy of your paper for our files.

For complete license and legal information, please see Section 1.12.

1.4 How to Retrieve and Install Amulet

You will download a different file depending on whether you're installing Amulet on a Unix, PC, or Macintosh system. You will get only the files you need to compile Amulet on your machine. If you plan to install Amulet on multiple platform types, you will need to download a different distribution for each platform type.

These instructions assume that a C++ compiler such as gcc, CC, or Visual C++ has been installed properly on your system, and you know the location of your window manager libraries, etc. Amulet will not compile with gcc 2.5.8.

1.4.1 The Amulet Manual

The Amulet documentation is also available for free, but it is copyrighted. This means you cannot distribute the Amulet manuals without written permission from the authors.

The Amulet manual is distributed separately from the Amulet source code. It is available in postscript format, either uncompressed, or compressed with compress (for UNIX) or gzip (for the PC). The amulet manual is also available online. The table of contents is at:

http://www.cs.cmu.edu/afs/cs/project/amulet/amulet3/manual/Amulet_ManualTOC.doc.html

To retrieve the Amulet documentation via WWW, launch your favorite browser and go to the following URL:

http://www.cs.cmu.edu/~amulet/amulet3-documentation.html

Follow the instructions on that web page to download a copy of the Amulet manual.

To download the Amulet manual using FTP, connect to ftp.cs.cmu.edu (128.2.206.173) and login as ``anonymous'' with your e-mail address as the password. Type 'cd /usr0/anon/project/amulet/amulet3' (note the double amulet's). Do not type a trailing ``/'' in the directory name, and do not try to change directories in multiple steps, since the intermediate directories are probably protected from anonymous access.

Set the mode of your FTP connection to binary: Some versions of FTP require you to type 'binary' at the prompt, and others require something like 'set mode binary'.

At the ``ftp>'' prompt, get the manual file you require using the get command: ``ammanual.ps'' is raw postscript, ``ammanual.gz'' is in gzip format, and ``ammanual.Z'' is UNIX compress format. The PC gzip file can be extracted using WinZip 6.2, which is available for evaluation from Nico Mak Computing, Inc. at http://www.winzip.com.

http://www.cs.cmu.edu/~amulet

and follow the Amulet3 Release link. You can also connect directly to the URL:

http://www.cs.cmu.edu/~amulet/amulet3-release.html

Scroll down to the section of the web page labelled ``Downloading the current release of Amulet.'' Follow the link appropriate for the version of Amulet you want to download. This will automatically download the compressed Amulet source code to your machine.

1.4.3 Installing Amulet on a PC

To install Amulet on your PC, you will need to retrieve the file amulet.tar.gz as described in Section 1.4.2. If you are using Microsoft's Internet Explorer, note that it will be confused by the two periods in the filename and will create a file with extension .tar. If you change the extension you should be able to successfully unpack the file as described below.

Procedures for building the Amulet libraries under Windows have changed significantly since Amulet Version 2. In particular, we now use long filenames and we use the same Makefile for both Windows and UNIX. It is not necessary to understand the Makefile to build Amulet, and you may still use Microsoft Developer Studio projects to build your own applications. You may invoke the Amulet Makefile from a Command Prompt using NMAKE or you may invoke the Makefile from a Microsoft Developer Studio project which we have supplied. If you have a need to customize how Amulet is built, see Section 1.6 for a description of the Amulet Makefile structure.

1.4.3.1 Unpacking amulet.tar.gz

Once you have retrieved the file amulet.tar.gz via FTP or WWW, you must extract it into the directory where you want it to reside, preserving the directory structure. The following instructions assume that you will be installing Amulet in the directory C:\amulet.

Amulet V3 for the PC is distributed as a gzipped tar file. It can be unpacked the Gnu tools gzip and tar, or it can be unpacked using WinZip 6.2. You can download an evaluation copy of WinZip 6.2 from the URL http://www.winzip.com.

To unpack using gzip and tar do the following at the MSDOS prompt. Having downloaded amulet.tar.gz to the parent directory (e.g. C:\), connect to the parent directory and run gzip to decompress amulet.tar.gz producing amulet.tar:

C:\> gzip -d amulet.tar

Next expand the archive using tar:

C:\> tar -x -f amulet.tar

To unpack using WinZip 6.2, open WinZip. Open the file amulet.tar.gz, telling WinZip that it is okay to decompress the file in a temporary folder. Extract the archive to C:\ (or wherever), checking the box ``Use Folder Names'' in the extract dialog.

1.4.3.2 Windows Environment Variables

The Amulet Makefiles are parameterized with two environment variables, AMULET_DIR and AMULET_VARS_FILE. The AMULET_DIR variable must be set to the directory in which you installed Amulet. It is used to during the build process to find the Amulet include files and the Amulet libraries, and to specify the location of images used by the sample programs. The AMULET_VARS_FILE variable specifies the Makefile.vars.* file that contains platform specific parameters used in the Amulet Makefile.

If you are using Windows NT, use the System dialog in the Control Panel to add the following variables to your list of User Environment Variables (substituting the appropriate pathname for C:\amulet):

Set AMULET_DIR=C:\amulet

Set AMULET_VARS_FILE=Makefile.vars.MSVC.Win32

If you are using Windows 95, add these settings (as they appear above) to your AUTOEXEC.BAT file, and restart your computer to have them take effect.

If you are using Microsoft Visual C++ 5.0, you should set your AMULET_VARS_FILE to Makefile.vars.MSVC5.Win32. It omits the compiler switch -DNEED_BOOL that is requred by previous versions of the Microsoft compiler.

1.4.3.3 Building the Library, Sample Applications and Test Programs with Visual C++

The Amulet Makefile includes targets to build development and release versions of the Amulet library, numerous test programs, and several sample applications. The Amulet test programs test the ORE object system, GEM graphics routines, OPAL graphical objects, Interactors event handlers, and Widgets. You can build and run these programs to test your installation of Amulet, but they are not intended to be particularly good examples of Amulet coding style. The executables for these programs are created in the amulet\bin directory. The source for the Amulet sample applications can be found in amulet\samples; executables are created in the amulet\bin directory. These programs are intended to be exemplary code; they are described in Section 1.5.

The instructions that follow assume that you have installed Amulet in C:\amulet. If you have installed Amulet elsewhere, substitute that pathname for C:\amulet.

1.4.3.3.1 Building from the MSDOS Command Prompt

Execute the following commands from a command prompt (that is, bring up an MSDOS Command Prompt Window, and type the following commands). Windows 95 users note that you may experience the ``out of environment space'' problem in the MSDOS Command Prompt Window. To fix, select the Memory tab of the Properties dialog for the window and increase the initial environment to at least 1024.

1. First set up the environment to run Visual C++ tools from the command prompt by running

vcvars32 x86

The batch file VCVARS32.BAT should be found in the BIN directory of your Visual C++ installation.

2. To build the Amulet library, connect to the amulet\bin directory and run NMAKE

cd c:\amulet\bin

nmake

This builds the default Amulet library amulet.lib and puts it in c:\amulet\lib.

3. To build one of the programs that comes with Amulet (for instance, the checkers game), run

nmake checkers.exe

This builds checkers.exe and puts it in c:\amulet\bin.

4. To build the Amulet library, test programs and sample applications, run

	nmake all

5. Eventually, you may want build both the default (development) and release (amulet-release.lib) versions of the amulet library. To do so, run

	nmake libs

Note that this step runs the command Gnu fileutils command rm. The Gnu fileutils package is obtainable via the URL http://www.cygnus.com/gnu-win32.

1.4.3.3.2 Building under Microsoft Developer Studio

The Microsoft Developer Studio project amulet.mak is set up to build the Makefile target all --the Amulet libraries, sample applications and test programs.

1. Under Microsoft Developer Studio, open the project workspace

C:\amulet\bin\amulet.mak

Note that Microsoft Visual Studio 97 (MSVC++ 5.0) warns that it will reformat the .mak file --but it doesn't. Compilation switches are stored in the Makefile.vars files, not in the project files.

2. Then from the Build menu, invoke

Build library tests samples

This builds the default Amulet library amulet.lib, putting it in c:\amulet\lib, and builds all of the Amulet sample applications and test programs, putting the executables in c:\amulet\bin.

3. To build other Makefile targets (for example checkers.exe, or libs), replace the target all on the Build command line of the Project Settings dialog of the Build menu with the desired target. For example, replace

NMAKE /f Makefile all

with

NMAKE /f Makefile checkers.exe

If you are using Microsoft Visual Studio 97 and notice that link times are extraordinarily long, you have encountered a bug in the VS97 linker. To resolve either set the linker option /OPT:NOICF or install VS97 Service Pack 1. See http://www.microsoft.com/kb/articles/Q151/5/01.htm for the word from Microsoft.

1.4.3.4 Building Your Own Applications

The easiest way to create a project file for your own Amulet application is to copy and modify the project file amulet\samples\tutorial\tutorial.mak (for MSVC++ 4.x) or amulet\samples\tutorial\tutorial.dsp (for MSVC++ 5.0) from the tutorial sample application, replacing tutorial.cpp with your own .cpp files. Alternatively, you can create your own project file. Whether you copy tutorial.mak/tutorial.dsp or create your own project file, you will need to configure Microsoft Developer Studio to find the Amulet library and include files.

1.4.3.4.1 Configuring Microsoft Developer Studio

In Microsoft Developer Studio, select the Directories tab of the Options dialog of the Tools menu. Add the directory C:\amulet\include to the list of include directories, and add the directory C:\amulet\lib to the list of library directories. (If you installed Amulet in some other directory, be sure to specify that pathname instead.)

1.4.3.4.2 Creating Your Own Project File

To make your own project file that uses Amulet, begin by creating a new project workspace of type application.

1. Select the C/C++ tab of the Settings dialog of the Build menu. Add the following preprocessor definition to your project:

DEBUG			Enable the Amulet inspector.

If you are using MSVC++ 4.x also add:

NEED_BOOL			Visual C++ 4.x does not support the type bool.

If you are converting Amulet V2 code, you may want to add

AMULET2_CONVERSION

See the release notes for more on this switch.

2. Select the Link tab of the Settings dialog of the Build menu. Add the following libraries to your project:

amulet.lib				The Amulet library.

winmm.lib				The Windows multimedia library.

/nodefaultlib:libc				Already present through amulet.lib.

3. If you want your program to handle terminal-style I/O, add the file amulet\src\gem\console.cpp to your project.

Now you are ready to build your project.

1.4.3.5 Using console.cpp to Simulate a Terminal Window

The Amulet test programs were designed in a Unix environment, and require a simulated terminal window for text output. We provide a simple way to add a console to any of your Amulet programs, using the file console.cpp. To include a console in your custom Amulet program, just add the file amulet\src\gem\console.cpp to your Visual C++ project. A console will automatically be allocated when your program starts, and destroyed when the program completes execution.

The Microsoft Windows NT console window allows selection, cutting, and pasting of text. Go to the window's menu (drag off the box in its upper left corner) to ``edit,'' and select the submenu item ``mark.'' This will allow you to make a selection in the window. Selecting the ``edit->copy'' item copies the selection to the cut buffer. If you want the default behavior to be selection mode, go to the ``Settings...'' menu item, and check off ``Quick Edit.'' You can also make this the default for all future console windows by using the ``Configure Default Values'' menu item. In Quick Edit mode, the left button selects text, and the right button copies it to the cut buffer.

The default size of an Amulet console screen buffer is 80 by 100 characters. You can use the scroll bars in the window to look at previous lines of text. By changing the values of the buffer_size structure in console.cpp and recompiling, you can change the size of the Amulet console buffer.

1.4.3.6 Building Windows Applications for Release

All of the .mak files distributed with Amulet contain both debug and release project configurations. It is important to note that both the Amulet library and application code should be compiled with the same compiler options. For release configurations, these options are encapsulated in the AM_RELEASE variable defined in the Makefile.vars.MSVC.Win32 and Makefile.vars.MSVC5.Win32 files. Use these options when linking with the library amulet-release.lib.

1.4.4 Installing Amulet on a Unix Workstation

To install Amulet on your Unix workstation, you will need to retrieve the file amulet.tar.Z as described in Section 1.4.2.

1.4.4.1 Unpacking amulet.tar.Z

Amulet is distributed as a compressed tar file. To unpack you must first uncompress the file, then extract its contents. At the Unix prompt, first type ``uncompress amulet.tar.Z''. Your copy of amulet.tar.Z will be replaced with amulet.tar. Now type ``tar -xvf amulet.tar'' at the Unix prompt to generate the amulet/ directory tree as a subdirectory of your current directory.

1.4.4.2 Setting your Environment Variables

The Amulet Makefiles have been written so that all Amulet users must set two environment variables in their Unix shell before they can compile any program. Consistent binding of these variables by all Amulet users ensures that the installed Amulet binaries will always be compatible with user programs. Once Amulet has been installed and programs are being written that only depend on its library file, it would be possible for users to write their own Makefiles without regard to these variables. However, we recommend that all Amulet users at a site continue to use consistent values of environment variables to facilitate upgrading to future versions of the system. Typically, these environment variables will be set in your .login file:

AMULET_DIR Set this to the root directory of the Amulet software hierarchy on your machine. The csh command to do this is:
```
setenv AMULET_DIR /usr/johndoe/amulet
```
AMULET_VARS_FILE Set this to the Makefile.vars.* file appropriate for your compiler and machine. Use only the filename, not the complete pathname to the file. This file will be included by the main Amulet Makefile.

If you are using SunOS, HP/UX or Solaris, then set AMULET_VARS_FILE to one of the following files, which have been tested by the Amulet group on our own machines.

Makefile.vars.gcc.Sun For gcc on SunOS 4.x
Makefile.vars.gcc.Solaris For gcc on Solaris
Makefile.vars.gcc.HP For gcc on HP/UX 9.x
Makefile.vars.CC.Sun For ObjectCenter's CC on SunOS 4.x
Makefile.vars.CC.HP For ObjectCenter's CC on HP/UX 9.x

For example, if you run csh, your .login might contain the lines

	setenv AMULET_DIR        /usr/johndoe/work/amulet

	setenv AMULET_VARS_FILE  Makefile.vars.CC.HP

If you run another shell, the commands to set environment variables, and to export them to all shell processes may be different; if in doubt, consult the man page for your chosen shell.

If you are using a different platform, you may find a file tailored to your platform that has been contributed by another Amulet user. While the Amulet group is not able to test these vars files directly, we do try and keep them current. Some of the files have contain tips for common configuration problems on the designated platform. Among the contributed vars files you will find:

Makefile.vars.gcc.AIX For gcc on AIX
Makefile.vars.gcc.digital For gcc on digital Unix
Makefile.vars.gcc.linux For gcc on linux (static library only)
Makefile.vars.gcc.linux-ELF For gcc on linux with ELF shared libraries
Makefile.vars.gcc.osf Fog gcc on OSF Unix
Makefile.vars.gcc.SGI For gcc on SGI
Makefile.vars.gcc.Ultrix For gcc on Ultrix
Makefile.vars.CC.AIX For xlc on AIX
Makefile.vars.CC.SCO For the native SCO Unix C++ compiler
Makefile.vars.SC.Solaris For the native Sun compiler on Solaris
Makefile.vars.Watcom.QNX For Watcom C++ on QNX/X-Windows

You may use any of these files to set your AMULET_VARS_FILE variable.

If you run csh, your .login might include the lines:

		setenv AMULET_DIR        /usr/janedoe/amulet

		setenv AMULET_VARS_FILE  Makefile.vars.gcc.linux-ELF

If you can't find your platform in the bin directory, then you should set your AMULET_VARS_FILE variable to the file:

Makefile.vars.custom For any other configuration

If you run csh, your .login might include the lines:

		setenv AMULET_DIR        /usr/jonwoo/amulet

		setenv AMULET_VARS_FILE  Makefile.vars.custom

If you use Makefile.vars.custom, try compiling Amulet first. If the compilation does not finish smoothly, you probably need to make changes to the variables in Makefile.vars.custom. See Section 1.6 for more information. Only edit amulet/bin/Makefile.vars.custom while installing Amulet.

1.4.4.3 Building the Library, Sample Applications and Test Programs

1. To build the Amulet library, connect to the amulet/bin directory and invoke make with no arguments.

cd amulet/bin

make

This produces the default amulet library libamulet.* in directory amulet/lib. The extension will vary depending on whether your machine supports shared libraries (typically with extensions .so and .sl) or only static libraries (with extension .a).

2. To build one of the programs that comes with Amulet (for instance the checkers game), run

make checkers

This builds checkers and puts it in amulet/bin.

3. To build the library, test programs and sample applications, run

make all

4. To build both the shared (if supported) and static versions of the Amulet library in both development (the default) and release variants run

make libs

If you are familiar with Amulet V2, note that we have removed the individual Makefiles for many of the sample applications. Instead everything is built using the main Makefile in amulet/bin.

If you are unable to compile Amulet using the Makefile.vars.* file supplied with the Amulet distribution, you may need to customize the Makefile variables for your platform. Set your AMULET_VARS_FILE environment variable to Makefile.vars.custom, and refer to Section 1.6. Change appropriate variables in Makefile.vars.custom, and recompile. If you are unable to compile Amulet after trying different combinations of compiler switches, please send mail to amulet-bugs@cs.cmu.edu and we will try to make the Amulet code more portable.

Once you have generated the library, you are ready to write your own Amulet programs and link them to the Amulet library. Your first experience with Amulet programming should involve the Amulet Tutorial, which includes a starter program and instructions to acquaint you with the compiling process. When you are ready to write your own Amulet program, see Section 1.4.4.4 for instructions on linking your new program to the Amulet library.

1.4.4.4 Writing and Compiling New Programs Using Amulet

It is important to set your AMULET_DIR and AMULET_VARS_FILE environment variables, and to retain the structure of the sample Makefiles in your local version. By keeping the line 'include $(AMULET_DIR)/bin/Makefile.vars' at the top of your Makefile, and continuing to reference the Amulet Makefile variables such as AM_CFLAGS and CC, you will be assured of generating binary files compatible with the Amulet libraries.

When you are ready to write a new program using Amulet, it is easiest to start with an example Makefile. The easiest way to start a new project is to copy the contents of samples/tutorial/ into a new directory, and edit the Makefile and tutorial.cc files to begin your project. Invoking make in that directory generates a binary for your Amulet program. The examples presented in the Amulet Tutorial all start from this point, and can be used as models for your programs.

1.4.4.5 Building Unix Applications for Release

All of the Amulet Makefiles are parameterized with two variables that determine what variant of the Amulet library is built and linked with Amulet applications.

OP Specifies whether the AM_DEVELOP or AM_RELEASE flags are used to compile the library and applications.
LIB_MODIFIER Specifies a modifier appended to the library filename to indicate a particular OP choice. For the development library LIB_MODIFIER is null; for the release library LIB_MODIFIER is -release.

To override the default definitions of these variables, for example to compile the Amulet tutorial and link with the release library, invoke make as follows:

make OP='$(AM_RELEASE)' LIB_MODIFIER=-release tutorial

1.4.5 Installing Amulet on a Macintosh

To install Amulet on your Macintosh, you will need to retrieve the file amulet.sea.hqx as described in Section 1.4.2. As with prior releases of Amulet, Amulet 3.0 uses Codewarrior project files. Specifically, the projects were built and tested with Codewarrior 10 (released Sept. 1996). For those who have earlier versions than Codewarrior 10, we suggest upgrading. While Amulet users have found that the Codewarrior 10 projects work smoothly with Codewarrior 11 Codewarrior 11 users should heed the caution in Section 1.4.5.6 below, if you create your own projects.

1.4.5.1 Unpacking amulet.sea.hqx

Once you have retrieved the file amulet.sea.hqx via FTP or WWW, unbinhex it. Some communications programs (such as Netscape and Fetch) do this for you automatically. If yours does not, try using Stuffit Expander. Run the application amulet.sea and select the directory where want the Amulet source tree to reside.

1.4.5.2 Macintosh Environment Variables

Amulet needs to know the location of your amulet directory for some bitmap files in the demo programs. Use SimpleText to create a text file called amulet.env in the Preferences folder of your active System Folder. This text file must contain the full pathname to your amulet directory. For example, if you have installed Amulet in the folder named amulet on the drive named Hard Disk then the pathname would be Hard Disk:amulet. Note that there should be no colon at the end of the pathname and that this file must be an ASCII text file.

If you are upgrading from a previous version of Amulet, your old amulet.env file should work just fine, provided it still points to your amulet root directory.

1.4.5.3 Processor Support: PowerPC and 68K

Amulet currently supports both the 68X00 processor series and the PowerPC. In addition, we support CodeWarrior 10 and CodeWarrior Pro 1. All versions use the identical source code with one exception. That exception is that the CodeWarrior Pro version requires the "MSL Standard Library", while the earlier version requires the older standard libraries. The Amulet header files will choose the correct headers based on the compiler version.

Since earlier versions of CodeWarrior do not allow multiple targets in one project file, the projects now come in three flavors. When referring to project files, *** is used to denote which project to use depending on compiler version. PPC is for PowerPC targets for CodeWarrior 10, 68K is for 68x000 target for CodeWarrior 10. PRO is for both targets using CodeWarrior Pro 1 and the MSL Standard Library.

Thus you would use amuletPPC.proj to build the Amulet library for CodeWarrior 10 for the PowerPC. But to use CodeWarrior Pro, you will not convert any CodeWarrior 10 projects. Instead use amuletPRO.proj which will let you target both the PowerPC and 68X000 processors.

1.4.5.4 Building the Amulet library

All the project files needed for Amulet are found in the amulet:bin:MAC subdirectory.

1.4.5.4.1 Creating the Precompiled Header file

The first step in building Amulet involves compiling the precompiled header. Open amulet:bin:MAC:pch:AmuletHeaders***.proj then select the AmuletHeaders.pch file in the project window and choose Compile from the Project menu. Codewarrior will deposit an AmuletHeaders*** file in amulet:bin:MAC:pch. This should only need to be done once at installation.

1.4.5.4.2 Compiling the Amulet Library

To build any of the sample programs or to link your own application to Amulet, you must first build the Amulet library. To do so, open amulet:bin:MAC:lib:amulet***.proj and choose Make from the Project menu. This may take a little while, depending upon your system. There may be warnings, but there should not be any fatal errors. If you do get any fatal errors, please send email to amulet-bugs@cs.cmu.edu so we can try to help you with your installation.

Once you have a compiled version of the Amulet library you are ready to write your own Amulet programs and link them to the Amulet library. Section 1.4.5.5 discusses how you can build and run some of the Amulet samples and test programs. Your first experience with Amulet programming should involve the Amulet Tutorial, which includes a starter program and instructions to acquaint you with the compiling process. When you are ready to write your own Amulet program, see Section 1.4.5.6 for instructions about linking your new program to the Amulet library.

To build a version of the Amulet library without debugging code, use the project file amulet:MAC:amuletNoDebug***.proj.

1.4.5.5 Compiling the Amulet Test Programs and Sample Applications

The Amulet distribution for the Macintosh includes Codewarrior projects to build numerous test programs, and several sample applications. The Amulet test programs test the ORE object system, GEM graphics routines, OPAL graphical objects, Interactors event handlers, and Widgets. You can build and run these programs to test your installation of Amulet, but they are not intended to be particularly good examples of Amulet coding style. The project files for these programs are in the amulet:bin:MAC:tests folder.

The source for the Amulet sample applications can be found in amulet:samples; project files are in the amulet:bin:MAC:samples folder. These programs are intended to be exemplary code; they are described in Section 1.5.

To generate an executable for any of the sample applications or test programs, open the project file for the program, and choose Make from the Project Menu. You can only compile these programs after you have successfully compiled the Amulet library.

The Amulet sample applications currently have no feedback during the launch process so it may appear that a program has crashed while it is still loading.

1.4.5.6 Writing and Compiling New Programs Using Amulet

The easiest way to create a project file for your own Amulet program is to start with the stationery project files provided with the Amulet distribution. These files are:

am_stationery68K.proj.stat for CodeWarrior 10 68x000,
am_stationeryPPC.proj.stat for CodeWarrior 10 PowerPC and
am_stationeryPRO.proj.stat for CodeWarrior Pro 1.

Open the appropriate project file, save it as your new project file and replace tutorial.cc with your application's .cpp files. At that point, you should be able to successfully compile your Amulet application.

1.4.5.7 Compiling Programs for Release

Amulet applications are smaller and faster if they are built without the Inspector and without debugging symbols. To prepare an Amulet application for release, first build a release version of the Amulet library, using the project file amulet:bin:MAC:lib:amuletNoDebug***.proj. It will replace the Amulet library with a file of the same name: Amulet***.lib. You will need to remember which library you have completed last.

Second, change your prefix file in your project to use Am_Prefix.h instead of Am_DebugPrefix.h. This is changed under the CodeWarrior Preferences... menu item in version 10. In version 11, it is found under the Project Settings... menu item. Select the Language Settings:C/C++ Language item from the scrollable area. Type in Am_Prefix.h in the Prefix File edit box and save. You are ready to Make your release (NoDebug) project.

1.5 Test Programs and Sample Applications

The procedure for compiling and executing the Amulet sample applications and test programs is different depending on your platform. See Section 1.4.3 for PC-specific instructions, Section 1.4.4 for Unix-specific instructions, or Section 1.4.5 for Macintosh-specific on installing Amulet and compiling the tests and samples.

The following list describes some of the sample programs provided with Amulet. The samples are all in the amulet/samples sub-directory.

examples/hello This program creates a window and displays 'hello world' in it. You can exit by hitting meta-shift-f1.
examples/goodbye_button This program creates a button widget on the screen which quits when pressed.
examples/goodbye_inter This program displays ``goodbye world'' in a window, and an interactor causes the program to quit when the text is clicked on.
examples/example1 This program is designed to be a good example of how to create graphical editors. It is heavily commented, and illustrates:. How to organize objects in groups How to attach interactors and widgets to groups so they only operate on the correct objects How to enable and disable interactors based on a global palette Use of the menubar, standard, built-in command objects, and the standard selection handles widget. How to use the standard load/save mechanism
examples/example2 This program is designed to be a good example of how to create dialog boxes and use widgets. It is heavily commented, and illustrates:. Using text input fields Constraining a value to be the same as a text field's value Popping up a dialog box and waiting for the answer Using the error built-in dialog box. Using a dialog box created using the Gilt Interface Builder Use of the Am_Tab_To_Next_Widget_Interactor to allow the user to tab among the fields Using the filter on text input field values Using a number entry field
tutorial/tutorial This program simply creates a window on the screen. It is the starting point for all the examples in the Amulet Tutorial.
checkers This is a two-player checkers game that demonstrates the multi-screen capabilities of Amulet in Unix. You can run it on two screens by supplying the names of the displays when the program is executed, as in 'checkers my_machine:0.0 your_machine:0.0'. On the PC or Macintosh, you can still run this program, but it can only be displayed on one screen.
space This program looks a little bit like NetTrek, and demonstrates many features of Amulet: constraints, bitmaps, polylines, widgets, and scrolling windows. Some of the interactions to try are: Leftdown in the background of the Short-Range Scan creates a ship Leftdown drag on an existing ship moves it Middledown+drag (META-leftdown+drag on PC, OPTION-SHIFT-leftdown+drag on the Macintosh) from one ship to another draws a phaser beam and destroys the destination ship Rightdown+drag (OPTION-leftdown+drag) from one ship to another establishes a tractor beam which stays attached to the ships through constraints Dragging the white rectangle in the Long-Range Scan changes the visible area in the Short-Range Scan. You can scroll the visible area with the scroll-bars or by dragging the white feedback rectangle in the Long-Range Scan.
agate/agate This program is used to train a new gesture classifier for use by the gesture interactor. See Section 5.3.5.6 for more information about the gesture interactor, agate, and gesture classifiers.
gilt This is an interactive editor to create dialog boxes and windows. It has its own chapter of this manual.
space2 A simple game that is designed to illustrate and test the animation capabilities.
tree A demo of animations. Click on a node and it moves to the top. Type `a' to toggle whether animations are on or off.

In addition, there are many test programs, typically one or more for each part of the system. You might look at these to see ways to use the various features at the different levels. In general, these require the console window, and you can run these, and then type ? to see the list of one-letter commands that operate them. The most useful test programs are:

src/gem/test* Lots of different test programs for the different kinds of graphics.
src/object/testobject Tests the ORE object system. Not interactive
src/opal/testopal Tests the Opal graphics system.
src/inter/testinter Tests the Interactors.
src/widgets/testwidgets Tests the widgets.
src/widgets/testselectionwidget Like a drawing editor. Tests the built-in command objects, load/save, the selection handles widget, etc.
src/anim/testanimators Tests all the different kinds of animations.

1.6 Amulet Makefiles

Amulet now uses the same makefiles on both UNIX and under Windows. The main Amulet Makefile, which is common to all platforms, is parameterized for specific platform/compiler combinations by including a subsidiary makefile called Makefile.vars.<compiler>.<platform>. You may need to understand this makefiles if you want to get Amulet working on a new platform, or if you want to customize how Amulet is built on one of the supported platforms.The name of this file is used to set your AMULET_VARS_FILE environment variable.

The main Makefile is also parameterized by including a subsidiary makefile called Makefile.lib.<platform>.<binding>, which controls how the Amulet libraries are linked, and by including a subsidiary makefile called Makefile.gem.<platform>, which identifies platform-specific gem files. There is less need to understand how these makefiles work.

1.6.1 Makefile Variables

The Amulet Makefile.vars.* files define makefile variables that name the tools used to build Amulet, control conditional compilation, specify other compiler and linker options, and control what libraries and built and how.

The following variables are used by the Amulet Makefile and defined in the Makefile.vars.* files.

CC Your compiler, such as /usr/local/bin/gcc. If you're compiling using ObjectCenter's CC, you may have to specify the pathname explicitly. Otherwise, a default (non-Centerline) CC may be used which will not successfully compile Amulet.
LD Your linker, such as /bin/ld. This command is used to link libraries into archive files.
AR Library archive tool. Defaults to ar. May not be needed on many platforms.
RANLIB Library random access tool. Defaults to ranlib. May not be needed on many platforms.
RM File deletion command. Defaults to /bin/rm.
AM_CFLAGS A list of switches that are always passed to the compiler, including the conditional compilation symbols listed in the next section, and any include paths you need to specify.
AM_DEVELOP Additional compiler switches used for development builds.
AM_RELEASE Additional compiler switches used for release builds.
AM_NODEBUGSYM Additional compiler switches used to build applications with the inspector enabled, but without debugging symbols.
AM_SAMPLE_FLAGS Set to one of $(AM_DEVELOP), $(AM_RELEASE) or $(AM_NODEBUGSYM); used when compiling sample applications and test programs.
AM_LIB_LDFLAGS A list of switches to pass to the linker.
AM_LIBS A list of libraries to link with your program, such as -lX11 and -lg++.
AMULET_ROOT Defaults to $(AMULET_DIR).
AM_GEM_SOURCE Specifies the Makefile.gem.* file naming the gem files used for a given platform.
AM_STATIC_LIB_MAKE Specifies the Makefile.lib.*.static file used to build static libraries on a given platform.
AM_SHARED_LIB_MAKE Specifies the Makefile.lib.*.shared file used to build shared libraries on a given platform. Defaults to $(AM_STATIC_LIB_MAKE).

AM_LIBS_TO_MAKE Specifies the library targets to build when invoking make libs -- any of amulet (the default library), develop-shared, develop-static, release-shared, release-static, or all-libs (both development and release, static and shared). Defaults to amulet.

The main Amulet Makefile uses the make variables OP, LIB_MODIFIER, and LIB_MAKE to determine how the Amulet library is built.

OP Specifies additional compiler switches that do not appear in AM_CFLAGS. Normally set to one of the sets of extra compiler flags: AM_DEVELOP, AM_RELEASE, or AM_NODEBUGSYM.
LIB_MAKE Specifies the name of a platform-specific library makefile. Used to select static or shared linking.
LIB_MODIFIER Specifies a modifier appended to the library filename to indicate a particular OP choice. For the development library LIB_MODIFIER is null; for the release library LIB_MODIFIER is -release.

You can override the definitions of these variables in your Makefile.vars.* file by supplying new definitions on the make command line (See Section Section 1.6.3).

1.6.2 Conditional Compilation Symbols

C++ is a standardized language, but many compilers do not fully support the ANSI standard completely or correctly. Because of this, Amulet requires different source code in certain places with various platform/ compiler combinations. We handle this with conditional code that depends on the compile-time definition of the variables defined in your AMULET_VARS_FILE. These variables need to be set appropriately for your system. This section is a guide to the variables that control the conditional Amulet code. If, after experimenting with the compiler variables documented below, you are still not able to successfully compile Amulet, please send mail to amulet-bugs@cs.cmu.edu so we can try to make the Amulet code more portable.

Before changing any of the Makefile variables, you should try compiling Amulet once with one of the default Makefile.vars.* files. If the procedure does not terminate smoothly, you should have some indication of what switches need to be added or changed. Make sure that your AMULET_VARS_FILE environment variable is set to Makefile.vars.custom (found in amulet/bin), and bring this file up in an editor. This is the only file that you should change.

The variables that control conditional Amulet code are defined with -D compiler switches. For example, we have found that the CC libraries on Suns do not provide the standard function memmove(), so we have to define it ourselves in Amulet. The Amulet version of memmove() is only defined when the compiler switch -DNEED_MEMMOVE is included in the compile call (which declares the variable NEED_MEMMOVE). By adding or removing the -DNEED_MEMMOVE switch, you control whether Amulet defines memmove().

The interface for defining these variables is the AM_CFLAGS list in Makefile.vars.custom. For each variable VAR, you would include the switch -DVAR in the AM_CFLAGS list to define the variable, or simply leave out the switch to avoid defining the variable. By iteratively adding or removing these variables from your AM_CFLAGS list and recompiling Amulet, you should be able to install Amulet on your system.

HP Including -DHP in the AM_CFLAGS list will cause some type casting required for HP's that is inappropriate on other machines.
GCC Including -DGCC in the AM_CFLAGS list causes different header files to be referenced than when Amulet is compiled with CC or Visual C++.
NEED_BOOL Including -DNEED_BOOL in the AM_CFLAGS list causes Amulet to define the bool type. This type is pre-defined in gcc.
NEED_MEMMOVE Including -DNEED_MEMMOVE in the AM_CFLAGS list causes Amulet to define its own memmove() function. This function is missing in some C libraries.
NEED_STRING Including -DNEED_STRING in the AM_CFLAGS list causes Amulet to include the standard header file strings.h in special places required by some versions of the CC compiler.
DEBUG Including -DDEBUG in the AM_OP list causes Amulet debug-ging code to be compiled into your binaries. If you do not define DEBUG, you will lose a lot of runtime debugging information, such as slot, object, and wrapper names, and tracing and breaking in the debugger, but your executable will be smaller and it will run faster. This switch is not the same as the -g option, which compiles debugging symbols for a debugger such as gdb into your executable. Using the DEBUG switch compiles in Amulet-specific runtime debugging information which makes it easier to debug your Amulet application while it's running. The options -g and -DDEBUG are mutually exclusive; neither is required to use the features the other provides.

1.6.3 Command Line make Options

Make allows you to specify override values for makefile variables on the command line. This allows quick testing of various Makefile configurations without having to edit the Makefile.vars.* file every time you want to try something new. To override a makefile variable on the command line, just type make <variable>=<value> <target>. For example, to profile testwidgets you might try:

make clean

make OP="-pg -static $(AM_RELEASE)" LIB_MODIFIER=-prof \

		LIB_MAKE="$(AM_STATIC_LIB_MAKE)" testwidgets

Note that it is important to run make clean to delete any object files that may have been compiled with different options before building a variant of the Amulet library.

1.6.4 Xlib Pathnames

Some compilers on Unix systems do not know where to find the Xlib library and include files. You may need to include the pathnames for your Xlib files in the AM_CFLAGS and AM_LIBS lists in Makefile.vars.custom. The include path should be provided with the -I switch, and the library path should be provided with the -L switch.

For example, some HP machines store their Xlib include and library files in /usr/include/X11R5/ and /usr/lib/X11R5/. If this is how your machine is set up, your AM_CFLAGS definition would look like this:

AM_CFLAGS=$(AM_OP) I$(AMULET_DIR)/include -DGCC -DDEBUG -DHP \

		-I/usr/include/X11R5

Your AM_LIBS definition would look like this:

AM_LIBS=-L/usr/lib/X11R5 -lX11 -lm

Note that a backslash is required at the end of a line when the definition of a Makefile variable continues on the next line.

If you are having trouble finding your Xlib include and library files, try looking in these directories:

/usr/include/X11R?, /usr/lib/X11R?

/usr/local/X11R?/include, /usr/local/X11R?/lib

1.7 Preparing Amulet Applications for Release

Many users complain that applications that link to the Amulet library are very large. It is not unusual to have a hello world program yield a few megabytes of executable. Obviously, not all of this is useful, necessary information. While the value of the following suggestions will vary from platform to platform, there are several things you can do to reduce the size of your executables, and to speed up your application.

On all platforms, the most significant step you can take to reduce the size of your executable is to compile the Amulet library and your application without symbolic debugging information.
To reduce the size of your executable and to speed up your application on any platform, compile the Amulet library and your application without the -DDEBUG switch. The preprocessor symbol DEBUG enables the Inspector, which adds both code and data to an application. The Inspector should not be needed in an application that is released to end users.
On some platforms, it is possible to compile Amulet into a shared library. This will make all of your Amulet applications smaller, since the Amulet library will not be stored redundantly with each executable. If you use shared libraries, you will need to distribute the shared libraries with your applications and install the libraries where they can be found at run-time. Amulet is automatically linked into shared libraries if you use gcc 2.7.0 or higher on SunOS, HP/UX, Solaris, or Linux. It may be possible to use shared libraries on other platforms; consult your compiler's documentation. DLL's are not supported under Windows.
Some compilers may offer a choice of optimization options to minimize space or maximize performance.
On UNIX platforms, running strip on your executables and shared libraries removes both the symbol table and any symbolic debugging information. Just type ``strip'' followed by the name of the program that's too large. This is one of the most effective way of shrinking your executables. It is much more efficient than recompiling the full Amulet system without symbolic debugging information, and is the only way to remove symbol tables, which are necessary for (static) linking, but are not needed at run time.
Under Windows, symbolic debugging information is kept in separate .pdb files. When you no longer need these files, you may safely delete them.

The Amulet Makefiles are designed to build both development and release versions of the Amulet libraries. The development libraries are compiled with both the Inspector and symbolic debugging enabled. The release libraries are compiled with neither the Inspector nor symbolic debugging enabled.

1.8 Amulet Header Files

Usually the only Amulet header file you'll need to include in your Amulet programs is amulet.h, which will include all of the others for you. If you like to use header files to supplement the reference manual, you can find them in the include/amulet/ directory.

Amulet header files fall into two categories, Basic, and Advanced. Basic header files define all the standard objects, functions, and global variables that Amulet users might need to write various applications. Advanced header files define lower level Amulet functions and classes which would be useful to an advanced programmer interested in creating custom objects in addition to the default objects Amulet supports. Most users will only ever include the Basic header files.

1.8.1 Basic header files

The header file amulet.h includes all the headers most amulet programmers will ever need to use: types.h, standard_slots.h, value_list.h, gdefs.h, idefs.h, opal.h, inter.h, widgets.h, gesture.h, and anim.h. Here is a summary of the basic header files, listing the major objects, classes, and functions they define.

gdefs.h: Am_Style, Am_Font, Am_Point_List, Am_Point_Array, Am_Image_Array
idefs.h: Am_Input_Char, predefined Am_Input_Char's
object.h: Am_Object, Am_Slot, Am_Instance_Iterator, Am_Slot_Iterator, Am_Part_Iterator
types.h: Am_String, Am_Value, Am_Error, Am_Wrapper, Am_Method_Wrapper
standard_slots.h: standard slot names, Am_Register_Slot_Key, Am_Register_Slot_Name, Am_Get_Slot_Name, Am_Slot_Name_Exists
opal.h: predefined Am_Style's, predefined Am_Font's, Am_Screen, Am_Graphical_Object, Am_Window, Am_Rectangle, Am_Roundtangle, Am_Line, Am_Polygon, Am_Arc, Am_Text, Am_Bitmap, Am_Group, Am_Map, predefined formulas, Am_Initialize, Am_Cleanup, Am_Beep, Am_Move_Object, Am_To_Top, Am_To_Bottom, Am_Create_Screen, Am_Do_Events, Am_Main_Event_Loop, Am_Exit_Main_Event_Loop, predefined Am_Point_In_ functions, Am_Translate_Coordinates
formula.h: Am_Formula, Am_Define_Formula, Am_Define_Value_Formula
value_list.h: Am_Value_List
text_fns.h: all text editing functions, Am_Edit_Translation_Table
inter.h: Am_Inter_Location, default interactor method types, Am_Interactor, Am_Choice_Interactor, Am_New_Points_Interactor, Am_One_Shot_Interactor, Am_Move_Grow_Interactor, Am_Text_Edit_Interactor, Am_Where_Function's, interactor debugging functions, Am_Command, Am_Choice_Command, Am_Move_Grow_Command, Am_New_Points_Command, Am_Edit_Text_Command, Am_Undo_Handler, Am_Single_Undo_Object, Am_Multiple_Undo_Object, Am_Abort_Interactor, Am_Stop_Interactor, Am_Start_Interactor, interactor tracing, undo handlers, Am_Pop_Up_Window_And_Wait, Am_Finish_Pop_Up_Waiting
anim.h: Am_Animator, Am_Stepping_Animator, Am_Style_Animator, Am_Exaggerated_Animator, Am_Visible_Animator, Am_Blink_Animator, Am_Through_List_Animator, Am_Object_In_Owner_Animator, Am_Point_List_Animator, Am_Fly_Apart_Animator, Am_Animation_Command, Am_Incrementer_Animation_Command, Am_Animation_Object_In_Owner_Command, Am_Animator_Animation_Command, Am_Constant_Velocity_Command, Am_Animation_Through_List_Command, Am_Animation_Blink_Command, Am_Animation_Wrap_Command, Am_Animation_Bounce_Command, Am_Linear_Timing, Am_Delayed_Timing, Am_Slow_In_Slow_Out, Am_Linear_Path, Am_Boolean_Path, Am_Style_Path, Am_Step_Path, Am_Through_List_Path
gesture.h: Am_Feature_Vector, Am_Gesture_Classifier, Am_Gesture_Trainer, Am_Gesture_Unrecognized_Command, Am_Gesture_Create_Command, Am_Gesture_Select_And_Do_Command
widgets.h: Am_Border_Rectangle, Am_Button, Am_Button_Panel, Am_Checkbox_Panel, Am_Radio_Button_Panel, Am_Menu, Am_Menu_Bar, Am_Option_Button, Am_Menu_Line_Command, Am_Vertical_Scroll_Bar, Am_Horizontal_Scroll_Bar, Am_Scrolling_Group, Am_Text_Input_Widget, dialog boxes, Am_Selection_Widget, Am_Selection_Widget_Select_All_Command, Am_Text_Input_Dialog, Am_Choice_Dialog, Am_Alert_Dialog, Am_Start_Widget, Am_Abort_Widget, Am_Global_Clipboard, Am_Graphics_Set_Property_Command, Am_Graphics_Clear_Command, Am_Graphics_Clear_All_Command, Am_Graphics_Copy_Command, Am_Graphics_Cut_Command, Am_Graphics_Paste_Command, Am_Undo_Command, Am_Redo_Command, Am_Graphics_To_Bottom_Command, Am_Graphics_To_Top_Command, Am_Graphics_Duplicate_Command, Am_Graphics_Group_Command, Am_Graphics_Ungroup_Command, Am_Show_Alert_Dialog, Am_Get_Input_From_Dialog, Am_Get_Choice_From_Dialog, Am_Show_Dialog_And_Wait
debugger.h: the inspector
undo_dialog.h: the selective undo dialog box

1.8.2 Advanced header files

All other header files are considered Advanced header files. They support advanced Amulet features, such as user-defined objects, daemons, constraints, and so on. Most users should never include these files explicitly. For users who will be using Amulet's advanced features, here is a brief summary of the contents of each advanced header file.

gem.h: Am_Drawonable, Am_Input_Event, Am_Input_Event_Handlers, Am_Region
am_io.h: Am_TRACE
object_advanced.h: Am_Demon_Queue, Am_Demon_Set, Am_Constraint, Am_Constraint_Iterator, Am_Dependancy_Iterator, Am_Slot_Advanced, Am_Object_Advanced, Am_Constraint_Context, Ore_Initialize
priority_list.h: Am_Priority_List_Item, Am_Priority_List
symbol_table.h: Am_Symbol_Table
types.h: NULL, Am_WRAPPER_DECL, Am_WRAPPER_IMPL, Am_WRAPPER_DATA_DECL, Am_WRAPPER_DATA_IMPL
formula_advanced.h: Am_Formula_Advanced, Am_Depends_Iterator
opal_advanced.h: Am_Aggregate, advanced opal object slots, Am_Draw_Method, Am_Draw, Am_Invalid_Method, Am_Invalidate, Am_Point_In_Obj_Method, Am_Translate_Coordinates_Method, Am_State_Store, Am_Item_Function, Am_Invalid_Rectangle_Intersect, Am_Window_ToDo
inter_advanced.h: Am_Initialize_Interactors, Am_Interactor_Input_Event_Notify, Am_Inter_Tracing, Am_Get_Filtered_Input, Am_Modify_Object_Pos, Am_Choice_Command_Set_Value, interactor methods, command methods, Undo handler functions
widgets_advanced.h: Computed_Colors_Record, Am_Checkbox, Am_Radio_Button_Item, Am_Menu_Item, widget drawing functions, widget formula constraints, other widget support functions

1.8.3 Standard Header File Macros

The actual names of the header files described above are slightly different on each machine. Directory paths aren't specified in the same way on the Mac as they are on Unix. To allow these files to be included simply without explicit conditional compilation on the various platforms, we've provided a set of C++ #defines which give each .h file a standard identifier on all platforms. These #defines are in amulet/include/am_inc.h, which is included by amulet.h.

Typically, you should only need to #include <amulet.h> in your program. If you need to include any of the other header files, then include the #defined names of the header files as found in am_inc.h, instead of the file's actual name. This helps ensure machine-independent compilation. For example, if you needed to include object_advanced.h and opal_advanced.h, the top of your program might look like:

#include <amulet.h>

#include OBJECT_ADVANCED__H

#include OPAL_ADVANCED__H

If for some reason you do not include amulet.h, you will have to include am_inc.h to get the machine-independent header file names.

Visual C++ sometimes has problems with am_inc.h if you have the precompiled headers option turned on in your project. Most of the time, building the project again fixes the problem (you don't need to do a Build All). If you get errors such as, ``#include expected a filename, found an identifier'', this is the problem you're experiencing. To avoid it in the future, turn off precompiled headers in your project.

1.9 Amulet Naming Conventions

Amulet uses a set of simple naming conventions in part to avoid name conflicts with other libraries at link time, but mostly to make Amulet code more readable and understandable.

All exported symbols have the prefix Am_ except for the methods and instance variables of C++ classes (e.g, Am_Button, but my_obj.Create()) since Create is a method).
All exported symbols use full words spelled out (e.g.: Am_Command instead of Am_Cmd).
All multi-word symbols used underscore between the words (e.g. Am_Menu_Line_Command).
The first letter of each word is capitalized.
All constants are in ALL CAPS (except for the preceding Am_). Slot names are constants, so they are in all caps (e.g. Am_LEFT).

Exported symbols are symbols that are available for the use of Amulet application developers.

1.10 Parts of Amulet

Amulet is divided into several layers, which each have their own interface (and chapter of this manual). The overall picture is shown below.

The Gem layer provides a machine-independent interface so the rest of Amulet is independent of the particular window system in use. Most programmers will not need to use Gem. Ore provides a prototype-instance object system and constraint solving that is used by the rest of Amulet. Gem and ORE can each be used as a stand-alone system without any of the rest of Amulet, if specific functionality is required without the overhead of the higher levels of code. Opal provides an object-oriented interface to the Gem graphics system, and the Interactors and Command objects handle processing of input events from Gem. Using these is a set of Widgets, including scroll bars, buttons, menus, text input fields, and dialog boxes. The Gilt interface builder allows many parts of an interface, especially dialog boxes, to be created interactively using the mouse.

1.11 Changes since Version 2

There have been many changes in Amulet since version 2. In particular, all code that worked with V2 must be edited to compile with version 3. A complete and up-to-date list of changes and known problems is provided in the V3 release notes on the Amulet Web site. For complete information about Amulet's new features, you should look in the specific sections of this manual.

The previous version of the manual described all the changes from Version 1.2 to Version 2, but they have been eliminated to save space. If you are still using V1.2, you should probably check in the old manual first.

1.12 Formal, Legal Language

1. This License Agreement, effective as of April 1, 1996, is between: Carnegie Mellon University having a principal place of business at 5000 Forbes Avenue, Pittsburgh, PA 15213-3890 (``CMU''); and a company (``COMPANY'').

2. CMU owns intellectual property rights to the computer software, electronic information and data, in all forms and versions, identified as Amulet, described in CMU Docket 96-050 (``Software''), and associated documentation (``Document''), collectively (``Program'').

3. CMU grants to COMPANY, upon the terms and conditions set out below, a fully-paid, nonexclusive, world-wide, royalty-free, non-revocable, commercial license to use the Program, or any portion thereof, for any purpose, including, but not limited to, the right to grant sublicenses under CMU's patent and trade secret rights, and copyrights, including any renewals and extensions, the right to use, copy adapt, prepare derivative works of, distribute, sell, lease, or otherwise dispose of, reverse engineer, or disassemble the Software, or any portion thereof (including all subsequent editions, revisions, supplements, and versions thereof), and CMU acknowledges that COMPANY hereby grants no reciprocal rights.

4. COMPANY acknowledges that the Program is a research tool still in the development stage, that it is being supplied ``as is,'' without any accompanying services or improvements from CMU.

5. CMU MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE, OR MERCHANTABILITY, EXCLUSIVITY OR RESULTS OBTAINED FROM SPONSOR'S USE OF ANY INTELLECTUAL PROPERTY DEVELOPED UNDER THIS AGREEMENT, NOR SHALL EITHER PARTY HERETO BE LIABLE TO THE OTHER FOR INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES SUCH AS LOSS OF PROFITS OR INABILITY TO USE SAID INTELLECTUAL PROPERTY OR ANY APPLICATIONS AND DERIVATION THEREOF. CMU DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT, OR THEFT OF TRADE SECRETS AND DOES NOT ASSUME ANY LIABILITY HEREUNDER FOR ANY INFRINGEMENT OF ANY PATENT, TRADEMARK, OR COPYRIGHT ARISING FROM THE USE OF THE PROGRAM, INFORMATION, INTELLECTUAL PROPERTY, OR OTHER PROPERTY OR RIGHTS GRANTED OR PROVIDED TO IT HEREUNDER. THE USER AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF CMU, EXPRESSED OR IMPLIED, TO ANY PERSON CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE PROGRAM UNDER THIS AGREEMENT.

6. COMPANY hereby agrees to defend, indemnify and hold harmless CMU, its trustees, officers, employees, attorneys and agents from all claims or demands made against them (and any related losses, expenses or costs) arising out of or relating to COMPANY's and/or its sublicensees' use of, disposition of, or conduct regarding the Licensed Technology and/or Licensed Product including but not limited to, any claims of product liability, personal injury (including, but not limited to, death) damage to property or violation of any laws or regulations including, but not limited to, claims of active or passive negligence.

7. COMPANY agrees that it will not make any warranty on behalf of CMU, express or implied, to any person concerning the application of or the results to be obtained with the Program.

8. Title to copyright to the Program and to Document shall at all times remain with CMU, and COMPANY agrees to preserve same. COMPANY agrees not to make any copies of the Document except for COMPANY's internal use, without prior written consent of CMU. COMPANY agrees to place the appropriate copyright notice on any such copies. Nothing herein shall be deemed to grant any license or rights in any other technology owned by CMU related to the Program.

9. COMPANY owns the rights to derivative works made by or on behalf of COMPANY. Nothing herein shall be deemed to grant to CMU, or any other party, any license or any rights in any technology owned by COMPANY whether or not related to the Program, or any license or any rights to COMPANY's products whether or not incorporating any portion of the Software, or any portion of any derivative works thereof, and CMU acknowledges that CMU has no rights to same.

10. This Agreement shall be construed, interpreted and applied in accordance with the laws of the Commonwealth of Pennsylvania.

11. Nothing in this Agreement shall be construed as conferring rights to use in advertising, publicity or otherwise any trademark or the name of ``CMU''.

12. COMPANY understands that CMU is not responsible for support or maintenance of the Program.

The complete list of people at CMU by whom Amulet has been developed by so far is: Brad A. Myers, Alan Ferrency, Rich McDaniel, Robert C. Miller, Andrew Faulring, Ellen Borison, Bruce D. Kyle, Yoshihiro Tsujino, Patrick Doane, Andy Mickish, Alex Klimovitski, Amy McGovern, William Moher, Robert Armstrong, Ashish Pimplapure, Patrick Rogan, Qiang Rao, and Chun K. So.