NetBeans Wiki: MobilityCustomComponentProjectSupport

MobilityCustomComponentProjectSupport

Your trail:

Page Info Plain View My Prefs Log in

This page (revision-108) last changed on 14:33 22-Oct-2008 by KarolHarezlak.

Custom Components API Project Support

TODO. new screenshots for the following changes:

project type is renamed to Mobile Designer Components
file type category and name are renamed to Mobile Designer and Mobile Designer Component

Problems:

Is it possible to extend Module Development API Support?
How flexible is Module Development Support API?

Abstract

Goal of this project is to have support for developers who would like to create Mobility Visual Designer Custom Components. It should be new type of the project based on the NB Module. It should generates all necessary Custom Component infrastructure. Creation of the project should be done using wizards based on the information provided by user. Custom Component Support Project type also should have one new file type to create Custom Component. The Custom Component is two Java files (Component Descriptor and Component Producer) and changes in the layer.xml of this Project. This module should help developers not only to design and install Custom Components but also should help users track behavior and structure of the newly crated Custom Components.

Project Infrastructure and Overview

To understand idea of this module it's necessary to look at the following documents:

To simplify Custom Component development all information should be store in one project. In the tutorial there are two separate NB Module Projects. First keeps information about Custom Components and second about Java ME libraries. It'd be better to avoid situation when implementation of Custom Component Project Support contains more that one type of the NB Module Development Project or NB Module Suite thats why Custom Components module in the most of the cases should be stand alone module.

Project should contain:

Basic functionality available in every NetBeans Module Project.
Ability to specify and provide information about Java ME libraries (JAR files) connected with particular Custom Components Project Support module.
Ability to create Component Descriptors and all necessary classes and changes needed to register Custom Components.
Ability to choose from the set of the VMD presenters to describe basic functions of Custom Components like visibility in the Mobility Palette, Navigator, Properties or set of Actions.
Store information about Custom Components icons and resources using wizards. The Custom Components Project Support should have the same Properties UI as the rest of the functionality just like regular NB Module Project.

Concept view of the Custom Components Project Support

Concept view of newly crated Custom Components Project Support with one added Component Descriptor, Component Producer and Java ME (Java SE type) Library.

Basic functionality

The Custom Components Project Support should be a new type of project based on the NB Module Development Project. All futures, UI and behavior could remain the same. It would be wise to limited amount of available file types for this type of the project to few really needed. Features like ability to add new TopComponent or Actions may be misleading and useless for users in this case.

More information about NB Module Development Module is available here:

Basic Platform Overview

New Project

FEATURE GOAL: Create new Custom Component Support Project.

New Custom Components Module Wizard should contains possibility to define following properties:

All Standard project properties like project path, name and display name.
Possibility to add Java ME libraries (jar files) related to this project and Custom Components so NB Libraries could be generated based on this Jar files. Very similar functionality is already available for NB Module Development Project Support and its called "Add Java SE Library Descriptor"
Possibility to start "Add Custom Component Wizard" to give user option to add Component Descriptors in "New Custom Components Module Wizard"

Two steps of the wizard flow should be optional: adding of Java ME libs and ComponentDescriptors. Just as it shown on the schema below:

New Project Flow Schema

Schema of the New Custom Components Project Wizard

NOTE: All values used in the screen shots are completely random and only shows idea of the UI. Content shown in screen shots are not connected with other screen shoots in any way.

Wizard Step 0 - Choose Project Type

The Custom Components Project Type is should be place in categories Mobility.

UI Proposal:

Custom Component Project Type

Wizard step 1 - Project Name and Location

In this step user should be able to edit three basic parameters of the project:

Project Name
Project Location
Project Folder

As it's shown on the screen:

UI proposal:

Basic project parameters

Wizard Step 2 - Basic Module Configuration (on the schema "Finish Information" Step 4)

Collection of basic information about project, like is shown below:

It should be possible to press "Finish" button at this step. By clicking finish Project should be generated with all necessary files.

Final Info

Wizard Step 3 - Add Java SE Library

In this window list of created libraries descriptors should be displayed with possibility to remove or add more.

"Remove" button should remove library descriptor from the list. Remove action should be confirmed with OK/Cancel Dialog.

"Add..." button should take user to the "Java SE Library Descriptor" wizard and give possibility to create library descriptor using "Add Java SE Library Descriptor Wizard. The wizard should look and behave similar to "Add Java SE Library Descriptor Wizard" ( It is not possible to completle reuse "Add Java SE Library Descriptor Wizard").

If user doesn't want to add libraries descriptors it should be possible to press wizard "Next" button to move to the next step without adding any Library descriptors.

If should be possible to press wizard "Finish" button to finish wizard at this step.

List of the libraries descriptors shown in the list of this step represents only libraries descriptors created by user in this step. It means if user create any library descriptor in the project then it should be listed in the List in this step.

UI proposal(already has been change, screen is not updated):

Add Library

Wizard Step 4 - Add Component Descriptor

In this step user should see list of added Component Descriptors with possibility to remove or add more.

"Remove" button should remove component descriptor from the list. Remove action should be confirmed with OK/Cancel Dialog.

"Add..." button should take user to the "New Component Descriptors" Wizard. Wizard is described in details in the section "Component Descriptors". This step is also optional so user may postpone creation of new Component Descriptors and click Finish button without adding any new Component Descriptors.

UI Proposal:

Add Library

Custom Component

FEATURE GOAL: Create and add Custom Component to the project. Add Java files: Component Descriptors along with Component Producers with basic set of Presenters defined in the Custom Component Descriptor. Wizard should be able to generate files and source code also "register" Component Producer and Component Descriptor in the layer.xml.

The Component Descriptor Wizard should should have following abilities:

It generates Java source file which extends Component Descriptor class
It generates Java source file which extends Component Producer class
It changes layer.xml so crated Component Descriptors and Producers are registered on the start of the Netbeans Mobility with installed module created with help of Custom Component Project Support.
Gives possibility in visual way add to the Component Descriptor some of the basic Presenters.

This feature will also be available as new File Type in NetBeans Module Project Type ( including Custom Components Project Type ). This feature should display wizard which helps user to generates Java source files and changes into the Custom Component Project.

UI Proposal: Custom Mobile Component type

NOTE: Since there is no Project Type for Custom Component Project (we use template of NB API Support) I'm not sure if it possible to have possibility to add Mobility Categories associated with NB API Support. In reality by clicking New File on the Custom Component project we should have possibility to have in categorizes of New File Mobility Custom Component Support and in File Type Custom Component type. This problem needs to be resolved somehow.

Wizard flow:

wizard flow

Wizard Step 1 - Prefix and Component Descriptor

Step 1

Prefix is used to generate name of the ComponentDescriptor and ComponentProducer class. Name of the ComponentDescriptor combine prefix+"CD" (CD stands for Component Descriptor) and for ComponentProducer prefix+"Producer". So if prefix is MyCustomCompnent then suggested component descriptor name in the wizard would be MyCustomComponentCD and for producer MyCustomComponentProducer.

Example class generated based on the information from step 1.

public class MyCustomComponentCD extends ComponentDescriptor {

    public static final TypeID TYPEID = new TypeID(TypeID.Kind.COMPONENT, "org.netbeans.mycustomcomponentjavame.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.

    }

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

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

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

}

Class name generated based on the prefix.

public class MyCustomComponentCD extends ComponentDescriptor {

Generation of TypeID is based on the TypeID String and it should provide fully qualified name of the Java ME class represented by this Component Descriptor.

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

The getTypeDescriptor method:

public TypeDescriptor getTypeDescriptor() {
        return new TypeDescriptor(FormCD.TYPEID, < Super Component Descriptor of the class + ".TYPEID" 
                TYPEID,                          < "TYPEID" of this component descriptor.
                true,                            < Value taken from check box Can Instantiate
                true);                           < Value taken from check box Can Derive

    }

The getVersionDescriptor method. MidpVersionDescriptor has three static methods: MIDP, MIDP1, MIDP2. They are represented in th UI as Combo Box Version Descriptor with three choses.

public VersionDescriptor getVersionDescriptor() {
        return MidpVersionDescriptor.MIDP;  < Value taken form Combo Box Version Descriptor
}

Rest of the class should be generated based on the template as it been shown in above.

Wizard Step 2 - Component Producer

Step 2

Step two is responsible for generation of Component Producer Java class.

public class MyCustomComponentProducer extends MidpComponentProducer {

    private static final String ICON_PATH_SMALL = "org/netbeans/mycustomcomponent/resources/canvas_16.png"; 
    private static final String ICON_PATH_BIG = "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
        return super.createMainComponent(document);
    }

Class name generated based on the prefix.

public class MyCustomComponentProducer extends MidpComponentProducer

Icons paths taken from Small Icon Path and Big Icon Path

private static final String ICON_PATH_SMALL = "org/netbeans/mycustomcomponent/resources/canvas_16.png"; 
private static final String ICON_PATH_BIG = "org/netbeans/mycustomcomponent/resources/canvas_32.png";

Constructor generated based on parameters like it's described in the code below:


public MyCustomComponentProducer() {
        super(MyCustomComponentCD.TYPEID, < TypeID of the Component Descriptor generated in the Step 1 of this wizard
                                         new PaletteDescriptor(MidpPaletteProvider.CATEGORY_DISPLAYABLES, < String Taken from Pallet Category Combo Box 
                                                                "My Custom Component",                     < String Taken from Palette Display Name
                                                                "Tool tip for My Custom Component",        < String taken from Palette Tool Tip
                                                                ICON_PATH_SMALL,                           < ICON_PATH_SMALL
                                                                ICON_PATH_BIG)                             <ICON_PATH_BIG
             );
    }

Palette Category Combo Box represents category where new Custom Component should be placed. Static values available in the MidpPaletteProvider class which should available in the Combo Box: CATEGORY_COMMANDS, CATEGORY_CUSTOM, CATEGORY_DISPLAYABLES, CATEGORY_ELEMENTS, CATEGORY_ITEMS, CATEGORY_PROCESS_FLOW, CATEGORY_RESOURCES

The checkValidity method:

Three choices available:

1) Always valid:

public Boolean checkValidity(DesignDocument document, boolean useCachedValue) {
        return true;
}

2) Depends on the platform:

public Boolean checkValidity(DesignDocument document, boolean useCachedValue) {
        if (useCachedValue) {
            return MidpJavaSupport.getCache(document).checkValidityCached(MyCustomComponentCD.TYPEID);
        }
        return MidpJavaSupport.checkValidity(document, MyCustomComponent.TYPEID);
}

In this scenario generated code has only one dynamic part which is MyCustomComponentCD.TYPEID.

3) Custom Definition:

public Boolean checkValidity(DesignDocument document, boolean useCachedValue) {
       throw new UnsupportedOperationException("Custom code needed"); 
}

In this scenario user needs to define validation on its own.

Last element of this step is "Add dependent library in the component creation" It generates code inside of the createMainComponent method using MidpProjectSupport.addLibraryToProject to add libraries to the Mobility project. "MyCustomComponentLibrary" string is taken from Library Name Text Filed.

protected DesignComponent createMainComponent(DesignDocument document) {
        MidpProjectSupport.addLibraryToProject(document, "MyCustomComponentLibrary"); < adding library to the Mobility Project
        return super.createMainComponent(document);
}

When "Add dependent library in the component creation" check box is deselected Library Name Text Field should be disabled and code MidpProjectSupport.addLibraryToProject... should not be a part of the createMainComponent method.

Wizard Step 3 - Presenters (Skipped)

This step needs to be redesign. Skipped for Now.

Wizard Step 4 - Final information

Last step should provide all information about generated code,classes and packages. It is also necessary to register Component Descriptors and Producers in the layer.xml. Component Descriptors should be registered in the NB file system in folder vmd-midp/components and Component Producers in vmd-midp/producers as its 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>

Java ME Libraries

FEATURE GOAL: Add Libraries descriptors for chosen Java ME jars.

This Wizard allows to add libraries to the list of the available libraries in the target instance of Netbeans. Connection between Java ME libraries, NB Modules and Component Descriptors is available the documents listed in the "Project Infrastructure and Overview" section. Description of the "Add Java SE Library Descriptor" is available in the Netbeans help (In "Search" help, keywords: Java SE Library Descriptor)

Additional Debugging Project Views

FEATURE GOAL: Activate on the Netbeans start up two hidden views of Mobility Visual Designer with Document structure and ComponentDescriptor/ComponentProducer tree.

Custom Components Project also should has possibility to run project with special parameters which shows two additional views. They provide additional information about structure of document and properties and tree of registered ComponentDescriptors. Information about views are store in system properties. Name of the property "vmd.structure.show" (boolean type). UI representing this feature should be implemented as a one of the Options available from Options(Preferences)/Miscellaneous/Mobility. As is shown on the screenshot below.

The "Activate Visual Designer Debugging Views" checkbox activate two hidden views "Document" and "Registry" in the Mobility Visual Designer. As it's shown below:

Registered Component Descriptors and Component Producers for particular Visual Midlet (project)

Structure of Design Document with all Design Components for particular Visual Midlet

Additional information and References

Very useful FAQ page, covers almost all aspects of this module

Affected Main UI Elements

There are two Main UI Elements affected by this spec:

New Project wizard

see Wizard Step 0 - Choose Project Type

Filed issue 136248

New File wizard

see Custom Component