Added May 2016
xcall XCALEN, idate, xcdates(), exitcode, xcflags, sr, sc, title, sdate, edate {,coldef, xcflags}
XCALEN.SBX is an XTREE-based implementation of a calendar control featuring the following extensions beyond what is available in the standard Month Calendar Control. The extensions can:
| • | Apply different colors and font effects to each date, whereas the standard Month Calendar is limited to marking selected dates in bold. |
| • | Store text associated with each cell that can be displayed as a tooltip. |
Source, samples and related functions can be found in SOSLIB:[907,49].
Sample Images
Parameters
xcdates() (ST_XCALEN) [in]
DIMX-allocated array of individual dates of interest to mark on the calendar. Dates do not have to be in order. There is no particular limit to the number of dates in the array, but only one element per date is recognized, and there is no particular value to dates that all outside the range set by sdate,edate. When the calendar is displayed, dates for which there is an element in the xcdates() array will be shown with a "+" beside the day number, and will be given the background color specified in the BG field of the ST_CALEN element; see sample images. The ST_CALEN structure is defined—in ASHINC:XCALEN.DEF—as follows:
defstruct ST_XCALEN
map2 DATE,B,3 ! standard (ODTIM/IDTIM) separated date
map2 BG,B,4 ! BackGround color (RGB value)
map2 MARK,B,2 ! various indicator flags (not yet defined.)
map2 COMMENT,s,1024 ! text
endstruct
The COMMENT field may contain up to 1024 bytes of free-format text to associate with the date. The text is displayed as a tooltip when the mouse hovers over the date; see sample images.
idate (B,4) [in]
initial date to select in calendar. Standard ODTIM/IDTIM format.
exitcode (Signed Num) [out]
Exit code indicating how control was exited:
Code |
Meaning |
|---|---|
-20001 |
Use clicked 'X' to close calendar |
-20002 |
Out of range, navigating to previous month |
-20003 |
Out of range, navigating to next month |
-20004 |
User clicked date |
-sr, sc (Num) [in]
Initial upper left corner of dialog in standard row/col units or in millirows and millicols.
title (String) [in]
Title (caption) for dialog. Ignore if the XCALF_NOCAPTION flag set in xcflags.
sdate, edate (B,4) [in]
Starting/ending date of range to allow for navigation. Standard ODTIM/IDTIM format. When user tries to navigate outside this range, routine returns exitcode -20002 or -20003.
coldef (String) [in]
Optional Advanced Coldef Options to be appended to the one automatically built. Allows you to customize the behavior of the control based on the capabilities of XTREE. Note that since the coldef string may grow quite large, and be frequently added to, you should probably use a dynamic string (s,0), lest you end up wasting time tracking down errors due to the string being truncated.
xcflags (B,4) [in]
Optional flags as defined in ASHINC:XCALEN.DEF:
Symbol |
Value |
Description |
|---|---|---|
XCALF_NOCAPTION |
&h0001 |
Eliminate caption bar from dialog |
XCALF_ARCEDIT |
&h0002 |
Allow right click to edit text for date; see comments |
XCALF_EDIT |
&h0004 |
Edit text for the current date |
Requirements
Two icon files, nav_left_24.png and nav_right_24.png are used for the left/right navigation arrows and must be stored in the %miame%/icons subdirectory of the client workstation. You can replace them with any 24x24 png images using the same file names.
Comments
Each call to the XCALEN.SBX routine scans the xcdates() array, creates the control, and then puts the focus on the calendar grid, allowing the user to navigate between months (up until the limit set by the starting/ending dates specified in the sdate,edate parameters). If allowed by the XCALF_EDIT flag, the user can right-click a date to edit the text associated with it. Or they can exit from the calendar mode by generating just about any other exitcode (i.e. ESC or click on another control). On return from the subroutine, the calendar control is still visible, so you can leave it on the screen for visible reference.
Aside from the XTREE customization possible via the coldef parameter, further customization would probably require making a copy of XCALEN.BP in SOSLIB:[907,49] and modifying it directly for your purposes.
Other than the internal ability to edit the text for a date, responsibility for maintaining the array of date information (text and colors) is purely on the programmer and outside the realm of XCALEN.SBX.
History
2016 March, A-Shell 6.3.1507: Routine added to A-Shell
