************************************************************ * * Desktop Utilities 4.0 - updated beta release * by Tony Morton and Rob Mueller * * Revision date: 14 November, 1994 * ************************************************************ Welcome to the newest version of Desktop Utilities, our general purpose suite of useful little utilities to spice up your IIgs. This release was actually planned to be a lot earlier, but we have had practically no time to work on this project since early this year, and so Desktop Utilities 4.0 remains largely incomplete. However, after a number of requests from people on the net and elsewhere, we have decided to go ahead and release what we have so far. Hopefully we will eventually have time to finish what we started, but it may not be for a while. This revised beta release contains new versions of the kernel and a slight alteration to the NDA Interface, along with a new version of DTULib for programmers and some revisions to the programmer docs. Among the 'general use' files, only the files DTUtils4.0 and NDA.Aux need to be updated; this can be done simply by copying over the old files. Included in this release are the following files: About.DTUtils4 Release notes (You Are Here) DTUtils4.0 Desktop Utilities 4.0 kernel NDA NDA Interface module, runtime NDA.Aux NDA Interface module, auxiliary VirtDAs Virtual DA Manager, runtime VirtDAs.Aux Virtual DA Manager, auxiliary VirtDAs.Doc Virtual DA Manager documentation MenuBar Menu Bar Manager Clocks Clock Manager The following files are of interest chiefly to programmers: Writing.Modules Programmer documentation (kernel) Module.Requests Programmer documentation (modules) DTULib Kernel function library DTULib.Src ORCA/Assembler source code for DTULib DTU.H C header file for kernel functions DTU.E Various assembler equates Important Note: We Want Your Money!! -------------- Desktop Utilities 4.0 is ShareWare, copyright (c) GyruS Software 1994, all rights reserved. It may be distributed freely, provided all the above files remain intact and unmodified (except for archiving purposes). To legally use Desktop Utilities 4.0 after a free trial period of 14 days, please send a $20 registration fee to: Tony Morton Ormond College University of Melbourne Parkville, Victoria 3052 Australia. As our part of the bargain, we will endeavour to send you a disk containing a choice selection of our other software. This may take a number of weeks, as we both have busy lives to live, so have patience! Installing Desktop Utilities 4.0 -------------------------------- To use Desktop Utilities 4 on your system, you need a IIgs, System 6.0 or above, at least 35K of free space on your System disk (although preferably more), and about 64K of spare RAM (generally not a problem if you have enough RAM to run System 6). The Finder (or a utility such as OpenIt which sends Finder open requests) is needed for initial installation, but once installed Desktop Utilities will operate in any desktop program. If you currently use Desktop Utilities 3.3, version 4.0 will coexist peacefully with the older version. Thus, you can take advantage of the improved Virtual DA Manager in version 4.0 without losing your wide menus, QuickSwitch, or Instant DAs. Eventually, all functions of version 3.3 (and more) will be provided as modules in version 4.0; see the list below. The final release of Desktop Utilities will, we hope, include a comprehensive installation utility. For now, installation involves a fairly simple three-step process: 1. Install the kernel. 2. Copy the modules to any convenient location. 3. Tell Desktop Utilities about the newly installed modules. To install the kernel, simply copy the 'DTUtils4.0' file into the 'System.Setup' folder within the 'System' folder of your hard drive or System disk, then restart the IIgs. During the startup process you should notice an extra icon (or version string) appear, indicating that the Desktop Utilities kernel is installed. The next step is to place the six module files (NDA, NDA.Aux, VirtDAs, VirtDAs.Aux, MenuBar and Clocks) in some convenient location. Four of the files (NDA, VirtDAs, MenuBar and Clocks) will be loaded at startup time and should preferably be placed on your System disk if you don't have a hard drive, while the other two (NDA.Aux and VirtDAs.Aux) are only loaded when needed. If space permits, it is recommended that you create a folder called 'DTU.Modules' (or some such name) within your 'System.Setup' folder, and place all six module files into this folder. However, Desktop Utilities gives you the freedom to place the module files wherever you like. Having installed the kernel and the module files, you now need to tell Desktop Utilities where to locate the modules. This is done from the Finder, by double-clicking on each of the six module files in turn. Each time Desktop Utilities will present a dialog box to confirm that you want to install the file. Once installed, Desktop Utilities will remember to look for the file in that location, prompting for the correct disk if necessary. IMPORTANT: When you install the Menu Bar Manager, a dialog box will appear, giving you the option to make the Menu Bar Manager active immediately. DO NOT DO THIS. Select the 'No' button or press Return. Selecting 'Yes' places you in severe danger of crashing. In future, either this will be fixed or the immediate installation option removed. The six module files comprise four modules: NDA Interface, Virtual DA Manager, Menu Bar Manager and Clock Manager. It is not necessary to install all of these, although the Clock Manager depends on the Menu Bar Manager being installed. As alluded to above, the NDA Interface and Virtual DA Manager come as two files, so that users with space problems can install the auxiliary files on a separate disk. If the auxiliary files are not installed along with the runtime files, Desktop Utilities will request that the auxiliary file be located when it is first needed. It will also detect when a file has been moved and allow you to relocate it, much as the Finder does now. At this stage, relocating a file involves entering the full pathname if certain tool sets are not available - sorry. Once a module file is installed, it can be removed by double clicking on it while holding down the Control key. Double clicking normally on an installed module file will generally cause some configuration function to be invoked, as though it had been selected from the NDA window (see below). If your IIgs crashes for any reason while installing or removing files, you may wind up with a corrupted kernel configuration file, and Desktop Utilities may start acting very strangely at startup time. If this occurs, the following emergency action is recommended: 1. Shift-boot the IIgs, to prevent Desktop Utilities being loaded. 2. Locate the file 'DTU.Settings' in your 'System.Setup' folder. 3. Delete this file. (If in the Finder, place it in the Trash can, then select 'Empty Trash'.) 4. Restart the IIgs normally. After doing this, you will need to reinstall the modules from scratch. Hopefully you should not need to do this in the first place (famous last words). Previously, it was recommended that you restart the IIgs as soon as possible after making changes to the configuration; changes have been made to the kernel that should (hopefully) make this unnecessary. Brief Overview of Kernel and Modules ------------------------------------ From the user's point of view, Desktop Utilities functions are now all contained within modules. These modules are looked after by a kernel (the DTUtils4.0 program) which performs a lot of mundane functions on the modules' behalf and also contains a powerful set of programming tools, available to all modules and to other programs that are 'Desktop Utilities aware'. Other programs can communicate with Desktop Utilities and its modules via the Inter Process Communication facility built into System 6. This is all described in the documentation files 'Writing.Modules' and 'Module.Requests'. For AppleShare users: Desktop Utilities takes some special actions if it detects that the user is booting from an AppleShare file server, as described in the section on settings files in 'Writing.Modules'. The code to do this exists, but has not been tested. If there is someone out there with the appropriate network setup (and preferably Internet access) that wants to test this feature, please let us know. The NDA Interface module provides a simple user interface to Desktop Utilities, available from the Apple menu. The NDA Interface can be used to install, remove and configure modules, and to invoke other module functions. (All of this can also generally be done using the Finder's request passing mechanism, so the NDA Interface is not strictly necessary.) Initially, the NDA's window contains a list of the available functions, which are invoked by double clicking on the title or by selecting the function and pressing 'Open'. Radio buttons can be used to switch between this list and a list of module files currently installed; here there are an additional two buttons which allow files to be installed or removed. The Virtual DA Manager is the most developed of the modules included in this beta release (although it omits a few features which are still on our 'wish list', principally support for Virtual DAs with request procedures). It performs a function which we still believe to be unique to Desktop Utilities, and which we consider its single most useful function; namely, allowing Classic and New Desk Accessories to be made 'virtual' so that they do not take up valuable RAM space while not in use and do not need to reside in the Desk.Accs folder. Full documentation for this module is provided in the file 'VirtDAs.Doc'. (Note that this documentation refers to some modules such as Annex and the DA Remover that do not exist. Generally the 'remove DA' function of Desktop Utilities 3.3 can be substituted for the DA Remover until the module is written.) The Menu Bar Manager and Clock Manager function more or less as a pair in this release. The Menu Bar Manager doesn't really do much without the Clock Manager; the Clock Manager won't do anything without the Menu Bar Manager. The Menu Bar Manager actually provides other modules with the ability to insert objects into the system menu bar so that they don't draw on top of each other, allows them to be moved to different locations on the menu bar by clicking on them with the Apple key held down, and allows objects to be moved off the menu bar onto the desktop. While on the desktop, objects occupy a little window which can be made into a 'windoid' by clicking the small button in the upper right hand corner. Windoids remain in front of other windows at all times; clicking in the button again turns a windoid back into an ordinary window. At present there are a few small bugs in the Menu Bar Manager, mainly to do with positioning of objects. The module in fact needs a complete rewrite, but works most of the time; occasionally it may forget the position of an object so that it fails to respond to mouse clicks. It also tends to leave ghost objects on the menu bar; these are perfectly harmless and disappear as soon as the menu bar is redrawn. Future versions of the Menu Bar Manager will fix these niggling problems and (we hope) also allow merging of two or more desktop objects into one, which can be moved around as a single unit. The Clock Manager is a small module which has been included primarily to demonstrate the capabilities of the Menu Bar Manager. It is basically a new implementation of the menu bar clock in version 3.3, where the various displays are selected from a pop-up menu rather than being cycled through by successive clicks. It is presently incomplete; the 'compact memory' and 'purge memory' buttons do not yet work, and the stopwatch currently does nothing at all. Among our first priorities when we get some spare time will be to finish this module. Other Modules ------------- Some other modules still in development for Desktop Utilities 4.0 are: Annex System Extender - like IR, allows DAs, fonts, inits, drivers and Finder Extensions to be loaded into the system at any time. Also interfaces with DA Remover and Virtual DA Manager to allow DAs to be removed or made virtual. DA Remover - allows DAs to be removed from the system, if safe to do so. Instant DA Manager - allows NDAs and CDAs to be opened in response to pre-programmed 'hot keypresses'. Wide Menu Manager - allows modules to use 'wide menus' a la version 3.3, for selecting from a very large number of items. Wide menus display up to 48 items at a time and scroll horizontally rather than vertically. Under version 4.0, we expect that wide menus will be truly hierarchical. QuickSwitch - program switcher, allows other programs to be launched from within any program, quitting the program automatically. Also contains facilities for loading documents automatically and setting the default data path. HotKeys - provides certain functions such as ejecting disks and capturing the screen, activated through the use of 'hot keypresses'. DTUFax - provides fax modem users with fax send and receive capabilities on the IIgs. BlankIt - modular screen blanker; fades screen to plain black or to cute animation when idle. CDA Interface - provides a sophisticated text-based interface for Desktop Utilities functions, including desktop emulation. P8 Enabler - enables Desktop Utilities functions (such as Virtual CDAs) under ProDOS 8, in conjunction with the CDA Interface module. Encouragement is urgently sought to give us some motivation to finish writing these modules! Programmer Notes ---------------- This release includes a library file 'DTULib' which provides a convenient interface for programmers to access the kernel functions described in the file 'Writing.Modules'. As explained in this file, assembly language programmers need only link this library with their object code and include a call to the 'DTUInit' subroutine, and all kernel functions will automatically be available exactly as described, with return parameters on the stack a la the Toolbox. DTULib also provides another set of routines, whose names are found by affixing 'P' to the end of the kernel function name. These routines include some glue code that pulls any parameters off the stack before returning, in order to be compatible with Pascal and C conventions. Word parameters are returned in the A register, while longword parameters are returned in the A and X registers with the low word in A. In the case of LoadCode which returns six bytes, the address is returned in A and X and the user ID in the global variable DTULoadedID. In each case, space for the result should still be included as a dummy parameter in the function call, as for example myList = MakeIndList ( 0, flags ) ; Use of DTULib is described more fully in the Writing.Modules guide. We have also included a header file DTU.H for the benefit of C programmers. However, neither of us has much experience writing C on the IIgs, and we do not have access to anything like a recent version of ORCA/C with which to test it. If anyone has problems using this header file with their compiler, please let us know. A Pascal interface file should be available in the near future. Revision History ---------------- (Version numbers quoted here refer to the kernel version released.) 4.0b3 Made vast improvements to error handling in kernel functions. Changed the way the DTU.Settings file is accessed, so that the file does not permanently remain open for read/write access; this has been the cause of virtually every major annoyance with 4.0b2. A small alteration to the NDA Interface module was required as a consequence of this change. 4.0b2 First public release. Bug Reports, Queries and Other Feedback --------------------------------------- If you find any bugs in Desktop Utilities 4 (beyond those mentioned above), or just have questions or comments about it, do not hesitate to contact either of the authors. The best method, if you have access to the Internet, is via EMail; our addresses are Tony Morton - amorton@ee.mu.oz.au Rob Mueller - robm@ecr.mu.oz.au We also read the comp.sys.apple2 and csa2.programmer newsgroups regularly, so a message posted in either of these groups will usually be read by us. (Rob has also known to frequent the #AppleIIgs channel on IRC; Tony has no time for such pursuits.) If you can't get on the Net, or have trouble getting in touch with us electronically for some reason, please send snail-mail to Tony at the address given above. Anyway, we hope you enjoy Desktop Utilities 4.0!