User Tools

Site Tools


about_calendarset_v6

CalendarSet version 6

CalendarSet version 6 includes the original API (no change needed in your existing code) as well as the more recent property-based API and adds new features:

  • Year view

  • Calendar.app-like display

  • Separate scrolling of all-day events area in Day/Week views
  • Separate 64-bit build signed & notarized on Mac

New Constants

  • CS_Action_YearMonthClick = 16
  • CS_Action_YearWeekClick = 17
  • CS_Action_DayWeekScroll = 18
  • CS_Action_ClickOnMonthDayNbr = 19
  • CS_View_Year = 6
  • CS_Objects_Area_MonthNames = “gMNf”
  • CS_Objects_Area_MonthNamesAbbrev = “gMNa”
  • CS_Objects_Area_DayNames = “gDNf”
  • CS_Objects_Area_DayNamesAbbrev = “gDNa”
  • CS_Objects_Evt_Icons = “icon”
  • CS_Objects_Area_DayTimeZones = “TimZ”
  • CS_Style_Grid = 18
  • CS_Style_Month = 19
  • CS_iCal_Clear = “clr”
  • CS_Event_UUID = “uid”
  • CS_Event_InfoText = “info”
  • CS_Area_DrawingMode = “draw”
  • CS_Area_ScrollMonthViewWeeks = “smvw”
  • CS_Area_HoursInDayView = “timH”
  • CS_Area_ShowEventsInYearView = “deyw”
  • CS_Area_YearViewLayout = “ywla”
  • CS_Area_ShowYearInYearView = “dyyw”
  • CS_Area_ShowInfoText = “info”
  • CS_Area_DayHeaderFormat = “Dfmt”
  • CS_Area_WeekHeaderFormat = “Wfmt”
  • CS_Area_MonthHeaderFormat = “Mfmt”
  • CS_Area_DayHeaderAlignment = “Dhal”
  • CS_Area_WeekHeaderAlignment = “Whal”
  • CS_Area_DayInfoFormat = “Dinf”
  • CS_Area_WeekInfoFormat = “Winf”
  • CS_Area_NoAllDayHeader = “Dnad”
  • CS_Area_ScrollDaysWeeks = “MSdw”
  • CS_Area_DefaultForNewEvent = “DCal”
  • CS_Area_ColorTheme = “CALI”
  • CS_Area_GoToPrevious = “Vprv”
  • CS_Area_GoToToday = “Vnow”
  • CS_Area_GoToNext = “Vnxt”
  • CS_Area_EventMouseDownModifiers = “evtm”
  • CS_Area_DragSrcArea = “ddSA”
  • CS_Area_DragDstProcessID = “ddDP”
  • CS_Area_DragSrcEvent = “ddSE”
  • CS_Area_DragDstRow = “ddDR”
  • CS_Area_DragDstArea = “ddDA”
  • CS_Area_DragDataType = “ddDT”
  • CS_Area_DragDstDate = “ddDD”
  • CS_Area_DragDstEvent = “ddDE”
  • CS_Area_DragEventMoved = “ddEM”

New Properties

CS_Area_DrawingMode

“draw”, Boolean, default 0 (False), read/write/persistent, xml name “drawingMode”.
Use Calendar.app - like drawing.
Background color of event is not used, calendar/event color is shaded instead.
Note: does not affect Old month view drawing and all views when Agenda API is used.

CS_Area_ScrollMonthViewWeeks

“smvw”, Boolean, default 0 (False), read/write/persistent, xml name “scrollWeek”.
In Month view: when there are more events than space in a day cell, the whole week row is scrollable instead of showing “+2” (meaning 2 more events are not visible).
Arrows for scrolling are displayed on the right side of the area and in each cell (containing events), number of events is displayed; can be scrolled with mouse wheel.

CS_Area_HoursInDayView

“timH”, integer, default 24, min 1, max 24, read/write/persistent, xml name “hoursInDay”.
In Day/Week view, display specified hours at a time (using scrolling when more hours are to be displayed).

CS_Area_YearViewLayout

“ywla”, integer, default 2, min 0, max 8, read/write/persistent, xml name “yearLayout”.

  • 0 = 1 row, 12 columns
  • 1 = 2 rows, 6 columns
  • 2 = 3 rows, 4 columns
  • 3 = 4 rows, 3 columns
  • 4 = 6 rows, 2 columns
  • 5 = 12 rows, 1 column
  • 6 = 1 row, 1 column → 1 month
  • 7 = 1 row, 3 columns → 3 months
  • 8 = 3 rows, 1 column → 3 months

CS_Area_ShowEventsInYearView

“deyw”, Boolean, default 1 (True), read/write/persistent, xml name “yearEvents”.
When set to 1, days in year view (layout 0 - 5) are colored if there are events.

CS_Area_ShowYearInYearView

“dyyw”, Boolean, default 1 (True), read/write/persistent, xml name “yearYear”.
When set to 1, year is displayed in year view.

CS_Area_ShowInfoText

“info”, Boolean, default 0 (False), read/write/persistent, xml name “showEventInfo”.
When set to 1, new event property CS_Event_InfoText is drawn in day/week view.

CS_Area_DayInfoFormat

“Dinf”, integer, default 0, min 0, max, 6, read/write/persistent, xml name “dayInfoFmt”.
Text drawn above the time column in Day view.

  • 0 = current state (depends on CS_Area_DisplayWeek, CS_Area_DisplayMonth)
  • 1 = same as 0, but forced short month name
  • 2 = same as 0, but forced full month name
  • 3 = week: W9
  • 4 = short month name: Feb
  • 5 = long month name: February
  • 6 = short month + year: Feb 2020

CS_Area_WeekInfoFormat

“Winf”, integer, default 0, min 0, max, 6, read/write/persistent, xml name “weekInfoFmt”.
Text drawn above the time column in Day-range/Week view.
Possible values are identical to CS_Area_DayInfoFormat.

CS_Area_DayHeaderFormat

“Dfmt”, integer, default 0, min 0, max 20, read/write/persistent, xml name “dayFormat”.
Text drawn in day header in Day view.

  • 0 = current state: DDD, DD / DDDD, DD depending on column width: Sat, 29. / Saturday, 29.
  • 1 = DDD, DD: Sat, 29.
  • 2 = DDDD, DD: Saturday, 29.
  • 3 = DD/MM: 29/02
  • 4 = MM/DD: 02/29
  • 5 = DD MMM: Feb 29
  • 6 = MMM DD: 29 Feb
  • 7 = DDD, DD MMM: Sat, 29 Feb
  • 8 = MMM, DDD DD: Feb, Sat 29
  • 9 = DDD, MMM DD: Sat, Feb 29
  • 10 = YYYY-MM-DD: 2020-02-29
  • 11 = DD DDD: 29 Sat
  • 12 = DDD DD: Sat 29

Adding 8 to selectors 5-12 uses full names, e.g. for 9 + 8 = 17: Saturday, February 29.

CS_Area_WeekHeaderFormat

“Wfmt”, integer, default 0, min 0, max 20, read/write/persistent, xml name “weekFormat”.
Text drawn in day header in Day-range/Week view.
Possible values are identical to CS_Area_DayHeaderFormat.

CS_Area_MonthHeaderFormat

“Mfmt”, integer, default 0, min 0, max 2, read/write/persistent, xml name “monthFormat”.

  • 0 = current state (short/full day name depending on column width)
  • 1 = short day name
  • 2 = full day name

CS_Area_DayHeaderAlignment

“Dhal”, integer, default 0, min 0, max 3, read/write/persistent, xml name “dayHdrAlignment”.
Modifies header alignment in Day view.

  • 0 = current state - use CS_Style_Header alignment
  • 1 = force left alignment
  • 2 = force centered alignment
  • 3 = force right alignment

CS_Area_WeekHeaderAlignment

“Dhal”, integer, default 0, min 0, max 3, read/write/persistent, xml name “weekHdrAlignment”.
Modifies header alignment in Day-range/Week view.

  • 0 = current state - use CS_Style_Header alignment
  • 1 = force left alignment
  • 2 = force centered alignment
  • 3 = force right alignment

CS_Area_NoAllDayHeader

“Dnad”, Boolean, default 0 (False), read/write/persistent, xml name “noAllDayHeader”.
When set to 1, the “all-day” text is not drawn above the time column in Day/Week view.

CS_Area_ScrollDaysWeeks

“MSdw”, Boolean, default 0 (False), read/write/persistent, xml name “scrollDaysWeeks”.
When set to 1, day/week view is “scrollable” with mouse wheel
When (possibly displayed) scrollbar is at the min/max and you scroll with mouse wheel more enough, displayed date range is changed, new CS_Action_DayWeekScroll is reported.

CS_Area_DefaultForNewEvent

“DCal”, integer, default 0, read/write, not persistent.
iCal to use for new events.

  • when dragging event inside area, identical calendarID is used
  • when dragging event across areas and destination area shows that owning calendar, identical calendarID is used
  • when zero, default calendar (CS_Area_DefaultiCal) is used
  • finally, when resolved iCal to use is not visible in the area (does not exist or is hidden), first visible calendar is used

CS_Event_UUID

“uid”, text, read/write/persistent, xml name “uid”.
This is the real event ID stored in VEVENT.
Usage is meant for iCal integration: UUID is the unique event identifier.
The CS_Event_UID name can be misleading, it could be eventID or objectID or simply eventKey.
It is actually the event key to internal map entry (key → displayed event in a view → event in a calendar).

CS_Event_InfoText

“info”, text, read/write/persistent, xml name “info”.
Not persistent in VEVENT, only in XML.
This text can be displayed in day/week view, see CS_Area_ShowInfoText.


New Accessors

CS_Objects_Area_MonthNames

“gMNf”, text array.
Get/set full month names (initialized from system).

CS_Objects_Area_MonthNamesAbbrev

“gMNa”, text array.
Get/set abbreviated month names (initialized from system).

CS_Objects_Area_DayNames

“gDNf”, text array.
Get/set full day names (initialized from system).

CS_Objects_Area_DayNamesAbbrev

“gDNa”, text array.
Get/set abbreviated day names (initialized from system).

CS_Objects_Area_DayTimeZones

“TimZ”, longint 2D array.
Get/set time zones per day (e.g. “mark lunch time between 12:00 and 12:30 with yellow on Monday-Friday”).
When using it with CS_GetObjects / CS_SetObjects, a two-dimensional longint array is expected, containing start hour in first column, end hour in second one and (optional in setter) color in third one.
To define colored time range for Sunday, use ?12:00:00? & ?12:30:00?.
For all other days, add 86400 per day, thus for Monday it will be ?12:00:00?+86400.
Don’t forget to include alpha channel in the ARGB color!
If color is zero (or not provided - array having only 2 columns), current non-working hours background color is used when drawn.

Example:

 ARRAY LONGINT($dayTimeZones;3;7)
 For ($i;0;6)
    $dayTimeZones{1}{$i+1}:=?12:00:00?+($i*86400)  // 12:00
    $dayTimeZones{2}{$i+1}:=?12:30:00?+($i*86400)  // 12:30
    $dayTimeZones{3}{$i+1}:=0xFFCCFFCC  // green
 End for 
 $l:=CS_SetObjects (xCalendar;CS_Objects_Area_DayTimeZones;$dayTimeZones)

Result:

CS_Objects_Evt_Icons

“icon”, longint array.
The iconIDs to get/set (no need to parse/create comma separated text with CS_Event_Icon).

CS_Style_Grid

18.
StyleID defining the grid color.
The only usable property is the background color (CS_Style_BackColor), default is gray (0xFF808080).
Used as grid color (horizontal & vertical in Month view, vertical in Day/Week view).
Used as frame color when CS_Area_DrawingMode = 1 (all views except Old month view: Day/Week, Month and Year view).

CS_Style_Month

19.
StyleID defining the color of the month name in year view.
Only text color is used.

CS_iCal_Clear

“clr”, write only, value is unused.
Remove all events from the specified calendar.

CS_Area_ColorTheme

“CALI”, integer.
Currently only allowed value is 1, write only.
When set, many properties are modified to match Calendar.app look: global styles & area properties (including styles).

CS_Area_GoToPrevious

“Vprv”, value is unused, write only.
Change displayed date range to “previous” (depends on the view, e.g. for day it is one day, for year view showing 1 month it is one month).

CS_Area_GoToToday

“Vnow”, value is unused, write only.
Change displayed date range to “now”.

CS_Area_GoToNext

“Vnxt”, value is unused, write only.
Change displayed date range to “next” (depends on the view, e.g. for day it is one day, for year view showing 1 month it is one month).

CS_Area_EventMouseDownModifiers

“evtm”, integer, read-only.
State of the key modifiers (control/option/command/shift/caps-lock) as it was at mouse down event.
Due to the asynchronous mouse handling, CS_Area_EventMouseModifiers can differ from CS_Area_EventMouseDownModifiers, esp. when using right-click (which synthesizes control key at mouse down).

CS_Area_DragSrcArea

“ddSA”, integer, read-only.
>0 means CalendarSet, <0 means AreaList Pro, 0 means other source.

CS_Area_DragDstProcessID

“ddDP”, integer, read-only.
Drop destination process number.

CS_Area_DragSrcEvent

“ddSE”, text, read-only.
Source event key when the drag is from CalendarSet.

CS_Area_DragDstRow

“ddDR”, integer, read-only.
Row in the view where the drop occurred in Day/Week view.

  • 0 = all-day area part
  • >0 timed event

CS_Area_DragDstArea

“ddDA”, integer, read-only.
Destination area in case it is a CalendarSet area.

CS_Area_DragDataType

“ddDT”, integer, read-only.
Destination in CalendarSet:

  • 0 = none
  • 1 = day
  • 2 = event
  • 3 = banner (all-day event)

CS_Area_DragDstDate

“ddDD”, integer, read-only.
Destination day in CalendarSet as POSIX time.

CS_Area_DragDstEvent

“ddDE”, text, read-only.
Destination event key when destination is event/banner in CalendarSet.

CS_Area_DragEventMoved

“ddEM”, Boolean, read-only.
Set to 1 (True) when CalendarSet handled the event move (dragging an event inside one area).


Modified Properties

CS_Area_View

Maximum value = 6 (CS_View_Year).
In Year view, CS_Action_YearMonthClick is reported for click on a month name and CS_Action_YearWeekClick for click on week number (when displayed).

CS_Area_ShowBanners

Type integer (was Boolean), default 0, min 0, max 32.
When value is > 1, it is used as maximum number of events to display in all-day area of Day/Week view (using separate scrollbar if more space is needed).

CS_Area_ShowEventTimes

Type integer (was Boolean), default 1, min 0, max 2.
When set to 2 and CS_Area_DrawingMode = 1 and CS_Area_ViewType is day/week view (1 - 4), event times are displayed as “from - to” when event ends in the same day

CS_Event_RecurrFrequency setter

Values 1-3 are no longer allowed.


Extended CS_Objects_Area_Banners and CS_Objects_Area_Events

Now you can use CS_GetObjects2 and specify a date array containing dates.
This function will return only banners/events for the specified dates (if any), not all banner/events in the view.
If the date array is empty, no events are returned.

ARRAY TEXT($atKeys;0)
ARRAY DATE($aDates;1)
$aDates{1}:=$dateOfInterest // e.g. CS_Area_ClickedDate
$err:=CS_GetObjects2 ($area; CS_Objects_Area_Events; $atKeys; $aDates)

Modified behavior

Modified day/week view

  • The view is now split into two views - one for the all day events, another for the timed events
  • Both can have scrollbars
  • All-day events part is resizable, default is “automatic” (after resizing, can be reset with double-click on the views separator line)
  • Default for all-day part size is “as much as needed”, with limit of 5 events (when CS_Area_ShowBanners = 1) and height 120 points (when the height is not set by user - another limit is half of the area size for resize by user)
  • View with timed events should scroll (on first redraw) to the working start hour
  • When some event is above/below the visible part of the view, a sign is drawn to indicate “there are more events”

Event created by drag

When not using compatibility API and event is created by drag in day/week view (CS_Area_AllowDragNewEvent = 1 (this is set with CS_Area_ColorTheme!), user clicks in a day and drags), it is not deleted on mouse up.
You can use CS_Area_ClickedEventID in the area method to get the position (date/time/duration/all-day), CS_Area_CSEvent is CS_Action_EventCreated or CS_Action_BannerCreated) to manipulate it.

CS_Event_Recurrence

This value is now sequential inside the view, not the real recurrence number (unless the owning iCal has property CS_iCal_IsBirthday).


Note

  • When compatibility API is used, the created events inherit styles from area (events are destroyed with calendar before area is destroyed)

→ old API modifies area-specific styles

  • When new API is used, the events inherit global styles (events are owned by calendar and can be created w/o any area) - all events in any area use the same global base styles

→ to modify appearance, change CS_Style_Default, CS_Style_Event & CS_Style_Banner with area reference ($1) = 0

Simply:

  • old API: area styles (event & banner inheriting from default)
  • new API: global styles (event & banner inheriting from default)

It is irrelevant whether event (or banner) overrides the style at event level or not.
Other styles used for drawing are always from the area (and area styles are initialized from the global styles).

about_calendarset_v6.txt · Last modified: 2022/03/03 19:31 by cs_admin