Visual Mobile Designer - Custom Components Tutorial (requires Netbeans 6.x sources)

This document is presented for archival purposes only. Here is the updated version of the Custom Component Tutorial .

Abstract

This tutorial is a quick introduction for developers who would like to create a plug-in for Designer 2. This document describes how to create a plug-in that adds a single custom component. Actually all the work can be done automatically using the "Add from Project" wizard in the "Palette Manager" in the Designer palette. The overall purpose is to show how plug-in development for NetBeans Mobility can be done. The plug-in also allows more customizations to be added later than the "Add from Project" wizard.

The documentation is intended as a starting point for exploring the nuts and bolts of the Visual Designer API and its MIDP model implementation.

Prerequisites

In this document, we assume that you have a JavaME class/library which contains a component that you want to add to Designer 2. If not you have to create it first.

We will use "mylibrary.MyForm" class like this:

package mylibrary;

public class MyForm extends Form {

  private int myValue;

  public MyForm () {
    super ("Hi");
    myValue = 5;
  }

  public int getMyValue () {
    return myValue;
  }

  public void setMyValue (int myValue) {
    this.myValue = myValue;
  }

}

The document will not describe how to add the library/class into your MobileApplication project. Let us know, if you would like to have it described in details.

Setup

• First you have to have a NetBeans IDE where you will develop. Download a build of NetBeans 6.0 from the www.netbeans.org site.
• Have an empty directory e.g. "/trunk". This directory will contains all sources of NetBeans IDE.

cd /trunk
hg clone http://hg.netbeans.org/main
ant

Also assure that you are passing "-Xmx256m" into "ANT_OPTS" environment property e.g.: add following line to ".antrc" script into your home directory:

export ANT_OPTS="-Xmx512m"

Creating a plugin module

• Start the NetBeans IDE for developing (not the one from the "/trunk" directory).
• Invoke "File | New Project..." main menu action.
• In wizard, use the "NetBeans Plug-in Modules | Module Projects" template and press Next.
• Set "mycustomcomponents" as a project name and "/trunk" as project location. Then press Next.
• Optionally modify parameters and finish this wizard.
• Note: New project has been created.

Setup module

Since the modele is created in the trunk directory it automatically integrates with NetBeans. All you have to do, it to set up your module dependencies.

• Invoke "Project Settings" popup menu action.
• In dialog, switch to "Libraries" tab.
• Press "Add..."
• In 2. dialog, search for "VMD" text.
• Press Ok, when the "VMD *" modules are found.
• Press Ok again to close the dialog.

Now you have everything set up.

Basic structures

Designer project is meta-modelling. This means:

• In JavaME, you have a class and instances. We call it run-time.
• In Designer 2, you have ComponentDescriptor, DesignComponent. We call it design-time. ComponentDescriptor is similar to a class, DesignComponent is similar to an instance.
• Instead types, there is TypeID which is unique idnetification of a class or a primitive value.

For more details, see MobilityDesigner2QuickGuide

ComponentDescriptor

First of all we have to create a component descriptor for "mylibrary.MyForm" component.

• Create a new class with name "MyFormCD"
• Extend it from ComponentDescriptor class
• Resolve imports and implement all abstract methods
• Class should look like this:

package org.netbeans.vmd.mycustomcomponents;

import java.util.List;
import org.netbeans.modules.vmd.api.model.ComponentDescriptor;
import org.netbeans.modules.vmd.api.model.PropertyDescriptor;
import org.netbeans.modules.vmd.api.model.TypeDescriptor;
import org.netbeans.modules.vmd.api.model.TypeID;
import org.netbeans.modules.vmd.api.model.VersionDescriptor;
import org.netbeans.modules.vmd.midp.components.displayables.FormCD;

public class MyFormCD extends ComponentDescriptor {
    
    // we use convention to typeid that reprensents a class that the second parameter is fully-qualified class-name 
    public static final TypeID TYPEID = new TypeID (TypeID.Kind.COMPONENT, "mylibrary.MyForm"); // NOI18N
    
    public MyFormCD() {
    }
    
    public TypeDescriptor getTypeDescriptor() {
        // we derive our component from "Form" component
        return new TypeDescriptor (FormCD.TYPEID, TYPEID, true, true);
    }

    public VersionDescriptor getVersionDescriptor() {
        return null; // not used for now
    }

    public List<PropertyDescriptor> getDeclaredPropertyDescriptors() {
        return null;
    }

    protected List createPresenters() {
        return null;
    }

}

• This represents a component that derives from Form and does not declare anything.
• Note that the MyFormCD class is derived from ComponentDescriptor class even thought we are describing MyForm component that is extending Form component.

Now you have to register this component descriptor. This is done in layers.

• Therefore modify layer.xml file to:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
<filesystem>
    <folder name="vmd-midp">
        <folder name="components">
            <file name="org-netbeans-vmd-mycustomcomponents-MyFormCD.instance"/>
        </folder>
    </folder>
</filesystem>

• This register the component descriptor, so now the designer will know about your component.

ComponentProducer

The component descriptor is not enough for describing how to create a component. Therefore there are ComponentProducers. They are describing how the component is created. It allows component templates ... For our demo, it is enough to understand that it is the thing that is listed in the palette on the right side of the IDE.

• Create a new class named "MyFormProducer"
• Make it extend "MidpComponentProducer"
• Resolve imports and implement the methods like this:

package org.netbeans.vmd.mycustomcomponents;

import org.netbeans.modules.vmd.api.model.ComponentProducer;
import org.netbeans.modules.vmd.api.model.DesignComponent;
import org.netbeans.modules.vmd.api.model.DesignDocument;
import org.netbeans.modules.vmd.api.model.PaletteDescriptor;
import org.netbeans.modules.vmd.midp.components.displayables.FormCD;
import org.netbeans.modules.vmd.midp.palette.MidpPaletteProvider;

public class MyFormProducer extends ComponentProducer {

    public MyFormProducer() {
        // producer unique identification, typeid of a component created by this producer and palette descriptor
        super(MyFormCD.TYPEID.toString(), MyFormCD.TYPEID, new PaletteDescriptor (MidpPaletteProvider.CATEGORY_DISPLAYABLES, "My Form", "This is my first component", FormCD.ICON_PATH, FormCD.ICON_LARGE_PATH)); // NOI18N
    }
    
    public Result createComponent(DesignDocument document) {
        // this is called to create a component that this producer represents
        DesignComponent createComponent = document.createComponent(MyFormCD.TYPEID);
        return new Result (createComponent);
    }

    public boolean checkValidity(DesignDocument document) {
        return true;
        // later, you can use:
        // return MidpJavaSupport.checkValidity(document, "mylibrary.MyForm"); // NOI18N
        // check whether your class is on the classpath of your project
    }

}

Now you have to register the producer in Designer. It is done in layer again. Therefore:

• Modify "layer.xml" file to look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
<filesystem>
    <folder name="vmd-midp">
        <folder name="components">
            <file name="org-netbeans-vmd-mycustomcomponents-MyFormCD.instance"/>
        </folder>
        <folder name="producers">
            <file name="org-netbeans-vmd-mycustomcomponents-MyFormProducer.instance"/>
        </folder>
    </folder>
</filesystem>

• Now the producer is register.

First run

Now we are going to run it for the first time.

• Invoke "Clean and Build Project" popup menu action on your project node in Explorer.
• After compilation, invoke "Install/Reload in Target Platform" popup menu action on the same node.
• It starts you target IDE, confirm license and:
• Create a new MobileApplication (in J2ME or Mobile category). Note uncheck "Create a Hello MIDlet"
• Create a new Visual Midlet (using MIDP|Visual MIDlet file template).
• Open the new midlet and disallow importing.
• Look at the palette, there should "My Form" item at "Displayables" category.

Since we had inherit all properties and presenters (explained later) from FormCD, then it behaves as the same way as a "Form" (except for code generation since it does not have specification of a constructor of "mylibrary.MyForm" class.

Properties

For having properties, you have to do two major things. Register a property for in the model and register a view of that property in the "Properties" window. For that you have to:

• Modify the getDeclaredProeprtyDescriptors method like this:

    public List<PropertyDescriptor> getDeclaredPropertyDescriptors() {
        return Arrays.asList (
            // create a property description
            // it is a property with name "myValue" which is of-type primitive int (see: MidpTypes class for more)
            // and it default value is "5"
            new PropertyDescriptor ("myValue", MidpTypes.TYPEID_INT, MidpTypes.createIntegerValue(5), false, true, MidpVersionable.MIDP)
        );
    }

• Now you have a property declared in the model of the component but it is not available to user by default.
• For doing it, you have to a correct presenter assigned to a component. Presenter is sort of a view on the data in the component. Also it can be taken as a provider of an ability of a component.
• For enabling a property to user, you have modify createPresenters method like this:

    protected List createPresenters() {
        return Arrays.asList (
            // create a properties presenter
            new DefaultPropertiesPresenter()
                // in the general properties category
                .addPropertiesCategory(PropertiesCategories.CATEGORY_PROPERTIES)
                    // add property myValue
                    .addProperty("My Value", PropertyEditorNumber.createIntegerInstance(), PROP_MY_VALUE)
        );
    }

Second run

• Close the previous IDE
• Run the clean and build your module again and run the IDE for the second time.
• In IDE, add a MyForm component to design.
• Select created MyForm component.
• Look at the "Properties" window. If you do not see the window, open it using "Window|Mobility Properties" main menu action.
• Now there is a "My Value" property with value editor.
• Value should be persistent in design, allow integer value or specified an user-code.

Code generator

• The last thing, you have to do is to specify code generation.
• It is done by adding a new CodeSetterPresenter.
• Add following code as an additional parameter to Arrays.asList method call in createPresenters:

            new CodeSetterPresenter()
                // we will use "myValue" property as a parameter
                .addParameters(MidpParameter.create(PROP_MY_VALUE))
                // define a default contructor of the "MyForm" class
                .addSetters(MidpSetter.createConstructor(TYPEID, MidpVersionable.MIDP).addParameters())
                // define "setMyValue" setter
                .addSetters (MidpSetter.createSetter("setMyValue", MidpVersionable.MIDP_2).addParameters(PROP_MY_VALUE))

Third run

• Close IDE, clean and build module, run the IDE again.
• Now the MyForm component should generate code in the Source code tab.

Summary

You can download mycustomcomponents.zip which is the source code of the module. Unzip it into "/trunk" directory. Then you can build it and run the IDE.

We have not talk about many things like programatically create/modifying/delete components in a document and how to plug a presenter for screen, flow, navigator, ... views. That will come in next tutorials.

contact: Karol Harezlak

Attachments

mycustomcomponents.zip

6901 bytes