User Tools

Site Tools


calendarset_v5_api

This section describes the new CalendarSet v5 API


Change in old CalendarSet API

CS_SetArray has a new parameter at the end: durationArrayName which should be a name of a time or longint array


Definitions

Calendar is a container of events (timed or all-day). Every area contains a default calendar (owned by the area) which is used in compatibility mode (and can be used by developer).

Events refer to timed events, banners refer to all-day events.

Area refers to Calendars and draws relevant events in View.


Compatibility mode

This is the old CS API (arrays, see the CalendarSet v4 documentation) or the Agenda API (fields).

The implicit default calendar is filled with the events and the “calendars to be shown” (CS_Objects_Area_Calendars) array is cleared.


Icons to be used in areas

When an icon is to be displayed and is not in the cache, 4D's picture library is consulted: if it contains an icon with the specified ID, it will be implicitly added to the icon cache.

command syntax
CS_AddIcon(iconID:L; picture:P)
CS_RemoveIcon(iconID:L)

General commands

command syntax comments
CS_CreateCalendar→ iCal:L
CS_DeleteCalendar(iCal:L)
CS_Load(area:L; xml:T) → error:LConfigure area with XML
CS_Save(area:L; xml:T) → error:LSave area configuration as XML
Must use a variable to get the XML
%CS_Area2 Identical to %CS_Area, but the area is focusable (can process keyDown events)
Note that a side effect of focusability is that 4D reports On Plugin area, not On Clicked
CS_PosixTimeToDateTime(posixTime:L; date:D; time:L)date and time contain the result
CS_DateTimeToPosixTime(date:D; time:L) → POSIX time:L

Event commands

command syntax comments
CS_ParseEvent(iCal:L; event:T) → result:LThe event can be a full path to a .ics file or directly the event text (starting with “BEGIN:VCALENDAR”)
CS_AddEvent(iCal:L; title:T; description:T; startDate:D; startTime:H; endDate:D; endTime:H; isFullDay:L; userID:L; optionalEventKey:T) → eventKey:TIf the optionalEventKey is provided, it must be unique!
CS_MoveEvent(iCal:L; eventKey:T; newiCal:L)Move event from one calendar (iCal) to another one (newiCal)
CS_RemoveEvent(iCal:L; eventKey:T; how:L)Remove event from iCal
how is used for recurring events (0 = remove all, 1 = remove this, 2 = remove this and future)

Calendar properties commands

command syntax
CS_SetCalendarPtrProperty(iCal:L; inProperty:T; inPointer:Z) → result:L
CS_SetCalendarLongProperty(iCal:L; inProperty:T; inValue:L)
CS_SetCalendarTextProperty(iCal:L; inProperty:T; inValue:T)
CS_GetCalendarPtrProperty(iCal:L; inProperty:T; inPointer:Z) → result:L
CS_GetCalendarLongProperty(iCal:L; inProperty:T) → value:L
CS_GetCalendarTextProperty(iCal:L; inProperty:T) → value:T

See Calendar Properties constants.


Event properties commands

command syntax
CS_SetEventPtrProperty(ref:L; eventKey:T; property:T; pointer:Z) → result:L
CS_SetEventLongProperty(ref:L; eventKey:T; property:T; value:L)
CS_SetEventDateProperty(ref:L; eventKey:T; property:T; value:D)
CS_SetEventTextProperty(ref:L; eventKey:T; property:T; value:T)
CS_GetEventPtrProperty(ref:L; eventKey:T; property:T; pointer:Z) → result:L
CS_GetEventLongProperty(ref:L; eventKey:T; property:T;) → value:L
CS_GetEventDateProperty(ref:L; eventKey:T; property:T) → value:D
CS_GetEventTextProperty(ref:L; eventKey:T; property:T) → value:T

Events created from the iCal events displayed in the area use “View:” + recurrenceNumber + “:” + eventKey of the master event.
If eventKey starts with “View:”, an area reference is expected in the first parameter ref, otherwise an iCal reference is expected.
See Event event properties constants.


Area properties commands

command syntax
CS_SetAreaPtrProperty(area:L; property:T; pointer:Z) → result:L
CS_SetAreaLongProperty(area:L; property:T; value:L)
CS_SetAreaDateProperty(area:L; property:T; value:D)
CS_SetAreaRealProperty(area:L; property:T; value:8)
CS_SetAreaTextProperty(area:L; property:T; value:T)
CS_GetAreaPtrProperty(area:L; property:T; pointer:Z) → result:L
CS_GetAreaLongProperty(area:L; property:T) → value:L
CS_GetAreaDateProperty(area:L; property:T) → value:D
CS_GetAreaRealProperty(area:L; property:T) → value:8
CS_GetAreaTextProperty(area:L; property:T) → value:T

See Area Area properties constants.


Area and general object properties commands

command syntax
CS_SetObjects(ref:L; property:T; array:Y) → error:L
CS_GetObjects(ref:L; property:T; array:Y) → error:L
CS_GetObjects2(ref:L; property:T; array:Y; array2:Y) → error:L

Depending on the property, ref can be an area reference, an iCal reference or is ignored (time zones, special days, users).
See General and Area Objects properties constants.


Event object properties commands

command syntax
CS_SetEventObjects(ref:L; eventKey:T; index:L; property:T; array:Y) → error:L
CS_SetEventObjects2(ref:L; eventKey:T; index:L; property:T; array:Y; array2:Y) → error:L
CS_GetEventObjects(ref:L; eventKey:T; index:L; property:T; array:Y) → error:L
CS_GetEventObjects2(ref:L; eventKey:T; index:L; property:T; array:Y; array2:Y) → error:L

Recurring events: events created from the iCal events displayed in the area use “View:” + recurrenceNumber + “:” + eventKey of the master event.
If the eventKey starts with “View:”, an area reference is expected in the first parameter ref, otherwise an iCal reference is expected.
See Event Objects properties constants.

The index parameter in the RULE/EXRULE array is counted from 1 and expects a long int array.
Use the CS_Objects_Evt_RuleBy@ and CS_Objects_Evt_ExRuleBy@ constants.


Styles

Styles are used everywhere.

Use zero as the area parameter to set workstation default.

StyleID is either one of the predefined styles (0-13 - see CS_Style_@ constants in Style properties) or defined by developer using CS_AddStyle.

Only global styles can be created.

command syntax comments
CS_AddStyle(styleID:L; masterStyleID:L) → error:LstyleID must be >= 100
masterStyleID is used as parent of the created style
CS_RemoveStyle(styleID:L) → error:LstyleID must exist and be >= 100
CS_SetStylePtrProperty(area:L; styleID:L; propertyID:T; value:Z) → error:Larea is ignored when accessing custom style (global styles are accessed when styleID is not one of the predefined styles)
CS_SetStyleLongProperty(area:L; styleID:L; propertyID:T; value:L)
CS_SetStyleRealProperty(area:L; styleID:L; propertyID:T; value:8)
CS_SetStyleTextProperty(area:L; styleID:L; propertyID:T; value:T)
CS_GetStylePtrProperty(area:L; styleID:L; propertyID:T; value:Z) → error:L
CS_GetStyleLongProperty(area:L; styleID:L; propertyID:T) → value:L
CS_GetStyleRealProperty(area:L; styleID:L; propertyID:T) → value:8
CS_GetStyleTextProperty(area:L; styleID:L; propertyID:T) → value:T

See Style Properties and Predefined styles constants.


Users

Users are only used by CS_AddEvent (creating ORGANIZER property from userID).

command syntax
CS_SetUserPtrProperty(userID:L; propertyID:T; value:Z) → error:L
CS_SetUserLongProperty(userID:L; propertyID:T; value:L)
CS_SetUserTextProperty(userID:L; propertyID:T; value:T)
CS_GetUserPtrProperty(userID:L; propertyID:T; value:Z) → error:L
CS_GetUserLongProperty(userID:L; propertyID:T) → value:L
CS_GetUserTextProperty(userID:L; propertyID:T) → value:T

Special days

Special days modify the specified dates display.

They can be created/cleared only by using CS_SetObjects with CS_Objects_SpecialDays or with old API (CS_SetDayStyle, CS_SetDayStyleB). See the CalendarSet v4 documentation)

command syntax
CS_SetSpecialDayPtrProperty(date:D; propertyID:T; value:Z) → error:L
CS_SetSpecialDayLongProperty(date:D; propertyID:T; value:L)
CS_SetSpecialDayRealProperty(date:D; propertyID:T; value:8)
CS_SetSpecialDayTextProperty(date:D; propertyID:T; value:T)
CS_GetSpecialDayPtrProperty(date:D; propertyID:T; value:Z) → error:L
CS_GetSpecialDayLongProperty(date:D; propertyID:T) → value:L
CS_GetSpecialDayRealProperty(date:D; propertyID:T) → value:8
CS_GetSpecialDayTextProperty(date:D; propertyID:T) → value:T
calendarset_v5_api.txt · Last modified: 2017/05/02 09:23 by cs_admin