jsTimePicker Description

jsTimePicker Design and Description

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

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

Also during OnOpen, The appropriate message hooks are set between the datetimepick window and the jsTimePicker PaintBox which allows all mouse and keyboard input received by the datetimepick window to be passed forward to the jsTimePicker PaintBox. This allows the jsTimePicker dBL PaintBox object to directly receive mouse click and move messages and keyboard messages. Hooks are also set to allow the jsTimePicker PaintBox to receive notification messages from the datetimepick window. These notification messages indicate user actions such as when the user selects an item. The jsTimePicker 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 jsTimePicker 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 jsTimePicker and to understand how to best use and take full advantage of jsTimePicker, 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 jsTimePicker 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 jsTimePicker object as necessary for subsequent use in dBL code.

Because the jsTimePicker 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 jsTimePicker documentation. And review the dBL sample forms included with the jsDateTime package to become more familiar with how jsTimePicker can be used in dBL applications.