Click above to get retro games delivered to your door ever month!

Function:    CALENDAR()

Purpose:     Pop up a configurable calendar on the screen

Syntax:      CALENDAR( [ date [, colors  [, row [, column ] ] ] ] )

Arguments:   date        - Optional date onto which to position the
                           cursor.

             colors      - Optional array of character strings specifying
                           the color settings to use.  The colors used for
                           the different parts of the on screen calendar
                           are specified as follows:

                           color[1] -  Calendar box and headers
                           color[2] -  Current day marker, (the cursor)
                           color[3] -  Day numbers inside the calendar

             row         - Optional numeric top row of the calendar.
                           Valid rows are from row 0 to row 10.  If not
                           specified or an invalid row value is given, the
                           default row is 1.

             column      - Optional numeric left column of the calendar.
                           Valid columns are from column 0 to column 56.
                           If not specified or an invalid column value is
                           given, the default column is 56.

Returns:     The date selected by pressing ENTER, or an EMPTY date if
             Escape was pressed.

Description: Function to provide a pop up calendar from which to select a
             date.  Typical uses are to provide pop-up help for entering
             dates in date fields.  The example below shows how this can
             be done.  Other uses would include a global SET KEY procedure
             to invoke a procedure that calls CALENDAR().  This provides
             the end user with a handy reference calendar at any time.
             The calendar display is 15 rows tall and 24 columns wide, and
             appears as:

                         +----------------------+
                         |      November  1990  |
                         |----------------------|
                         |  S  M  T  W  T  F  S |
                         |              1  2  3 |
                         |  4  5  6  7  8  9 10 |
                         | 11 12 13 14 15 16 17 |
                         | 18 19 20 21 22 23 24 |
                         | 25 26 27 28 29 30    |
                         |                      |
                         |----------------------|
                         |  Day   Month   Year  |
                         |  . .   PgUp    ^PgUp |
                         |  . .   PgDn    ^PgDn |
                         +----------------------+

             CALENDAR() is fairly perpetual inasmuch as Clipper's date
             routines are.  The screen calendar can be moved and
             CALENDAR() will remember the last screen location the next
             time it is invoked (during an application session).  The
             default location of the calendar is in the upper right hand
             corner of the screen @ 1,56.

Notes:       CALENDAR() will not handle dates beyond 2999.  If the color
             string is not provided, the current color setting will be
             used to determine the Standard and Enhanced colors, and
             BRIGHT() will be used to create the color used for the
             calendar numbers inside the box.

             If you provide row,column parameters, CALENDAR() will
             position to that location regardless of where the user may
             have moved it with the control-arrow keys.

             CALENDAR() handles the following keys as follows:

             Date positioning keys:            
             Up          - Back one week
             Down        - Forward one week
             Left        - Back one day
             Right       - Forward one day
             PgUp        - Back one month
             PgDn        - Forward one month
             Ctrl-PgUp   - Back one year
             Ctrl-PgDn   - Forward one year


             Calendar screen placement keys    
             Ctrl-Up     - Move up one row
             Ctrl-Down   - Move down one row
             Ctrl-Left   - Move left one column
             Ctrl-Right  - Move right one column

             The <colors> argument may optionally be a SETCOLOR() style
             color string where the 1st, 2nd, and 3rd colors correspond to
             the Standard, Enhanced and Unselected color positions
             respectively.  This permits an in-line call to CALENDAR() to
             take the form CALENDAR(DATE(),"R/W,W/R,,R+/W") which can
             simplify having to declare an array just to pass color
             settings.

Example:     *-- set key procedure to provide F1 pop-up date help in READs
             PROCEDURE MyHelp
             PARAMETERS callproc, linenum, readvar
             PRIVATE temp
             SET KEY 28 TO                 && disable help while in help
             IF TYPE(readvar) = "D"        && if variable is a date type
                temp = CALENDAR(&readvar)  && pop up the calendar
                IF .NOT.  EMPTY(temp)         && if a date was selected
                   &readvar = temp         &&  assign to the readvar
                ENDIF
             ENDIF
             SET KEY 28 TO MyHelp          && turn help back on
             RETURN

Source:      RL_CALEN.PRG

See also:    STR2DATE()