Introduction			Disclaimer
	Tooltypes			Multiple files
	Bugs			Contacting the author
	History			Future

Introduction

In the beginning there was Scott Ellis's Sabot. But then I became annoyed with the way I couldn't quit the program without sending it a CTRL-C or start a program using the WBStart-Handler, so I looked for other mail notification programs. There was no other program with the simplicity of Sabot, but also with the power that I needed. So I decided to write my own.

And here it is.

MailWatch requires OS 2.0 or above, and either WBStart-Handler or wbstart.library. Some sort of mail or news program would probably come in handy as well.

Reasons you should use MailWatch:

• Implemented as a commodity.
• Can watch one file or many (dynamically allocated).
• Can optionally run a program on start, and again when it stops.
  (I use this to run AmiPOP on start, and then to kill it when I quit MailWatch, using CLIExchange.)
• Can also run programs or scripts when the state of the mailfiles change.
• Can start programs via the CLI, or (if icons for the programs are found), via wbstart.library on OS 3.x systems, or WBStart-Handler on OS 2.x systems.
• Quits if run again (in good AUISG style, unlike Sabot).
• Written with Amiga E v3.2e.
• To inspire me to write more Amiga software.

[contents]

Disclaimer

If anything goes wrong -- it isn't my fault.

[contents]

Tooltypes

Here is a list of the supported tooltypes...

Tooltype	Config code	Description
MAILFILE	FILE	The name of the file that you wish to watch.
ICON_NONE ICON_OLD ICON_NEW	ICNO ICOL ICNE	The locations of the icons which the program will use to indicate the state of the mailfile. These must not contain the '.info' part of the name. The existence of these files is not checked - if one or more is not there, the appropriate state will be indicated by a non-existent AppIcon.
NAME_NONE NAME_OLD NAME_NEW	NANO NAOL NANE	The name that will be placed under the AppIcon, for each state of the file. This means that you can have the name of the AppIcon change from, for example, 'Old Mail - Boring!' to 'New - ClickMeNow!'... if you really must.
ICON_X ICON_Y	ICOX ICOY	The initial location of the AppIcon. These values are not checked - if they do not fit within the screen then the icon simply will not open. If they are not there then the Workbench will have the responsibility for placing the AppIcon.
CONFIG	n/a	The name of a configuration file specifying the options for a number of files to be watched. Use of this tooltype is mutually exclusive with the MAILFILE tooltype. See the multiple files section for further details.

There are also tooltypes that control the actions taken by the program when various events occur. If an icon exists for any of the programs referred to by these entries, the selected program will be run from the Workbench using wbstart.library (on OS 3.x +) or WBStart-Handler (on OS 2.x), otherwise it will be run from the CLI.

Tooltype	Config code	Description
ACTION_START	n/a	The name of a program/script to run when the program is started.
ACTION_STOP	n/a	The name of a program/script to run when the program is stopped (i.e. another copy is run, or Commodities Exchange is used to remove the program from memory).
ACTION_DBLCLICK	ADBL	The name of a program/script to run when the AppIcon is double-clicked.
ACTION_NONE ACTION_OLD ACTION_NEW	ANON AOLD ANEW	The name of a program/script to run when status changes to 'no mail', 'old mail' or 'new mail'.

[contents]

Multiple files

MailWatch supports the watching of multiple mailfiles through an external config file. The format of this file is fairly simple; it looks like a list of the tooltypes found in the original icon. However, the tooltype names have been replaced by four-letter codes.

The typical config file will start with a line something like this:

FILE EMail:Spool/AmiPOP.received

# these abbreviations are for NAME_NONE, NAME_OLD + NAME_NEW
NANO None
NAOL Some
NANE New Mail

# these abbreviations are for ICON_NONE, ICON_OLD + ICON_NEW
ICNO icons/none-alternate
ICOL icons/old-alternate
ICNE icons/new-alternate

# these abbreviations are for ICON_X, ICON_Y
ICOX 200
ICOY 40

# and this one is for ACTION_DOUBLECLICK
ADBL Sys:MailReader/MailReader

You may then set up two more icons (and notification sequences) like this:

FILE EMail:Spool/AnotherFile.1
ADBL Sys:Utilites/More

FILE EMail:Spool/AnotherFile.2

If any of the values are not present for a particular file, they are inherited from the ones in the MailWatch icon's tooltypes; these serve as default values for all files. This means that you do not have to set the same values for all files, thus bulking up the size of the config file; just specify those values that are different, and leave the rest to inherit the values defined in the icon tooltypes.

Basically, each FILE line starts the definition of a new AppIcon -- anything between this and the next FILE line is taken to describe the required attributes of that AppIcon (except, of course, blank lines and comments).

Have a look at the config file that comes with this archive for an in-depth explanation; it is heavily commented. This config file is only there as an example; the entries are spurious and will not work on your machine (or indeed on mine).

[contents]

Bugs

At the moment there are no known bugs in MailWatch. Mail me if you think you've found one, and want it fixed.

[contents]

Contacting the author

This program -- appropriately enough, I guess, is MailWare. Mail me at this address: [agraham@hal9000.net.au]

I would appreciate feedback, bug reports, gifts, shareware registrations to your programs, computers, CDs, video tapes... but I don't expect them.

[contents]

History

1.0 - 1.1 (6/96)

• Initial versions -- unreleased.

1.2 (7/7/96)

• Initial Aminet Release.

1.3 (14/7/96)

• Bug fix - AppIcon would fail to change sometimes [grrr].

1.4 (31/7/96)

• Bug fix - in certain conditions, wbstart.library/handler could be passed the wrong name, and the program would fail to start.

2.0ß (23/9/96) (Only released to beta-testers)

• MailWatch now supports watching multiple files (requested by Mathias Delantes).

2.0 (2/12/96)

• Finally written some decent documentation!
• After a suggestion from Mathias Delantes, any 'watched' file that is there on startup now means that MailWatch will display the 'Old' icon and not the 'New' one.

2.1 (6/12/96)

• Added the ACTION_NONE, ACTION_OLD, ACTION_NEW tooltypes/config file entries. (thanks to Francis Labrie for suggesting this)
• Changed many of the config file field names for more consistency with the tooltypes. Also changed a few of the tooltype entries as well (look at Tooltypes to see what has changed).
• Found a bug in the change introduced in v2.0 - serves me right for implementing it as a quick hack... All fixed now - would only happen when the mailfile wasn't there initially, and would then show the first change up as 'old' instead of 'new'.
• Cleaned up a few (minor) mistakes in this documentation -- mainly typos.
• Added the 'Beep' program to the distribution.
• There is now a MailWatch web page! Follow the link from my Amiga Page, and tell me what you think.

2.2 (7/12/96)

• Embarked on a much needed code cleanup. Executable is now 2K smaller (went from 31K to 29K) and the main source is now 5K smaller (went from 17K to 12K). Source layout is now much more logical.
• No imposed limit on the number of mail-files, except that MailWatch will quit with an error message if it cannot allocate enough signals (used for file notification). This is a change from previous versions, which had a hardwired maximum number of icons.
• 'Multiple files' is no longer a special case in the source code. The mechanism for allocating the AppIcons is now the same for all, whether you have 1 or 10. This means that, if you have specified a file to watch in the program's tooltypes as well as some in the config file, the one in the icon will be the first to be set up. Previously, if you used the config file, the icon's commands were used as defaults, but were not acted upon themselves. (If you prefer the old behaviour, just neglect to set MAILFILE in the program's icon).
• Oops! Forgot to copy the actions (introduced in v2.1) from the tooltypes to the other icons specified in the config file. This could be solved by specifying the action in the config file, but the default values should have been there. Fixed now, though, so I guess it's OK.

[contents]

Future

Well, I'm not sure at the moment. I've changed mail programs since YaM became freeware, and that has it's own built-in icon notification already.

I'll gladly implement any suggestions that I recieve, though...

Possible future improvements include a preferences program and the use of a window to display the status of all the files, rather than AppIcons. These would both require a lot of work. At the moment I'm too busy with other projects (and my real life ).

[contents]