R A I N M I N D E R

Rainminder uses a very simple script-language for defining the moment when a certain message will be shown. The message can have different fonts and colors and can even display the contents of an ASCII-file. The message window grows/shrinks according to the amount of displayed text.

Rainminder also has a build-in fortunecookie program to display random fortunes/quotes/jokes. Note that to use this feature you need a fortune-file which can be found around the Web (i.e. from a linux distribution).

Rainminder can be used as wharf or as plugin module. When used as wharf it functions as lstime-compatible clock so you can easily replace your old clock with this one.

To install just copy the Rainminder.dll to your Litestep directory (eg. C:\Litestep\), copy the images to the same folder where you keep all the other Litestep images (eg. C:\Litestep\Images), edit your Step.rc and create Rainminder.cfg. Check Step.rc and Usage for more info.

Rainminder uses a very simple script language to define events and results. The format is:

IF Evaluation functions THEN Action Functions ENDIF.

So every event must start with IF-word and end with ENDIF. Evaluation functions are evaluated once per second and if TRUE the action functions will be executed. You may use normal boolean operators (AND & OR) between the Evaluation functions. You may also group the functions with parenthesis.

Some of the Evaluation functions need also a compare value (those that doesn't return a boolean value). As a compare operator you may use these:

• = (equal)
• != (unequal)
• > (greater)
• < (less)
• >= (greater or equal)
• <= (less or equal)

Check the included configuration file (Rainminder.cfg) for examples.

Now few things you should be aware of when playing with this piece of software:

• The parser doesn't notice all kind of syntax errors. It can handle some of the most basic ones, but doesn't care about things like correct number of parameters or equal amount of opening and closing parenthesis. So if the event is not working as it should (i.e. the message is not shown when it should) the reason might be a syntax error in configuration file which the parser missed.
• You can use #-char as an end of line comment.
• Rainminder may be disabled/enabled by pressing the right mouse button on the wharf.
• The configuration file is parsed only when Rainminder is ran the first time so remember to Recycle after modifications to Rainminder.cfg file.
• You can get rid of the message window simply by clicking it with left mouse button.

Evaluation functions

Light red parameters are optional.

File([FILENAME])
Parameters: FILENAME, name and path of the the compared file.
Return: TRUE if the file exists.

Year()
Parameters: -
Return: Current year in four digits (eg. 1999).

Month()
Parameters: -
Return: The number of current month (eg. 7). Values from 1 to 12.

Day()
Parameters: -
Return: The number of current day (eg. 10). Values from 1 to 31.

Weekday()
Parameters: -
Return: The number of current weekday (eg. 3). Values from 1 to 7, where 1 is Sunday and 7 is Saturday.

Hour()
Parameters: -
Return: Current hour in 24H format (eg. 15). Values from 0 to 23.

Min()
Parameters: -
Return: Current minutes (eg. 31). Values from 0 to 59.

Sec()
Parameters: -
Return: Current seconds (eg. 59). Values from 0 to 59.

Date()
Parameters: -
Return: Current date. The format is DD-MM-YYYY. You must always use 2 digits with the day and the month and 4 with the year (i.e. Date()=02-04-1999).

Time()
Parameters: -
Return: Current time. The format is HH:MM (NOTE: no seconds!). You must always use 2 digits with the hours and the mins (i.e. Time()=09:05)

FirstRun()
Parameters: -
Return: TRUE if Rainminder is ran first time.

Recycle()
Parameters: -
Return: TRUE if Rainminder is ran another time (like when Litestep is recycled).

Click()
Parameters: -
Return: TRUE if left mouse button was pressed on wharf since last evaluation.

BangActivate([ID])
Parameters: ID, if given only bangs with the same ID are evaluated to TRUE.
Return: TRUE if !ActivateRainminder bang command was the cause of the evaluation.

QuickAlarm()
Parameters: -
Return: TRUE when quickalarm goes off.

AmpSongChanged()
Parameters: -
Return: TRUE when Winamp's currently playing song has changed. The changing is determined by the position of the song in the playlist. So if the position remains the same when song changes (i.e. you only have one song in the playlist), tha change won't be noticed. 

Action functions

Note that the font, color and alignment setting apply the whole line, so you can't use for example different colors in the same line. The last function for the current line is used even if it is located after the text.

Light red parameters are optional.

Text([STRING])
Parameters: STRING, string that will be displayed in message window.
Notes: Use quotes (") around the string. A line of text can be composed from many Text()-functions.

VariableText([STRING])
Parameters: STRING, string that will be displayed in message window.
Notes: Like Text, but can include environment variables, which are expanded.

NewLine()
Parameters: -
Notes: Creates a new message line.

Date([FORMATSTRING])
Parameters: FORMATSTRING, optional string which can be used to control the output. If missing a date representation for current locale is used.
Notes: String can include following format codes:

• %a Abbreviated weekday name
• %A Full weekday name
• %b Abbreviated month name
• %B Full month name
• %c Date and time representation appropriate for locale
• %d Day of month as decimal number (01 – 31)
• %H Hour in 24-hour format (00 – 23)
• %I Hour in 12-hour format (01 – 12)
• %j Day of year as decimal number (001 – 366)
• %m Month as decimal number (01 – 12)
• %M Minute as decimal number (00 – 59)
• %p Current locale’s A.M./P.M. indicator for 12-hour clock
• %S Second as decimal number (00 – 59)
• %U Week of year as decimal number, with Sunday as first day of week (00 – 53)
• %w Weekday as decimal number (0 – 6; Sunday is 0)
• %W Week of year as decimal number, with Monday as first day of week (00 – 53)
• %x Date representation for current locale
• %X Time representation for current locale
• %y Year without century, as decimal number (00 – 99)
• %Y Year with century, as decimal number
• %z, %Z Time-zone name or abbreviation; no characters if time zone is unknown
• %% Percent sign

Time([FORMATSTRING])
Parameters: FORMATSTRING, optional string which can be used to control the output. If missing a date representation for current locale is used.
Notes: Check Date() for the format codes.

Font([TYPEFACE], [HEIGHT], [STYLE])
Parameters: TYPEFACE, name of the font. HEIGHT, height of the font. STYLE, optionally BOLD, ITALIC or BOLDITALIC.

Color([R], [G], [B])
Parameters: R, value of red component (0-255). G, value of green component (0-255). B, value of blue component (0-255).

Align(CENTER|LEFT|RIGHT)
Parameters: Text alignment

PrintFile([FILENAME])
Parameters: FILENAME, name of the ASCII-file that will be displayed in the message window.

Fortune([FILENAME])
Parameters: FILENAME, name of the Fortune-file that will be used to fetch a random fortune and displayed in the message window. Fortune files are normal ASCII-files with %-char separating the fortunes.

Execute([FILENAME])
Parameters: FILENAME, name of the file that will be executed.

PlaySound([FILENAME])
Parameters: FILENAME, name of the WAV-file that will be played.

ShowDuration([MINDURATION], [TEXTLENGTHFACTOR])
Parameters: MINDURATION, minimum amount of seconds.that the message window will be shown. TEXTLENGTHFACTOR, amount of milliseconds per character that will be added to the showduration. These will override the step.rc settings.

Bang([BANGCOMMAND], [ARGS])
Parameters: BANGCOMMAND, a bang command that will be executed. ARGS, optional arguments for the command.

AmpText()
Parameters: -
Notes: Displays Winamp's currently playing song. The text is taken from the Winamp-windows title and not from the ID3Tag!

QuickAlarmText()
Parameters: -
Notes: Displays the QuickAlarm's custom text that was set in the QuickAlarm-dialog.

Theme([THEMENAME])
Parameters: THEMENAME, name of the theme used in the MessageWindow. If no parameters are given the default theme is used. Check the Themes-section for more info about themes.

Position([X], [Y], [HOLD])
Parameters: X, new X-position of the MessageWindow. Y,  new X-position of the MessageWindow. HOLD, Corner that stays put when window is resized. This is similar to RMHold and uses the same values. The values given in step.rc are overwritten with this Action function.

BangText()
Parameters: -
Notes: Displays the !ActivateRainminder's TEXT if it was given.

If you want to put Rainminder in your wharfbar do not use the LoadModule to load the plugin but define a wharf for it (i.e. *Wharf "Rainminder" RainminderWharf.bmp @C:\LITESTEP\Rainminder.dll). If you are using the lstime.dll as your default clockwharf the easiest way is just to replace it with Rainminder.dll.

Important note: If you use Rainminder as a wharf and you don't have lstime as your clock you still need to set the step.rc commands that the lstime needs as Rainminder needs them too. Check Litestep documentation for more info about lstime.

RMPixmapPath [PATH]
Path where the images are and where the theme-forlders are relative to. If missing step.rc's PixmapPath is used instead.

RMTopLeftPic [FILENAME]
Name of the message window's topleft corner bitmap. Default is "RMTopLeftPic.bmp".

RMTopPic [FILENAME]
Name of the message window's top bitmap. Bitmap is tiled if window is too big. Default is "RMTopPic.bmp".

RMTopRightPic [FILENAME]
Name of the message window's topright corner bitmap. Default is "RMTopRightPic.bmp".

RMLeftPic [FILENAME]
Name of the message window's left bitmap. Bitmap is tiled if window is too big. Default is "RMLeftPic.bmp".

RMRightPic [FILENAME]
Name of the message window's right bitmap. Bitmap is tiled if window is too big. Default is "RMRightPic.bmp".

RMBottomLeftPic [FILENAME]]
Name of the message window's bottomleft corner bitmap. Default is "RMBottomLeftPic.bmp".

RMBottomPic [FILENAME]
Name of the message window's bottom bitmap. Bitmap is tiled if window is too big. Default is "RMBottomPic.bmp".

RMBottomRightPic [FILENAME]
Name of the message window's bottomright corner bitmap. Default is "RMBottomRightPic.bmp".

RMCenterPic [FILENAME]
Name of the message window's center bitmap. Bitmap is tiled if window is too big. Default is "RMCenterPic.bmp".

RMPositionX [INTEGER]
Messagewindow's X-coordinate. You can use negative values to define the position that is relative to right edge of the screen. Values which end with '%'-char are interpret as portition of the screensize (i.e. "RMPositionX 50%" would center the window).  Default is 0.

RMPositionY [INTEGER]
Messagewindow's Y-coordinate. Works similarily as X-coordinate. Default is 0.

RMShowDuration [INTEGER]
Minimum time in seconds that the message window is visible. Can be longer if RMTextLengthFactor is also defined. Default is 60.

RMHold TOPLEFT|TOPRIGHT|BOTTOMLEFT|BOTTOMRIGHT|CENTER
Corner that stays put when window is resized. This is also the corner that RMPositionX and RMPositionY define. Default is TOPLEFT.

RMConfig [FILENAME]
Name of the Rainminder config file. Use full path.

RMTextLengthFactor [INTEGER]
Time in milliseconds that will be multiplied with the number of characters in text. The result will be added to RMShowDuration time and that will define how long the window will be shown. This way the show duration can be relative to amount of displayed text. Useful with fortunes.

RMTheme [THEMENAME]
Name of the default theme. Check Themes-section for more info.

Example additions to step.rc:

*Wharf "Rainminder" RMWharf.bmp @C:\LITESTEP\Rainminder.dll
RMPixmapPath "C:\Litestep\Rainminder\"
RMConfig "C:\Litestep\Rainminder\Rainminder.cfg"
RMPositionX 50%
RMPositionY 50%
RMShowDuration 40
RMTextLengthFactor 10
RMHold CENTER
RMTheme "RMDefault"

• !EnableRainminder Enables the Rainminder
• !DisableRainminder Disables the Rainminder
• !ToggleRainminder Enables/Disables the Rainminder
• !ActivateRainminder [ID] [TEXT] Activates evaluation (use with BangActivate()). The ID corresponds to the ID in BangActivate() and the TEXT can be shown with BangText()-function.
• !RainminderQuickAlarm [MINS] Creates a quick reminder that will be shown after MINS has been passed. If no args are given a dialog will be opened where you can set time. QuickAlarm() evaluation function will evaluate to true when QuickAlarm sets off.

Different themes can be used with each message. You can define the used theme with Theme([THEMENAME])-Action function. The THEMENAME-parameter works the same way as with RMTheme.

There is a seperate bitmap for each corner, edge and for the center. The edge and the center bitmaps are tiled if the area of the window is larger than the bitmap. The names of the bitmap are defined with RMTopLeftPic, RMTopPic, ... step.rc commands. All themes must have all the nine images.

The sizes of the images may vary. Textarea is calculated from the edge bitmaps (left, right, top and bottom) so that the width of the left and right bitmap determine the horizontal position of the textarea and height of the top and bottom bitmap determine the vertical position.

The message window also has a minimum size which is determined by the corner bitmaps. The minimum size is reached when only the corner bitmaps are visible. The window won't shrink smaller than the minimum even if there is not enough text to fill the whole area.

You may use the traditional pink color (255,0,255) for transparency.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Please note that this software is still in beta-state and is most likely to have defects and may not work as it should. Use it at your own risk. The author is not responsible for any damage, direct or indirect, that this software may cause.

http://www.iki.fi/~rainy

You may also send comments and bug-reports to author:

rainy@iki.fi

Please put the name of the product (i.e. RAINMINDER) in the subject-field of the mail. It may be useful if you write the version of the product also.

• GUI (If I have some spare time...)
• More Action Functions: ShowBitmap(), ...
• More Evaluation Functions: RegKey(), ...
• (Un)Installer

• Fixed respawning QuickAlarm-bug.
• Now uses initModuleEx for compability with the newer builds.
• Bang(), Execute(), PlaySound(), PrintFile() and Fortune() supports now environment variables.
• !ActivateRainminder-Bang can now have arguments.
• Changed BangActivate() to take one optional parameter.
• Added BangText() to show the text from a !ActivateRainminder-Bang.
• Added VariableText() to show text with environment variables.
• \n inside a text is interpreted as newline
• Added DigiColonWidth for the clock to set the width of the colon between hours & mins
• Fixed a memory-leak when quitting (or recycling)
• FirstRun() now evaluates to true only when Litestep is started and not when it is recycled. You can use Recycle() for recycle-time messages.

18 DECEMBER 1999 (Version 0.5 ß)

• Fixed the fortune-randomizer. No more empty fortunes (I hope ;)
• Added Position([X], [Y], [HOLD]) Action function to set the window position.
• Positions can be defined with %-char.
• Added Themes. Use Theme([ThemeName]) to change MessageWindows graphics and RMTheme in step.rc to set the default theme.
• Removed the limit of one QuickAlarm at a time.
• QuickAlarm-dialog now has a textbox for custom messages. Use QuickAlarmText() to display it.
• Added some basic Winamp support. AmpSongChanged() evaluation function can be used to show messages when song changes. AmpText() prints the currently playing song.

10 DECEMBER 1999 (Version 0.4 ß)

• Fixed a bug with redrawing the clock's background.
• The window position can be set with negative coordinates.
• Added support for GetRevID-message, so Rainminder shows in the LS !About dialog.
• Now uses static linking to MFC. A bit larger executable but reduces problems with MFC42.DLL.

23 SEPTEMBER 1999 (Version 0.3 ß)

• Added Bang([BangCommand], [Args]) action function which executes a LS bang command.
• Added Quickalarms (used with !RainminderQuickAlarm [MINS] and QuickAlarm()).
• Fixed a bug in Date() evaluation
• Fixed a bug with the wharf clock transparency
• Added RMPixmapPath step.rc-command

9 SEPTEMBER 1999 (Version 0.2 ß)

• Changed the message window to be opened as non-active, so that it won't popup over screensaver & games.
• If there wouldn't be any text in the message window it is not displayed.
• Added PlaySound([Filename]) and Execute([Filename]) Action Functions.
• Doesn't have to be a wharf anymore. Can be loaded with LoadModule as well.
• Added couple of Bang-commands: !EnableRainminder, !DisableRainminder, !ToggleRainminder and !ActivateRainminder.
• Added RMTextLengthFactor step.rc-command.
• Added ShowDuration([MinDuration], [TextFactor]) Action function.

31 JULY 1999 (Version 0.1 ß)

• Initial Betarelease