DesignTimeCustomComponent

Mobility Visual Designer - Part One: Custom Components Tutorial - "Design Time"

Contents


Abstract

This documents shows how to create Netbeans Module Project for Mobility Custom Components. Describes basics of Visual Designer Components architecture. It also contains useful references to the documents about Visual Designer architecture. Result of this tutorial is fully functional Visual Designer and Java ME component based on the Java Me Form.java class.

Introduction to both parts of this tutorial: Custom Component Tutorial

You may want to look at the final result of this tutorial which is available here:

CustomComponentTutorial_DesignTimeCustomComponent.zip

NOTE: NOTE: To run project from zip file you have to change Netbeans Platform to one registered in your Netbeans IDE.

Custom Component Project Infrastructure

If you not familiar with Netbeans Module Development look at this Document before you start: Introduction to NetBeans Module Development

First step is to create Netbeans Module Suite for projects created during this tutorial and name it MyCustomComponentSuite. Next step is to create new Netbeans Plugin Module which will contain component descriptor, producers and presenters with additional functionality. It is necessary to change two default parameters of creating Project Module first is name of the project to MyCustomComponent and package in the Code Base Name to org.netbeans.mycustomcomponent also mark this module as a part of the MyCustomComponentSuite and define position of the layer.xml.

Suite and Module

MyCustomComponentSuite and MyCustomComponent Netbeans Module Project.

MyCustomComponent project also has to have dependencies on the following modules:

  • VMD Midp - Visual Designer implementation of MIDP 2.
  • VMD Model - Visual Designer Model.
  • VMD Properties - Module responsible for Netbeans Properties Window.


\ MyCustomComponent Module dependencies

MyCustomComponent Module dependencies.

ComponentDescriptor

ComponentDesciptor class represents a component descriptor. It is registered in the component descriptor registry and then available for using in document. Component itself is just a data container and does not know anything about data. Component descriptor does not contain data but describes types of these data. In the other worlds ComponentDescriptor contains information about particular component. Information holds by ComponetDescirptor are Presenters which implementing functionality and behavior of the component and other information like if ComponentDescriptor inherits from other CustomDescriptor. Very important thing when it comes to descriptor is unique TypeID. In most cases TypeID combine two information:

  • Kind of the component which for ComponentDescriptor is TypeID.Kind.Component
  • CustomComponent string which represents fully qualified name of the Java ME class Object. To understand how it works lets look at CustomComponent which represents JavaME Form . Fully qualified name of this class is javax.microedition.lcdui.Form so CustomComponet string for TypeID is excatly the same javax.microedition.lcdui.Form

First step is to create new CustomCompont implementation. In MyCustomComponent module we have to create new package org.netbeans.mycustomcomponent.descriptors and inside this package create new Java class MyCustomComponentCD (CD in the name of the class stands for ComponentDescriptor). Next step is to extend MyCustomComponentCD class with abstract class org.netbeans.modules.vmd.api.model.ComponentDescriptor then use code generation to create all abstract ComponentDescriptor methods.

By this point we should have MyCustomComponentCD class with four methods:

  • public TypeDescriptor getTypeDescriptor() - Returns a type descriptor of this component descriptor.
  • public VersionDescriptor getVersionDescriptor() - Returns a version descriptor of this component descriptor.
  • public List<PropertyDescriptor> getDeclaredPropertyDescriptors() - Returns a list of property descriptors that are declared in this particular component descriptor or override property descriptors from the super component descriptor.
  • protected List<? extends Presenter> createPresenters() - Returns a list of new instances of presenters that are declared in the component descriptor or override presenters.


First we have to take care of the getTypeDescriptor()


public static final TypeID TYPEID = new TypeID (TypeID.Kind.COMPONENT, "customcomponents.MyCustomComponent");


    @Override
    public TypeDescriptor getTypeDescriptor() {
        return new TypeDescriptor(FormCD.TYPEID, //This indicates that MyCustomComponents derives from component descriptor FormCD.
                                  TYPEID,        // TypeID of this component descriptor.
                                  true,          // Instantiate ability. Indicates if DesignComponent can be create based on this Component Descriptor.
                                  true);         // Derive ability. Indicates if this DesignComponent could be used as a super type.
    }

???Next step is to define version description so our component descriptor could provide about information about MIDP version it's been designed for.??? Our component descriptor is valid for all version of the MIDP.


    @Override
    public VersionDescriptor getVersionDescriptor() {
        return MidpVersionDescriptor.FOREVER; 
    }

When you look at the source code of the MyCustomComponent class in the project MyCustomComponent.java class in the project MyCustomComponentJavaME you notice that it has only one additional method comparing to the Form class. To control and store information about "warning" parameter of this method we have to declare property inside of the MyCustomComponentCD using method getDeclaredPropertyDescriptors().


    @Override
    public List<PropertyDescriptor> getDeclaredPropertyDescriptors() {
        return Arrays.asList(
                new PropertyDescriptor(PROP_WARNING, // Name of the property
                                       MidpTypes.TYPEID_JAVA_LANG_STRING,   // Type of the property
                                       PropertyValue.createNull(),          // Default value of the property
                                       true,                                // Is property allows null  
                                       true,                                // Is property allows user code insted of String value
                                       MidpVersionable.MIDP)                // For what version of MIDP this porperty is valid
                );
    }

We are not going to add any Presenters for now so MyCustomComponent has only presenters derived form FormCD so our method returns null.
This is final version of MyCustomComponentCD:


package org.netbeans.mycustomcomponent.descriptors;

import java.util.Arrays;
import java.util.List;
import org.netbeans.modules.vmd.api.model.ComponentDescriptor;
import org.netbeans.modules.vmd.api.model.Presenter;
import org.netbeans.modules.vmd.api.model.PropertyDescriptor;
import org.netbeans.modules.vmd.api.model.PropertyValue;
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.MidpTypes;
import org.netbeans.modules.vmd.midp.components.MidpVersionDescriptor;
import org.netbeans.modules.vmd.midp.components.MidpVersionable;
import org.netbeans.modules.vmd.midp.components.displayables.FormCD;


public class MyCustomComponentCD extends ComponentDescriptor {

    public static final TypeID TYPEID = new TypeID(TypeID.Kind.COMPONENT, "org.netbeans.mycustomcomponentjavame.MyCustomComponent");
    public static final String PROP_WARNING = "warning";
    
    
    @Override
    public TypeDescriptor getTypeDescriptor() {
        return new TypeDescriptor(FormCD.TYPEID, //This indicates that MyCustomComponents derives from component descriptor FormCD.
                TYPEID,                          // TypeID of this component descriptor.
                true,                            // Instantiate ability. Indicates if DesignComponent can be create based on this Component Descriptor.
                true);                           // Derive ability. Indicates if this DesignComponent could be used as a super type.

    }

    @Override
    public List<PropertyDescriptor> getDeclaredPropertyDescriptors() {
        return Arrays.asList(
                new PropertyDescriptor(PROP_WARNING,                        // Name of the property
                                       MidpTypes.TYPEID_JAVA_LANG_STRING,   // Type of the property
                                       PropertyValue.createNull(),          // Default value of the property
                                       true,                                // Is property allows null  
                                       true,                                // Is property allows user code insted of String value
                                       MidpVersionable.MIDP)                // For what version of MIDP this porperty is valid
                );
    }

    @Override
    public VersionDescriptor getVersionDescriptor() {
        return MidpVersionDescriptor.MIDP;  // ComponentDescriptor valid for all version of MIDP
    }

    @Override
    protected List<? extends Presenter> createPresenters() {
        return null;
    }

}



ComponentProducer

Represents a factory for components. The DescriptorRegistry contains a set of component producers. These producers are usually visualized in the palette and represents a component. Producer is a place to define PaletteDescriptor, set property of new created DesignComponent, attach DesignComponent to the parent component or do other components related actions. In this tutorial we are going to use implementation of the ComponentProducer designed for MIDP. We need to create new package in the MyCustomComponent module org.netbeans.mycustomcomponent.producers then create new Java class and extend it with MidpComponentProducer. As you can see we also has to create new PaletteDescriptor in the constructor. In this particular case producer is always visible in the Palette thats why method checkValidity(DesignDocument document) always returns true.



package org.netbeans.mycustomcomponent.producers;

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.MidpProjectSupport;
import org.netbeans.modules.vmd.midp.palette.MidpPaletteProvider;
import org.netbeans.modules.vmd.midp.producers.MidpComponentProducer;
import org.netbeans.mycustomcomponent.descriptors.MyCustomComponentCD;


public class MyCustomComponentProducer extends MidpComponentProducer {

    private static final String ICON_PATH = "org/netbeans/mycustomcomponent/resources/canvas_16.png"; 
    private static final String ICON_LARGE_PATH = "org/netbeans/mycustomcomponent/resources/canvas_32.png"; 
    
    public MyCustomComponentProducer() {
        super(MyCustomComponentCD.TYPEID, new PaletteDescriptor(MidpPaletteProvider.CATEGORY_DISPLAYABLES, // Palette category
                                                                "My Custom Component",                     // Palette display name
                                                                "Tool tip for My Custom Component",        // Palette tooltip
                                                                ICON_PATH,                                 // Small icon
                                                                ICON_LARGE_PATH)                           // Large icon
             );
    }
    
    @Override
    public Boolean checkValidity(DesignDocument document, boolean useCachedValue) {
        return true;
    }

    @Override
    protected DesignComponent createMainComponent(DesignDocument document) {
        MidpProjectSupport.addLibraryToProject(document, "MyCustomComponentLibrary"); // Library is added to the Mobility Project Resources when component is created
        return super.createMainComponent(document);
    }
    
    
}

Function if the createMainComponent(DesignDocument) will be explained in part two of our tutorial.

Registration of ComponentDescriptors and ComponentProducers

Last step is to register component descriptors and component producers in the layer.xml. Default folder for component descriptors is vmd-midp/components and for producers vmd-midp/producers just like it is shown below:

<?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-mycustomcomponent-descriptors-MyCustomComponentCD.instance"/>
        </folder>
        
        <folder name="producers">
            <file name="org-netbeans-mycustomcomponent-producers-MyCustomComponentProducer.instance"/>
        </folder>
        
    </folder>
</filesystem>

Summarizing

This document shown how to create project infrastructure and necessary files to define existence of the custom component in the so called "Design Time". Second document describes how to create Java ME classes which represents our component in the "Runtime" (emulator, real device platform) and how to merge them into our current project infrastructure. If you decide to run project at this point you wont be able to see created component in the Mobility Palette because our Java ME libraies are not on the Mobility Project classpath.


contact: Karol Harezlak


Back to MobilityDesignerHome

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo