-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*- -*-*-*- Announcing The Release Of Version 3.0 of Amulet -*-*-*- -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*- We are delighted to announce the official release of Amulet Version 3.0. We have fixed several bugs found in the V3.0beta code and documentation, and have ported the system to new releases of the Microsoft Visual C++ and CodeWarrior Pro. There are LOTS of new features since V2.0. In Amulet V3, we have made significant changes to the slot interface that are designed to help users avoid common programming mistakes. This means that code written for Amulet V2 is unlikely to work without changes in Amulet V3. In particular, you must now use Set() to change the value of a slot that is already present in an object and you must use Add() to put a value in a new slot. See Section 2.1 for details. The preprocessor symbol, AMULET2_CONVERSION, was defined by default in the compiler options used to build the Amulet V3 Beta libraries. The symbol causes misuses of Add versus Set to be reported as run-time warnings instead of errors; it also makes the code run a lot slower. For the official Amulet V3 release, we no longer define AMULET2_CONVERSION by default. If you are just now converting from Amulet V2 for the first time, you may want to add -DAMULET2_CONVERSION to the compilation switches defined in your Makefile.vars file. If you are a new Amulet user, this does not affect you. For more details see Section 2 below. We support Amulet on Unix with gcc v2.7.2 and 2.7.2.1 on Suns and HPs, and with Centerline's ObjectCenter Version 2.1, using either X11/R5 or X11/R6. On the PC, we support Visual C++ V4.0, V4.2 and V5.0 under Windows NT (3.5.1 and 4.0) and Windows 95. On the Macintosh, we support both M68000 and PowerPC processors with CodeWarrior v10 and CodeWarrior Pro 1 (CodeWarrior 12). Many people have also succeeded in using Amulet V3 on other platforms as well, notably Linux. This document is the complete change discussion that describes all the changes since V2.0. Primarily, we have added: * Animation using the novel and easy to use animation constraints. * An interface builder for laying out widgets interactively. * Multiple looks and feels that mimic Motif, Windows 95 and Macintosh. * A mechanism to save and load Amulet objects to files. * "Wrappers" for external types so it is easier to put them into Amulet objects with full type checking, printing and editing. Amulet users will need to edit their V2 code to use this new version, but we think you will find it worthwhile. A section below contains an extensive discussion of the changes you will need to make. To get the new version, see http://www.cs.cmu.edu/~amulet/amulet3-release.html We are happy to announce that the new documentation is also ready for V3. You can get it from the same place as the source files: http://www.cs.cmu.edu/~amulet/amulet3-release.html#documentation The V3 manual does not document the changes between V2 and V3. For that, you can see below. This file is also available as: http://www.cs.cmu.edu/afs/cs/project/amulet/amulet3/announce3.0 The rest of this file contains: 0. Changes Since Amulet V3.0alpha 0.0 Changes Since V3.0beta 0.1 Changes Between V3.0alpha2 and V3.0beta 0.2 Changes Between V3.0alpha and V3.0alpha2 1. Changes Between Amulet V2.1 and Amulet V3.0alpha 1.1 Major Changes 1.2 Minor Changes 1.3 Very Minor Changes 1.4 Bug Fixes 2. Description of Non-Backwards Compatible Changes 2.1 Get/Set/GV/Get_Part changes 2.2 Am_Custom_Gridding_Method 2.3 Enums are now 1st class types 2.4 Renamed Print_Name() to be Print() everywhere. 2.5 Multi_Constraint 2.6 Slot Name Changes 2.7 Image Files Moved 3. Quick Guide to New Features 3.1 Animations 3.2 Gilt 3.3 Pointer_Wrappers and Enum_Wrappers 3.4 Drag-and-drop 3.5 Save and Load 3.6 Print(), Println(), To_String(), From_String() 3.7 New Look and Feels 4. How to Make Amulet V3. 4.1 Amulet V3 For Unix 4.2 Amulet V3 For the PC 4.3 Amulet V3 For the Macintosh = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 0. Changes Since Amulet V3.0alpha ============================================== 0.0 Changes Since V3.0beta ------------------------------------------- * Ported Amulet to MSVC++ 5.0 and CodeWarrior 12. In order to accomplish the latter, added conditional support for new osstrstream interface. In particular, CodeWarrior 12 removed the standard definition of strstream, so we added new macros, so you can use the following code with all compilers: #include STR_STREAM__H char line[300]; OSTRSTREAM_CONSTR (oss,line, 300, ios::out); reset_ostrstream(oss); oss << value << ends; OSTRSTREAM_COPY(oss, line, 300); do something with line * We have turned OFF the AMULET2_CONVERSION switch in the Makefiles. If you are converting an application from V2, you may add this switch to AM_CFLAGS in the Makefile.vars.. file to change Add/Set errors into warnings. Using the switch is expensive so we recommend removing it, deleting object files and libraries, and rebuilding after you have changed your application. * On Unix and the PC, Amulet now uses the Am_TITLE string for a window's icon title when the Am_ICON_TITLE slot has the value Am_No_Value. And the default value for the Am_ICON_TITLE slot is now Am_No_Value. * You can now change the cursor in a window by setting the Am_CURSOR slot of an Am_Window with an Am_Cursor object. This is not yet implemented on the Macintosh. * We have found and fixed some (but not all) memory leaks. * We have fixed some (but not all) discrepencies in Windows draw functions. Added mask methods to many draw functions. * We have fixed the inspector menu bug, which prevented the inspector from recognizing certain menu items on certain platform. * We have fixed window position bug. Menus now pop up in the correct place when their owner window is moved, even when the window is moved while it is invisible. * We have fixed some discrepencies in the manual, and added more index items. * We now use a well-formed default font name to look up a font under X-windows, if no font is returned when we use a less-than-well-formed name. (Some platforms return a better font when the less-than-well-formed name is used.) * Fixed parsing of PAGE_UP and PAGE_DOWN key symbols. * Poping up a menu on the PC no longer deactivates the application window. * For MS-Windows, we have incorporated changes to console.cpp contributed by Robert M. Muench. The change fixes a memory leak, and allows users to write to a log file. 0.1 Changes Between V3.0alpha2 and V3.0beta ------------------------------------------- * Added the documentation! * We have enabled warnings about misuse of Add and Set. See Section 2.1 below * We have rationalized the compiler options used to produce the Amulet libraries. The default library "amulet" is compiled for application development with optimization on, with debugging symbols defined, and with the Amulet inspector enabled. The release library "amulet-release" is compiled for application release with optimization on, without debugging symbols, and without the inspector enabled. * On the Macintosh, we have offset the default Am_TOP and Am_LEFT values of the Am_Window object so windows are not hidden by the Menu Bar. * On the Macintosh, we have renamed types.h to be amulet/types.h to avoid conflicts with the Codewarrior include file of the same name. * The slot Am_UNDO_HANDLER is now a default slot in the Am_Window object. (So you must use Set() not Add() to change its value.) * Contributed Makefile.vars... and Makefile.lib... files have been moved from amulet/contrib to amulet/bin. * In addition to the growing set of platforms in use by Amulet users, Amulet users have been able to compile Amulet V3 using the native Sun compiler SC 3.0.1 and 4.0 (C++ 4.1); using gcc under digital unix and NetBSD, and using MSVC++ 5.0. There are contributed Makefile.vars... and Makefile.lib... files in amulet/bin. * See amulet/contrib/listbox for a new listbox widget contributed by an Amulet user. * Changed the name of Am_H_FRAME and Am_V_FRAME slots to be Am_RIGHT_OFFSET and Am_BOTTOM_OFFSET. * Fixed formulas Am_Vertical_Layout and Am_Horizontal_Layout so they no longer use Am_X_OFFSET and Am_Y_OFFSET slots, but instead use Am_LEFT_OFFSET and Am_TOP_OFFSET like the other formulas, due to a conflict with scrolling groups. * We have rationalized the CodeWarrior 10 projects for the Macintosh so they permit straightforward integration with other libraries; and we have resized the projects to fully accommodate the memory requirements of the sample applications. * Lots of small bug fixes (Gilt align-down, option buttons in modal windows, interactors running continuously, etc.) 0.2 Changes Between V3.0alpha and V3.0alpha2 -------------------------------------------- NEW FEATURES: ------------- * This version works on the Macintosh. See the installation instructions below. * Amulet now supports Japanese character input and output (with some limitations) under UNIX/X11 using two-byte JIS (ISO) or EUC encodings and under Windows-J 95/NT using the multi-byte SHIFT-JIS encoding. (Windows-J is the Japanese version of Windows.) Japanese input is not fully supported under X11 -- so far only Roman-Kana conversion is implemented. There is currently no support for Japanese I/O on the Macintosh; please let us know if you want to help us get this working. The font Am_Japanese_Font is exported from opal.h; other sizes, faces and families are available. See amulet/src/opal/testJIO.cc for examples. * Added Am_Pop_Up_Error_Window(str) function to widgets.h * New feature: Am_CHECKED_ITEM slot of a command object can be set, and then that item in an Am_Menu_Bar or Am_Menu will show up with a checkmark. * The Am_Slot_Key variables Am_SCROLLING_GROUP and Am_UNDO_DIALOG_BOX have been renamed to Am_SCROLLING_GROUP_SLOT and Am_UNDO_DIALOG_BOX_SLOT, to avoid linker name space conflicts under VMS. * Amulet users have successfully built Amulet V3 alpha under Linux using gcc, on QNX/X-windows using Watcom 10.6, and under OpenVMS using the DEC compiler. There are new and revised contributed Makefiles.vars files for Linux and QNX/X-Windows as well as contributed command for building under OpenVMS. * See amulet/contrib/outline for a new outline widget (that looks like a MS tree control) contributed by an Amulet user. * The Undo_Dialog_Box is now part of the Amulet library, so it is no longer necessary to explicitly include or link in undo_dialog_box.cc. BUG FIXES: ---------- * We fixed the problem where Amulet would not compile with DEBUG off because some symbols were missing. * Transparent gifs now display under Windows95. * Made property setting in Gilt undoable * Using Am_Start_Interactor will now work right after the interactor has been created, so you can use this to create an interactor that is always running. * Some cleanup/destruction-time bugs have been fixed so Amulet doesn't crash when quitting. = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 1. Changes Between Amulet V2.1 and Amulet V3.0alpha ============================================== 1.1 Major Changes ----------------- * Any property of an object can be easily animated by attaching an "animation constraint" to it. See below for a description of how to do this. Amulet's animation constraints were described in the conference paper: Brad A. Myers, Robert C. Miller, Rich McDaniel, and Alan Ferrency, "Easily Adding Animations to Interfaces Using Constraints." ACM Symposium on User Interface Software and Technology, UIST'96, November 6-8, 1996. Seattle, WA. pp. 119-128. ftp://a.gp.cs.cmu.edu/afs/cs.cmu.edu/project/amulet/www/papers/animate.ps * Added the Gilt interface builder which allows windows, groups, and dialog boxes to be designed interactively, and which generates C++ code for inclusion in applications. * Widgets now change their look to match Motif, Windows 95 or the Macintosh. See below for details. * Standard mechanisms for saving Amulet objects to a file and loading them back which can be used by all applications. * Application-specific types are easier to put into Amulet objects with full type checking, custom printing and custom reading, using Pointer_Wrappers for pointers and Type_Wrappers for types which fit into a word (like Enumerated types, Am_Input_Chars, bit masks, etc.) The Inspector can allow full printing and editing of these. * The syntax and semantics of Get and Set and friends have been significantly changed to be more consistent and provide more capabilities. GV has been eliminated--just use Get instead. See below for details. * Enhanced debugging: more types of values print out correctly in the Inspector, and can be edited. Usually when Am_Error's occur, the programmer is asked whether to go into the inspector or not, and the system has been engineered so the Inspector can be used even when parts of the system are messed up. 1.2 Minor Changes ----------------- * Turned on Amulet's MEMORY switch on PCs and Macintoshes, which makes initialization and exectution much faster. * All objects in Amulet have methods for Printing and getting their name as a string, which are designed to be used when debugging. * New widgets and graphical objects: - Am_Vertical_Up_Down_Counter widget - Am_Number_Input_Widget: a text input widget for numbers. Numbers can be restricted to be in a range. See samples/examples/example2.cc for how to use. - Am_Password_Input_Widget: a text input widget that hides the characters typed. Works just like the Am_Text_Input_Widget. - Am_Arrow_Line: lines with an arrowhead. Head size controlled by slots Am_HEAD_WIDTH (default=3) and Am_HEAD_LENGTH (5) - New widget for pop-up menus. The new Am_Pop_Up_Menu_Interactor is a one shot interactor that pops up a menu. In addition to regular Am_One_Shot_Interactor slots, also has Am_FILL_STYLE, Am_ITEMS, and Am_WIDGET_LOOK which affect the sub-menu. Command in inter is called if item doesn't have a command. Am_VALUE of inter is set with selection from menu. - Am_Fade_Group: objects in this group can be faded out by setting the Am_VALUE of the group to be 0..99. Uses a halftoning trick. - Am_Flip_Book_Group: chooses ONE of the parts to show. Use the regular Add_Part method to add parts to a flip book. The Am_VALUE slot of the flip_book_group itself determines which one part will be displayed. To display different parts, set the flip_book's Am_VALUE to the desired part's index (which starts from zero). * Some additional command objects: - Am_Open_Command, Am_Save_Command, Am_Save_As_Command: use the built-in load-save mechanism (see below). - Am_Standard_OK_Command, Am_Standard_Cancel_Command: useful for putting into custom dialog boxes. - Am_About_Amulet_Command - brings up the About Amulet dialog box - Am_Cycle_Value_Command - Provide a list of labels in the Am_LABEL_LIST slot, and it goes through the list with each click. The Am_VALUE of the command is set with the index of the current label in the list (from 0). If the list has 2 values, then this will be a toggle, like "Turn Grid On" <-> "Turn Grid Off" with the Am_VALUE taking on 0 and 1. Undoing returns the Am_VALUE and label to the original values. You can also explicitly set the Am_VALUE slot of the command to change the current state. Typically, a constraint would depend on the Am_VALUE of the command. BUG: The Am_VALUE slot takes on a string value temporarily before settling down with the correct value, so constraints must be written to deal with this. - Am_Gesture_Select_And_Do_Command, Am_Gesture_Create_Command, Am_Gesture_Unrecognized_Command: New commands in gestures that do the often-needed operations: * Added some additional built-in constraints, and made many of the existing constraints take offset parameters, so you more frequently can use built-in constraints rather than writing your own: - Am_Fill_To_Bottom - uses object's slot Am_V_FRAME as the border - Am_Fill_To_Right - uses object's slot Am_H_FRAME as the border - Am_Fill_To_Rest_Of_Width - Am_H_SPACING between the left side of this obj and the rest of the objects in the owner, leaving Am_H_FRAME on the right - Am_Fill_To_Rest_Of_Height - same, but for height - Am_Width_Of_Parts - now leaves Am_H_FRAME border all around - Am_Height_Of_Parts - now leaves Am_V_FRAME border all around - Am_Right_Is_Right_Of_Owner - leaves Am_H_FRAME - Am_Bottom_Is_Bottom_Of_Owner - leaves Am_V_FRAME - Am_Fill_To_Right_Of_Owner - leaves Am_H_FRAME - Am_Fill_To_Bottom_Of_Owner - leaves Am_V_FRAME The following now take an optional offset and multiplier parameters, and compute (value*multiplier + offset). Default for multiplier is 1.0 and 0 for offset. - Am_Same_As (key, offset, multiplier) - Am_From_Owner (key, offset, multiplier) - Am_From_Part (part, key, offset, multiplier) - gets the key slot from part - Am_From_Sibling (sibling, key, offset, multiplier) - gets the key slot from sibling - Am_From_Object (object, key, offset, multiplier) - given an object, get its key slot. Useful when object is a global variable. The following built-in constraints have not been changed: Am_Center_X_Is_Center_Of, Am_Center_Y_Is_Center_Of, Am_Center_X_Is_Center_Of_Owner, Am_Center_Y_Is_Center_Of_Owner, * Am_TEXT_CHECK_LEGAL_METHOD for Am_Text_Input_Widget and Am_Text_Interactors. Method defined in inter.h. * Am_Selection_Widget now handles multiple windows and drag-and-drop of objects among windows. See below for details. * New sample programs, such as Space2, Circuit, tree, and examples*.cc to demonstrate features and help developers understand how to use Amulet. * We reorganized the samples/ subdirectory so that a number of the programs no longer have sub-subdirectories. Make all the samples in the top-level bin/ directory instead of in the samples directory. Also, the hello world and goodbye world programs moved from samples/hello to samples/examples. * Can get to characters at the top of a font by holding down the meta key when entering a string. For example, under Unix, European characters are accessible this way: the meta key basically sets the 8th bit before sending the character to the font. * Added ability to recognize and display transparent GIFS. * Added support for selecting in a region to selection handles. The slot Am_REGION_WHERE_TEST can be set to a method of type Am_In_Region_Method to determine which objects should be selected, but the default method, Am_Group_Parts_Inside, is probably adequate for most applications. * New events that can be used in Interactors as the START_WHEN are