jsDatePicker Description

jsDatePicker Design and Description

The following is a brief description of basic overall operation and design of the jsDatePicker 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 jsDatePicker. In reality, jsDatePicker 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, jsDatePicker 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 jsDatePicker 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 jsDatePicker at runtime. The form.metric setting is checked at runtime in jsDatePicker.onOpen and if form.metric # 6, the jsDatePicker object will release itself.

At runtime, a jsDatePicker object is really a cluster of 2 objects - a PaintBox and a datetimepick window. During onOpen, jsDatePicker creates a datetimepick window which is parented to the jsDatePicker PaintBox and positioned and sized the same as the jsDatePicker 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 jsDatePicker PaintBox. On top is the datetimepick window.

Also during OnOpen, The appropriate message hooks are set between the datetimepick window and the jsDatePicker PaintBox which allows all mouse and keyboard input received by the datetimepick window to be passed forward to the jsDatePicker PaintBox. This allows the jsDatePicker dBL PaintBox object to directly receive mouse click and move messages and keyboard messages. Hooks are also set to allow the jsDatePicker PaintBox to receive notification messages from the datetimepick window. These notification messages indicate user actions such as when the user selects an item. The jsDatePicker class receives the datetimepick 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 datetimepick window.

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

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

Because the jsDatePicker class is, in the most simple definition, a dBL 'wrapper' for the operating system's datetimepick window class, the most authoritative resource for information regarding datetimepick 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 datetimepick.

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