Working with the Visual Components of WFC

While there are some differences in the WFC visual components of Win32 and Dynamic HTML (DHTML) applications, there are many more similarities. These similarities enable the WFC component model to easily serve both types of applications. For example, both the Win32 and DHTML models include basic control types, such as edit boxes, check boxes, buttons, radio buttons, and combo boxes. For the most commonly used controls in Win32, there is usually a DHTML control with the same name prefaced by the letters "Dh" (for example, the com.ms.wfc.ui.Edit class has a corresponding com.ms.wfc.html.DhEdit class). Fonts, color constants, and most event types are also shared between the Win32 and DHTML models.

Of course, there are also components that are specific to each model, such as tables for DHTML or list view controls for Win32 components.

Probably the most notable difference between the WFC Win32 and DHTML components is that the DHTML components are not available from the Forms Designer. This means you must create, add, and modify DHTML elements in the code editor; however, the underlying Java code looks very similar in both models.

Windows Visual Components

The WFC framework is rooted in its visual components: WFC is integrated with Visual J++, a visual development tool, and sits on top of the Win32 API for the Windows operating system. The main package in WFC that supports the visible components is com.ms.wfc.ui and the base class for most visual elements in WFC is com.ms.wfc.ui.Control. Most of the WFC controls extend this class, including the Form class, which is the visual container for controls.

The Control Class

The Control class contains all the essential base properties, methods, and logic for manipulating a Win32 window. These methods can be categorized as follows:

Methods for setting and retrieving the control's properties, such as the size of the display and client rectangles, the foreground color, background color, associated brush, cursor, text, font, position, and so on. These methods have names that start with set or get (for example, setBrush and getBrush).
Event methods. For every event that a control generates, there are three methods implemented in the control. For example, for the move event, there is an onMove method, which triggers the event, an addOnMove method, which assigns an event handler to the move event, and a removeOnMove method, which removes the event handler. The Control object handles most basic control events.
Methods dealing with parent/child relationships of controls. For example, the add method adds a child control, and assignParent and getParent assign and retrieve the parent control. There are also methods for handling arrays of child controls.
Methods affecting the layout, z-order, painting, and input focus of the control, such as bringToFront, sendToBack, updateZOrder, performLayout, focus, show, hide, update, invalidate, createGraphics, and createWindowGraphics.
Low level event-processing methods. At the Win32 level, windows receive messages from the system. In the Control class, every input message to a control has a protected process method (for example, processCmdKey, processCmdKeyEvent, or processDialogKey). These methods are important only if a control extending this base class wants to override them to do special processing.
Methods relating to window handles, messages, and thread invocation. These are available for programmers experienced with the Win32 programming model. For example, createHandle, destroyHandle, getRecreatingHandle, fromHandle, fromChildHandle all deal with window handles, and sendMessage and reflectMessage allow the control access to the underlying window messages. For descriptions of the thread invocation methods, see Using Java Threads with WFC.

The Control class extends com.ms.wfc.core.Component class, which is the base class for all WFC components.

Using Forms

A form is the main visual element of an application or a custom dialog box associated with an application. The com.ms.wfc.ui.Form class serves as the foundation for forms in WFC.

The Visual J++ Forms Designer starts with the Visual J++ form template, which provides a class extending com.ms.wfc.ui.Form, and helps you to set properties on the form and add controls to it. The Form-derived class adds a method called main, not found in Form. The form is run when the com.ms.wfc.app.Application.run method is called from main and passed a new instance of the Form-based class (this code already exists in the template). For more information, see "Starting and Quitting an Application" in Using WFC Application Services. A Form-based class used as a modal dialog box can be run by calling the Form.showDialog method (showDialog also runs modal dialog boxes that are based on the com.ms.wfc.ui.CommonDialog box class). A Form-based modeless custom dialog box can be opened by calling the form's show method, which makes the form visible.

The Form class extends com.ms.wfc.ui.Control, so it has all the Control methods plus many of its own for handling its role as a container for controls and as a window. These include methods used to:

Add and remove handlers for the active, closed, closing, deactivate, inputLangChange, inputLangChangeRequest, MDIChildActivate, menuComplete, menuStart, and ownedForm events.
Set the form's window properties, for example, to set the form's initial maximized or visible state, start position and border style; or to determine whether the form has an automatic scroll bar, a control box, or a minimize box, and whether the form's icon is in the task bar.
Determine the relationship of menus, controls, or other forms placed on the form, such as setting the main menu, arranging controls, supporting multiple document interface (MDI) forms, or determining whether the form receives all the control's key events.
Set properties when the form is used as a modal dialog box and to run and retrieve results from a dialog box when the form is an application. This includes methods to set the Accept, Cancel, and Help buttons on a dialog box, to start a dialog box, and to set and retrieve the dialog result values returned by a modal dialog box.

This list is not comprehensive but provides a general idea of what a form is. One other class in the com.ms.wfc.ui package extends Form, and that is the UserControl class. UserControl is a class for creating your own composite Form-based controls that you can install in the Toolbox.

Overview of WFC Controls

All visible WFC controls reside in the com.ms.wfc.ui package. With over 240 classes in this package, it can be difficult to immediately determine which classes you want to use. Fortunately, the classes fall into several major categories, as follows:

Classes that are controls in the Visual J++ Toolbox and directly extend the com.ms.wfc.ui.Control class or ultimately derive from the Control class.
Classes that are controls in the Visual J++ Toolbox and use CommonDialog as a base class (this includes the CommonDialog class itself). CommonDialog wraps the Win32 CommonDialog API.
Classes that contain constant values used by controls. These classes all extend com.ms.wfc.core.Enum.
Classes that represent events and extend com.ms.wfc.core.Event or are event handler classes (delegates).
Classes that represent intrinsic Windows graphical objects such as brushes, bitmaps, colors, cursors, fonts, pens, palettes, icons, regions, and images. For pointers to detailed information on using these objects, see the next section, "Accessing Graphical Services."
Classes that, like Control, extend com.ms.wfc.core.Component but do not require the visual run time overhead of Control. Some examples are ColumnHeader, Menu (and MainMenu, ContextMenu, and MenuItem, which extend it), RebarBand, StatusBarPanel, ToolTip, and ImageList (and ImageListStreamer, which extends it).
Miscellaneous classes that wrap other Windows interfaces; these include Help, which wraps the Windows Help engine, HTMLControl, which wraps a browser, and MessageBox, which wraps the Windows message box, among others.

The following com.ms.wfc.ui classes directly extend Control. Controls that extend these classes are listed in the description.

Class	Description
Animation	Encapsulates a Windows animation control, a rectangular control that plays an Audio-Video Interleaved (AVI) animation file.
AxHost	Wraps an ActiveX control and exposes the control as a WFC control.
Button	Encapsulates a Windows button control.
Checkbox	Encapsulates a Windows check box control, which is a labeled box that is checked or unchecked to select or clear an option.
ComboBox	Encapsulates the Windows combo box control.
DateTimePicker	Encapsulates a Windows date and time picker control, which allows users to specify date and time information.
Edit	Encapsulates a Windows edit control, which is a rectangular control that the user can enter text into.
Form	Represents the basic top-level window.
GroupBox	Encapsulates a group box control, which is a rectangle that contains other controls.
Label	Encapsulates the Windows label control, which displays a string of text that the user cannot edit.
ListBox	Encapsulates the Windows list box control, which displays a list from which the user can select one or more items. ListItem is used with this class. The CheckedListBox control extends this class.
ListView	Encapsulates the Windows list view control, which displays a collection of items, each consisting of an icon (from an image list) and a label.
MDIClient	Represents a window that contains MDI child windows.
MonthCalendar	Encapsulates a Windows month calendar control, which provides a simple calendar interface from which the user can select a date.
Panel	Represents a container you can use to parent other controls visually. The TabPage class extends Panel.
PictureBox	Encapsulates a Windows PictureBox control used to contain bitmaps.
ProgressBar	Encapsulates the Windows ProgressBar control, which dynamically tracks the progress of an operation by moving a bar.
RadioButton	Encapsulates a Windows radio button (or option button) control, which displays an option that can be selected or cleared.
Rebar	Encapsulates a rebar control, which contains other controls within moveable, resizable bands. RebarBand is used with this class.
RichEdit	Encapsulates a Windows RichEdit control.
ScrollBar	Represents the base class for scroll bar controls. HScrollBar and VScrollBar extend ScrollBar.
Splitter	Encapsulates the splitter control, which allows the user to resize docked controls at run time.
StatusBar	Encapsulates the Windows status bar control. StatusBarPanel is used with this class.
TabBase	Defines the base class that contains common functionality for Tab classes controls. TabControl (which uses TabPage) and TabStrip (which uses TabItem) extend this class.
ToolBar	Encapsulates the ToolBar custom control. ToolbarButton is used with this class.
TrackBar	Encapsulates a Windows trackbar control (also known as a slider control), which contains a slider for selecting a value in a range.
TreeView	Encapsulates a Windows tree view control. TreeNode is used with this class.
UpDown	Encapsulates the up-down control (sometimes called a spinner control).

Accessing Graphical Services

In the WFC environment, applications perform graphical operations by using the Graphics object, which encapsulates the native drawing capabilities of the Windows operating system. This object provides flexible support for the most commonly used drawing operations, including displaying images and icons and drawing lines, polygons, and text.

The Graphics object performs its work by wrapping a Windows device context, a system data structure that defines system graphical objects, their associated attributes, and the graphic modes affecting output to a device. Because you can retrieve the device context that underlies a Graphics object, you can use the Graphics object seamlessly with native Win32 drawing routines.

All WFC objects that extend the Control object support creating a Graphics object through the createGraphics method. In addition, all objects that extend the Image object, such as Bitmap, Icon, and Metafile, support the creation and retrieval of their associated Graphics object through the getGraphics method.

For more information on how to use this object, see Graphical Services.

Dynamic HTML Visual Components

Dynamic HTML elements make up the second set of visual components in WFC. The controls in com.ms.wfc.html are based on the Dynamic HTML object model. The classes in com.ms.wfc.html are used to create new elements and also to bind to existing elements on an HTML page. These components can be created and manipulated on a client browser or on a server, which sends them to a client browser. This object model exists on several platforms. Therefore, it is not fundamentally rooted in Win32, although user interface controls tend to be similar because the standard set of buttons, list boxes, radio buttons, and so on, are present on both.

Both sets of WFC controls (Win32 and Dynamic HTML) have a similar base because they both ultimately derive from com.ms.wfc.core.Component. Components are elements that can be hosted in a container and support the IComponent interface, which has methods for siting the component. How components and containers are hooked up is of little concern to most programmers using WFC; however, because elements from both com.ms.wfc.html and com.ms.wfc.ui are based on components, they exhibit similar characteristics. For example, all components are added to their parent containers using the add method.

For a better understanding of how to use the com.ms.wfc.html package, see Programming Dynamic HTML in Java.