Script Info

Name: Remind Me
Author: Five Speed Software, Inc.
Description:
This script prompts the user for a number of minutes, and then for a short reminder string. Then it sets a system alarm and reminds the user after the specified number of minutes. This script uses Dash Board's built-in DashBoardDoDialog() method to prompt the user. (It also probably shows that we could improve Dash Board by allowing a dialog with two entry fields, so that two dialogs would not be necessary.)
Last Modified: Tuesday, March 2, 1999
Download: The example scripts are now included as part of every Dash Board download.

This example script is copyright © 1998, 1999 by the author listed above, and may be freely used, modified, and distributed, provided that it is distributed free of charge.

Script Code

//NOTE: See detailed description below for a
//line-by-line explanation

local numMinutes :=
:DashBoardDoDialog('integer, "In how many minutes should I remind you?", "Remind Me", "15", NIL, NIL);

if numMinutes = NIL then return;

local remindText :=
:DashBoardDoDialog('string,"Enter the reminder text","Remind Me", "Don't forget!", NIL,NIL);

if remindText = NIL then return;

local alarmKey := TimeInSeconds() & ":RM:FiveSpeed";


AddAlarm(alarmKey, time() + numMinutes, ["Remind Me Script Says:", remindText], NIL, NIL);

Discussion

First, we set the variable "numMinutes" to the value entered by the user. This is the number of minutes later that we will set the alarm for. To get the number from the user, we use Dash Board's built in DashBoardDoDialog() method. The six parameters to this method control what kind of value the dialog should return (e.g., an integer number, a text string, etc...) and how the dialog looks (the title, the prompt message, etc.). Since we specify 'integer as the type we want, the dialog will not allow the user to enter a non-numeric value. See the Dash Board Scripter's Guide for more information.

local numMinutes :=
:DashBoardDoDialog('integer, "In how many minutes should I remind you?", "Remind Me", "15", NIL, NIL);

Next, after the user has dismissed the dialog, we make sure that the user did not tap the cancel button. If the user taps the cancel button, the DashBoardDoDialog() method will return NIL. So we check if the numMinutes variable is equal to NIL. If it is, we return immediately. (The return statement stops the execution of the script.)

if numMinutes = NIL then return;

If we ware still going after that, it means that the user has entered a number. Next, we want to get the text for the reminder. Again, we use the DashBoardDoDialog() method to ask the user to enter some reminder text.

local remindText :=
:DashBoardDoDialog('string,"Enter the reminder text","Remind Me", "Don't forget!", NIL,NIL);

And once again, if the user has canceled, we return immediately to stop the script.

if remindText = NIL then return;

If we are still going, it means that the user has entered a number of minutes, and some reminder text. So, it's time to set the alarm. We will use the standard Newton OS global function AddAlarm() to add out alarm to the system alarm registry. To use AddAlarm(), we must create a unique ID for this alarm. We know from reading the Newton Programmer's Reference that the ID should be a text string, no more than 24 characters, and should include our unique developer's signature. Since Five Speed Software's unique developer signature is "FiveSpeed" our unique ID will end with that. We will use a combination of the time in seconds, the text "RM" for this script, and out unique developer's signature. Using the TimeInSeconds() function allows us to ensure that if the user uses our Remind Me script more than once, each alarm has a unique ID. The following code will set the "alarmKey" variable to something like "173902015:RM:FiveSpeed", depending on the time.

local alarmKey := TimeInSeconds() & ":RM:FiveSpeed";

Finally, we set the alarm. We use the AddAlarm() global function, which is documented in the Newton Programmer's Reference. The first parameter is the unique ID of our alarm, which we set above. The second parameter is the time the alarm should go off. We use the global function Time() to get the current time in minutes, then we add numMinutes, which is the number of minutes the user entered in the dialog. This sets the alarm for the current time plus the number of minutes the user has entered, The third parameter is an array of two text strings. The first string is the title of the alarm slip, and the second is the actual text of the message. We use the remindText variable, which is the text that the user entered in the second dialog.

AddAlarm(alarmKey, time() + numMinutes, ["Remind Me Script Says:", remindText], NIL, NIL);

Now we are done! The alarm should be set to remind the user at the appropriate time.

 


Contents copyright © 1997-2004, Five Speed Software, Inc.