Calendar Object Plugin

 Online Help

Description

The Calendar object plugin allows you to add an Outlook-style calendar right into your AutoPlay Media Studio applications. Drop it on your page and you've got a great looking and super flexible calendar, that's ready for you to customize!

While it looks great right out of the box, we've made it easy to configure with flexible drawing options, fonts, colors, borders, special days and much more. Events like "On Select" and "On Month Select" make it easy to detect when a day (or series of days) is clicked or a month is selected.

It's great for use in a variety of applications, such as scheduling, reminders, bulletin boards, timesheets, general calenders and so much more.

Properties

Rows

Controls the number of rows of calendars what will be drawn within the objects bounding rectangle. This number can be between 1 and 100 inclusive.

Columns

Controls the number of columns of calendars what will be drawn within the objects bounding rectangle. This number can be between 1 and 100 inclusive.

Note: The object size will not grow or shrink to fit the correct number of rows or columns. If the number of rows and columns is too large to fit the objects bounding rectangle, the calendars will still be drawn but they may not be visible. Make sure to re-size your calendar object to fit all of your specified rows and columns.

Note: The calendar that exists at row one and column one is referred to as the "focus calendar".

General Font

This is the font that will be applied to the calendar in general. It will control the appearance of the date numerals, the day of the week headings, and the month/year calendar headings.

Special Days Font

This font will control the appearance of dates that have been marked special using the Calendar.AddSpecialDate() action. This font will only alter the appearance of the date numerals that have been marked special.

Multi-Select

Enables or disables the ability to select more then one date on the calendar at runtime. If checked the user will be able to select multiple dates on the calendar. If unchecked only one date can be selected at a time.

Highlight Today

Highlights that date that is currently specified to be "today". By default "today" is the current day when the runtime is active, however the "today" date can be changed programmatically using the Calendar.SetToday() action. If checked the "today" date will be marked with a red bounding rectangle. If unchecked the "today" date will not be marked in any way.

Non-Month Days

Displays date numerals in the calendar that do not correspond to the current month. If checked date numerals corresponding to the previous and next month will be displayed in the current calendar month. If unchecked those date numerals will be left out.

Note: If multiple rows and columns are used this will only affect the focus calendar and the calendar that appears at the bottom right.

3D Border

Surrounds the calendar plugin with a three-dimensional border. If checked the calendar object will be surrounded with a three-dimensional border, if unchecked the calendar object will have the "flat" look applied to it.

Background Color

Controls the color of the calendar's background.

Month Days Color

Controls the color of the calendar's date numerals, not including the non-month days.

Non-Month Days Color

Controls the color of the calendar's non-month date numerals.

Special Days Color

Controls the color of the calendar's date numerals that have been marked as special. This will not affect any other dates and will control the appearance of special date numerals in conjunction with the special date font.

Events

On Select

Fires when the calendar selection changes. This event will be fired if the selection is programmatically using the Calendar.SetSelection() action or if the end-user selects days using the mouse. The following event variables are automatically set whenever this event is triggered:

e_StartDate:

(string) The start date of the selection in the format: "YYYY-MM-DD". If the calendar does not have multiple selection enabled e_EndDate will be equal to this value.

e_EndDate:

(string) The end date of the selection in the format: "YYYY-MM-DD". If the calendar does not have multiple selection enabled e_EndDate will be equal to e_StartDate.

On Month Select

Fires when the a month is selected in the calendar's month heading list. This event will be fired if the selection is set programmatically using the Calendar.SetCurrentMonthYear() action or if the end-user selects the month using the mouse. The following event variables are automatically set whenever this event is triggered:

e_CurrMonthYear:

(string) The current month year in the format: "YYYY-MM". This value will always correspond to the current month year in the focus calendar.

e_SelMonthYear:

(string) The selected month year in the format: "YYYY-MM". If the selection is not altered this may be equal to e_CurrMonthYear. This value corresponds to the month year value that the calendar where the selection occurred will contain. It is not tied to the focus calendar.

Actions

Calendar.AddSpecialDate
Calendar.ClearSelection
Calendar.ClearSpecialDates
Calendar.GetCurrentMonthYear
Calendar.GetSpecialDates
Calendar.GetToday
Calendar.SetCurrentMonthYear
Calendar.SetSelection
Calendar.SetToday
Calendar.SetWeekStartDay
Calendar.ShowToday

Calendar.AddSpecialDate (string ObjectName, string Date)

Description:

Adds an special date to a calendar object.

ObjectName:

(string) The name of the calendar object.

Date:

(string) The special date (YYYY-MM-DD).

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Prompt the user for a special day they wish to add to the calendar.
date_entered = Dialog.MaskedInput("Special Day", "Please enter the special day to you want to add:", "####-##-##", "2003-12-25", MB_ICONQUESTION, " ");

-- If the user didn't press the Cancel button...
if (date_entered ~= nil) then
	-- Marks the user input date as a special day on the "Calendar1" calendar object.
	-- The date will display in red.
	Calendar.AddSpecialDate("Calendar1", date_entered.Displayed);
	
	-- See if an error occurred calling Calendar.AddSpecialDate.
	-- If an error occurred, display the error message.
	error = Application.GetLastError();
	if (error ~= 0) then
		Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
	end
else
	-- Display a dialog notifying the user the date could not be set as special.
	Dialog.Message("Notice", "An error occurred, please retry inputting the date.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Calendar.ClearSelection (string ObjectName)

Description:

Removes the selection (if any) from the specified calendar.

ObjectName:

(string) The name of the calendar object.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Clears the date(s) currently selected on the calendar.
Calendar.ClearSelection("Calendar1");

Calendar.ClearSpecialDates (string ObjectName)

Description:

Removes all special dates (if any) from the specified calendar.

ObjectName:

(string) The name of the calendar object.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Clears all special dates marked on the calendar object.
Calendar.ClearSpecialDates("Calendar1");

string Calendar.GetCurrentMonthYear (string ObjectName)

Description:

Returns the current month and year displayed in the focus calendar (YYYY-MM).

ObjectName:

(string) The name of the calendar object.

Returns:

(string) The current month year displayed in the focus calendar (YYYY-MM). If an error occurs, an empty string ("") is returned.

Example:

-- Get the current year and month displayed in the calendar object.
current_monthyear = Calendar.GetCurrentMonthYear("Calendar1");

-- Check if an error occurred.
error = Application.GetLastError();

if (current_monthyear ~= "") then
	-- Display a dialog containing the current year and month.
	Dialog.Message("Currently Year-Month", "The current year and month in the calendar is "..current_monthyear, MB_OK, MB_ICONINFORMATION);
else
	-- If an error occurred, display the error message.
	Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

table Calendar.GetSelection (string ObjectName)

Description:

Returns a table containing the beginning and ending selection dates.

ObjectName:

(string) The name of the calendar object.

Returns:

(table) A table containing the beginning and ending selection dates in the format YYYY-MM-DD. The table entries are indexed by the keys "Begin" and "End". You can access the values by tb.Begin and tb.End. If there are no dates selected or an error occurs, nil is returned.

Example:

-- Get the beginning and ending of the selection in the "Calendar1" calendar object.
selection = Calendar.GetSelection("Calendar1");

-- If a selection was made, display the dates in a dialog.
-- If no selection is made, notify the user in a dialog.
if (selection ~= nil) then
	Dialog.Message("Calendar Selection", "The beginning of the selection is: "..selection.Begin.."\r\nThe end of the selection is: "..selection.End, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
	Dialog.Message("Notice", "There are no dates selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

table Calendar.GetSpecialDates (string ObjectName)

Description:

Returns a numerically indexed table of all the special dates.

ObjectName:

(string) The name of the calendar object.

Returns:

(table) A numerically indexed table containing all of the special dates associated with the calendar. The dates will be in the ISO date format: YYYY-MM-DD. If no special dates are marked, or an error occurs, nil is returned.

Example:

-- Get the special dates on the "Calendar1" calendar object.
special_dates = Calendar.GetSpecialDates("Calendar1");

-- If at least one special date is selected...
if (special_dates ~= nil) then
	-- Convert the table of dates to a formatted string with newlines as delimiters.
	special_date_string = Table.Concat(special_dates, "\r\n", 1, TABLE_ALL);
	
	-- Display all of the special dates in a dialog.
	Dialog.Message("Special Dates", "The special dates marked on the calendar are: \r\n\r\n"..special_date_string, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
	-- Notify the user that no special dates are marked.
	Dialog.Message("Notice", "There are currently no special dates marked on the calendar.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

string Calendar.GetToday (string ObjectName)

Description:

Returns the current today date for the calendar (YYYY-MM-DD).

ObjectName:

(string) The name of the calendar object.

Returns:

(string) The current today date for the calendar (YYYY-MM-DD). If an error occurs, an empty string ("") is returned.

Example:

-- Get the current date in the calendar.
date_today = Calendar.GetToday("Calendar1");

-- If the date was retrieved successfully, display it in a dialog.
if (date_today ~= "") then
	Dialog.Message("Today's Date", "Today's date is "..date_today, MB_OK, MB_ICONINFORMATION);
end

Calendar.SetCurrentMonthYear (string ObjectName, string MonthYear)

Description:

Sets the current month and year displayed in the focus calendar.

ObjectName:

(string) The name of the calendar object.

MonthYear:

(string) The month and year to set in the focus calendar (YYYY-MM or YYYY-MM-DD).

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Sets the visible month and year in the calendar to "2004-01-01".
Calendar.SetCurrentMonthYear("Calendar1", "2004-01-01");

Calendar.SetSelection (string ObjectName, string StartDate, string EndDate = "")

Description:

Sets the selected dates in the calendar object.

ObjectName:

(string) The name of the calendar object.

StartDate:

(string) The starting date of the selection (YYYY-MM-DD).

EndDate:

(string) The ending date of the selection, defaults to the starting date (YYYY-MM-DD). If not specified a single day specified by StartDate will be selected.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Prompt the user for the beginning date to be selected in the calendar.
begin_date = Dialog.MaskedInput("Selection Date - Begin", "Please enter the beginning date to be selected:", "####-##-##", "2003-12-24", MB_ICONQUESTION, " ");

-- Prompt the user for the end date to be selected in the calendar.
end_date = Dialog.MaskedInput("Selection Date - End", "Please enter the end date to be selected:", "####-##-##", "2003-12-25", MB_ICONQUESTION, " ");

-- If the user didn't press the Cancel button...
if ((begin_date ~= nil) and (end_date ~= nil)) then
	
	-- Set the selection in the calendar to the beginning and end days the user entered.
	Calendar.SetSelection("Calendar1", begin_date.Displayed, end_date.Displayed);
	
	-- See if an error occurred calling Calendar.SetSelection.
	-- If an error occurred, display the error message.
	error = Application.GetLastError();
	if (error ~= 0) then
		Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
	end
else
	-- Display a dialog notifying the user the dates could not be set.
	Dialog.Message("Notice", "An error occurred, please retry inputting the dates.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Calendar.SetToday (string ObjectName, string Today)

Description:

Sets the date that will be highlighted as "today".

ObjectName:

(string) The name of the calendar object.

Today:

(string) The date that will be used as the today date (YYYY-MM-DD).

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Prompt the user for the date they would like to set as today's date.
date_entered = Dialog.MaskedInput("Today's Date", "Please enter the date you want to set as today:", "####-##-##", "2003-12-25", MB_ICONQUESTION, " ");

-- If the user didn't press the Cancel button...
if (date_entered ~= nil) then
	-- Set the input date as today's date on the calendar.
	Calendar.SetToday("Calendar1", date_entered.Displayed);
	
	-- See if an error occurred calling Calendar.SetToday.
	-- If an error occurred, display the error message.
	error = Application.GetLastError();
	if (error ~= 0) then
		Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
	end
else
	-- Display a dialog notifying the user the date could not be set.
	Dialog.Message("Notice", "An error occurred, please retry inputting the date.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Calendar.SetWeekStartDay (string ObjectName, number Day)

Description:

Sets which day of the week will be the "first" day of the week displayed in the calendar (i.e., whether the week should start on Sunday, Monday, etc.).

Note: The "first" day of the week is displayed the furthest to the left.

ObjectName:

(string) The name of the calendar object.

Day:

(number) The day of the week that will be used as the first day of the week, represented by a number from one to seven:

1 - Sunday
2 - Monday
3 - Tuesday
4 - Wednesday
5 - Thursday
6 - Friday
7 - Saturday

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- make the calendar's weeks start on Monday

Calendar.SetWeekStartDay("Calendar1", 2);

Calendar.ShowToday (string ObjectName)

Description:

Forces the currently specified "today" date to be visible in the calendar.

ObjectName:

(string) The name of the calendar object.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Force the currently specified "today" date to display in the calendar.
Calendar.ShowToday("Calendar1");

Error Codes

0 (Calendar.OK)-(no error)
1100  -The specified object could not be found.
78001 (Calendar.ERR_DATE_VALUE_OUT_OF_RANGE)-The specified date value is out of range. ("100-01-01" - "9999-12-31")
78002 (Calendar.ERR_DATE_INVALID)-The specified date is invalid.
78003 (Calendar.ERR_DAY_OUT_OF_RANGE)-The day of the week value is out of range. (1-7)

Change Log

1.0.1.0

1.0.0.1

1.0.0.0

Additional Information

Author:

Indigo Rose Corporation
support.indigorose.com

Copyright:

The Calendar Object Plugin is copyright © 2003-2005 Indigo Rose Software Design Corporation.

Website:

http://www.indigorose.com

Copyright © 2005 Indigo Rose Software Design Corporation.
All Rights Reserved.