## Creating Lightweight Java Components

This topic describes how you can create lightweight Java components and add them to HTML topics using the HTML `<OBJECT>` tag. The last section in this topic contains references to supplemental information about lightweight components and the HTML `<OBJECT>` tag.

References to supplemental information are included at the end of this topic.

### Lightweight Components for HTML Topics

Components intended for HTML topic pages are very similar to generic lightweight components. Components that do not require information about the View, or have parameters that can be set, can be used without modification.

#### View Information

Lightweight components that require information about the `View` must implement `javax/javahelp/impl/ViewAwareComponent`. These components implement the method `setViewData()`. The component can determine information from the `View` about the environment in which it is executing. For example, in the code snippet below the `Document` object is derived from the `View`:

        private View myView;
        static private URL base;

        public void setViewData(View v) {
            myView = v;
            Document d = myView.getDocument();
            // System.err.println("myDocument is: "+d);

            base = ((HTMLDocument) d).getBase();
            // System.err.println(" base is: "+base);

        }

For more information about the `Document` interface see the following Swing API:

        http://java.sun.com/j2se/1.4.1/docs/api/javax/swing/text/Document.html

Text formatting information can be derived from the `View` by querying its attribute set. Use the method `getAttributes` as shown below:

        AttributeSet as = v.getAttributes();

Format attributes can be used by the component when the `AttributeSet` is passed as a parameter to a `StyleConstants` method. There are methods that can be used to determine a number of attributes, including the font family, font size, font weight, font style, underlining, background color, and foreground color. For example, to determine the default background color of an object, you can do the following:

        Color color=StyleContants.getBackground(as)

For a full list of formatting attributes and corresponding methods see:

        http://java.sun.com/j2se/1.4.1/docs/api/javax/swing/text/StyleConstants.html

#### Using Parameters

If your component takes parameters, you should follow these two additional steps:

1. Add accessor methods for each parameter that can be set.
2. Create a `BeanInfo` class that corresponds to the lightweight component class.

The component must accept parameter elements in any order.

#### Accessor Methods

Add accessor methods that enable the component to access the parameters through the Java reflection mechanism. In the following example, the `AButton` class has implemented accessor methods for the parameter "data" in the methods `getData` and `setData`:

        private String data = "";

        public void setData(String s) {
    	data = s;
        }

        public String getData() {
    	return data;
        }

| Even if the internal representation is not a `String`, both the returned value for the getter method and the parameter in the setter method must be a `String`.

#### BeanInfo Class

Create a `BeanInfo` class that provides explicit information about the lightweight component. The only method used by the `ContentViewer` from the `BeanInfo` classes is `getPropertyDescriptors`. In the complete example below, `JHSecondaryViewerBeanInfo` defines the property data accessible through the `getData()` and `setData()` methods in `JHSecondaryViewer`:

    public class JHSecondaryViewerBeanInfo extends SimpleBeanInfo {

       public JHSecondaryViewerBeanInfo() {
       }

       public PropertyDescriptor[] getPropertyDescriptors() {
          PropertyDescriptor back[] = new PropertyDescriptor[15];
          try {
             back[0] = new PropertyDescriptor("content", JHSecondaryViewer.class);
             back[1] = new PropertyDescriptor("id", JHSecondaryViewer.class);
             back[2] = new PropertyDescriptor("viewerName", JHSecondaryViewer.class);
             back[3] = new PropertyDescriptor("viewerActivator", JHSecondaryViewer.class);
             back[4] = new PropertyDescriptor("viewerStyle", JHSecondaryViewer.class);
             back[5] = new PropertyDescriptor("viewerLocation", JHSecondaryViewer.class);
             back[6] = new PropertyDescriptor("viewerSize", JHSecondaryViewer.class);
             back[7] = new PropertyDescriptor("iconByName", JHSecondaryViewer.class);
             back[8] = new PropertyDescriptor("iconByID", JHSecondaryViewer.class);
             back[9] = new PropertyDescriptor("text", JHSecondaryViewer.class);
             back[10] = new PropertyDescriptor("textFontFamily", JHSecondaryViewer.class);
             back[11] = new PropertyDescriptor("textFontSize", JHSecondaryViewer.class);
             back[12] = new PropertyDescriptor("textFontWeight", JHSecondaryViewer.class);
             back[13] = new PropertyDescriptor("textFontStyle", JHSecondaryViewer.class);
             back[14] = new PropertyDescriptor("textColor", JHSecondaryViewer.class);
             return back;
          } catch (Exception ex) {
    	 return null;
          }
       }
       }

#### Parameter Names

When naming parameters, be sure to avoid names reserved in the HTML 4.0 specification for use as `<OBJECT>` tag attributes. For a complete list of `<OBJECT>` attributes see the HTML 4.0 specification:

        http://w3c.org/TR/REC-html40/

### Using the `<OBJECT>` Tag

You add lightweight components to JavaHelp topics by means of the `<OBJECT>` tag and its `classid` attribute. The help viewer only recognizes `classid` values prefixed with the "`java:`" tag. All other `classid` tags are ignored. The following example creates an `ALabel` within the HTML topic:

        <OBJECT CLASSID="java:sunw.demo.object.ALabel"</OBJECT>

You can use standard `<OBJECT>` tag attributes (see the HTML 4.0 specification for more details), but to be recognized the lightweight component must have getter and setter methods for those attributes. A getter or setter method must operate on a `String`. For example, in the following example width and height for the `ALabel` are set if there are `getWidth`/`setWidth` and `getHeight`/`setHeight` methods in `ALabel`:

        <OBJECT
            CLASSID="java:sunw.demo.object.ALabel"
            width="400" height="500">
        </OBJECT>

Parameters are passed to lightweight components by using the `<param>` tag. A parameter is only recognized if the component has getter and setter methods for that parameter. A getter or setter method must operate on a `String`. In the example below, the help viewer passes a number of parameters and their values to a the `JHSecondaryViewer` component:

        <OBJECT classid="java:com.sun.java.help.impl.JHSecondaryViewer">
            <param name="content" value="../topicB/glossary_def.html">
            <param name="viewerActivator" value="javax.help.LinkLabel">
            <param name="viewerStyle" value="javax.help.Popup">
            <param name="viewerSize" value="300,400">
            <param name="text" value="Click here">
            <param name="textFontFamily" value="SansSerif">
            <param name="textFontSize" value="x-large">
            <param name="textFontWeight" value="plain">
            <param name="textFontStyle" value="italic">
            <param name="textColor" value="red">
        </OBJECT>

### Supplemental Information

The following information supplements the information in this topic.

Lightweight Java Components

For general information about lightweight Java components see:

    http://java.sun.com/j2se/1.4.1/docs/guide/awt/demos/lightweight/index.html

JavaHelp Components

As a reference, the sources to the lightweight components that implement JavaHelp system popups and secondary windows (`JHSecondaryViewer.java` and `JHSecondaryViewerBeanInfo.java`) can be found in `src.jar` at:

    com\sun\java\javahelp\impl

For a description of how the `<OBJECT>` tag is used to implement popups and secondary windows, see Using Popup and Secondary Windows.

HTML 4.0 Specification

You can find a detailed description of the `<OBJECT>` tag as part of the HTML 4.0 specification:

    http://w3c.org/TR/REC-html40/