User Tools

Site Tools


user_action_commands

User Action Commands


Responding to User Actions on a CalendarSet Object

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) 

Commands

CS_GetAction

(AreaRef;ActionCode)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
← ActionCode integer type of user action

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:

Action Value Constant
User clicked on a day (no event selected) 1 CS_Action_ClickOnDay
User closed the window (valid only for a CalendarSet plugin window – deprecated in 64-bit 4D) 2 CS_Action_WindowClosed
User clicked on an event or banner 3 CS_Action_ClickOnEventBanner
User dragged an event or banner 4 (deprecated)
User resized a banner 5 CS_Action_BannerResize
User resized the window 6 (obsolete)
User dropped something onto the area 7 CS_Action_Drop
Dragging a non CalendarSet/AreaList Pro object over the area 8 CS_Action_DragOver
User resized an event 9 CS_Action_EventResize
User clicked on the “All day” area (below the day header) 10 CS_Action_ClickOnAllDay
User clicked on a day header 11 CS_Action_ClickOnDayHdr
User clicked on the Month/Year (upper left) 12 CS_Action_ClickOnYearHdr
User hit DELETE/BACKSPACE 13 CS_Action_DeleteEvent
User created banner by drag 14 CS_Action_BannerCreated
User created event by drag 15 CS_Action_EventCreated

Example

// 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 

CS_GetEvtSelect

(AreaRef; Type; EventIndex)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
← Type integer event or banner selected
← EventIndex integer array element corresponding to selected item

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.

Type Value Constant
Event 1 CS_Type_Event
Banner 2 CS_Type_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.

Example

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 

CS_GetResizBanr

(AreaRef; BannerIndex)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
← BannerIndex integer array element corresponding to resized banner

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.

Examples

// 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 

CS_GetSelect

(AreaRef; StartDate;EndDate;Contiguous;DaysArray)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
← StartDate date the start date of the selection
← EndDate date the end date of the selection
← Contiguous integer 1 if selected dates are adjacent to each other
← DaysArray date array array of currently selected items

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).

Mode Value
The current selection is made of the days that are specified in DaysArray 1
The current selection covers the range StartDate to EndDate 2

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.

Example

// 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 

CS_GetSelItems

(AreaRef; ItemType; SelectedItems)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
→ ItemType integer kind of item to return
← SelectedItems integer array index of all items belonging to selected days

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.

Type Value Constant
Events 1 CS_Sel_Events
Icons 2 CS_Sel_Icons

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.

Example

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 

CS_LastClick

(AreaRef; DateClicked; WasDouble; Modifiers)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
← DateClicked date date that was clicked by user
← WasDouble integer was event a double-click?
← Modifiers integer modifier keys

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.

Modifier Key Value Constant
None 0 CS_Attr_Days
Ctrl / command (Windows = Ctrl key, MacOS = Command key) 256 Command key mask
Shift 512 Shift key mask
Caps Lock 1024 Caps lock key mask
Option (Windows = Alt key, Mac OS = Option key) 2048 Option key mask
Control (MacOS only) 4096 Control key mask

Example

// 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 

CS_SetCallback

(AreaRef; MethodToExecute)

Parameter Type Description
→ AreaRef longint area reference of the CalendarSet area
→ MethodToExecute text method to execute when calendar is clicked

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.

Action Value Constant
User click on day (no event selected) 1 CS_Action_ClickOnDay
User closed the window (valid only for a CalendarSet plugin window) 2 CS_Action_WindowClosed
User clicked on an event or banner 3 CS_Action_ClickOnEventBanner
User dragged an event or banner (deprecated) 4
User resized a banner 5 CS_Action_BannerResize
User resized the window (obsolete) 6
User dropped something onto the area 7 CS_Action_Drop
Dragging a non CalendarSet/AreaList Pro object over the area 8 CS_Action_DragOver

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.

Example

// 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 

user_action_commands.txt · Last modified: 2018/02/27 18:45 by cs_admin