The Amulet V3.0 Reference Manual Brad A. Myers, Ellen Borison, Alan Ferrency, Rich McDaniel, Robert C. Miller, Andrew Faulring, Bruce D. Kyle, Patrick Doane, Andy Mickish, Alex Klimovitski March, 1997 CMU-CS-95-166-R2 CMU-HCII-95-102-R2 School of Computer Science Carnegie Mellon University Pittsburgh, PA 15213 This manual describes Version 3.0 of the Amulet User Interface Toolkit, and replaces all previous versions: CMU-CS-95-166-R1/ CMU-HCII-95-102-R1 (Jan, 1996), CMU-CS-95-166/ CMU-HCII-95-102 (June, 1995), and all change documents. Copyright © 1997 - Carnegie Mellon University This research was sponsored by NCCOSC under Contract No. N66001-94-C-6037, Arpa Order No. B326. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official poli- cies, either expressed or implied, of NCCOSC or the U.S. Government. Keywords: User Interface Development Environments, User Interface Management Systems, Constraints, Prototype-Instance Object System, Widgets, Object-Oriented Programming, Direct Manipulation, Input/Output, Amulet, Garnet. Abstract The Amulet User Interface Development Environment con- tains a comprehensive set of tools that make it significantly easier to design and implement highly interactive, graphical, direct manipulation user interfaces. Applications imple- mented in Amulet will run without modification on Unix, PC, and Macintosh platforms. Amulet provides a high lev- el of support, while still being Look-and-Feel independent and providing applications with tremendous flexibility. Amulet currently provides a low-level toolkit layer, which is an object-oriented, constraint-based graphical system that allows properties of graphical objects to be specified in a simple, declar- ative 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. Higher-level tools, such as the Gilt interface builder, allow parts of the user interface to be layed out without program- ming. The Amulet toolkit is available for unlimited distribution by anonymous FTP or WWW. Amulet uses X/11 on Unix- based systems, the native Windows NT or Windows 95 toolkit on PCs, and standard Quickdraw on the Macintosh. This document contains an overview of Amulet with down- load and installation instructions, a tutorial, and a full set of ref- erence manuals for the Amulet system. TABLE OF CONTENTS 1. Amulet V3.0 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.1 Introduction 19 1.2 Amulet Email Addresses 20 1.3 Using Amulet in Products: Copyright and Licensing 20 1.4 How to Retrieve and Install Amulet 21 1.4.1 The Amulet Manual 21 1.4.2 Retrieving the Amulet source code distribution 22 1.4.2.1 Retrieving the source distribution via FTP 22 1.4.2.2 Retrieving the source distribution via WWW 22 1.4.3 Installing Amulet on a PC 23 1.4.3.1 Unpacking amulet.tar.gz 23 1.4.3.2 Windows Environment Variables 23 1.4.3.3 Building the Library, Sample Applications and Test Programs with Visual C++ 24 1.4.3.4 Building Your Own Applications 26 1.4.3.5 Using console.cpp to Simulate a Terminal Window 27 1.4.3.6 Building Windows Applications for Release 27 1.4.4 Installing Amulet on a Unix Workstation 27 1.4.4.1 Unpacking amulet.tar.Z 27 1.4.4.2 Setting your Environment Variables 28 1.4.4.3 Building the Library, Sample Applications and Test Programs 29 1.4.4.4 Writing and Compiling New Programs Using Amulet 30 1.4.4.5 Building Unix Applications for Release 30 1.4.5 Installing Amulet on a Macintosh 31 1.4.5.1 Unpacking amulet.sea.hqx 31 1.4.5.2 Macintosh Environment Variables 31 1.4.5.3 Processor Support: PowerPC and 68K 31 1.4.5.4 Building the Amulet library 32 1.4.5.5 Compiling the Amulet Test Programs and Sample Applications 33 1.4.5.6 Writing and Compiling New Programs Using Amulet 33 1.4.5.7 Compiling Programs for Release 33 1.5 Test Programs and Sample Applications 34 1.6 Amulet Makefiles 36 1.6.1 Makefile Variables 36 1.6.2 Conditional Compilation Symbols 37 1.6.3 Command Line make Options 39 1.6.4 Xlib Pathnames 39 1.7 Preparing Amulet Applications for Release 39 1.8 Amulet Header Files 40 1.8.1 Basic header files 41 1.8.2 Advanced header files 42 1.8.3 Standard Header File Macros 43 1.9 Amulet Naming Conventions 43 1.10 Parts of Amulet 44 1.11 Changes since Version 2 44 1.12 Formal, Legal Language 44 2. Amulet Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2.1 Setting Up 49 2.1.1 Install Amulet in your Environment 49 2.1.2 Copy the Tutorial Starter Program 49 2.2 The Prototype-Instance System 50 2.2.1 Objects and Slots 50 2.2.2 Dynamic Typing 51 2.2.3 Inheritance 52 2.2.4 Instances 55 2.2.5 Prototypes 56 2.2.6 Default Values 59 2.2.7 Destroying Objects 59 2.2.8 Unnamed Objects 60 2.3 Graphical Objects 60 2.3.1 Lines, Rectangles, and Circles 60 2.3.2 Groups 60 2.3.3 Am_Group 62 2.3.4 Am_Map 63 2.3.5 Windows 63 2.4 Constraints 63 2.4.1 Formulas 64 2.4.2 Declaring and Defining Formulas 64 2.4.3 An Example of Constraints 65 2.4.4 Values and constraints in slots 67 2.4.5 Constraints in Groups 68 2.4.6 Common Formula Shortcuts 69 2.5 Interactors 70 2.5.1 Kinds of Interactors 71 2.5.2 The Am_One_Shot_Interactor 72 2.5.3 The Am_Move_Grow_Interactor 73 2.5.4 A Feedback Object with the Am_Move_Grow_Interactor 74 2.5.5 Command Objects 75 2.5.6 The Am_Main_Event_Loop 75 2.6 Widgets 76 2.7 Debugging 78 2.7.1 The Inspector 78 2.7.2 Tracing Interactors 79 2.8 To Learn More 80 3. ORE Object and Constraint System . . . . . . . . . . . . . . . . . . . . . . . . . . 81 3.1 Introduction 83 3.2 Version 83 3.3 Include Files 84 3.4 Objects and Slots 84 3.4.1 Get, Peek, Set and Add 84 3.4.2 Slot Keys 85 3.4.3 Value Types 86 3.4.4 The Basic Types 87 3.4.5 Bools 88 3.4.6 The Am_String Class 88 3.4.7 No Type, Zero Type, and Error Types 89 3.4.8 Using Wrapper Types 90 3.4.8.1 Standard Wrapper Methods 90 3.4.9 Storing Methods in Slots 91 3.4.10 Flag parameters to Get and Set 92 3.4.11 Using Am_Value 93 3.4.12 Advanced features of the Am_Value_Type 95 3.5 Inheritance: Creating Objects 95 3.6 Destroying Objects 97 3.7 Parts 98 3.7.1 Parts Can Have Names 98 3.7.2 How Parts Behave With Regard To Create and Copy 99 3.7.3 Other Operations on Parts 99 3.8 Formulas 100 3.8.1 Formula Functions 101 3.8.1.1 Defining Formulas without Macros 102 3.8.1.2 Formulas Returning Multiple Types 102 3.8.2 Using Slots in a Formula without Creating Dependencies 103 3.8.3 Putting Formulas into Slots 104 3.8.4 Slot Setting and Inheritance of Formulas 105 3.8.5 Calling a Formula Procedure From Within Another Formula 105 3.9 Lists 105 3.9.1 Current pointer in Lists 106 3.9.2 Adding items to lists 106 3.9.3 Other operations on Lists 107 3.10 Iterators 108 3.10.1 Reading Iterator Contents 108 3.10.2 Types of Iterators 109 3.10.3 The Order of Iterator Items 109 3.11 Connecting C++ Types 110 3.11.1 Type Support 111 3.11.2 Pointer Wrappers 112 3.11.3 Enum Wrappers 113 3.11.3.1 Enumerated Types 113 3.11.3.2 Bit Fields and Longs 116 3.11.4 Writing a Wrapper Using Amulet’s Wrapper Macros 117 3.11.4.1 Creating the Wrapper Data Layer 117 3.11.4.2 Printing and Editing Values 119 3.11.4.3 Using The Wrapper Data Layer 120 3.11.4.4 Creating The Wrapper Outer Layer 121 3.12 Saving and Loading Objects from Files 122 3.12.1 Simple Interface For Storing and Loading Objects 122 3.12.2 Types of Data to Store 124 3.12.3 General Mechanism 125 3.13 Errors 126 3.14 Advanced Features of the Object System 126 3.14.1 Destructive Modification of Wrapper Values 126 3.14.2 The Am_Web Constraint 127 3.14.2.1 The Validation Procedure 128 3.14.2.2 The Create and Initialization Procedures 129 3.14.2.3 Installing Into a Slot 130 3.14.3 Using Am_Object_Advanced 130 3.14.4 Controlling Slot Inheritance 131 3.14.5 Controlling Formula Inheritance 132 3.14.6 Writing and Incorporating Demon Procedures 133 3.14.6.1 Object Level Demons 133 3.14.6.2 Slot Level Demons 134 3.14.6.3 Modifying the Demon Set and Activating Slot Demons 135 3.14.6.4 The Demon Queue 136 3.14.6.5 How to Allocate Demon Bits and the Eager Demon 137 4. Opal Graphics System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 4.1 Overview 141 4.1.1 Include Files 141 4.2 The Opal Layer of Amulet 141 4.3 Basic Concepts 142 4.3.1 Windows, Objects, and Groups 142 4.3.2 The “Hello World” Example 143 4.3.3 Initialization and Cleanup 144 4.3.4 The Main Event Loop 144 4.3.5 Am_Do_Events 144 4.4 Slots Common to All Graphical Objects 145 4.4.1 Left, Top, Width, and Height 145 4.4.2 Am_VISIBLE 145 4.4.3 Line Style and Filling Style 145 4.4.4 Am_HIT_THRESHOLD and Am_PRETEND_TO_BE_LEAF 146 4.5 Specific Graphical Objects 146 4.5.1 Am_Rectangle 146 4.5.2 Am_Line 147 4.5.3 Am_Arrow_Line 148 4.5.4 Am_Arc 148 4.5.5 Am_Roundtangle 149 4.6.6 Am_Polygon 150 4.6.6.1 The Am_Point_List Class 151 4.6.6.2 Using Point Lists with Am_Polygon 153 4.6.7 Am_Text 154 4.6.7.1 Am_String in Am_Text objects 154 4.6.7.2 Fonts 155 4.6.7.3 Japanese Text Input and Output 156 4.6.7.4 Functions on Text and Fonts 157 4.6.7.5 Editing Text 157 4.6.8 Am_Bitmap 158 4.6.8.1 Loading Am_Image_Arrays From a File 159 4.6.8.2 Using Images with Am_Bitmap 159 4.7 Styles 159 4.7.1 Predefined Styles 160 4.7.2 Creating Simple Line and Fill Styles 160 4.7.2.1 Thick Lines 160 4.7.2.2 Halftone Stipples 161 4.7.2.3 Clone_With_New_Color 161 4.7.3 Customizing Line and Fill Style Properties 161 4.7.3.1 Color Parameter 162 4.7.3.2 Thickness Parameter 162 4.7.3.3 Cap_Flag Style Parameter 163 4.7.3.4 Join_Flag Style Parameter 163 4.7.3.5 Dash Style Parameters 164 4.7.3.6 Fill Style Parameters 164 4.7.3.7 Stipple Parameters 165 4.7.4 Getting Style Properties 165 4.8 Groups 166 4.8.1 Adding and Removing Graphical Objects 167 4.8.2 Layout 168 4.8.2.1 Vertical and Horizontal Layout 168 4.8.2.2 Custom Layout Procedures 170 4.8.3 Am_Resize_Parts_Group 170 4.8.4 Am_Fade_Group 170 4.8.5 Am_Flip_Book_Group 171 4.9 Maps 172 4.10 Methods on all Graphical Objects 174 4.10.1 Reordering Objects 174 4.10.2 Finding Objects from their Location 174 4.10.3 Beeping 175 4.10.4 Filenames 176 4.10.5 Translate Coordinates 176 4.11 Windows 177 4.11.1 Slots of Am_Window 178 4.11.2 Cursors 179 4.11.3 Destroying windows 179 4.12 Am_Screen 180 4.13 Predefined formula constraints 180 5. Interactors and Command Objects for Handling Input. . . . . . . . . . 183 5.1 Include Files 185 5.2 Overview of Interactors and Commands 185 5.3 Standard Operation 186 5.3.1 Designing Behaviors 186 5.3.2 General Interactor Operation 187 5.3.3 Parameters 187 5.3.3.1 Events 188 5.3.3.2 Graphical Objects 192 5.3.3.3 Active 194 5.3.3.4 Am_Inter_Location 194 5.3.4 Top Level Interactor 196 5.3.5 Specific Interactors 196 5.3.5.1 Am_Choice_Interactor 197 5.3.5.2 Am_One_Shot_Interactor 199 5.3.5.3 Am_Move_Grow_Interactor 201 5.3.5.4 Am_New_Points_Interactor 204 5.3.5.5 Am_Text_Edit_Interactor 206 5.3.5.6 Am_Gesture_Interactor 209 5.4 Advanced Features 213 5.4.1 Output Slots of Interactors 213 5.4.2 Priority Levels 214 5.4.3 Multiple Windows 215 5.4.4 Running_Where 216 5.4.5 Starting, Stopping and Aborting Interactors 217 5.4.6 Support for Popping-up Windows and Modal Windows 218 5.4.7 Enabling and Disabling Interactors 219 5.5 Customizing Interactor Objects 220 5.5.1 Adding Behaviors to Interactors 220 5.5.1.1 Available slots of Am_Choice_Interactor and Am_One_Shot_Interactor 221 5.5.1.2 Available slots of Am_Move_Grow_Interactors 221 5.5.1.3 Available slots of Am_New_Point_Interactors 222 5.5.1.4 Available slots of Am_Text_Interactors 222 5.5.1.5 Available slots of Am_Gesture_Interactors 222 5.5.2 Modifying the Behavior of the Built-in Interactors 222 5.5.3 Entirely New Interactors 223 5.6 Command Objects 224 5.6.1 Implementation_Parent hierarchy 225 5.6.2 Undo 226 5.6.2.1 Enabling and Disabling Undoing of Individual Commands 226 5.6.2.2 Using the standard Undo Mechanisms 227 5.6.2.3 The Selective Undo Mechanism 228 5.6.2.4 Building your own Undo Mechanisms 230 5.7 Debugging 231 6. Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 6.1 Include Files 235 6.2 Introduction 235 6.3 Am_Time 235 6.4 General Interface 236 6.5 Starting and Stopping Animations 237 6.6 Turning On and Off Animations 237 6.7 Parameters of all Animators 238 6.8 Types of Animations 239 6.8.1 Am_Animator 239