User Tools

Site Tools


configuring_calendarset

Configuring CalendarSet


Using the Advanced Properties Dialog

CalendarSet includes a point-and-click interface for configuring a CalendarSet object from within the Design environment. This dialog provides access to configure nearly every feature available via CalendarSet commands, and is very easy to use.

The Advanced Properties dialog lets you specify the names of the arrays to be displayed, almost all options including event / banner selection, color settings, and default styles and color for all CalendarSet text. There is a preview tab to instantly view the options that you’ve selected.

Once you click the OK button to complete the configuration, the settings will be saved by 4D within the plugin area object on your form. Whenever this form is opened in the user / runtime environments, the settings made here will be applied to your CalendarSet object before the form method or any object methods are executed. Essentially, you are replacing the default settings provided by CalendarSet with new values of your choosing.

You can use commands in combination with the Advanced Properties Dialog. In this case, CalendarSet first reads the settings specified in the dialog, then uses the settings specified by commands.


To Display the Advanced Properties Dialog

1. Double-click a CalendarSet object in the Form editor. 4D will display the Object Properties palette.

2. Click the Advanced Properties button. The Advanced Properties Dialog will be displayed.

The dialog has several panes, accessed via the tabs at the top, which provide access to the various configuration options.


Setting the Data to Display

Data is passed to CalendarSet via 4D arrays. You can tell CalendarSet the names of the arrays using the first pane on the Advanced Properties Dialog.`

These arrays must be loaded from within your 4D methods. Typically, the arrays will be loaded using the 4D SELECTION TO ARRAY command in the On Load event in the CalendarSet object’s method.

We recommend that you use the appropriate compiler declarations for all arrays you display, to ensure that you correctly specify the data type of all arrays.

Refer to the 4D manuals for the details on defining arrays, and loading them with data.


Setting Options

The second pane on the Advanced Properties Dialog is used to set many of the options available for the display and behavior of the CalendarSet object. You can see the results of any settings you make by clicking on the Preview tab, to view a sample object.


Formatting Options

CalendarSet lets you configure the font, size, style, and color used to display the various textual items on a CalendarSet object. Each of the types is accessed by the tab within this formatting pane. You can see the results of any settings you make by clicking on the Preview tab, to view a sample object.


Dragging

CalendarSet supports drag-and-drop between CalendarSet objects, as well as with AreaList Pro objects, 4D objects or external files. You can configure the dragging behavior using the Dragging pane of the Advanced Properties Dialog. Please read the section Drag and Drop for more information.


Preview

CalendarSet’s Advanced Properties Dialog provides a pane for previewing the current configuration settings. This is useful during the configuration process, as you can quickly see the results of any setting you select.

The Preview pane shows sample data using the settings you have specified in the Options, Formatting, and Dragging panes. The arrays you specify can’t be displayed, due to 4D’s process architecture, which keeps the Design environment in a special process.


Using CalendarSet Commands

CalendarSet commands are used in the On load, On clicked, On Plug in Area and On drop form events.

A CalendarSet object is initialized in the On load phase as the form is about to be displayed.Typically, this initialization will be contained in the object method for the CalendarSet object.

If you use an object method with a CalendarSet object, and you want the object method to execute On load, be sure to check the “On load” checkbox in the object’s Events properties.


Parameters and default values

Most commands use parameters of various types, for which constants are available.

The default value (i.e. if no specific value is set using a CalendarSet command) for numeric parameters is 0 unless otherwise indicated.


Setting Events, Banners and Icons

4D arrays are passed directly to CalendarSet for display, using CS_SetArray for events, CS_SetIconArray for icons, and CS_SetBanrArray for banners.

The arrays contain the data to be displayed on the days, as well as font, size, style, and color configuration.

All arrays passed to a CalendarSet object must have the same number of elements.

Note: some arrays are passed as a string which is the array name, rather than just the array itself. In other words, the array name is enclosed in quotes. This approach is taken to allow CalendarSet to automatically handle certain tasks involved in redrawing a calendar area.


Color table

All color settings used in CalendarSet refer to the same color table.

Each item in the color array allows you to specify either the index into the 4D color palette (positive numbers) or one of the hardcoded (negative) numbers specified in the color table shown below.

Color Value Constant
Black -1 CS_Color_Black
White -2 CS_Color_White
Red -3 CS_Color_Red
Green -4 CS_Color_Green
Blue -5 CS_Color_Blue
Cyan -6 CS_Color_Cyan
Magenta -7 CS_Color_Magenta
Yellow -8 CS_Color_Yellow
4D Colors 1 to 256

The 4D color palette is a 16 by 16 grid. To determine a color’s value, you can locate the color’s position on the color grid in the Design environment (the Color submenu which is available in the Form and Method editors), and count the number of rows down and columns across.

The equation is: ColorValue = ( (RowNumber – 1) x 16) + ColumnNumber.


Setting Color, Font, Size, and Style Attributes

The default attributes for each type of object on a CalendarSet area are specified using CS_FontDefaults. Colors are set according to the Color table.

The types of objects are day numbers, items, day names, banners, and current day number and background color.

Additionally, you can specify a unique color for a particular item using CS_SetArray, CS_SetBanrArray, and CS_SetDayStyle / CS_SetDayStyleB. These commands are also used to control font, size, and style.

Banners also have a background color attribute which can be set using the commands discussed above.


Setting Icons

CalendarSet allows display of an icon in a day (cell).

CS_SetIconArray specifies the icons to display, along with the size of the icons.


Displaying Event times

Time is supported in events. If you want to use this feature and display event times:

  • The timeArray parameter to CS_SetArray contains the name of a longint or time array.
  • When the showEventTimes parameter to CS_SetEventOpts is set to 1 (or any nonzero value), events are displayed with the time on the right side if the column is wide enough.

Displaying the Month Name

You can display an abbreviation of the month name on the first day of each month, using CS_Options.


Displaying Out of Range Days

Out of range days, such as the days before and after the month being displayed, can be displayed in several different ways, using CS_Options.


Extending the CalendarSet Frame

The border of the calendar may be extended to include the day headers (days of the week) using CS_Options.


Specifying the First Day of the Week

The default value for the first day of week is taken from the system. You can change this using CS_Options.

Use -1 to apply the system setting in your call to CS_Options.


Calendar Colors

The colors of the entire calendar may be set from the Color table using CS_SetCalColor.

The background color of unused days (those outside the date range specified for display using CS_SetRange) is also set with CS_SetCalColor.

CS_FontDefaults also sets Current day background (selector value 5). For compatibility reasons, when the area background color is set (CS_SetCalColor), the current day background color is set to the same value. Set the current day background color after setting the area background color.

Note: Icons colors may appear distorted when using background colors other than white.


Day Selection

You can control whether the user can click to select days, using CS_Options.

Choices include the selection highlight mode, using DayHighlightMode, and the type of selection, using DaySelectionType.

Highlight modes are no selection, day number only highlights, or entire day highlights. Selection types are no selection, or multiple contiguous or discontiguous days to be selected.


Event Selection

You can configure what type of selection to allow using CS_SetEventOpts. The parameter AllowEventSelect will consist of two values:

Mode Value Constant
No event selection 0 CS_EventSelect_None
Single event selection 1 CS_EventSelect_Single

See Responding to User Actions on a CalendarSet Object for information about how to handle the selection of an event.


Banner selectibility can be set using CS_SetBanrOpts.

You can enable or disable banner resizing by setting AllowBannerResize using CS_SetBanrOpts.

When banner resizing is allowed, CalendarSet will automatically update the appropriate elements in the banner arrays that were passed using CS_SetBanrArray. See Responding to User Actions on a CalendarSet Object for information about how to handle the selection of a banner.

The user’s action of resizing a banner is communicated to you using CS_GetAction.

This command should be called whenever the CalendarSet object method is executed (in this case, after the resize has occurred). CS_GetAction returns a value of 5 (CS_Action_BannerResize: user resized a banner). You can then call CS_GetResizBanr to determine which banner was resized.


Word Wrap

CalendarSet will optionally word wrap event text to fit within a day’s width, rather than truncating text which doesn’t fit. This is controlled by the ShowWordWrap parameter of CS_SetEventOpts to 1.

No word wrapping will be performed for banners. CalendarSet will automatically truncate data and display the standard ellipsis (…) if the banner width is too small to display the full text. The ellipsis is displayed in the middle of the banner text.


Event Markers

To distinguish two or more events from each other within a day, each event can be optionally marked using a special character.

The parameter EventMarker can be set to 0, 1 or 2 to show no mark, a bullet, or a dash respectively. If 0 (no mark) is chosen (which is the default), you can choose a marker of choice by setting the first character of the event text passed in using CS_SetArray to the desired character followed by a space.

Possible marker candidates from the Arial font are “• - Ð Þ —.”


Hiding Days

You can hide one or more days in a week using CS_HideDays.


Date format

The date format (MM/DD/YY vs DD/MM/YY) will honor the workstation system settings.


Commands


_CS_Area

_CS_Area is the command used to identify the plugin area when you create an plugin area object on a form.

It is only used in the object definition for a CalendarSet object, and should never be used as a plugin command in a 4D method.


CS_FontDefaults

(AreaRef; Selector; Font; Size; Style; ForeColor; BackColor)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ Selector integer attribute identifier
→ Font text font name
→ Size integer font size
→ Style integer font style
→ ForeColor integer foreground color
→ BackColor integer background color (day names, banners and current day only)

CS_FontDefaults allows you to specify the default font and color characteristics for various items in the calendar.

Note: invalid values in any characteristic will do nothing.

Selector — Integer. Specifies which attribute that you want to set. The possible values for Selector are:

Mode Value Constant
Day numbers (cells) 1 CS_Attr_Days
Text that appears in each cell (including time) 2 CS_Attr_Text
Day names that appear at the top of the calendar (headers) 3 CS_Attr_Headers
Banners 4 CS_Attr_Banners
Current date day number and background color 5 CS_Attr_Current

Font — Text. Use this parameter to specify the font for the selected attribute. Pass an empty string (“”) to use the default font: Lucida Grande on MacOS and Segoe UI on Windows.

Size — Integer. Use this parameter to set the font size of the selected attribute. Pass 0 to use the default font size for the specified attribute: 9 for all items and both platforms.

Style — Integer. Use this parameter to set the font style of the selected attribute. Pass -1 to use the default font style for the specified attribute: bold for days (CS_Attr_Days), headers (CS_Attr_Headers) and current day (CS_Attr_Current), plain for event text (CS_Attr_Text) and banners (CS_Attr_Banners).

You can use the usual 4D constants (or a combination, e.g. Bold + Italic) to set the styles:

Value Style
0 Plain
1 Bold
2 Italic
3 Underline

ForeColor — Integer. Use this parameter to set the foreground color of the selected attribute. Refer to the Color table for possible values. Pass 0 to use the default foreground color for the specified attribute: black for all items.

Note : font name, size, style and foreground color settings for day numbers, day names, and banners can be overridden on an item by item basis using other commands: CS_SetDayStyle, CS_SetDayStyleB, CS_SetArray, and CS_SetBanrArray.

BackColor — Integer. Use this parameter to set the background color of the selected attribute. Refer to the Color table for possible values. Pass 0 to use the default background color for the specified attribute. The defaults are palette index 243 for headers a.k.a. day names (selector 3), -2 (white) for banners (selector 4) and none (use area back color set with CS_SetCalColor) for current day (selector 5).

Note : CS_SetBanrArray can override the banner background color, too.

Examples

// Show day number in Arial 10 point plain, black color 
 CS_FontDefaults (eCalArea; CS_Attr_Days; "Arial"; 10; 0; 0) 
// Show day names in Helvetica 9 point bold, black color 
 CS_FontDefaults (eCalArea; CS_Attr_Headers; "Helvetica"; 9; 1; 0) 
// Set current day background color to light blue (Cyan) leaving the default values for the other attributes 
 CS_FontDefaults (eCalArea; CS_Attr_Current; ""; 0; -1; 0; CS_Color_Cyan) 

CS_HideDays

(AreaRef; HideSunday; HideMonday; HideTuesday; HideWednesday; HideThursday; HideFriday; HideSaturday)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ HideSunday integer don’t display Sunday
→ HideMonday integer don’t display Monday
→ HideTuesday integer don’t display Tuesday
→ HideWednesday integer don’t display Wednesday
→ HideThursday integer don’t display Thursday
→ HideFriday integer don’t display Friday
→ HideSaturday integer don’t display Saturday

CS_HideDays allows you to procedurally hide any of the days on the calendar. This is most useful for hiding the weekend days to only show a weekday calendar.

A value of 1 for any day will hide that day, a value of 0 will show the day. The default for all days is zero (all days are visible by default).

Examples

// Hide Saturday and Sunday 
CS_HideDays (eCalArea; 1; 0; 0; 0; 0; 0; 1) 
// Hide Sunday only
  CS_HideDays (eCalArea; 1; 0; 0; 0; 0; 0; 0) 
// Show Saturday and Sunday only 
CS_HideDays (eCalArea; 0; 1; 1; 1; 1; 1; 0) 
// Show only the current day
  CS_SetRange (eCalArea;Current date;Current date) // set active range to current date only 
C_INTEGER(v1;v2;v3;v4;v5;v6;v7;vDayNum) // declare variables for use below 
For($i;1;7) // initialize the variables to hide all days 
 $TempPtr:=Get pointer("v"+String($i)) 
 $TempPtr->:=1 
End for
  vDayNum:=Day number(Current date) 
$TempPtr:=Get pointer("v"+String(vDayNum)) 
$TempPtr->:=0 // don’t hide today 
CS_HideDays (eCalArea;v1;v2;v3;v4;v5;v6;v7) 

CS_Options

(AreaRef; DayHighlightMode; DaySelectionType; UnusedInfo; MonthPrefix; FirstDayOfWeek; ExtendFrame)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ DayHighlightMode integer type of highlighting to use for day selection
→ DaySelectionType integer type of selection allowed
→ UnusedInfo integer how to display unused cells
→ MonthPrefix integer display the month name for first day of month
→ FirstDayOfWeek integer which day starts a week
→ ExtendFrame integer include headers within enclosing frame

CS_Options is used to control several CalendarSet options.

Each parameter is an integer, and is defined as follows:

DayHighlightMode — Integer, 0, 1, or 2. Type of highlighting to use for selected days (cells). There are three possible values:

Mode Value Constant
No Highlight 0 CS_Highlight_None
Highlight entire day’s cell 1 CS_Highlight_Cell
Highlight number only 2 CS_Highlight_Number

DaySelectionType — Integer, 0, 1, or 2. Controls how days are selected. There are three possible values:

Mode Value Constant
Single day only 0 CS_DaySelect_Single
Multiple days selectable (contiguous) 1 CS_DaySelect_ Multiple
Discontiguous day selectable 2 CS_DaySelect_ Discontiguous

UnusedInfo — Integer, 0, 1, or 2. Defines how unused days will be displayed. Unused days are those outside of the date range defined with CS_SetRange. There are three possible values:

Mode Value Constant
Nothing displayed 0 CS_Unused_Blank
Cell is grayed out 1 CS_Unused_GrayedEmpty
Cell is grayed and day number and banners are displayed (default) 2 CS_Unused_GrayedNumBan

Note: drag and drop onto “out of range” days in the same area will only be allowed if the UnusedInfo parameter is set to CS_Unused_GrayedNumBan.

MonthPrefix — Integer, 0 or 1. A value of 1 will display the month name for the first day of every month:

Mode Value Constant
No month names on first day 0 CS_MonthOnFirstOff
Month names on first day 1 CS_MonthOnFirstOn

FirstDayOfWeek — Integer, -1 to 6. Controls the day of the week on which a week will begin.

Mode Value Constant
Use the system setting (default) -1 CS_FirstDayOS
Sunday 0 CS_FirstDaySun
Monday 1 CS_FirstDayMon
Tuesday 2 CS_FirstDayTue
Wednesday 3 CS_FirstDayWed
Thursday 4 CS_FirstDayThu
Friday 5 CS_FirstDayFri
Saturday 6 CS_FirstDaySat

ExtendFrame — Integer, 0 or 1.


Mode Value Constant
CalendarSet will not extend the frame 0 CS_Frame_NotExtended
The frame that is drawn around the CalendarSet area is extended to include the header labels representing the days of the week 1 CS_Frame_Extended

Examples

// Highlight number only, multiple cells (contiguous), unused cells grayed, month prefix, 
// Sunday start, extend frame
  CS_Options (eCalArea;CS_Highlight_Number;CS_DaySelect_Multiple;CS_Unused_GrayedNumBan;\ 
 CS_MonthOnFirstOn;CS_FirstDaySun;CS_Frame_Extended) 
// Highlight entire cell, multiple cells (discontiguous), unused cells blank, no month prefix 
// Monday start, don’t extend frame
  CS_Options (eCalArea;CS_Highlight_Cell;CS_DaySelect_Discontiguous;CS_Unused_Blank;\ 
 CS_MonthOnFirstOff;CS_FirstDayMon;CS_Frame_NotExtended) 

CS_Register

(registrationCode; options; email) → result

Parameter Type Description
→ registrationCode text Pass the registration key to register your copy of CalendarSet. The key is either linked to the 4D or 4D Server serial number (individual licenses), to the machine ID (merged licenses), to the name of the company / developer (unlimited annual licenses) or to the product (master keys for Online registration)
→ options Longint An optional longint combining up to 4 bits: force check, Online registration options
→ email text Online registration option: developer email to notify when a license is issued or resent.
→ result Longint 0 or error code

CS_Register is used to register the CalendarSet plugin for standalone or server use.

Please see the License Types section for detailed information about the licensing options available for CalendarSet.

Multiple calls to CS_Register are allowed. The plugin will be activated if at least one valid key is used, and all subsequent calls to CS_Register will return 0, unless the force check bit is set to true in the options parameter.

registrationCode — You must call CS_Register with a valid registration key, otherwise CalendarSet will operate in demonstration mode - it will cease to function after 20 minutes. In case a master key is used the plugin will attempt a connection to e-Node's license server for Online registration.

options — Optional. This parameter combines up to 4 bits as described below. The default mode (registrationCode being a passed as the only parameter) is silent: no force check, no confirmation, no alert, no email.

Bit number Description
0 Force check: if this bit is is on (true), registrationCode is tested regardless of current registration state. If the plugin was not previously registered and the result is 0, it is registered the same way as if the bit was off (or the whole options parameter omitted) 
If the plugin was previously successfully registered, a registration error will be returned in result in case registrationCode is invalid, but the plugin will remain registered.
1 Online registration option: confirm connection “Is it OK to connect to e-Node’s license server to register CalendarSet?”
2 Online registration option: display alert if registration error
3 Online registration option: display alert if registered

email — Optional. The developer email address where to send Online registration information.

result — 0 or error code:

Result code Description
0 OK
1 Beta license has expired
2 Invalid license
3 The license has expired
4 The OEM license has expired
5 The maximum number of users has been exceeded
6 The license is for a different environment (e.g. the licence is for a single-user version, but you are using it with 4D Server)
7 The license is linked to a different 4D license
8 Invalid merged license
9 Only serial / ID licenses are allowed in text license files (includes Register button and Online registration)
10 Unauthorized master key (Online registration)
11 Can't connect to e-Node's license server to perform Online registration
12 No Online registration license available for this master key (unknown or all used)

When CS_Register is called with an empty string, the license dialog will be displayed if CalendarSet is not registered and the dialog was not yet displayed. This allows you to show the registration dialog to your users without effectively calling a CalendarSet command or displaying a CalendarSet area.

Note: alternately to CS_Register, you can place a plain text file into your 4D Licenses folder or use the Demo mode dialog “Register” button. This is only valid for non-unlimited licenses.

Basic example

C_LONGINT ($result)
  
$result:=CS_Register ("YourRegistrationKey") 
Case of 
 :($result=2)
    
  ALERT ("The CalendarSet licence is invalid.") 
 :($result=3)
    
  ALERT ("The CalendarSet licence has expired.") 
 etc. 
End case 

Example with multiple calls

C_LONGINT ($result) // ignored in this case 
$result:=CS_Register ("Registration key one") 
$result:=CS_Register ("Registration key two") 
$result:=CS_Register ("Registration key three") 

etc.

If ($result#0) // registration failed on all keys 
 ALERT ("CalendarSet could not be registered.") 
End if 

Force check example

In this example we assume that only “Registration key two” is valid, but you want to check the other keys status.

C_LONGINT ($result)
  
$result:=CS_Register ("Registration key one";1) // invalid, will return an error, the plugin isn't registered 
$result:=CS_Register ("Registration key two";1) // valid, will return 0, the plugin is registered 
$result:=CS_Register ("Registration key three";1) // invalid, will return an error, the plugin is still registered 

Online registration examples

Confirm connection, alert if successful, alert if failed, send email notification to developer@4dchampions.com:

C_LONGINT ($result) 
$result:=CS_Register ("Master key";0 ?+1 ?+2 ?+3;" developer@4dchampions.com") 

Silent connection, alert if successful, alert if failed, no email notification:

C_LONGINT ($result)
  
$result:=CS_Register ("Master key";0 ?+2 ?+3) 

CS_SetArray

(AreaRef;DateArray;TextArray; FontArray; SizeArray; StyleArray; ColorArray; TimeArray)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ DateArray text dates of each item
→ TextArray text text of each item to display (name of text array)
→ FontArray text font to use for each item (name of text array)
→ SizeArray text size of each item (name of numeric array)
→ StyleArray text style of each item (name of numeric array)
→ ColorArray text color of each item (name of numeric array)
→ TimeArray text time of each item (name of long integer or time array)

CS_SetArray is used to specify the arrays that are used to display events in each of the days. The arrays passed to this command are typically loaded using the 4D command SELECTION TO ARRAY, with the values in records containing event or other date-based information. Each of the arrays can be thought of as a column of a table, and each row of that table contains the array elements which correspond to an event record. For a particular record, there is information for the date of the event, the text, and font, size, style, and color. If the arrays are changed after calling CS_SetArray, you will need to call Area_Refresh to force CalendarSet to show the changes.

Note: modifying the event arrays doesn’t require reissuing CS_SetArray, but you must call Area_Refresh.

This command is optional (although usually you will use it), and is used to display text events and (optionally) times on one or more days. 
Note: The array parameters are actually strings and not the arrays themselves.

DateArray — Text (name of a date array). Used to define which days you want the event to be displayed on.

TextArray — Text (name of a text array). Used to define the text of the events to be displayed.

Note: DateArray and TextArray are required (otherwise no events will be displayed).FontArray — Text (name of a text array). The referenced array contains the fonts to display each corresponding event. Use an empty text array to use the default font value for all events.

SizeArray — Text (name of a numeric array). The referenced array is used to specify the font size of the text for each corresponding event. Use an empty numeric array to use the default size value for all events.

StyleArray — Text (name of a numeric array). The referenced array is used to specify the style (plain, bold, italic, etc.) of the text for each corresponding event. Use an empty numeric array to use the default style value for all events.

ColorArray — Text (name of a numeric array). Each item in the color array allows you to specify the color from the Color table. Use an empty numeric array to use the default color value for all events.

TimeArray — Text (name of a longint or time array). Used to define the times of the events to be displayed.

You can omit the styling arrays using empty strings. 
For example, assigning “” as ColorArray will have the effect of ignoring FontArray, SizeArray and StyleArray, not only ColorArray. 
You have to provide an array name, but this array can be an empty ARRAY INTEGER (or correctly sized but containing zeros).

Notes :

1. When an empty string is provided as the array name (or the name does not resolve to an array of the proper type), all styling arrays are ignored. 


2. When the name of an empty array is provided, the default for that styling property is used for all (missing) elements. 


3. When the array has less elements than needed, default for that styling is used for missing elements. 


4. To use default for a given element, use:

- empty text for FontArray

- -1 for StyleArray

- 0 for all other styling arrays

Example

// Display all items for this month from the appointments file 
C_DATE(vDay1ThisMth;vDay1NextMth)
  
vDay1ThisMth:= Add to date(!00/00/0000!;Year of(Current date);Month of(Current date);1) 
vDay1NextMth:= Add to date(vDay1ThisMth;0;1;0) 
QUERY([Appts];[Appts]Appt Date>=vDay1ThisMth;*) // find the appointments for this month 
QUERY([Appts]; & ;[Appts]Appt Date<vDay1NextMth) 
 // Now load the appointment data into arrays
   
 // note that each appointment item has a field for the date, item text, font, size, style, color and time. 
 // this makes loading the data and displaying it very easy to accomplish 
SELECTION TO ARRAY([Appts]Appt Date;aDates;[Appts]Item;aItems;[Appts]Item Font;\ 
 aFonts;[Appts]Size;aSizes;[Appts]Styles;aStyles;[Appts]Color;aColors;[Appts]Time;aTimes) 
// and display the data in the CalendarSet plugin area named "eMonth"
  
CS_SetArray (eMonth;"aDates";"aItems";"aFonts";"aSizes";"aStyles";"aColors";"aTimes") 

CS_SetBanrArray

(AreaRef; StartDateArray; EndDateArray; TextArray; FontArray; SizeArray; StyleArray; ForeColorArray; BackColorArray)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ StartDateArray text start dates for each banner
→ EndDateArray text end dates for each banner
→ TextArray text text for each banner
→ FontArray text font for each banner
→ SizeArray text size for each banner
→ StyleArray text style for each banner
→ ForeColorArray text foreground color for each banner
→ BackColorArray text background color for each banner

CS_SetBanrArray allows you to specify the arrays that are used to draw the banners that are displayed in the calendar.

The arrays are passed in quotes, which is why the parameter type is text. The size, style, foreground color, and background color arrays are of type integer.

Note: modifying the banner arrays doesn’t require reissuing CS_SetBanrArray, but you must call Area_Refresh.

StartDateArray — Text (name of a date array). The referenced array is used to define the start date for each banner.

EndDateArray — Text (name of a date array). The referenced array is used to define the end date for each banner.

TextArray — Text (name of a text array). Used to define the text of the banners to be displayed.

Note: StartDateArray, EndDateArray and TextArray are required (otherwise no banners will be displayed).

FontArray — Text (name of a text array). The referenced array contains the fonts to display each corresponding banner.

SizeArray — Text (name of a numeric array). The referenced array is used to specify the font size of the text for each corresponding banner.

StyleArray — Text (name of a numeric array). The referenced array is used to specify the style (plain, bold, italic, etc.) of the text for each corresponding banner.

ForeColorArray — Text (name of a numeric array). The referenced array is used to specify the foreground color for each banner. Each item in the color array allows you to specify the color from the Color table.

BackColorArray — Text (name of a numeric array). The referenced array is used to specify the background color for each banner. Each item in the color array allows you to specify the color from the Color table.

See CS_SetArray regarding default values and omitting styling arrays.

Example

CS_SetBanrArray (eMonth;"aStDates";"aEnDates";"aItemTexts";"aFonts";"aSizes";"aStyles";\ 
"aForeColors";"aBackColors")

CS_SetBanrOpts

(AreaRef; AllowBannerSelect; AllowBannerResize)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ AllowBannerSelect integer allow selection of banners
→ AllowBannerResize integer allow resizing of banners

CS_SetBanrOpts is used to control whether banners are selectable and/or resizable. You can detect the selection of a banner using CS_GetEvtSelect. You can detect that a banner has been resized using CS_GetResizBanr.

AllowBannerSelect — Integer, 0 or 1. Use this parameter to allow or disallow the selection of banners.

Mode Value Constant
No bannner selection allowed 0 CS_Banner_NoSelect
Single banner select 1 CS_Banner_Select

AllowBannerResize — Integer, 0 or 1 Use this parameter to allow or disallow the resizing of banners.

Mode Value Constant
Banner resizing not allowed 0 CS_Banner_NoResize
The user will be able to resize banners by clicking on either of the 1 CS_Banner_Resize banner’s flags and dragging to a new date 1 CS_Banner_NoResize

Default values

If CS_SetBanrOpts is not used, both AllowBannerSelect and AllowBannerResize default to 1. If CS_SetBanrOpts is used, both default to 0 (if the parameter is not used).

Examples

//Allow banner selection, allow banner resizing 
CS_SetBanrOpts(eCalArea;CS_Banner_Select;CS_Banner_Resize) 
// No banner selection, no banner resizing 
CS_SetBanrOpts(eCalArea;CS_Banner_NoSelect;CS_Banner_NoResize)

CS_SetCalColor

(AreaRef; CalForeColor; CalBackColor)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ CalForeColor integer color of calendar unused days
→ CalBackColor integer color of calendar background

CS_SetCalColor is used to set the foreground and background color of the calendar. The unused days (those outside the date range defined using CS_SetRange) are drawn in the foreground color. The entire background of the calendar is shown in the background color.

CalForeColor — Integer. Refer to the Color table. The default is palette index 193.

CalBackColor — Integer. Refer to the Color table. The default is palette index 195.

Examples

// Unused days color blue, background color very light gray 
CS_SetCalColor(eCalArea; CS_Color_Blue;241) 

CS_SetDayStyle

(AreaRef; TargetDate; DayFont; DaySize; DayStyle; DayColor; ClearOthers)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ TargetDate date date to change the font info
→ DayFont text font name for the day number
→ DaySize integer font size for the day number
→ DayStyle integer font style for the day number
→ DayColor integer font color for the day number
→ ClearOthers integer clear custom info for all other days

CS_SetDayStyle allows you to change the font and style of the day number for any of the days in the calendar. You specify the date to be changed, as well as the font, size, style, and color for that date.

TargetDate — Date. This parameter specifies the date that the command will act on. The TargetDate does not have to be part of the currently displayed date range.

DayFont — Text. This parameter specifies the font to use for TargetDate.

DaySize — Integer. This parameter specifies the font size to use for TargetDate.

DayStyle — Integer. This parameter specifies the font style to use for TargetDate.

DayColor — Integer. This parameter specifies the foreground color to use for TargetDate. Refer to the Color table possible color values.

ClearOthers — Integer. Use this parameter to specify whether or not you want the special font info cleared for all other days in the calendar. This is useful if you just want to have one day using special font info.

Example

// Display the current date in Times 12 point bold, black color 
// set all other days to the default style 
//CS_SetDayStyle// (eCalArea; Current date; "Times"; 12; 1; 0; 1) 

CS_SetDayStyleB

(AreaRef; DateArray; DayFont; DaySize; DayFace; DayColor; ClearOthers)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ DateArray date array date to change the font info
→ DayFont text font name for the day number
→ DaySize integer font size for the day number
→ DayStyle integer font style for the day number
→ DayColor integer font color for the day number
→ ClearOthers integer clear custom info for all other days

CS_SetDayStyleB is identical to CS_SetDayStyle except that it accepts a date array (instead of a date variable) as the second argument.

It applies the specified style to all days in the array.

Example

// Show all days with appoints (contained in array aDates) as Palatino 10 point bold italic, black color 
// don’t clear other day formatting
  CS_SetDayStyleB (eCalArea; aDates; "Palatino"; 10; 3; 0; 0) 

CS_SetEventOpts

(AreaRef; AllowEventSelect; ShowWordWrap; EventMarker; ShowEventTime)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ AllowEventSelect integer allow selection of events
→ ShowWordWrap integer word-wrap event text
→ EventMarker integer character to mark each event
→ ShowEventTime integer show times next to events

CS_SetEventOpts is used to control whether events are selectable, word-wrapped, and the marker character to use (if any) for each event.

AllowEventSelect — Integer, 0 or 1. Use this parameter to allow or disallow the selection of events.

Mode Value Constant
No event selection 0 CS_EventSelect_None
Single event selection 1 CS_EventSelect_Single

ShowWordWrap — Integer, 0 or 1. Use this parameter to word-wrap the text of an event to fit within a day. If word-wrapping is not enabled, then event text will be truncated on the right edge of each day.

Mode Value Constant
No word wrapping will be performed 0 CS_WordWrap_Off
Word wrapping will be performed on all events 1 CS_WordWrap_On

EventMarker — Integer. 0, 1 or 2. This parameter is used to control the symbol that is shown to the left of the event text. The symbol is used to help the user distinguish different events (useful when ShowWordWrap is 1).

Mode Value Constant
No marker 0 CS_Marker_None
Bullet 1 CS_Marker_Bullet
Dash 2 CS_Marker_Dash

ShowEventTime — Integer. 0 or 1. This parameter is used to display the times associated to the events. This feature requires that a TimeArray has been set using the CS_SetArray command.

Mode Value Constant
Don't show event times (even if a time array has been set) 0 CS_EventTime_Hide
Show event times (provided that a time array has been set) 1 CS_EventTime_Show

Default values

If CS_SetEventOpts is not used, all parameters following AreaRef default to 0. If CS_SetEventOpts is used, all default to 0 (if the parameter is not used).

Examples

//Allow event selection, word-wrap event text, mark events with bullet, don't show event times
CS_SetEventOpts(eCalArea;CS_EventSelect_Single;CS_WordWrap_On;CS_Marker_Bullet;CS_EventTime_Hide) 
// No event selection, word-wrap event text, mark events with dash, show event times 
CS_SetEventOpts(eCalArea;CS_EventSelect_None;CS_WordWrap_On;CS_Marker_Dash;CS_EventTime_Show) 

CS_SetEvtSelect

(AreaRef; Type; EventIndex)

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

CS_SetEvtSelect is used to procedurally select events or banners. 
Type — Integer, 1 or 2. Use this parameter to specify if you are selecting events or banners.

Mode Value Constant
Event 1 CS_Type_Event
Banner 2 CS_Type_Banner

EventIndex — Integer. Index within the array that was passed to CalendarSet via either CS_SetArray or CS_SetBanrArray.

Use CS_GetEvtSelect to determine what event or banner was selected by the user.

Examples

// Set the first event to be selected 
CS_SetEvtSelect(eCalArea;CS_Type_Event;1) 
// Set the third event to be selected 
CS_SetEvtSelect(eCalArea;CS_Type_Event;3) 
// Set the fourth banner to be selected 
CS_SetEvtSelect(eCalArea;CS_Type_Banner;4) 

CS_SetIconArray

(AreaRef; DateArray; IconArray; SizeArray)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
→ DateArray text date for display of each icon
→ IconArray text picture library numbers for each icon
→ SizeArray text size for each icon

CS_SetIconArray is used to specify the array that is used to display icons in each of the days. DateArray, IconArray, and SizeArray are the names of the arrays, enclosed in quotes.

Note : calling CS_SetIconArray after making changes to the icon arrays is more effective than Area_Refresh.

DateArray — Text. This parameter is the name of a date array, and is used to define which days that you want icons displayed on.

IconArray — Text. This parameter is the name of an integer array and specifies the 4D picture library IDs of the icons to display. The icons specified in IconArray must be stored in the picture library. There can be, at most, one icon per day in a calendar.

SizeArray — Text. This parameter is the name of an integer array and specifies the length in pixels of the side of the frame in which each icon will be drawn (scaled proportionally, centered). The following values are allowed:

Mode Value Constant
Best Size — CalendarSet will draw the size that fits best depending on the available space in the day cell 0 CS_Icon_Best
Small Icons (16 x 16) 16 CS_Icon_Small
Large Icons (32 x 32) 32 CS_Icon_Large

Examples

SELECTION TO ARRAY([Dates]Appt Date;aIconDates;[Dates]Icon ID;aIconIDs;[Dates]Icon Size;aIconSizes) 
// The icon info is in the arrays aIconDates, aIconIDs, and aIconSizes 
CS_SetIconArray(eCalArea;"aIconDates";"aIconIDs";"aIconSizes") 
//Add icon #2118 from the 4D picture library to the date 4/12/2015 within a 32 x 32 pixels square 
$Position:=Find in array(aIconDates;!04/12/2015!) //see if the date is already in the appointment dates list 
If ($Position=-1) // not there yet 
 APPEND TO ARRAY(aIconDates;!04/12/2015!) // let's add it 
 $Position:=Size of array(aIconDates)
   
 ARRAY INTEGER(aIconIDs;$Position)
   
 ARRAY INTEGER(aIconSizes;$Position) 
End if 
aIconIDs{$Position}:=2118 
aIconSizes{$Position}:=CS_Icon_Large 
Area_Refresh (eCalArea) 

CS_SetRange

(AreaRef;StartDate;EndDate)

Parameter Type Description
→AreaRef longint area reference of the CalendarSet area
↔ StartDate date the first date to be displayed in the calendar
↔ EndDate date the last date to be displayed in the calendar

CS_SetRange tells CalendarSet the date range to display. The date range will default to the current month if this command is not used.

Note : StartDate and EndDate are input / output parameters as explained below.

StartDate — Date. This value will set the first date for the Calendar. Pass a variable to retrieve the current value.

Note : an invalid value to StartDate will set it to the first day of the current month.

EndDate — Date. This value will set the last date for the Calendar. Pass a variable to retrieve the current value.

Pass a value of !00/00/00! to have CalendarSet set EndDate to be the last day of the month specified in StartDate.

Note : if StartDate is after EndDate the values are exchanged.

The current selection of cells may be lost when this command is called: the selected days will be cleared when StartDate is modified or the number of weeks is changed (calling CS_SetRange with current values for StartDate and EndDate will not clear the selection). To maintain the selection, use CS_GetSelect prior to calling CS_SetRange, and CS_SetSelect afterward.

Examples

Set the calendar to display the month of March, 2015 (MM/DD/YY format):

CS_SetRange (eCalArea;!03/01/2015!;!00/00/00!) 

Get the starting and ending dates of the currently displayed calendar:

CS_SetRange (eCalArea;vStartDate;vEndDate) 

CS_SetSelect

(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 selection is contiguous, 0 if not
→ DaysArray integer array of currently selected items

CS_SetSelect sets the current selection of the calendar. This is the opposite action of CS_SetSelect.

StartDate — Date. This parameter specifies the first day to highlight.

EndDate — Date. This parameter specifies the last day to highlight. All days between and including StartDate and EndDate will be highlighted if Contiguous is 1.

Contiguous — Integer.

Mode Value Constant
The current selection is set to be each of the days that are specified in DaysArray 0 CS_Sel_Discontiguous
The current selection is set to the range StartDate to EndDate 1 CS_Sel_Contiguous

DaysArray — Date array. This parameter is used to pass a list of discontiguous days you wish to select (highlight).

Example

// Highlight the current date
  
ARRAY DATE(aDate;0)
  
C_DATE(vStart;vEnd)
  
vStart:=Current date
  
vEnd:=vStart
  
CS_SetSelect (eCalArea;vStart;vEnd;1;aDate) 
// Highlight the first three days of March 2015 (MM/DD/YY format) 
CS_SetSelect(eCalArea;!03/01/15!;!03/03/15!;CS_Sel_Contiguous;aDate) 
// Highlight the 1st and 15th of May 2015 (MM/DD/YY format):
  
ARRAY DATE(aDate;2)
  
aDate{1}:=!05/01/15!
  
aDate{2}:=!05/15/15! 
CS_SetSelect(eCalArea;!00/00/00!;!00/00/00!;CS_Sel_Discontiguous;aDate) 

configuring_calendarset.txt · Last modified: 2017/08/17 17:46 by cs_admin