Object I/O library for Macintosh ********************************************* Contents ======== = About the Object I/O library = * Important compatibility notes * = Status & Feedback = Installation = What's New = What's Coming = Hints for converting programs About the Object I/O library ========================================== This distribution contains the new I/O library: the Object I/O library for the Clean language. It is a complete redesign of the 0.8 I/O library and adds many new concepts. Please note that we have refered to this new library in earlier notes as the 1.0 I/O library. We decided to name this system the Object I/O system because of its more powerful capabilities to construct and compose interactive objects. The Object I/O library is currently available only for Macintosh (PowerPC & 68k) and Windows (95/NT). * Important compatibility notes * ================================= The Object I/O library is not upward compatible with the 0.8 I/O library and they can not be used together in the same program. The version 1.0.1 and 1.1 of the Object I/O library are not upward compatible either. Status & Feedback ================= The definition of the Object I/O library has not been fully stabilised. Depending on your wishes and our experience with the Object I/O system it may happen that definitions change. We will work hard to do this in an upward compatible way but this is sometimes simply not possible or acceptable. Please be prepared that it may occur that you have to adapt your programs. We apologize for this inconvenience. It is our goal to stabilise the Object I/O library as soon as possible. This version is fully supported, so please send bugs reports by email to clean@cs.kun.nl. We will also continue to support the I/O library version 0.8 until the Object I/O library is stable and available for Macintosh and Windows. If you have questions, remarks or suggestions for improvements we invite you to send them to the Clean discussion list clean-list@cs.kun.nl We will answers questions on this list and use your remarks to improve the Object I/O libray. The distribution will updated on a regular basis. New versions are announced on our mailing lists (clean-list and clean-announce). Installation ============ To install the Object I/O library version 1.0.1 on your Macintosh do the following steps (version 1.1 works similar) * Transfer ObjectIO_1.0.1.sea.hqx to you local site with FTP (text mode). * Use BinHex (Stuffit Expander, BinHex 4.0, or the BinHex option in Stuffit or Compact Pro) to convert this file to the self extracting archive ObjectIO_1.0.1.sea; * Double Click the archive ObjectIO_1.0.1.sea. This will automatically extract the files from the archive. * Set the paths (Options->Paths...) in the Clean IDE so that Clean will use the new library. What's New ========== New features of the Object I/O library are: * Easy composition of objects * Interactive process creation * Message passing of arbitrary function and data types * Local state that can be added at any graphical user interface element * Clipboard handling of text Improvements to the 0.8 I/O library are: * Orthogonal treatment of all graphical user interface element definitions * All callback functions have easier composable types * All graphical user interface elements can be added and removed dynamically * Windows and dialogues can be constructed in a hierarchic way easily * Windows and dialogues can contain arbitrary collections of controls * Control layout has been improved by adding local layout scope * The program state is no longer required to be unique. Semantic differences to the 0.8 I/O library are: * The Files environment can be accessed only indirectly to warrant hygienic programs * The Events environment can not be accessed anymore but will be handled correctly with the process creation functions * Fonts are no longer static resources, but can change in time. Therefore to access fonts, one requires an environment parameter. * Id-s have become an abstract data type and can be generated only by the Object I/O system. * Window updates are no longer program state transition functions but describe the current look. What's Coming ============= To be expected soon: * Bitmaps handling * Clipboard handling of Pictures * Timers can be added to other devices as element instance * Local state becomes shareable between elements of different device type We are preparing a tutorial document that explains programmers what the Object I/O library is all about and how it should be used. Because this is not available yet we have converted some interactive Clean programs that used the 0.8 I/O library to use the Object I/O library to give programmers some idea of the differences between the two libraries. Unfortunately, there is no automatic way to convert Clean programs to use the Object I/O library. Also in preparation is an online technical reference manual in html-format that you can view with your favourite browser. It will contain extensive descriptions of all functions, types, module structure of the Object I/O library. Hints for converting programs ============================= When converting a program that uses the 0.8 I/O library to use the 1.0 I/O library the following transformation steps are frequently taken. * All Object I/O module names that you can use start with 'Std...'. The module StdIO imports all these modules. * If your program required the Files environment in its program state, then it can be removed. The Files environment can be accessed indirectly by means of the process state (PSt). Note that the program state no longer is required to be unique. * The StartIO function application becomes more concise. The new definition can be found in StdProcess, and is named startIO. * Instead of one program state, two initial state values need to be given. * Instead of an IOSystem argument that describes the initial graphical user interface configuration, the initial actions are supposed to create this configuration. * If your program used an AboutDialog, then this can be added as a process attribute (ProcessHelp). The 'gui utilities' folder contains the Help module to open the former about dialog. * Device definitions need to be changed according to the new algebraic type definitions. These changes are in most cases straightforward. * It is a good idea to inspect which Id values are really used in your program, because Ids are now an optional attribute of every interactive object. Remove all Ids that are not used to increase readability of your program. * Another way to get rid of Ids is in case of control layout. In some case you need Ids to get some layout done. Consider if this can also be achieved by introducing a new layout scope by means of the CompoundControl (illustrated by the 'Edit Record' dialogue definition of the original simple database example with the converted simple database example). * Ids are abstract data types and can be generated only by the Object I/O library. These functions generate fresh Id values, but require an environment parameter. The easiest to convert is to create these Id values before the startIO call, using the World, and parameterise the initialisation action function with these ids (see also the converted example programs). The functions that use these Ids can then be easily added as local functions of the initialisation action, or need to be parameterised with the proper Ids. * If your program uses fonts then an additional environment parameter needs to be added to all functions that open fonts and get metrics information. For the Object I/O version 1.0.1 this environment can be World as well as PSt, for version 1.1 it can be only Picture. * The update function of a window is now a constant function that simply describes what the window currently looks like. This means that at every location in your program where a change of look is implemented, also the look of the window has to be changed (use the function setWindowLook in StdWindow). * The drawing functions have been overloaded (see StdPicture and StdPictureDef). In most cases the changes are apparant. * In many cases it is helpful to change an IOSt transition function into a PSt transition function. The module StdPSt contains such transition functions that help you do this.