Overview of component writing

In this chapter, you can learn about writing components in the following topics:

All this material assumes you have some familiarity with using JBuilder and its standard components.


Fast track to writing components

Writing a new component involves the following steps:

  1. Determine what functionality you require in the new component.

  2. Choose, based on the requirements, which is best:
  3. Develop the basic component code. If you are building a complex component (one that contains other components) or modifying an existing component, you can use the UI Designer to do most of your work.
  4. Create any special properties your component needs including property editors if required.
  5. Create any special events your component needs by writing their event classes and listener interfaces.
  6. If desired, customize which elements show in the Component Inspector and which event is the default, if any, using the special information interfaces.
  7. If you want your users to be able to edit your entire component at one time, build a customizer for it.
  8. Compile and test the component.
  9. Create an image to represent your component on the Component Palette.
  10. Develop the online documentation to help your component users understand the new component.
  11. Install the new component on JBuilder's Component Palette.

For more fast-track information about building JavaBeans components, see Creating JavaBeans with BeansExpress.


Component writers versus component users

It's important to make the distinction between a component writer and a component user. The component writer creates components and then makes them available to component users. Component users can then use these new components in the applications they write; they do not create components themselves.

When we refer to users in this book, we are not referring to the users of the applications written by component users, but to the component users themselves.


Component design tips

Component writers work with objects at a deeper level than most component users do. Creating new components usually requires that you extend existing classes to create new classes.

There are important differences between creating a component for use in JBuilder and the more common task of creating an application or applet that uses components:

Because of these differences, you must be aware of the rules of the JavaBeans component model, and you must think about how other programmers will use the components you write.

Component writing requires a deeper knowledge of objects

A major difference between creating components and using them is that when you create a new component, you extend an existing object to create a new one, adding new properties, methods, and events. Component users, on the other hand, use existing components and customize their behavior at design time by changing properties and specifying responses to events.

When extending an existing class to create a new one, you have access to protected class members, parts of the superclass unavailable to end users of that same class. Subclasses also must call on their superclasses for a lot of their implementation, so component writers must be familiar with inheritance and delegation.

Component writing follows more conventions

Writing a component is a more traditional programming task than visual application creation, and there are more conventions to follow than when you use existing components. Before you start writing components of your own, use the components that come with JBuilder to become familiar with naming conventions and the type of capabilities component users will expect from components you create.

Try to anticipate how your component might be used. You want to make your component useful in many situations and you want it to be error free.

Component writing requires design for reuse

Perhaps the most important thing to learn in the creation of components is the desirability of no dependencies. Components are easy to use when there are no restrictions on what a programmer can do with a component and when. The very nature of components suggests that different programmers will incorporate them into applications in varying combinations, orders, and environments. Design your components so that they function in any context, without requiring any preconditions.

When designing components, keep in mind the interaction of properties. Ensure that a user can set properties in any order, or to any combination of values, without the component failing. Constrain properties, when necessary, to a given set of acceptable values (enumerated properties). Design events and methods to function independently of their order of occurrence at runtime. The general rule is that no element of a component should depend upon another event, value, or method call to function.

Your components should have everything they need to function built in. If a component always needs a certain helper class or companion non-UI component, it is up to the component writer to develop those additional objects.

For example, the TreeView and TreeControl components in the JavaBeans Component Library require a tree node class to function. The general tree node class (LinkedTreeNode) has been developed and delivered in another library package (borland.jbcl.model). The component user who needs a TreeControl component does not need to reinvent the node class to use the component.


Ways of creating components

JBuilder gives you several ways to begin creating components. You can

Modifying existing components

The simplest way to create a component is to extend an existing, working component and customize it. You can derive a new component from any of the components provided with JBuilder. For instance, you might want to change the default property values of one of the standard controls.

Example
A new software project might require blue backgrounds on all of the dialog boxes in the application. Instead of relying on all members of the development team to change the background color on every dialog box they create, you can extend BevelPanel and change the default background color. Once installed as a new component, the blue panel would be available to all developers with no extra work on their part.

The following code declares the new panel component, with the new default background color setting.

import  java.awt.*;

public class BluePanel extends BevelPanel { 
     public BluePanel()   {
          super(); 
          setBackground(Color.blue);     //Sets the background color to blue. 
      } 
}

Once compiled and tested, BluePanel is ready for use by the team of developers.

Creating non-UI components

JBuilder has both UI (user interface) components and non-UI components. Non-UI components provide encapsulated functionality to the user interface, generally by interacting with the UI components. They are never visible in the user interface. Making them components allows component users to work with them visually. An example of a non-UI component is JBuilder's Database component.

UI and non-UI components follow the same rules. They are public classes with a public constructor that takes no parameters. You write their properties, methods, and events exactly as you do those of a UI component.

Note
Component users work differently with non-UI components. Although a non-UI component is selected from the Component Palette and dropped on the UI Designer exactly as a UI component is, non-UI components never display in the UI Designer. JBuilder adds the non-UI component to the Component Tree.

To work with a non-UI component using JBuilder's environment, select the component on the Component Tree. The component's properties and events appear in the Component Inspector.

Creating composite components

If you need more flexibility than extending existing controls provides, you can compose a new component by constructing and connecting the smaller building blocks called models, views, view managers, item painters, and item editors. Components assembled this way are called composite components.

Each composite component needs

You work programmatically with these elements, instantiating those appropriate to your component and writing custom elements as needed for your special cases. Many general-use elements are available as part of the JavaBeans Component Library (JBCL). Understanding model-view architecture discusses this way of constructing components in detail.

Creating original components

You can create a wholly new component. As long as you follow the JavaBeans component model, your components will appear in the UI Designer and work in the Component Inspector. It will also work in other visual development environments that accept components that follow the JavaBeans specification.

Before you begin creating your component, consider what the its primary attributes should be. Will your component contain other components? Do you want it to be transparent so that other components behind it show through, or do you want it to be opaque so that it completely covers other components? Do you want a lightweight component?

For information about lightweight versus heavyweight components, see Lightweight components.

JBuilder offers several components you can use as starting points for building new UI components. The following table lists the classes available to you:
com.sun.java.swing.JPanel An opaque, lightweight visual Swing JavaBean container
com.sun.java.swing.JComponent A transparent, lightweight visual Swing JavaBean container
borland.jbcl.view.BeanPanel A transparent, lightweight visual Swing/JBCL JavaBean container with extra code for event dispatching, texture mapping, and focus handling
borland.jbcl.control.BevelPanel A borland.jbcl.view.BeanPanel with beveled edges
java.awt.Panel A heavyweight visual JavaBean container
java.awt.Canvas A heavyweight visual JavaBean that is not a container
java.awt.Container A lightweight, transparent visual JavaBean container
java.awt.Component A lightweight, transparent visual JavaBean that is not a container


Installing components

Once you have built a valid JavaBeans component, you are ready to install it on the Component Palette. The class files for your new component must be on your classpath.

To install a completed component,

  1. Choose Tools|Configure Palette or right-click the Component Palette and choose Properties.
  2. The Palette Properties dialog box appears.

  3. Select the Pages tab.
  4. In the Pages column, select the page on the Component Palette on which you want the component to appear.
  5. Select the class name for the component from either the Add from Archive page or the Add from Package page.
  6. If you are still developing your component and haven't placed the classes into a .JAR or .ZIP file yet, use the Add from Package page.

    If you deployed your component as a .JAR or .ZIP file, use the Add from Archive page.

  7. Choose Install when you are finished.

  8. Choose OK to close the dialog box.

Specifying a component image

Each component on the Component Palette has an image to represent it. If you don't specify an image for the component, the default JBuilder component icon appears. If you want to specify a unique image for your component, you can use the Palette Properties dialog box. The image that represents a component on the Component Palette must

To specify an image for your component on the Component Palette with the Palette Properties dialog box,

  1. Choose Tools|Configure Palette or right-click the Component Palette and choose Properties.
  2. Select the Pages tab.
  3. Select the page your component is on and select the component.
  4. Choose Properties to display the Item Properties dialog box.
  5. Choose Select Image and specify the .GIF file you want for your component.
  6. Choose OK to close the Item Properties dialog box.
  7. Choose OK when you are finished.

Specifying a Component Palette page

If none of the existing pages on the Component Palette are appropriate for your new component, you can specify a new page for it.

To specify a new page in the Component Palette,

  1. In the Palette Properties dialog box, choose the Add button.
  2. Enter the name of the new page.

When you are through using the Palette Properties dialog box, the new page appears on the Component Palette.