💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Utilities › DTUtils4.txt captured on 2023-01-29 at 04:56:06.

View Raw

More Information

-=-=-=-=-=-=-




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!