jsListView Description

jsListView and jsSysListView Design and Description

The following is a brief description of basic overall operation and design of the jsListView dBL class. Because the jsSysListView class is a subclass of the jsListView class, this description also applies to the jsSysListView 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 jsListView. In reality, jsListView 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, jsListView 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 jsListView 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 jsListView at runtime. The form.metric setting is checked at runtime in jsListView.onOpen and if form.metric # 6, the jsListView object will release itself.

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

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

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

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

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

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