User interaction with a CalendarSet object is handled in the On load, On plug in area, On Clicked and On drop form events. Once again, the CalendarSet object method or form method, or callback will contain the procedures to detect user actions, such as selection, double-clicks, etc.

You may also use certain CalendarSet commands in other 4D methods, such as a query button object method which changes the arrays currently displayed in a CalendarSet object.

In such a method, if you modify the banner/event arrays in any way (other than calling CS_SetArray / CS_SetBanrArray), you’ll need to use Area_Refresh to update the CalendarSet object.

Note: CalendarSet will update automatically when area settings are modified.

The user’s action is communicated to you using CS_GetAction whenever the CalendarSet object method or form method, or callback method (or for an plugin window, the callback method only) is executed — i.e., the user has clicked on the CalendarSet area. CS_GetAction returns either a day was selected, or an event was selected.

If an event was selected, you can then call CS_GetEvtSelect to determine the event that is selected. CS_LastClick is available to obtain more information about the click itself, such as whether the click was a double-click, and what modifier keys were used.

You can select an event procedurally using CS_SetEvtSelect, which is similar in syntax to CS_GetEvtSelect.

Note: if you are referencing the area through a pointer, make sure that you use an expression to make sure that CalendarSet does not receive 0 due to 4D limitations:

Don't use


 CS_GetAction ($srcObject->;vAction) //To obtain the action of the object </color>

use


 CS_GetAction (($srcObject->);vAction) 

or


 CS_GetAction ($srcObject->+0;vAction) 

(AreaRef;ActionCode)

This routine is called from the CalendarSet object method (or for a CalendarSet plugin window, from the MethodToExecute) See CS_SetCallback in order to determine the last CalendarSet action. Please read the section Responding to User Actions on a CalendarSet Object for more information.

ActionCode — Integer. This parameter is returned with a value indicating what action the user made on the CalendarSet object.

Possible values are:

// eCalendar object method, detect a click on a day, an event or a banner and act accordingly 
C_LONGINT(vAction;vEvtType;vIndex) 
CS_GetAction (eCalendar;vAction) 
Case of 
 :(vAction=CS_Action_ClickOnDay) // clicked on a day 
  ShowDay 
 :(vAction=CS_Action_ClickOnEventBanner) // clicked on an event or banner 
  CS_GetEvtSelect (eCalendar;vEvtType;vIndex) 
  Case of 
   :(vEvtType=CS_Type_Event) //event 
    ModifyDay (vIndex) 
   :(vEvtType=CS_Type_Banner) //banner 
    ModifyBanner (vIndex) 
  End case 
End case 

(AreaRef; Type; EventIndex)

CS_GetEvtSelect is used to determine what event was selected by the user. You will usually call CS_GetAction prior to this command.

Only one event can be selected at a time (requires CS_SetEventOpts to be called with the AllowEventSelect parameter set to CS_EventSelect_Single).

Type — Integer, 1 or 2. The value returned in Type indicates whether the selected item is an event or banner.

EventIndex — Integer. This value is an index within the array that was passed to CalendarSet via either CS_SetArray or CS_SetBanrArray.

Use CS_SetEvtSelect to procedurally select an event or banner.

C_LONGINT(vAction;vType;vIndex) 
If(Form event=On Clicked) 
 CS_GetAction(eCal;vAction) 
 If(vAction=CS_Action_ClickOnEventBanner) // did the user select an event or banner? 
  CS_GetEvtSelect(eCal;vType;vIndex)
  Case of 
   :(vType=CS_Type_Event) //event
    ALERT("Event "+aEvent{vIndex}+" was selected.") 
   :(vType=CS_Type_Banner) //banner
    ALERT("Banner "+aBanner{vIndex}+" was selected.") 
  End case
 End if //CS_Action_ClickOnEventBanner 
End if // On Clicked 

(AreaRef; BannerIndex)

CS_GetResizBanr is used to determine which banner was resized. You should call this command from the source area’s object method (or callback method for an plugin window) after first using CS_GetAction and retrieving an action code of 5 (CS_Action_BannerResize), indicating the user has resized a banner.

BannerIndex — Integer. Index of the resized banner within the arrays passed to CalendarSet using CS_SetBanrArray.

Note: CalendarSet automatically updates the start and end date array values to reflect the modified banner duration.

// eCal object method 
C_INTEGER(vActionCode;vEvtIndex)

  CS_GetAction(eCal ;vActionCode) // Determine user action 
Case of 
 :(vActionCode=CS_Action_BannerResize) // User resized a banner 
  CS_GetResizBanr(vCal;vEvtIndex) 
End case 

(AreaRef; StartDate;EndDate;Contiguous;DaysArray)

CS_GetSelect will return the days that are currently highlighted in the calendar.

StartDate — Date. This value is the first day the is currently selected. A value of !00/00/00! is returned if no days are selected.

EndDate — Date. This value is the last day that is currently selected. A value of !00/00/00! is returned if no days are selected.

Contiguous — Integer. This value indicates whether (1) or not (0) all of the cells that are selected are contiguous (located adjacent to each other).

DaysArray — Date array (optional). If passed, this array will be filled with the dates of each of the selected items in the calendar, whether the selection is contiguous or not.

Use CS_SetSelect to procedurally highlight one or more days.

// get the selection of days for the eCalendar object

// use the selected dates as query criteria for a QUERY 
// of the [Followup] file 
C_DATE(vStart;vStop)
ARRAY DATE(aDates;0) 
CS_GetSelect (eCalendar;vStart;vStop;vContiguous;aDates) // get the selected days 
// now vContiguous = 1 if the selection is contiguous 
If(vStart#!00/00/00!) // make sure at least one day is selected 
 QUERY([Followup];[Followup]Followup Date=aDates{1};*) // start the built QUERY 
 For($i;2;Size of array(aDates)) // step thru each element of the date array 
  QUERY([Followup]; | ;[Followup]Followup Date=aDates{$i};*) 
 End for 
 QUERY([Followup]) // kick off the built QUERY 
End if 

(AreaRef; ItemType; SelectedItems)

CS_GetSelItems will return each of the array items (events or icons) belonging to the selected days in the calendar.

You will usually use this command after first using CS_GetAction to determine that the user has made a selection.

ItemType — Integer. This parameter specifies the type of items to return information about.

SelectedItems — Integer array. This parameter contains the index of each item in the array that corresponds to a selected day in the calendar. See FS_ArrayIntrsct for an example of this command.

C_LONGINT(vAction;vType;$i) 
ARRAY INTEGER(aIndex;0) 
If(Form event=On Clicked) 
 CS_GetAction(eCal;vAction) 
 If(vAction=CS_Action_ClickOnDay) // did the user select a day or days? 
 // get the events on this day or these days 
  CS_GetSelItems(eCal;CS_Sel_Events;aIndex) 
  For($i;1;Size of array(aIndex))
  
  // do something with each event’s arrays
  
  // for this example we’ll put a bullet character at the beginning of each event’s text 
   aEvent{aIndex{$i}}:="• "+aEvent{aIndex{$i}} 
  End for 
  Area_Refresh (eCal) // notify CalendarSet 
 End if //CS_Action_ClickOnDay 
End if // On Clicked 

(AreaRef; DateClicked; WasDouble; Modifiers)

CS_LastClick will return information on where the last click occurred.


DateClicked — Date. This parameter returns the date that was selected by the user. This value will be !00/00/00! if a banner or an event is selected.

WasDouble — Integer. This parameter indicates if the user has double-clicked (1) or single-clicked (0).

Modifiers — Integer. This parameter returns the values of any modifier keys (or combination of) which were pressed by the user when they clicked.

// eCalendar object method, detect a double-click on a day 
// If command key depressed, add a banner
// Otherwise, add an event 
Case of
 
 :(Form event=On Clicked) 
  CS_GetAction (eCalendar;vAction) 
 If(vAction=CS_Action_ClickOnDay) // clicked on a day 
  CS_LastClick (eCalendar;vDate;vDC;vMod) 
  If(vDC=1) // was it a double-click? 
   If(vMod & Command key mask)#0) // command key? 
    ADD CAL BANNER (vDate) 
   Else 
    ADD CAL EVT (vDate) 
   End if // command key 
  End if //double-click
 End if //CS_Action_ClickOnDay 
End case 

(AreaRef; MethodToExecute)

CS_SetCallback allows you to associate a method with a calendar area.

The method will be executed whenever the calendar is clicked on or other actions are performed by the user, such as closing the window, resizing a banner, or drag and drop. This command is normally used to detect and act on a user action on a CalendarSet plugin area or window.

MethodToExecute — Text. When CalendarSet detects a user action on a calendar area, the specified method will be executed. CalendarSet will pass two parameters to the method.

The first parameter, AreaRef, is received by the callback method in $1, and is of type long integer.

The second parameter, received in $2, represents the ActionCode, and is of type integer. The possible values for ActionCode, which are the same as the values returned by CS_GetAction, are shown below.

The drag action (value 4) is deprecated: drag and drop should be handled entirely when the drop occurs, with the CS_Action_Drop action. See Drag and Drop.

With CS_Action_DragOver only (when the dragged object is an external source), the callback method can return a $0 result, to selectively accept or refuse the drop. See Using the callback method and Receiving a drop from a non-CalendarSet Object.

When testing the value of the second parameter, a Case statement is recommended.

// Open a CalendarSet object in an plugin window.

// Configure the calendar for single day selection.
// Highlight the entire day, show info in unused days, display month prefix. 
// Show the Current date in Times 14 point bold.
// Set the click method to be "HandleCalClick". 
vCalWindow:= Open external window(50; 50; 400; 400; 4; "Calendar Window"; "_CS_Area") 
 // open the window with CalendarSet displayed 
CS_Options(vCalWindow;CS_Highlight_Cell;CS_DaySelect_Single;CS_Unused_GrayedNumBan;CS_MonthOnFirstOn) 
CS_SetDayStyle (vCalWindow;Current date;"Times";14;1)

CS_SetCallback(vCalWindow;"HandleCalClick") 
// Project method HandleCalClick 
C_LONGINT($1;$CalArea) // CalendarSet object reference 
C_INTEGER($2;$Action) // type of user action 
$CalArea:=$1 // reassign received parameters for better readability 
$Action:=$2 
Case of 
 :($Action=CS_Action_ClickOnDay) // user click on a day 
  CS_GetSelect ($CalArea;vDateSt;vDateEn;vContig;aDays) 
  ModDayInfo ($CalArea;vDateSt) // add/modify the info for that day 
 :($Action=CS_Action_WindowClosed) // user click in plugin window close box or the hosting form is closed 
  SaveCalendar // save any changes 
 :($Action=CS_Action_ClickOnEventBanner) // clicked on an event or banner 
 :($Action=CS_Action_BannerResize) // resized a banner 
 :($Action=CS_Action_Drop) // dropped an event or banner (or a non-CalendarSet object) 
  // handle the drag and drop here 
 :($Action=CS_Action_DragOver) //dragging a non CalendarSet/AreaList Pro object over the area 
  $0:=1 //allowdrop 
End case