Creating a Basic Control

This section provides an overview of creating a control by walking you through the process. Here you will learn how to define a basic control and provide functionality for its base events.

For more information, see:

Defining a Control

A custom control subclasses the WFC Control class. To make your control visible in the Toolbox inside Visual J++, you also need to extend the com.ms.wfc.ui.Control.ClassInfo class. The ClassInfo class contains metadata used to provide design-time information about a class and to browser component properties and events at run time. If you do not require that your control be visible in the Toolbox, you do not need to extend com.ms.wfc.ui.Control.ClassInfo. However, you must still subclass Component.ClassInfo, which implements com.ms.wfc.core.IClassInfo. This inner class must be named ClassInfo.

Note   The WFC Component Builder creates a skeleton control, including properties and methods, which you can fill in. The information in this section includes details about how a control is built to help you build a control manually and to explain what the builder does.

The following shows a skeleton control. If you compile it, the control is registered on your computer and becomes available in the Customize Toolbox dialog box:

// MyControl.java
import com.ms.wfc.ui.*;
import com.ms.wfc.core.*;

public class MyControl extends Control {
    public static class ClassInfo extends Control.ClassInfo {
    }
}

If you add an instance of this control to a form, you will see its properties and events in the Properties window. You can change these properties, and you can also see that the control already supports backColor, foreColor, anchor, dock, mouse events, focus, and more. The com.ms.wfc.ui.Control class defines the default implementation of these common properties and events.

Adding a Control Description

You can include a text description for controls exposed as ActiveX controls. Host applications can then query and display the description. To create a description, add a DescriptionAttribute object in the ClassInfo class. The following example shows how you can add a text description:

public static class ClassInfo extends Control.ClassInfo
{
   public void getAttributes(IAttributes attribs){
   super.getAttributes(attribs);
   attribs.add(new DescriptionAttribute("This describes MyControl"));
}

Providing Functionality for Class Events

The com.ms.wfc.ui.Control class exposes a common set of members with default functionality. For example, if you create a basic control as described earlier, a text property is available for it in the Properties window.

Typically, to add functionality to your control, you must override the members for that control exposed by the base class. Most events in WFC are exposed in their base class with a protected on<eventname> member, which lets subclasses override the event without having to attach event handlers. In your override code, you define the functionality you want for that event. Generally, you implement the default functionality of the member by calling the superclass' event. By placing the call to the superclass' event, you can specify the order in which the event is triggered.

Note   There are additional methods for receiving events when you are not subclassing an event defined in the superclass. For more details, see Working with Control Events.

The following example illustrates how you can override the protected onPaint method to define what the control should display at run time. In the example, the superclass' event is called first to perform the superclass' own paint method. The control's own code displays the value of its text property by calling the drawString method of a Graphics object:

// MyControl.java
import com.ms.wfc.ui.*;
import com.ms.wfc.core.*;

public class MyControl extends Control {
    protected void onPaint(PaintEvent p) {
        super.onPaint(p);
        Graphics g = p.graphics;
        g.drawString(getText(), 0, 0);
    }

    public static class ClassInfo extends Control.ClassInfo {
    }
}

In this example, you display text by calling the control's getText method to retrieve the text stored in the control. When you compile and add your new version of the class, the control now contains whatever text you typed into the text property. Because com.ms.wfc.ui.Control provides a text property, there isn’t really a need to create a new one.

The parameter for onPaint is a PaintEvent, which contains event-specific data. When you are subclassing a protected member, the object sending the event is implicitly known because the sender is this (the current instance of the class). The event data varies from event to event. In this case, the PaintEvent looks like this:

public class PaintEvent extends Event {
     // Graphics object with which painting should be done.
    public final Graphics graphics;
    
     // Rectangle into which all painting should be done.
    public final Rectangle clipRect;
}

The graphics member of the PaintEvent refers to a com.ms.wfc.ui.Graphics object. This is the WFC wrapper for a drawing surface, a Win32 device context. The Graphics object exposes methods to draw strings, lines, points, ellipses, and so forth. You can change the values of the font, foreColor, and backColor properties, and these will display correctly, because the Graphics object that is passed in through the PaintEvent event is set up with the correct fonts and brushes based on the settings in the control. For more details about painting, see Updating Visual Display.