NOTICE WARNING CONCERNING COPYRIGHT RESTRICTIONS: The copyright law of the United States (title 17, U.S. Code) governs the making of photocopies or other reproductions of copyrighted material. Any copying of this document without permission of its author may be prohibited by law. The Garnet Toolkit Reference Manuals: Support for Highly-Interactive, Graphical User Interfaces in Lisp Brad A. Myers, Dark) Giuse, Roger B. Dannenberg, Brad Vander Zanden, David Kosbie, Philippe Marchal, Ed Pervin, John A. Kolojejchick November 1989 CMU-CS-89-196 School of Computer Science Carnegie Mellon University Pittsburgh, PA 15213 Copyright © 1989 - Carnegie Mellon University This research was sponsored by the Defense Advanced Research Projects Agency (DOD), ARPA Order No. 4976, Amendment 20, under contract F33615-87-C-1499, monitored by the Avionics Laboratory, Air Force Wright Aeronautical Laboratories, Aeronautical Systems Division (AFSC), Wright-Patterson AFB, Ohio 45433-6543. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the Defense Advanced Research Projects Agency or the US Government. Abstract The Garnet User Interface Development Environment contains a comprehensive set of tools that make it significantly easier to design and implement highly-interactive, graphical, direct manipulation user interfaces. Garnet provides a high level of support, while still being Look-and-Feel independent and providing the applications with tremendous flexibility. The Garnet tools are organized into two layers. The toolkit layer provides an object-oriented, constraint-based graphical system that allows properties of graphical objects to be specified in a simple, declarative manner, and then maintained automatically by the system. The dynamic, interactive behavior of the objects can be specified separately by attaching high-level "interactor" objects to the graphics. The higher layer of Garnet includes an interface builder tool, called Lapidary, that allows the user interface designer to draw pictures of all graphical aspects of the user interface. The Garnet toolkit layer software is now available for distribution. It uses Common Lisp and the X window manager, and is therefore portable across a wide variety of platforms. This document contains an overview, tutorial and a full set of reference manuals for the Garnet Toolkit. 1U Overall Table of Contents Overview of the Garnet Toolkit 1 Introduction to the toolkit and overview of this technical report. Comprehensive Support for Graphical, Highly-Interactive User Interfaces: The Garnet User Interface Development Environment 13 Conference paper presenting an overview of the Garnet project. An On-line Tour through Garnet 33 A guided tour and tutorial of some of Garnet's features. KR Reference Manual; Constraint-Based Knowledge Representation 51 The object and constraint system in Garnet. Opal Reference Manual; The Garnet Graphical Object System 85 Support for graphical output. Interactors Reference Manual; Encapsulating Mouse and Keyboard Behaviors 127 Support for input from the user. Aggregadgets and Aggrelists Reference Manual 179 Convenient way to create composite objects. Garnet Gadgets Reference Manual 201 A set of pre-defined interaction techniques. Debugging Tools for Garnet; Reference Manual 223 Tools to help debug Garnet code. Garnet Demos 239 Descriptions of the demonstration programs provide with Garnet. A Sample Garnet Program 247 Code for a simple graphical editor that allows the user to create boxes connected by arrows. Global Index 261 An index to all the names and procedures in the entire Garnet Toolkit. Overview of the Garnet Toolkit Brad A. Myers November 1989 Abstract This article provides an overview of the Garnet Toolkit, and a guide to this technical report. Copyright © 1989 - Carnegie Mellon University This research was sponsored by the Defense Advanced Research Projects Agency (DOD), ARPA Order No. 4976, Amendment 20, under contract F33615-87-C-1499, monitored by the Avionics Laboratory, Air Force Wright Aeronautical Laboratories, Aeronautical Systems Division (AFSC), Wright-Patterson AFB, Ohio 45433-6543. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the Defense Advanced Research Projects Agency or the US Government. Table of Contents 1. Introduction 3 2. Important Features of Garnet 3 3. Coverage 4 4. How to Get Garnet 4 5. Directory Organization 5 6. Site Specific Changes 6 6.1. File names 6 6.2. Fonts 6 6.3. Keyboard Keys 6 7. How to compile Garnet 7 8. How to load Garnet 7 9. Overview of the Parts of Garnet 8 10. Overview of this Technical Report 8 11. What You Need To Know 8 12. Planned Future Extensions 9 Index 11 Section 2 Important Features of Garnet Page 3 L Introduction The Garnet 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 Garnet are called the *'Garnet Toolkit," and these provide mechanisms that allow programmers to code user interfaces much more easily. The higher level tools allow both programmers and non-programmers to create user interfaces by just drawing pictures of what the interface should look like. Garnet stands for Generating an Amalgam of Real-time, Novel Editors and Toolkits. Preliminary versions of the Garnet Toolkit have been used by a number of CMU and external sites for projects building graphical editors. We have now released the toolkit for general use. This document contains an overview, tutorial, and a full set of reference manuals for the Garnet Toolkit. The higher levels of Garnet will be released in the future. Garnet is written in Common Lisp for the X window manager. Therefore, Garnet is quite portable to various environments. Garnet is running on IBM RTs using CMU Common Lisp, and on Suns using Lucid Common Lisp, versions 2.1 and 3.0. Versions for Allegro Common Lisp, and VAXLisp on VMS VAXStations are planned. Currently, Garnet supports X/l 1 R2 or R3 using the standard CLX interface. Garnet does not use the standard Common Lisp Object System (CLOS) or any X toolkit. 2. Important Features of Garnet Garnet is being designed as part of a research project, so it contains a number of novel and unique features. These are described in the article on page 13. In summary, the important features of Garnet are: • The Garnet Toolkit ic <k signed to support the entire user interface of an application; both the contents of the application window and its menus and dialog boxes. For example, Garnet directly supports selecting graphical objects with the mouse, moving them around, and changing their size. • It is look-and-feel independent. Garnet allows the programmer to define a new graphical style, and use that throughout a system. Alternatively, a pre-defined or standard style can be used, if desired. • It is object-oriented. • It uses a prototype-instance object model instead of the more conventional class-instance model, so that the programmer can create a prototype of a part of the interface, and then create instances of it. If the prototype is changed, then the instances are updated automatically. Therefore, Garnet uses its own, custom object system (called KR), and does not use CLOS. • Constraints are integrated with the object system, so any slot (also called an "instance variable") of any object can contain a formula rather than a value. When a value that the formula references changes, the formula is re-evaluated automatically. Constraints can be used to keep lines attached to boxes, labels centered at the top of rectangles, etc. (see Figure 1). Constraints can also be used to keep application-specific values connected with the values of graphical objects, menus, scroll bars or gauges in the user interface. • Objects are automatically refreshed when they change. Pictures are displayed by creating graphical objects which are retained. If a slot of an object is changed, the system automatically redraws the object and any other objects that overlap it. Also, the system handles window refresh requests from X. Page 4 Garnet Toolkit How to Get Garnet Section 4 • The programmer specifies the handling of input from the user at a high level using abstract interactor objects. Typical user interface behaviors are encapsulated into a few different types of interactors, and the programmer need only supply a few parameters to get objects to respond to the mouse and keyboard in sophisticated ways. • There is built-in support for laying out objects in rows and columns, for example, for menus. • A number of gadgets (also called widgets or interaction techniques) are provided to help the programmer get started. These include menus, buttons, scroll bars, sliders, circular gauges, graphic selection, and arrows. • Garnet is designed to be efficient. Even though Garnet handles many aspects of the interface automatically, an important goal is that it execute quickly and not take too much memory. We are always working to improve the efficiency, but Garnet can currently handle dozens of constraints attached to objects that are being dragged with the mouse on IBM/RTs or Sun 3's. 3. Coverage Garnet is designed to handle interfaces containing a number of graphical objects (up to about 2000) which the user can manipulate with the mouse and keyboard. Garnet does not handle applications with a significant text editing component (except for strings that might be used as labels or fields of a table or dialogue box). Garnet is suitable for applications of the following kinds: • Conventional drawing programs such as Apple Macintosh MacDraw. • Icon manipulation programs like the Macintosh Finder (which allows users to manipulate files). • Box and arrow diagram editors like Apple Macintosh MacProject (which helps with project management). • Graphical Programming Languages where computer programs can be constructed using icons and other pictures (a common example is a flowchart).