Event class (Calendar)

The Cursor property defines the mouse-cursor for the event. The Cursors property defines the set of mouse cursors assigned to the different parts of the control, such as its background, dates, headers, or other interactive elements. It provides a general way to configure how the cursor appears depending on the area the user is hovering over. The Cursor property specifies the mouse cursor for the current event and takes precedence over the control's Cursors property while the mouse pointer is positioned over that event. This allows an individual event to override the default cursor behavior defined at the control level.

"pointer" {string}, The cursor is a pointer that indicates a link (typically an image of a pointing hand)

The Date property indicates the date of the event. One or more events can occur on the same date, and an event can occur on multiple dates. This property can be set to various formats to specify the date, including null or undefined for the current date and time, a number representing the year, a string in specific date formats, or a JavaScript Date object. This flexibility allows you to easily manage and display events based on their associated dates within the control.

The Date property can be any of the following:

• {null} or {undefined}, indicates the current date and time (equivalent of Date.Now())
• {number}, indicates the Jan 1st of the year, such as "Jan 1st 2001" for 2001
• {string}, defines the date in string-format as "#MM/DD/YYYY[ HH:mm:ss]#", such as "#10/10/2011 14:48#" or string-format as "YYYY-MM-DDTHH:mm:ss.sssZ" (ISO 8601), such as "2011-10-10" (date-only format), "2011-10-10T14:48:00" (local date-time format), "2011-10-10T14:48:00Z" (UTC date-time format), or "2011-10-10T14:48:00.000+09:00" (date-time format with milliseconds and time zone offset)
• {Date}, indicates a javascript Date to be copied, such as "Wed, 25 Mar 2015 15:00:00 GMT" for new Date("2015-03-25T15:00:00Z")

The time-section of the date is ignored, and the event occurs on the date regardless of the time. For instance, if the event's date is set to "Wed, 25 Mar 2015 15:00:00 GMT", the event occurs on "Wed, 25 Mar 2015" regardless of the time-section of the date.

null {null}, is equivalent of Date.Now()
2001 {number}, is equivalent of Mon, 01 Jan 2001 00:00:00 GMT
"#12/31/1971 13:00#" {string}, is equivalent of Fri, 31 Dec 1971 13:00:00 GMT
new Date("2015-03-25T15:00:00Z"), is equivalent of Wed, 25 Mar 2015 15:00:00 GMT

The Index property retrieves the event's index. The index is a zero-based number that indicates the position of the event within the control's events collection. By using this property, you can determine the order of events, access specific events based on their position, or perform operations that require knowledge of an event's index within the collection.

The following statements are equivalents:

 oEvent.GetIndex(), retrieves the event's index
 oEvent.Index, retrieves the event's index

where oEvent is an object of Event type

The Key property specifies the key associated with the event. The key serves as a unique identifier for the event, allowing you to reference and manage it within the control. By using this property, you can easily access specific events based on their unique identifiers, enabling dynamic interactions and modifications. The Events.Item(key) method can be used to retrieve an event by its key, providing a convenient way to access specific events based on their unique identifiers.

"logo" {string}, defines the event with the giving key (logo). You can use the oCalendar.Event("logo") method to request the event giving its key.

The Options property defines the event's options (visibility, caption, ...) at once. Each option of the EventOptions type has associated a property of the Event object, which means that the following statements are equivalent:

oEvent.SetOptions({date: "#1/1/2001#", shape: "red"}), sets the event's date and shape
oEvent.Options = {date: "#1/1/2001#", shape: "red"}, sets the event's date and shape
oEvent.Date = "#1/1/2001#"; oEvent.Shape = "red", sets the event's date and shape

oCalendar.Event(0).Options = {shape: "red", height: 32}, changes the event's height and background
oCalendar.Event(0).SetOptions({shape: "red", height: 32}), changes the event's height and background

The Repetitive property defines the general expression used to specify recurring or repetitive events within the control. It allows you to describe patterns such as daily, weekly, monthly, or custom intervals, enabling an event to automatically repeat according to the defined schedule. By setting this property, you can manage recurring events efficiently, ensuring that they appear on all relevant dates without manually assigning each occurrence.

The Repetitive property supports:

• Value format, when using the value keyword. For instance, "weekday(value) = 1", the event occurs every Monday. The expression supports predefined constants (dpi, bias, ...), unary of binary operators (not, +, -, ...), bitwise operators (bitor, bitand, ...), and number, string and date operators as listed here
• ICalendar format, as described in RFC 5545. For instance, "FREQ=WEEKLY;BYDAY=MO", the event occurs every Monday (requires "exontrol.icalendar.js"). The ICalendar format supports the following rules:
  • FREQ, {string} The FREQ rule part identifies the type of recurrence rule. This rule part MUST be specified in the recurrence rule.

    The valid values are "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY" and "YEARLY", as explained:

    • SECONDLY, to specify repeating events based on an interval of a second or more
    • MINUTELY, to specify repeating events based on an interval of a minute or more
    • HOURLY, to specify repeating events based on an interval of an hour or more
    • DAILY, to specify repeating events based on an interval of a day or more
    • WEEKLY, to specify repeating events based on an interval of a week or more
    • MONTHLY, to specify repeating events based on an interval of a month or more
    • YEARLY, to specify repeating events based on an interval of a year or more

    For example, "FREQ=DAILY;" indicates a daily recurrence rule.

  • DTSTART, {Date} The DTSTART value specifies the date the recurrence starts from, in YYYYMMDD[THHNNSS[Z]] format. If missing the current date and time is used.

    The format supports:

    • DATE format, as YYYYMMDD (for example, 20220101 indicates January 1st, 2022)
    • DATE-TIME format, as YYYYMMDDTHHNNSS (for example, 20220101T090000 indicates January 1st, 2022, at 09:00 AM local time)
    • DATE-TIME in UTC format, as YYYYMMDDTHHNNSSZ (for example, 20220101T090000Z indicates January 1st, 2022, at 09:00 AM UTC)

    where:

    • YYYY indicates the year
    • MM indicates the month (01 = January, 02 = February, ..., 12 = December)
    • DD indicates the day of the month (01 through 31)
    • T character is used to separate the date and time portions of the value
    • HH indicates the hour (00 through 23)
    • NN indicates the minute (00 through 59)
    • SS indicates the second (00 through 60)
    • Z character indicates that the time is in UTC format.

    For example, "FREQ=DAILY;DTSTART=20220101T090000Z;" indicates a daily recurrence rule starting from January 1st, 2022, at 09:00 AM UTC.

  • INTERVAL {number} The INTERVAL rule part contains a positive integer representing at which intervals the recurrence rule repeats.

    The default value is "1", meaning:

    • every 1 second for a SECONDLY rule
    • every 1 minute for a MINUTELY rule
    • every 1 hour for an HOURLY rule
    • every 1 day for a DAILY rule
    • every 1 week for a WEEKLY rule
    • every 1 month for a MONTHLY rule
    • every 1 year for a YEARLY rule

    For example, "FREQ=DAILY;INTERVAL=8" indicates a recurrence rule every eight days

  • COUNT, {number} The COUNT rule part defines the number of occurrences at which to range-bound the recurrence. The DTSTART value always counts as the first occurrence. The COUNT rule part is a positive integer.

    For example, "FREQ=DAILY;COUNT=10" indicates a recurrence rule for 10 times

  • WKST, {string} The WKST rule part specifies the day on which the workweek starts. The default value is MO. The WKST rule part is significant when a WEEKLY "RRULE" has an interval greater than 1, and a BYDAY rule part is specified. This is also significant when in a YEARLY "RRULE" when a BYWEEKNO rule part is specified.

    Valid values are:

    • MO, for Monday
    • TU, for Tuesday
    • WE, for Wednesday
    • TH, for Thursday
    • FR, for Friday
    • SA, for Saturday
    • SU, for Sunday

    For example, "FREQ=WEEKLY;WKST=SU" indicates a weekly recurrence rule where the week starts on Sunday

  • UNTIL, {Date} The UNTIL rule part defines a DATE or DATE-TIME value that bounds the recurrence rule in an inclusive manner. If the value specified by UNTIL is synchronized with the specified recurrence, this DATE or DATE-TIME becomes the last instance of the recurrence.

    The format of UNTIL is YYYYMMDD[THHNNSS[Z]], supporting:

    • DATE format, as YYYYMMDD (for example, 20220101 indicates January 1st, 2022)
    • DATE-TIME format, as YYYYMMDDTHHNNSS (for example, 20220101T090000 indicates January 1st, 2022, at 09:00 AM local time)
    • DATE-TIME in UTC format, as YYYYMMDDTHHNNSSZ (for example, 20220101T090000Z indicates January 1st, 2022, at 09:00 AM UTC)

    where:

    • YYYY indicates the year
    • MM indicates the month (01 = January, 02 = February, ..., 12 = December)
    • DD indicates the day of the month (01 through 31)
    • T character is used to separate the date and time portions of the value
    • HH indicates the hour (00 through 23)
    • NN indicates the minute (00 through 59)
    • SS indicates the second (00 through 60)
    • Z character indicates that the time is in UTC format.

    For example, "FREQ=DAILY;UNTIL=20220110T090000Z" indicates a daily recurrence rule until January 10th, 2022, at 09:00 AM UTC.

  • BYWEEKNO, {string} The BYWEEKNO rule part specifies a COMMA-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. The week numbering follows the ISO 8601 standard, where the first week of the year is the week that contains the first Thursday of the year. For example, week number 1 is the week with the first Thursday in January. Week number 52 is the week with the last Thursday in December. Week number 53 is only used in years where January 1st is a Thursday or a leap year where January 1st is a Wednesday. The BYWEEKNO rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY.

    For example, "FREQ=YEARLY;BYWEEKNO=20,30" indicates a yearly recurrence rule on the 20th and 30th weeks of the year

  • BYDAY, {string} The BYDAY rule part specifies a COMMA-separated list of days of the week. Each BYDAY value can also be preceded by a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific day within the MONTHLY or YEARLY "RRULE". For example, within a MONTHLY rule, +1MO indicates the first Monday of the month, whereas -1MO indicates the last Monday of the month. Within a YEARLY rule, +3TU indicates the third Tuesday of the year. Valid values for n are 1 to 5 or -5 to -1. The BYDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY.

    Valid values are:

    • MO, for Monday
    • TU, for Tuesday
    • WE, for Wednesday
    • TH, for Thursday
    • FR, for Friday
    • SA, for Saturday
    • SU, for Sunday

    For example, "FREQ=WEEKLY;BYDAY=MO,WE,FR" indicates a weekly recurrence rule on Monday, Wednesday and Friday

  • BYMONTHDAY, {string} The BYMONTHDAY rule part specifies a COMMA-separated list of days of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY.

    For example, "FREQ=MONTHLY;BYMONTHDAY=15,-1" indicates a monthly recurrence rule on the 15th and the last day of the month

  • BYYEARDAY, {string} The BYYEARDAY rule part specifies a COMMA-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). The BYYEARDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY.

    For example, "FREQ=YEARLY;BYYEARDAY=100,200" indicates a yearly recurrence rule on the 100th and 200th days of the year

  • BYSETPOS, {string} The BYSETPOS rule part specifies a COMMA-separated list of values that corresponds to the nth occurrence within the set of recurrence instances specified by the rule. BYSETPOS operates on a set of recurrence instances in one interval of the recurrence rule. For example, in a WEEKLY rule, the interval would be one week A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another BYxxx rule part. For example "the last work day of the month" could be represented as: FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 Each BYSETPOS value can include a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific occurrence within the set of occurrences specified by the rule.

    For example, "FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1" indicates a monthly recurrence rule on the last work day of the month

  • BYMONTH, {string} The BYMONTH rule part specifies a COMMA-separated list of months of the year. Valid values are 1 to 12.

    For example, "FREQ=YEARLY;BYMONTH=1,6,12" indicates a yearly recurrence rule on January, June and December

  • BYHOUR, {string} The BYHOUR rule part specifies a COMMA-separated list of hours of the day. Valid values are 0 to 23.

    For example, "FREQ=DAILY;BYHOUR=9,14,18" indicates a daily recurrence rule at 09:00 AM, 02:00 PM and 06:00 PM

  • BYMINUTE, {string} The BYMINUTE rule part specifies a COMMA-separated list of minutes within an hour. Valid values are 0 to 59.

    For example, "FREQ=HOURLY;BYMINUTE=0,30" indicates an hourly recurrence rule at minute 0 and minute 30 of each hour

  • BYSECOND, {string} The BYSECOND rule part specifies a COMMA-separated list of seconds within a minute. Valid values are 0 to 60.

    For example, "FREQ=MINUTELY;BYSECOND=0,15,30,45" indicates a minutely recurrence rule at second 0, second 15, second 30 and second 45 of each minute

"" {string} or null {null}, the event is not repetitive (no effect)
 "0" {string}, no occurrence
 "1" {string}, the event occurs every day
 "weekday(value) = 1" {string}, the event occurs every Monday
 "weekday(value) in (1,2) and month(value) = 6", the event occurs every Monday and Tuesday, on June only
 "value in (#6/8/2012#,#6/11/2012#,#6/20/2012#)", the event occurs on 6/8/2012, 6/11/2012 and 6/20/2012
 "value >= #6/1/2012# and ( (value - #6/1/2012#)/86400000 mod 5 = 0)", the event starts on 6/1/2012, and shows up every 5 days

 or using ICalendar format (requires "exontrol.icalendar.js"):

  "FREQ=DAILY;INTERVAL=2" {string}, the event occurs every 2 days
  "FREQ=WEEKLY;BYDAY=MO,WE,FR" {string}, the event occurs every Monday, Wednesday and Friday
  "FREQ=MONTHLY;BYDAY=1SU" {string}, the event occurs in the first Sunday of every month

The Selectable property indicates whether the user can select the date of the event. By using this property, you can control the interactivity of specific dates within the calendar, allowing you to enable or disable selection based on certain conditions or criteria. This is particularly useful for managing events that should not be selectable, such as past events or holidays.

false {boolean}, the date can not be selected
true {boolean}, the date can be selected

The Shape property defines the shape for the event. It allows you to customize how the event appears - such as rectangular, circular, or custom shapes - so that different types of events can be visually distinguished. By using this method, you can enhance the calendar's readability and provide a more intuitive representation of events based on their significance or category. The Shapes property specifies the shapes assigned to each part of the control.

The Shape property can be any of the following:

• the shape's name within the exontrol.Shapes.Calendar or exontrol.Shapes namespace
• a CSS color
• a JSON string-representation of an object of exontrol.Def.Shape type, for the event
• an object of {normal,hover,click,disabled} type. The normal, hover, click and disabled are objects of exontrol.Def.Shape type

null {null}, no custom shape is applied (default object's shape may be applied)
"" {string}, no custom shape is applied (no default object's shape is be applied)
"red" {string}, fills the object's background in red (CSS color)
'{"fillColor": "red"}' or '{"normal":{"fillColor": "red"}}' {string}, fills the object's background in red (JSON-representation of an object of exontrol.Def.Shape type)
"xxx" {string}, indicates that exontrol.Shapes.Calendar.xxx or exontrol.Shapes.xxx is applied on the object's background. If the xxx field is missing, no custom shape is applied (no default object's shape is be applied)
"Button" or exontrol.Shapes.Button {object}, applies the "Button" shape on the object as defined into exontrol.Shapes namespace (@since 5.2)

The ToolTip property specifies the event's predefined tooltip. The tooltip is specified as an ex-HTML string, which can include formatted text, images, or other HTML elements to provide rich, contextual information. This tooltip is displayed automatically when the mouse cursor hovers over the event, offering users guidance, descriptions, or additional details without requiring any clicks or other interactions. By using this property, you can customize the information shown for each event individually, enhancing the usability and interactivity of the control.

null {null}, undefined {undefined} or "" {string}, no tooltip for the event is displayed
"<img>image</img> and text" {string}, the image and text is being shown once the mouse pointer hovers the event. The image can be added using the exontrol.HTMLPicture.Add method

The UserData property stores any extra-data associated with the event. This property allows you to attach custom information to the event, such as identifiers, references to external records, status flags, or other metadata required by your application. By utilizing this property, you can enhance the functionality of your events by storing and retrieving additional context-specific data that is not part of the standard event properties, enabling more advanced processing and integration with other components or data sources.

oEvent.UserData = {id:123, name:"John Doe"}, associates the object {id:123, name:"John Doe"} to the event as extra-data

The Remove() method removes the event from the events collection. By using this method, you can efficiently manage the events within the calendar, allowing you to delete specific events as needed. The Remove method updates the collection accordingly and ensures that any associated data or references are properly handled. The Events.Remove(id) method is an alias to this method, which allows you to remove an event directly from the events collection by its index, unique identifier, or direct reference.

oEvent.Remove(), removes the event from the events collection.