LE-NAG:
     LeverEdge NAG is a program to remind you of events before you
     miss them.  Events can be scheduled to occur once or repeat
     daily,weekly,monthly or yearly.  You can be alerted of the
     event in a number of ways from a screen flash to a message
     requester.

     ** The reqtools.library is not required but is recommended. **

     Shareware, binary only.
     Author: Craig M. Lever

Disclaimer:
     I will do my best to fix bugs as they appear and/or improve the
     program but I won't be held responsible for what is outside my
     control:

     I make no warrantee to the usefulness of this program nor can I
     be held responsible for any damage caused while using it.

Distribution:
     LeverEdge NAG is copywrite 1992 by Craig Lever, All Right
     Reserved.  This program can be distributed free of charge
     electronically or via publicly distributable disk collections
     where only a reasonable price for copying and media is charged.
     Otherwise contact me for permission.  This hopefully will prevent
     older versions from showing up on magazine cover disks to my
     surprise.

     This shareware version has a couple of things added to encourage
     contributions.  First it has two internal events, one alerts you
     with a requester which can be acknowledged immediately so it will
     only come up once and another which flashes the screen with a
     DisplayBeep every half hour.  Also the AmigaDOS execute alert
     will prompt you with a requester so you can confirm or abort the
     command.
     
     If you feel inclined, send a contribution to the address below.
     I suggest $5 but feel free to send me any amount.  I'll accept US
     and Cdn currency money orders or cheques drawn from a Canadian
     bank.  I'm even interested in collecting samples of foreign
     currency so if you don't want to go through the hassle of getting
     a money order and don't mind the risks of sending currency via
     the mail then go for it.  The postal service may frown on you
     sending coins so I don't recommend that.

     If you do send $5 Cdn. or more (and it is enough to cover the cost
     of a disk and postage) I'll send you the latest version with the
     shareware notices and the requester for the AmigaDOS execute alert
     removed.  If you send more than $5 Cdn the remainder will go into
     an updates credit account to cover shipping and disk costs to send
     updates.  Just let me know (by mail or electronically) that you
     want the update and I'll send it if your "account" can cover the
     costs.  If you don't have any credit left you can always send more
     which will be added to the account.  The costs of your updates will
     be about $1.25 Cdn for a disk (or you can send me a disk to use)
     plus postage (assume its the same as the postage on the first
     registered version I send you). I still haven't figure out an
     ideal way to inform registered users of updates, if you send me an
     electronic address I can try and keep you informed that way and I
     will also redistribute the latest shareware version when enough
     important updates have been made.

Reaching me:
     I can be reached at the following mailing address:
          Craig Lever
          RR #1.
          Airdrie, Alberta, Canada.
          T4B 2A3

     I can also be reached through some of the Fido Amiga echoes
     or by Fido Netmail:
          Craig Lever @ 1:134/27  The AMUC Express   (403) 282-5224
     or AmigaNet echos and Netmail:
          Craig Lever @ 40:100/57 Urban eXpress BBS  (403) 291-9892
     and UseNet (the 1st is handled through a UseNet-Fido tosser):
          Craig.Lever@f27.n134.z1.fidonet.org
	  craig_lever%uexpress@castrov.cuc.ab.ca

Instructions:
 A)  Startup

     The program can be started from the workbench by clicking on its
     icon or from the CLI.

     The format from the CLI is:
          LE_NAG [-t #] [-l #] [-h #] [-w #] [-m #] [-s #] [-d #]
                 [-f file] [-b #] [-k #] [-q #]
               -t sets the top edge of where the window opens
               -l sets the left edge of where the window opens
               -h sets the height of the window (0 = minimum)
               -w sets the width of the window  (0 = minimum)
               -m sets the check minutes value  (explained later)
               -s turns on or off Day Schedule  (0 = off, 1 = on)
               -d display a quick summary of the events for a # of days      
               -f sets events file to use (default is ".Events")
               -b background run (0 = foreground with window,
	          otherwise no window is displayed until you
		  use the foreground/background hotkey)
               -k RawKey Code for background/forground toggle hotkey
	          (default is 0x28 for Left_Amiga+'L', 0 disables)
		  Note: RawKey Codes are not the same as ASCII
		  so you'll need a table if you wish to change this. 
               -q quit immediately (0 = no, 1 = yes)
	          nags once for the current time and closes down
               where # is an integer

     This CLI format can also be used with the Workbench with
     tooltypes and projects.  Using Info/Information from the
     Workbench menu you can save the options into the icon
     as one or more tooltype lines.  And if you start the program
     from a project icon this will automatically include a 
     -f option to set the event file to the project.  You can also
     add tooltypes to the project icon.

     If you wish to put LE-Nag in your startup sequence I recommend
     one of the following.

     If you aren't planning on using alerts which print to the
     console:
          cd <LE-Nag directory>
          run >nil: <nil: le-nag [arguments]
     If you do want console output:
          NewCLI con:280/10/360/60/LE-Nag s:Le-Nag.script
     and s:Le-Nag.script would be:
          cd <LE-Nag directory>
          le-nag [arguments]
     Or you could use tooltypes and put the program in the WBStartup
     drawer under WB2.0.

     When the program runs it will open a window on the workbench
     screen.  For those of you without the benefit of WB 2.0's window
     sizing gadgets you can use the right mouse button to minimize and
     maximize the window.
     
     Using a hotkey the window can be shut down so the program run in
     the background or reopenned to return to the foreground using a 
     hotkey.  A hotkey is a key pressed along with the Left-Amiga key.  
     The default hotkey is Left-Amiga+'L' but this can be changed if
     that combination conflicts with another program.


 B)  Features

     The window is divided into a couple of regions of related
     gadgets described below.

     - Calendar

     The top left region is called the Calendar and includes gadgets
     to change the displayed year, month, day, hour and minute.  The
     calendar is used to enter times for events as well as setting a
     time used by other functions to test how events respond at a
     given time, to view a given day's events or to move to events
     scheduled for a given day.

     - Day Schedule

     To the right of this is the Day Schedule gadget.  If this gadget
     is selected it shows what times during the calendar day have
     events scheduled as well as highlighting days on the calendar
     where events with their Calendar Color set (or the Highlight Day
     alert) occur.  Each space on the Day Schedule represents 15 
     minutes.  If there are no events occuring during that 15 minutes a
     '-' shows.  If there is one event a '*' is displayed.  If more
     than one events occur then a "#' appears.
     You may wonder why it is an On/Off gadget?  Well turning it on
     will slow down the response when changing the Calendar day, month
     or year since the events list must be rescanned.  So to avoid this
     overhead it can also be left off.
     Note:  the Day Schedule is not updated as you edit so after you
            make changes and want to see the result just turn it off
            and then back on.


     - Event Information Area

     The bottom of the window is the Event Information area where
     event are enters or viewed.

     At the top of this area is the Event string gadget
     where the event can be described with up to 80 characters.

     Below this is the Alert Type gadget and the Execute string
     gadget.  The Alert Type gadget cycles through the types of
     alerts events can generate, they include:
         Print:          Outputs to the console window.
         DisplayBeep:    Flashes the screen with DisplayBeep().
         AmigaDOS:       Executes and AmigaDOS command in C: or
                         the current directory.
                         ** Since the AmigaDOS execute is very powerful
                         and potentially dangerous, the shareware
                         version requires the reqtools.library to
                         function and puts up a requester to verify
                         the AmigaDOS command.
         Requester:      Opens a requester on the Workbench.
                         The requester is more flexible than any
                         other method of alert since it gives you
                         three choices of response:
                              Acknowledge
                              Acknowledge and Save Events file
                              Get Out of My Face
                         Where GOMF just gets rid of the requester,
                         Acknowledge adjusts the acknowledge time
                         which is discussed later.  But basically an
                         acknowledged event won't come up again until
                         after the current event time passes.     
                         (or never again if the event does not repeat)
                         ** Requires the reqtools.library **
         SPEAK:          Talks using the AmigaDOS SPEAK: device which
                         has to be installed with MOUNT SPEAK:
                         SPEAK: requires the translator.library
                         and narrator.device in libs: and devs:
                         The AmigaDOS 2.0 & 1.3 manuals both describe
                         the options for changing the qualities of
                         the voice. (See speak-handler)          
                         And example on how to use options would be:
                         " \nopt/p300/r\Hello.\nopt/s100/p100/n\nBye."
                         Which would say "hello" with a high pitch
                         robotic voice and then "bye" in a slower,
                         lower and less robotic (normal) voice.
                         ** SPEAK: does not return an error
                         message if it can't open its sound channel.
                         If it can't the output will just disappears.
         Play Sound:     Plays up to 4 IFF sound file simultaneously.
                         If an voice is unavailable the sound    
                         will not be played.  Also only the first
                         128K (131072 bytes) will be played if the
                         sample is longer.
         Highlight Day:  This is a special event that changes the
                         color of the day on the calendar.  It is
                         special in two ways.  First, it is only in
                         effect if the Day Schedule gadget is
                         selected.  And second, it is not affected by
                         the acknowledge time.
			 ** days can also be highlighted now by 
			 just setting the Calendar Color gadget.

     The Execute string (up to 80 characters long) is used to provide
     information to be used in the alert, for example, what is printed
     if Print is the Execute type, what is executed if the Execute
     type is AmigaDOS.
     
     There are some escape sequences supported when this string is
     expanded, these are:
          \t - expanded to a tab
          \n - expanded to a line feed (and carriage return)
          \r - expanded to a carriage return
          \\ - used to indicate a single \
     \n and \r can be used to seperate commands for the AmigaDOS
     alert and to seperate IFF sound files for the Play Sound alert.

     In addition to the escape sequences there are some conversion
     sequences which allow you to include information about the event
     and the time when the alert occurred, these are:
          %eX or %EX for info on the event time
          %cX or %CX for info on the current time
          %aX or %AX for info on the last acknowledge time
          %lY or %LY for info on the length
          %dY or %DY for info on the diff. between event & current time
          %s  or %S  for the event text
          %%  used to indicate a single %

          and X can be the folowing:
               c - century integer     ie 19
               C - century text        ie Nineteen
               y - year integer        ie 92
               Y - year text           ie NinetyTwo
               m - month integer       ie 2
               M - month text          ie February
               w - weekday             ie 4        (Sunday is 0)
               W - weekday text        ie Thursday
               d - day integer         ie 4
               D - day text            ie Fourth
               h - 12 hour integer     ie 5
               H - 12 hour text        ie Five
               i - 24 hour integer     ie 17
               I - 24 hour text        ie Seventeen
               p or P - AM/PM phase    ie PM
               n - minutes integer     ie 15
               N - minutes text        ie Fifteen
               s or S - seconds        ie 4030030303
          and Y can be the folowing:
               d - days integer        ie 493
               D - days text           ie NintyThree (text shows only 2 digits)
               h - hours integer       ie 6
               H - hours text          ie Six
               n - minutes integer     ie 15
               N - minutes text        ie Fifteen
               s or S - seconds        ie 4030030303

          If X or Y isn't in the list then the default is to print the
          seconds count.

          The % conversions can even use formatting information like
          field sizing and left right justification which C programmers
          are probably familiar with.  For those unfamiliar with these,
          here  is the format:
               %[flags][width][.precision]type

               where:
                    type is the sequences described above
                    flags can be -,+,# or <space>.  The most useful is
                         '-' which will left justified the number or text.
                    width is an integer specifying the minimum width
                         a leading zero causes numbers to be printed
                         with leading zeroes, ie 02
                    precision is an integer.  For text it specifies
                         the maximum # of character to display.
                         For numbers it works the same as width with
                         a leading zero.

     If the Execute string is empty then the Event string will be
     used in its place.

     Below the execute gadgets are a number of time gadgets which
     are set by selecting the time gadget and moving the Calendar
     gadgets to change its contents.
     Once the value is correct the gadget can be clicked again to
     unselect it or it is also unselected if another time gadget is
     selected.  The changes can also be cancelled with the Cancel
     gadget if the time gadget is still selected.
     There are two different types of time gadgets, some are absolute
     time gadgets which are tied to a date and some are relative time
     gadgets which measure an interval of time of some length.
     Here is a description of what each time gadget means:
          Event Time     - start time of the event or start time of
                           the first event if it repeats.  Absolute.
          Length         - length of the event. Relative.  It is set
                           by moving the calendar to the time the
                           first event ends.
          Advance Notice - period of time before the event occurs
                           when it will generate alerts.  Relative.
          Interval       - controls how many times the alert will
                           occur between the advance notice and the
                           event time.  It sets how many minutes
                           are between alerts.  Relative.
          Acknowledge    - is the time this event was acknowledged.
                           If the next event time after the
                           acknowledge time is the same as the next
                           event time when the program is nagging
                           then no alert is generated.  Absolute.

     There is one more gadget in the area called Group.  This is a 4
     digit ASCII code you can assign to an event.  This allows you to
     link serval related events together.  If one gadget is
     acknowledged then all of the others will also have their
     acknowledge time updated.  For example perhaps you can watch the
     same TV program at 2 different times, if you see it the first
     time and acknowledge then you won't be alerted of the other time
     it is on.
     There is one exception, if group code is blank then these events
     are treated as ungrouped and acknowledging them does not effect
     all other gadgets that have a blank group.
     To the right of the time gadgets are the flags used to determine
     how the event will occur or repeat.
     Yearly Monthly and Weekly are used with the Repeat gadget value
     to determine when to event can occur if it repeats.
     The repeat gadget indicates the interval of weeks, months or
     years between events.  If Weekly is set it is the number of
     weeks, if Monthly is set (and Weekly isn't) then it is the number
     of months, if Yearly is set (and neither Weekly or Monthly are)
     then is is the number of years.
     If Weekly is set then the Monthly and Yearly gadgets indicate
     if the event can occur on a month or year not equal to that of
     the original event time.
     Similarly if Weekly isn't set and Monthly is then Yearly
     indicates if the repeating event can occur in months outside the
     year of the original event time.
     This approach allows you to set up events which repeat but stop
     when the month or year ends.

     Below the Yearly gadget is a gadget called D= and one for each
     day of the week.  The D= stands for Day Equals and means the
     event time must be one of the days set in the weekday gadgets.
     The most obvious use of this is to produce an event for Friday
     the 13th if your the superstitious type (or Thursday the 12th if
     your worried about Friday the 13th viri)
     If the Day Equals gadget is not set and some of the weekday ones
     are then the whole week after the event time is checked and any
     days where the weekday gadgets are set are treated as events.
     This has two uses for me.  First to make events that repeat daily
     by making events that repeat weekly and setting all the weekday
     gadgets on.  And second, to make events that occur on a particular
     day of the week in a particular week of every month, like my AMUC
     User's group meeting on the 3rd Wed of every month.  To set it up
     I just picked a month for the event to start, select the 15th of
     that month (the 3rd week can start no earlier than the 15th) and
     set the repeat count to 1, and turned on Yearly, Monthly. Weekly
     and Wednesday.
     There are three other flag gadgets.  The Color gadget is for
     setting the color of the days the event occurs on the calendar.
     The color can be a value between 1 and 15, zero is ignored. The
     other two gadgets are used to automate some options which can be
     performed after the alert occurs.  The first is Auto Ack or
     Auto Acknowledge which causes an acknowledge to occur after the
     event is processed.  It is useful if your not using the Requester
     alert where you can manually acknowledge.  What acknowledging does
     is prevent the event from occurring again until the time is past
     the event time which already generated an alert.  The other is
     AutoSave which saves the Events file after the alert occurs.  It
     is most useful when combined with Auto Ack so the change in the 
     acknowledge time is stored.
     
     Note the above description of acknowledging is a little week so
     here is a little more correct (but confusing) description.
     If the event does merit an alert the next thing that is done
     is to check to see if an alert would occur at the same event time
     if the current time was the acknowledge time.  So if time flows
     left to right and A is the acknowledge time for a repeating event
     (shown as the number 1-9) only the event times greatter than or
     equal to 5 will generate alerts in the folowing example.
     
          1     2     3   A 4     5     6     7     8     9...
     
     - System Time

     In the upper right of the window there is a gadget displaying the
     current time.  It can be set the same as any time gadget by
     selecting it and changing the calendar and then unselecting it.

     - Check Minutes

     Below System Time is the Check Minutes gadget.  This determines
     how often the program checks to see if any events occur.  Note
     this is not quite like the interval time gadget as it effects all
     events.  With larger Check Minutes values there is also a bit
     greater risk of events being missed if something happens to the
     clock but it also reduces how often the program need the CPU.

     - Control Panel

     Below Check Minutes is a group of gadgets I call the Control Panel.

     Next and Previous move from one event to the next.

     Delete removes the currently displayed event.
     Note:  Currently deleted events are NOT recoverable.

     The New gadget is for creating a new blank event.

     Cancel has two functions.  If a time gadget is selected it undoes
     the changes you have made to that time gadget. Otherwise it swaps
     the current event's information with an undo event.  This undo
     event is initially set to the information in the event when you
     first moved to it with Next/Previous.  If it is a new event then
     it equals the contents of the current event just before you
     create the new event. This is useful for making events which
     contain much of the same information, just enter the similar 
     information and hit New then Cancel and you have a second copy.

     Next to Cancel is Save which saves the events to file (".Events"
     in the current directory is the default).  As an additional note
     LE-NAG files can be joined together with JOIN (or TYPE) as .Event
     files are just a list of Events without any header or footer
     information.

     The next gadget is the Edit Mode gadget which effects the
     functions of Next/Previous and to a lesser extent, Delete and
     New.  It has three settings:
          Edit All   - Next and Previous simply move from the
                       current event to one immediately adjacent to it.
          Edit Day   - Next and Previous try to move to the
                       next/previous event which occurs on the day
                       shown in the Calendar area.  Delete will also
                       try to move to an event occurring on the
                       Calendar day but if it can't it will move to an
                       adjacent event.
          Edit Group - Next/Previous will only move to an event which
                       has the same group as the current event.  Delete
                       will try the same but if one doesn't exist it
                       will go to an adjacent Event.  New will also put
                       the Group of the current event into the new
                       event's Group automatically.

     The last gadget is Goto and it is used with time gadgets to move
     the Calendar to the time values shown in them.  First Goto is
     selected and then a time gadget is selected.  Goto is cancelled
     if Goto,Cancel or something other than a time gadget is selected.
     Selecting absolute time gadgets after Goto will move to the time
     shown in them whereas relative time gadgets will move the Calendar
     to a position relative to the event time.  Interval, and Advance
     Notice move to before the event time and Length moves to after the
     event time, ie at the event end time.

     Thanks you for taking the time to look at these rather long docs.
     I hope it helps more than it hurts as you try to understand
     LE-NAG.

     This program has been tested with an 6M A3000 under 1.3 and 2.0,
     a 1M A500 under 1.3 and a 256K A1000 under 1.3 (WB loaded).

Many Thanks go to:
     Bryce McCormick, my alpha/beta/gamma tester, who directly and
     indirectly inspired changes to the program and made it more
     difficult for me to shelf for any great length of time.

     Stephen Vermuelen, what can I say, if there is a Amiga
     programming question that he doesn't know the answer to I haven't
     had to ask it yet.

     Bob Leivian who ported the calendar program found on Fish 34.
     It served its purpose as this program was being written and was a
     good model for this program.

     Anders Bjerin who's Amiga C Manual continues to be the source of
     the underlying interface monitoring code in anything I start.
     Thanks also for the EasySound IFF 8SVX player.

     Timm Martin who's timer device code cut down considerably the
     time necessary to get this program functional even if I did have
     to work the code over a bit.

     Leo Schwab who's process spawning code made this program
     multitask internally where it needed it most.

     Nico Francois who's ReqTools library made nagging with good 
     looking requesters only a function call away.

     And ofcourse Fred Fish for providing a reliable first source for
     the PD programs and the source code of programmers like those
     mentioned above.

ReqTools is Copyright (c) Nico Francois
