GRIDPLUS2 - Calendar
Home Reference Manpage Examples Download License Contact

GRIDPLUS Calendar

In order to simplify creation of screens GRIDPLUS provides a GRIDPLUS calendar command mode. This uses a simple syntax to create a calendar style date display/selection widget. The GRIDPLUS calendar can have its contents set using the gpset commands. The selected date in the GRIDPLUS calendar can be read, in the same manner as other GRIDPLUS widgets, from the "null" array -or- from a specified variable.

The starting day of the week can be specified using the -weekstart option. The default is Monday.

Navigating the Calendar

Initial

By default the calendar will initially display the current month/year. The -date option can be used to display a specified month/year when the calendar is created. The date must be in the format specified by -dateformat. The day part of the date is not used (but must be specified) unless the -selecttoday option is also specified.

Note: The current day (if in the month/year displayed) is shown with a solid black border.

Manual

By default the calendar has a navigation bar ("navbar").

To navigate the calandar, click on one of the icons in the navbar.

The current day (today), if in the month/year displayed, is shown with a solid black border.

Note: To display a calendar without a navbar use the -navbar 0 option (See Example 3).

Script

The calendar can be navigated using the gpnav command.

Syntax:-

gridplus::gpnav item ?current|month|year? ?increment?
gridplus::gpnav item date
gridplus::gpnav item {month year}

Examples

gpnav .mycal month +1

...Will navigate one month forward.

gpnav .mycal year -2

...Will navigate two years backward.

gpnav .mycal current

...Will navigate to current month/year.

gpnav .mycal current +1

...Will navigate to one month forward from current month/year.

gpnav .mycal 12/03/1963

...Will navigate to December 1963. Assuming that -dateformat is "us".

gpnav .mycal {12 1963}

...Will navigate to December 1963.

Selecting a Date and Setting the Value

By default the value of the "null" array variable associate with a calendar is null. To select a date, click on the number of the day required. The selected day is highlighted using the colours defined by -calselectcolor. The default colours are black/gray (See Example2). The value of the item is set to the selected date in the format defined by -dateformat.

It is possible, using the -variable option, to have the calendar value set in a specified variable. This can be used to have more than one calendar share the same value (See Example3).

If the -selecttoday 1 option is specfied the current date is automatically selected when the calendar is created. If the -date option is also specfied, the date specified is displayed and automatically selected.

The value of a calendar can be set using either gpset or gpselect. The value of the associated variable is set. The calendar will also "navigate" to the month/year of the specified date and the day will be highlighted.

For Example:

gpset .mycal 08/25/2009
-or-
gpselect .mycal 08/25/2009
...Will set/select August 25th 2009.

To clear the selection and the calendar value specify null as the date...

For Example:

gpset .mycal {}
-or-
gpselect .mycal {}

Using the -selectonly option it is possible to clear the selection without altering the value.

For Example:

gpset -selectonly .mycal {}
-or-
gpselect -selectonly .mycal {}

This can be used when more than one calendar share the same value (See Example 3).

Invoking a Command When Selecting a Date -or- Navigating the Calendar

The -command option can be used to specify the name of a command to be invoked when a date is selected.

The -navcommand option can be used to specify the name of a command to be invoked when a navigating the calendar to a new month/year.

Note: The calendar name, unit and increment are passed as parameters to the "navcommand" (See Example 3).

Setting Day and Month Names

Day and month names should be correct for the current locale. If this is not the case use the GRIDPLUS set command/mode to explicitly set the locale.

For Example:

gridplus set -locale de_DE

Examples

This section contains examples which illustrate the main GRIDPLUS calendar command mode features.

The following example assumes that the reader is familiar with the contents of the Grid/Layout page. Information given on that page will not be duplicated here.

Note: The examples assume that the GRIDPLUS package has already been "required" and the commands imported.


Calendar Example 1

Window:

Source Code:

gridplus calendar .mycal

gridplus layout .main -wtitle "Example" {
   .mycal
}

pack .main

Comments:

This example creates a calendar call ".mycal".

Note: The current day (today) is shown with a solid black border.


Calendar Example 2

Example to demonstrate colour and relief options.

Window:

Source Code:

gridplus calendar .mycal1
gridplus calendar .mycal2 -calcolor black/lightgray -calselectcolor white/red   -calrelief groove
gridplus calendar .mycal3 -calcolor blue/lightblue  -calselectcolor yellow/blue -calrelief solid

gridplus layout .main -wtitle "Example" {
   .mycal1 .mycal2 .mycal3
}

pack .main

Comments:

This example creates three calendars:-

".mycal1" uses the default option values.

".mycal2" uses the -calcolor black/lightgray option to set the calendar to have black text on a light gray background. The -calselectcolor white/red option sets the colour of the selected date to have white text on a red background. The -relief groove option gives the calendar a groove style border.

".mycal3" uses the -calcolor blue/lightblue option to set the calendar to have blue text on a light blue background. The -calselectcolor yellow/blue option sets the colour of the selected date to have yellow text on a blue background. The -relief solid option gives the calendar a solid style border.

Note: Day "18" has been manually selected in each of the calendars to show the effect of the -calselectcolor option.


Calendar Example 3

Example to demonstrate how two calendars can be controlled by one navbar. The navbar in the top calendar navigates both calendars such that the bottom calendar is one month in advance of the top calendar. Both calendars are associated with the same -variable so that the pair of calendars have one value.

Window:

Select day "10" in the "July" calendar...

Navigate one month forward...

Source Code:

#==================================#
# Command invoked as "-navcommand" #
#==================================#

proc navigate {name unit {increment +1}} {
   gpnav .mycal2 $unit $increment
}

#==========================#
# Create/display calendars #
#==========================#

gridplus calendar .mycal1 -command "gpset -selectonly .mycal2 {}" -variable mydate -navselect 1 -navcommand navigate
gridplus calendar .mycal2 -command "gpset -selectonly .mycal1 {}" -variable mydate -navselect 1 -navbar 0

gpnav .mycal2 month +1

gridplus layout .main -padding 0 -pad 0 -wtitle "Example" {
   .mycal1
   .mycal2
}

pack .main

Comments:

proc navigate {name unit {increment +1}} {
   gpnav .mycal2 $unit $increment
}

Defines a procedure called "navigate", which will be invoked as the -navcommand for ".mycal1" (See below). The purpose of this procedure is to keep ".mycal2" one month ahead of ".mycal1".

The -navcommand procedure is passed three parameters: The name of the calendar invoking the -navcommand, The navigation unit (current|month|year) and the value of the increment (Which will be either "+1" for a "next" arrow -or- "-1" for a "previous" arrow.)

The -navcommand is invoked by the navbar on ".mycal1". As this procedure is to navigate ".mycal2" so as to be one month ahead of ".mycal1", the name is not required. The value of the increment has a default of "+1" as the increment value is not passed when the unit is "current".

gridplus calendar .mycal1 -command "gpset -selectonly .mycal2 {}" -variable mydate -navselect 1 -navcommand navigate

Creates a calendar called ".mycal1".

The procdure specified by the -command option ("gpset -selectonly.mycal2 {}") is invoked when a day is selected. This command clears the selection in the other (".mycal2") calendar. The "-selectonly" option specifies that only the display selection is cleared, the value of the associated calendar value variable is left unchanged.

The -variable mydate option specifies that the value date selected in the calendar be set in the "mydate" variable rather than the default. This variable is shared by ".mycal2".

The -navselect 1 option specifies that when the calendar is navigated so that the month/year displayed is the same as that for the date value of the variable associated with the calendar, the day of the date value with automatically be selected in the calendar display.

-navcommand navigate option specifies that a procedure called "navigate" should be invoked when a navbar icon is selected.

gridplus calendar .mycal2 -command "gpset -selectonly .mycal1 {}" -variable mydate -navselect 1 -navbar 0

Creates a calendar called ".mycal2".

The procdure specified by the -command option ("gpset -selectonly .mycal1 {}") is invoked when a day is selected. This command clears the selection in the other (".mycal1") calendar. The "-selectonly" option specifies that only the display selection is cleared, the value of the associated calendar value variable is left unchanged.

The -variable mydate option specifies that the value date selected in the calendar be set in the "mydate" variable rather than the default. This variable is shared by ".mycal1".

The -navselect 1 option specifies that when the calendar is navigated so that the month/year displayed is the same as that for the date value of the variable associated with the calendar, the day of the date value with automatically be selected in the calendar display.

-navbar 0 option specifies that the navbar is not displayed for this calendar.

gpnav .mycal2 month +1

Sets the initial display of ".mycal2" to be one month ahead of the current month.

gridplus layout .main -padding 0 -pad 0 -wtitle "Example" {
   .mycal1
   .mycal2
}

Creates a layout called ".main" to display the calendars one above the other.

pack .main

Packs the ".main" layout.

Reading and Setting GRIDPLUS Calendar Values

The values of the GRIDPLUS widgets are stored in a global array with a null name.

For Example:

global {}

For GRIDPLUS calendar widgets the array element has the same name as the widget frame: Thus the value of ".mycalendar" is referenced as "$(.mycalendar)".

The recommended method to set GRIDPLUS calendar values is to use either gpset or gpselect (See a Selecting a Date and Setting the Value).


Copyright © 2013 Adrian Davis.