CALENDAR

A Calendar control looks like a monthly calendar. It displays all of the days in one particular month. The user can click upon a day to select it. He can also advance to the next month(s), or go to the previous month(s). Alternately, a Calendar control can be used to select a range of contiguous days.


Uses

A Calendar control is useful for letting the user select a date, or a range of days.


Styles

Shortcut The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut.

A CALENDAR can have any, all, or none of the following styles:

Select Range (MULTI) Allows the user to select a range of days. By default, the maximum range is one week. You can change the maximum range that can be selected by sending a SETMAXSELCOUNT message.
Day state (STATE) The control generates GETDAYSTATE events to request information about which days should be displayed in bold.
No Today (NOTODAY) Doesn't display the "today" date at the bottom of the control.
No Circle (NOCIRCLE) Doesn't circle the "today" date.
Week numbers (WEEK) Displays week numbers (1-52) to the left of each row of days. Week 1 is defined as the first week that contains at least four days.
No Sibling (NOSIBLING) Prevents this control from drawing into any overlapping controls.
Group Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins). For example, to make a group of radio buttons function properly, the first radio button should have the GROUP style, and the subsequent buttons must not.
Tabstop The user can move to this control using the TAB key.
Disabled Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement.
Hide Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement.
Border Has a border.


Extra styles

A Calendar can have the following extra styles:

Quiet Do not report any events for this control.
Modal Frame (MODALFRAME) Has a double border.
Static Edge (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input.
Client Edge (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge.
Accept files (FILES) Accepts drag-and-drop files (ie, the DROPFILES event).
Align text right (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties).
Read right-to-left (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right).
Transparent The control is to be transparent. Any controls that are beneath this one are not obscured.


Events

A Calendar generates the following events:

Event name When it occurs
SELCHANGE A new day has been selected, or the month has been advanced by the user.
SELECT A new day has been explicitly selected by the user. This is similar to SELCHANGE, but it happens only when the user makes an explicit date selection. SELCHANGE applies to any selection change.
GETDAYSTATE The control wants you to return information about which days to display in bold.
RELEASE The Calendar control is releasing mouse capture.


REXX Variable

A Calendar must have a REXX variable associated with it. Before opening the window which contains the Calendar, you must set this variable's value to the date of the day you wish selected. The date format should be the same as that returned by DATE("S").

If the Calendar has the MULTI style, then the above variable will be the starting date of the range. A second REXX variable should also be set to the ending date of the range. The variable you set to the ending date is the associated variable name with a "2" appended to it.


Dynamically add/remove a CALENDAR

You can dynamically add a Calendar to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:

CALENDAR X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator
X and Y is the position of the top left corner of the control, relative to the window's top left corner.

Width and Height are the size of the control, in pixels.

Styles and ExtraStyles are those listed above, with each style separated by a | character.

VariableName is the variable name to be associated with the control.

Accelerator is the keyboard shortcut that causes the control to be selected for user input.

Before adding a Calendar, you should set its associated REXX variable to the date of the day you wish selected. If using the MULTI style, set two variables to the start, and end, dates of the range. Here we create a Calendar control with an REXX variable name of MyDate. We select the current day.

/* Select the current day. */
MyDate = DATE("S")

/* Create the Calendar control. */
error = GuiAddCtl("CALENDAR 10,10,100,80, BORDER, CLIENTEDGE|QUIET, MyDate")

You can dynamically remove a Calendar by calling GuiRemoveCtl. Here we remove the above CALENDAR:

error = GuiRemoveCtl("MyDate")


Select a date

To select a day, first set the associated REXX variable to the date of the desired day, as shown above. Then call GuiSetCtlValue, passing that quoted variable name. Here we select the date January 10, 2005:

MyDate = "20050110"
GuiSetCtlValue("MyDate")
To unselect all days, DROP the variable:
DROP MyDate
GuiSetCtlValue("MyDate")


Query the selected date

To determine which day has been selected, call GuiGetCtlValue. This will set its associated REXX variable to the control's current selection. For example, here we query the above control's selection:
error = GuiGetCtlValue("MyDate")
IF error == "" THEN SAY "Selected date:" DATE('N', MyDate, 'S')
Note: If using the MULTI style, then two variables are set.

If there's no selection, then the rexx variable is DROP'ed.


Set today's date

To set today's date (ie, the date initially shown when the calendar is displayed), call GuiAddCtlText, passing the quoted variable name associated with the control, and today's date:

GuiAddCtlText("MyDate", DATE("S"))
Note: If you do not set today's date, the calendar control automatically opens to whatever today's date happens to be.