Table of Contents
Configuring CalendarSet
Using the Advanced Properties Dialog
Warning: this interface is only maintained for compatibility with old versions of CalendarSet (v3). When used, CalendarSet will run in compatibility mode, which can affect the behavior. To delete the area's advanced properties hit the “Clear & Save” button.
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 Selection and Resizing
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 |
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)