LuaCalendar by Smurfier

Introduction

LuaCalendar is a Calendar skin designed for use with the Rainmeter program. By using the power of the Lua scripting language, the skin loads instantly and is extremely flexible. The skin itself is designed to use Style Sheets, allowing for complete customization of the look and feel of the skin while retaining all of the functionality of the script.

One of the major features of the skin is the ability to display events that are defined by the user. This was a long requested feature of the existing calendar skins. All of the easily configured settings and features are listed below.

Release Notes


Download from MediaFire.
Version 6.0
10/01/2016
  • Added the Options skin.
  • Added the ability to define Event File Variables.
  • Added the ability to change the string case of Event names.
  • Added the Skip option to repeating events.
  • Added the Time-stamp option to Event files.
  • Formulas are now allowed in all Event File number options.
  • Variables can now be used in all Event File options.
  • Added Custom repeating events.
  • Fixed an issue with Week range where current day style was not being applied.
  • Fixed an issue where custom month names would break the calendar.
See more changes

Calendar Settings

All settings can be found in the Settings.inc file or through the Options skin.

Style
Set to the name of a style sheet found in the Styles folder.
More information below.
StartOnMonday0
Set to 1 to have the week start on Monday.
DayLabelsS|M|T|W|T|F|S
A pipe delimited list of custom text for Weekday labels.

Example: Sun|Mon|Tue|Wed|Thu|Fri|Sat

Note: Do not adjust for StartOnMonday. This is done automatically.
MonthLabels1|2|3|4|5|6|7|8|9|10|11|12
A pipe delimited list of custom text for Month labels.

Example: Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec
LabelText{$MName}, {$Year}
Allows for personalized formatting of the calendar title. A list of available variables can be found here.

Example: LabelText={$MName} of {$Year}
LeadingZeroes0
Set to 1 to add a leading zero to any number below 10.
HideLastWeek0
Set to 1 to hide week 6 if not included in the current month.
EventFile
A pipe delimited list of paths to Event files formatted as described below. These paths are relative to the skin folder unless a full path is specified.
NextFormat{$day}: {$desc}
The formatting used for the NextEvent skin variable. Use {$day} to display the day number and {$desc} for the comma delimited list of events.
RangeMonth
Can be set to either Month or Week to display a whole month or just the current week. Setting to Week disables the ability to move through the calendar.

Note: It is important to inherit this setting from the style. The style must be designed for the either range.
ShowMoonPhases1
When set to 1, the Moon Phases of Full and New will be shown for the current month. The date for these phases may be off by a day.
MoonColor""
The RGB or HEX color used for displayed Moon Phases. When set to "" the color used is defined by the style sheet.
ShowEvents1
When set to 1, the Events from all Event Files and Moon Phases will be shown on the calendar.
DisableScroll1
When set to 1 the calendar's mouse scroll actions are disabled.

Skin Actions

LuaCalendar has the ability to show different months while using the Month range. While some styles may have visual elements for this, not all do. This is where the Skin Actions come in.

Scroll Actions

When hoving over the skin, scroll using the scrollwheel on the mouse up to move back and down to move forward. This action is based on the update speed of the skin. It groups multiple scrolls during on update into a single scroll action.

Context Menu Actions

Under the submenu named "Custom skin actions" in the context menu several options have been made available. These options include editing of the calendar options, moving through the months, and returning to the current month.

Using Event Files

To use Event Files set EventFile to the path of a text file on the calendar measure. Multiple files can be aggregated together using a pipe delimiter and all files must be in the same folder which is the first item in the list.

Examples

There is no limit to the number of Events used. Event files must be formatted in the following XML style format, indents not required. The complete contents of the Event file must be enclosed in <EventFile></EventFile> tags.

<EventFile Title="Holidays" Repeat="Year">
<Variable Name="Variable Name" Case="Variable Value"/>
<Event Month="1" Day="10">Event Description</Event>
<Set Month="2">
<Event Day="12">Some Other Event<Event/>
</Set>
<!--This is a comment.-->
</EventFile>

Event Options

The following settings may be set on each EventFile, Event, or Set tag and are overridden by those nested within them.

Title*
The title of the event which is displayed after the event.
Month
The month in which the event occurs.
Day
The day on which the event occurs.

Example: <Event Month="11" Day="({$FirstMon}+1)*(({$Year}%2)=0)" Repeat="Year">Election Day</Event>
Election day is defined as the Tuesday following the First Monday in November every even numbered Year.
Year*
The Year the event occurs on.
TimeStamp*
A Lua Timestamp representing a specific date. This option overrides any provided Day, Month, or Year options.
Color*
The RGB or HEX color to be used for the specified event(s). Formulas can be used in this setting but must be enclosed in parenthesis.

Example: <Event Month="1" Day="4" Year="1986" Color="FF0000FF" Repeat="Year">Smurfier's BDay</Event>
Repeat*
When used, this option allows an event to repeat using a specified pattern as listed below.
  • Month: The event repeats on the same day each month. If a multiplier is used a full date must be specified, else only a day is necessary.
  • Year: The event repeats on a yearly basis. Month and day must be specified.
  • Week: The event repeats on a weekly basis. A full date must be specified.
  • Custom: The event will repeat based on the number of seconds specified in the Multiplier option. A number greater than 86400 must be used.
Note: A single day is represented as 86400.
Multiplier*
The frequency an event repeats. Must be specified using positive whole numbers.
Anniversary*
When set to true the number of times the event has repeated will be shown. The value can also be represented by a number. Any value over 0 is interpreted as true. A formula can be used but must be enclosed in parenthesis.

Example: <Event Month="1" Day="4" Year="1986" Repeat="Year" Anniversary="true">Smurfier's BDay</Event>
Appears as: Smurfier's BDay (26)
Inactive*
When set to true the event is skipped when parsing the Event File.
Case*
Can be used to change the case of an event description. May be set to Lower, Upper, Title, Sentence, or None.
Skip*
Can be used to skip occurrences of a repeating event. The format is a list of dates presented as MM/DD/YYYY using the pipe delimiter to separate dates.

Example: Skip="01/04/2014|01/04/2015"
Finish*
Specifies a date that a repeating event ends on. Uses the MM/DD/YYYY format.

*This field is optional.

Event File Variables

Variables can be created that are specific to the the Event File that it is created in. The variable can then be used in all options in the event file.

Example: <Variable Name="Variable Name" Case="Variable Value"/>

Variables

There are a few instances when certain Variables can be used with LuaCalendar settings. The first being LabelText and the others being in the options of the Holiday Files. Variables are surrounded by {$Curly Brackets} with the dollar sign in front of the variable name, and are case insensitive.

Static Variables

{$MName}
The name of the currently shown month. If a name is not provided the month number is used.
{$Month}
The currently shown month number.
{$Year}
The currently shown year.
{$Today}
The current day number. This variable is effected by the LeadingZeroes setting and is only available when in the current month.

Variable Days

Variable Days are used to calculate holidays that occur on days like the Second Tuesday of the month. Each of these variables have two parts. The first part defines what kind of variable you want (First, Second, Third, Fourth, Last). The second part simply defines what day of the week to use (Sun, Mon, Tue, Wed, Thu, Fri, Sat).

Example: <Event Month="11" Day="{$FourthThu}" .../>

Built-In Event Variables

In order to support events that require complex calculations, LuaCalendar supports certain Built-In events. These events create both a {$EventName:Month} and an {$EventName:Day} variable. The value of these variables are recalculated for each year so that they are kept up to date.

Currently the supported Built-In Events are Easter, OrthodoxEaster, GoodFriday, AshWednesday, and MardiGras.

Style Sheets

LuaCalendar uses style sheets in order to allow for complete customization of the look and feel of the skin. Style sheets are files with individual MeterStyles and Variables used to define the meter properties of the skin. These files in located in the Styles folder, under another folder whose name defines the name of the style sheet.

There are three style sheets included with LuaCalendar. The Default style is very basic and is based on the old Enigma calendar. Default2 shows a little bit of what the style sheets can actually do. The third style sheet is made to match the Enigma 3.1 calendar.

Creating Style Sheets

There are two files used to create a style sheet. Styles.inc contains all of the meter styles required as well as any special meters. Variables.inc is used to create any variables specifically used by the style sheet.

Required Meter Styles - Day Labels

LblTxtSty
Used to define the main text properties of the Day Labels.
LblTxtStart
Used to define the properties of the first day label.
LblCurrSty
Used to define the current day of the week.

Required Meter Styles - Main Text

TextStyle
Defines the main text properties for the calendar days.
FirstDay
Defines the properties of the first calendar day. Should be used mostly for positioning.
NewWk
Defines the first day of each week. Is not applied to the first calendar day.
CurrentDay
Defines the current day of the month.
LastWeek
Defines the last weeks of the calendar when the current month does not extend beyond week 4 or 5. Only applies when HideLastWeek is set to 1.
PreviousMonth
Defines the days in the previous month.
NextMonth
Defines the days in the following month.
HolidayStyle
Defines the days on which a event occurs. This style is added onto other styles.
WeekendStyle
Defines weekends in the current month. This style is only applied if an event is not present on that day.

Script Defined Variables

These variables are created and updated by the script.
ThisWeek
Defines the week in which the current day occurs. Returns a number in the range 1-6.
Week
Defines the current weekday. Returns a number in the range 0-6.
Today
Defines the current day number. Follows the formatting of the LeadingZeroes option.
Month
The current name of the displayed month.
Year
The currently displayed year.
MonthLabel
The month label as defined by the LabelText setting.
NotCurrentMonth
Set to 1 when browsing outside the current month, else 0.
LastWkHidden
A number defining how many weeks at the end of the calendar need to be hidden.
NextEvent
A list of upcoming events in the currently displayed month following the style defined in the NextFormat setting.
WeekNumberN
WeekNumberN (where N is the numbers 1-6) is the week number (1-53) of the week.

Script Functions

These functions can be used with !CommandMeasure "ScriptMeasure" "Command()" to control the calendar.
Move(number)
Moves the calendar number of months. The number parameter must be a whole integer and can be either positive or negative. Using 0 will reset the Calendar to the current month.

Changelog

 

6.010/01/2016

5.011/20/2013

4.111/27/2012

4.011/4/2012

3.57/20/2012

3.45/22/2012

3.34/18/2012

3.2.23/26/2012

3.2.13/12/2012

3.23/11/2012

3.1.33/1/2012

3.1.22/24/2012

3.1.12/7/2012

3.12/5/2012

3.0.11/2/2012

3.01/21/2012

2.2.31/15/2012

2.2.28/22/2011

2.2.18/14/2011

2.28/13/2011

2.18/8/2011

2.08/8/2011