[Showcase] myCalendar module

Thomas Hertzler
Tango One Software, Inc.

What is myCalendar?

The module yak_myCalendar replaces the swing calendar component. It will open it's own window, when invoked but you should also be able of making it a permanent fixture on your main form via a tab-less tabpanel.

I have tried to design the calendar to where input can be made quickly an reliably. myCalendar can return a full DATETIME object or one where the time portion is zeroed out. Every element can be changed by you in designer, the reason I didn't use HTML. So if you don't like the layout feel free to make changes.

I am sure that other developers have started making modules in Servoy and hopefully we'll soon have a library of ready-made problem solvers.

Legal

1. The module yak_cal_myCalendar is 'free' as in 'free' beer. Free to use, free to copy.
2. Do whatever you want with it. If you use it, mention it in the credits.
3. Make improvements available to the community.

Naming conventions

Global references (variables and methods) for this module start with 'yak_cal_', where 'yak' is the 3 letter unique identifier for Tango One Software, registered via EBAY for the sum of EUR 2,000.00 on January 24th (*). 'cal' stands for calendar - I like to keep it simple.

Requirements

• Servoy 2.2b3 or higher
• Font 'Tahoma' installed.
• Access to DB Server 'example_data'

Installation

Import module into repository including sample data.

Rigging your date fields

1. Place a button next to the date field you want to serve. Label it '...' to be consistent with the widget of displayType 'CALENDAR'. Or whatever...
2. Name the button after the dataProvider property of the date field. Example: If the dataprovider for the date field is 'dob', name the button 'dob'. This is CRITICAL.
3. Connect method globals.yak_cal_myCalendar(KB) to the 'onAction' property of that button.
4. That's it.

METHOD/FORM: yak_cal_myCalendar:

This is a visual calendar. It is intended for mixed keyboard and mouse data entry.

The left and right arrow buttons decrease or increase time by 1 month.

Hold SHIFT while clicking the arrows and time will decrease or increase by 1 year.

Hold CTLR while clicking the arrows and time will decrease or increase by 10 years.

The '=' button sets the calendar to the current date and time. Selecting a day will send the focus to the hour field so you can start typing the hour. Then TAB for minutes.

Of particular interest are the three exit button AM|PM|DT. AM & PM will return the full dateTime, while DT will only return the date portion, erasing hours and minutes. Seconds and milliseconds are always zeroed out.

Note that once you start entering the time the mouse is no longer required. You can TAB to minutes, AM|PM|DT, hit enter and be done.

myCalendar validates hours and minutes. The application will beep and a message will be displayed in the status bar when hours or minutes are out of bounds. Hours between > 12 and < 24 will be accepted along with a warning in the statusbar but normalized to AM/PM.

The user will still have to use the AM|PM buttons to decide whether the time is AM or PM!

If the date field that you want to populate is empty, myCalendar will initialize with the last valid dateTime entry. That way the user can quickly create dates that are in succession.

METHOD/FORM: yak_cal_myCalendarKB:

All data entry can (and should) be done via the keyboard. The quickest way to get the actual date and time into your date field is to hit ENTER and then CTRL-ENTER. For every other data change you will TAB from left to right and leave via DT|AM|PM, which work as above.

Remind yourself and your customers that SHIFT-TAB goes back in the tab-sequence. There really is no need to use the mouse here.

ESC will cancel data entry and close the calendar. Default values and validation work analog to the visual calendar.

METHOD/FORM: yak_cal_Documentation:

Contains a copy of this text for your convenience.

Limitations:

* No 24h / military time support, yet.

* Has not been tested on Mac OS X and Linux. OS X will need a different styles. That's next.

* I would like to place the calendar relative to the date field and/or remember its last position.

Unfortunately Servoy's support for window coordinates is incomplete at this point in time.

* Be aware that if you use icons instead of the (ugly) buttons, Servoy will not recognize modifier keys (CTRL|SHIFT) when 'showClick' is disabled. I have reported this anomaly to the respective forum. Hopefully this will get fixed soon. Hint, hint.

* myCalendar should work fine for dates since 1900 and higher. I suggest you run your own boundary tests and verify min-max dates with an Outlook or iCal calendar.

Here is some excellent reading for those who question my cautionary note:

http://webexhibits.org/calendars/

* Probably lot's of stuff I haven't thought about yet.

* Send comments to thertzler@mac.com.

(1) That's a joke.