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 run >nil: 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 . 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