jsCalendar Description

jsCalendar Design and Description

The following is a brief description of basic overall operation and design of the jsCalendar dBL class. Don't worry if you don't clearly understand what is described. Simply read it for purposes of 'awareness'. Much of the following will become clearer as you become familiar with using jsCalendar. In reality, jsCalendar is quite simple to use. What follows is a small attempt to satisfy those who want to know 'just a bit more'.

At design time in the Form Designer, jsCalendar consists of a single PaintBox subclass. It can be placed on a Form, a SubForm, a Container, or a NoteBook. Simply ensure that the form's metric property is set to 6 - Pixels, select the jsCalendar class on the Component Palette, and drop it anywhere on the Form, Container, or NoteBook, or instantiate it as you would any other class within a SubForm. The form.metric property *must* be set to 6 - Pixels for proper function of jsCalendar at runtime. The form.metric setting is checked at runtime in jsCalendar.onOpen and if form.metric # 6, the jsCalendar object will release itself.

At runtime, a jsCalendar object is really a cluster of 2 objects - a PaintBox and a monthcal window. During onOpen, jsCalendar creates a monthcal window which is parented to the jsCalendar PaintBox and positioned and sized the same as the jsCalendar object. In effect, we now have 2 objects stacked directly on top of each other. At the bottom, directly on the surface of the form or container, is the jsCalendar PaintBox. On top is the monthcal window.

Also during OnOpen, The appropriate message hooks are set between the monthcal window and the jsCalendar PaintBox which allows all mouse and keyboard input received by the monthcal window to be passed forward to the jsCalendar PaintBox. This allows the jsCalendar dBL PaintBox object to directly receive mouse click and move messages and keyboard messages. Hooks are also set to allow the jsCalendar PaintBox to receive notification messages from the monthcal window. These notification messages indicate user actions such as when the user selects an item. The jsCalendar class receives the Calendar notifications through the OnMiddleMouseUp event, filters the notification message values, and fires custom events, which allows the dBL developer the ability to respond to events which occur in the monthcal window.

The remaining function of the jsCalendar object is to serve as the dBL 'bridge' between the application dBL code and the monthcal window via the windows API. Through many properties and methods, the advanced functionality of the monthcal window can be directly exploited using relatively simple dBL application code. To understand 'why' there are so many properties and methods in jsCalendar and to understand how to best use and take full advantage of jsCalendar, it would help to first understand some basic terminology and the underlying Calendar technology.

The monthcal window is a message-based window rather than a function-based window. All Calendar functionality is implemented via messages sent to the monthcal window. Some of these messages use complex data structures to pass information to and from the monthcal window. The jsCalendar class implements methods (functions) which provide wrappers for the messages and structures. Each method encapsulates a specific message supported by the Calendar window by creating and filling any necessary data structures, sending the appropriate message to the monthcal window, and then retrieving any returned data as necessary from the associated data structures, and setting values to appropriate properties of the jsCalendar object as necessary for subsequent use in dBL code.

Because the jsCalendar class is, in the most simple definition, a dBL 'wrapper' for the operating system's monthcal window class, the most authoritative resource for information regarding Calendar technology, operation, and reference can be found at MSDN online under Individual Control Reference. Also, be sure to search MSDN for other information and examples of using Calendar.

But most of all, be sure to read the remaining jsCalendar documentation. And review the dBL sample forms included with the jsDateTime package to become more familiar with how jsCalendar can be used in dBL applications.