Mobility Visual Designer - Custom Property Editors

Abstract

This documents describes how to create Custom Property Editors for Visual Designer v2. See general information about Property Editors here: MobilityDesigner2Properties.

Used shortcuts:

• PE - Property Editor
• PV - Property Value

Simple PE

Simple PE is a PE what doesn't support user code input instead of particular type of value. For example for String value user can input only String but not an expression in java (or in other language) which will generate a String. To create simple PE developer should extend org.netbeans.modules.vmd.api.properties.DesignPropertyEditor class. Good example of simple PE is a org.netbeans.modules.vmd.midp.propertyeditors.PropertyEditorInstanceName class. This PE allows user input name of instance of some particular entity in the Visual Designer, for example "backCommand1". Obviously there is no need for user code support in this PE. Let's in brief see what each method does.

• public Component getCustomEditor() - returns custom component to edit value when user press "..." button, i.e. editing value using not inplace editor.
• public String getAsText() - returns String representation of current PV.
• public void setAsText(String text) - sets current PV using String representation from user input.
• public void customEditorOKButtonPressed() - reacts for OK button in the custom editor pressing, usually saves current PV since there is no other callback from custom editor and PV must be saved only when that dialog window closed.
• public void init(DesignComponent component) - allows to pass DesignComponent (model) to PE.
• public boolean supportsDefaultValue() - determines whether PE supports default value. If so then "Reset to default" button will be displayed in the custom PE.
• public boolean canWrite() - determines whether PE can write PV to the model. If not then it will only display current PV.

PropertyEditorUserCode

User code support allows user to input or select not particular value but also an java expression which will generate this value. To create PE with user code support developer should extend org.netbeans.modules.vmd.midp.propertyeditors.api.usercode.PropertyEditorUserCode class and provide at least one implementation of org.netbeans.modules.vmd.midp.propertyeditors.api.usercode.PropertyEditorElement class. Let's see as an example org.netbeans.modules.vmd.midp.propertyeditors.PropertyEditorInputMode class. This PE is intended for input mode specification of TextBox and TextField lcdui Form elements.

In constructor developer must provide label for user code element and invoke method initElements() with given elements:

    private PropertyEditorInputMode() {
        super(NbBundle.getMessage(PropertyEditorInputMode.class, "LBL_INPUT_MODE_UCLABEL")); // NOI18N
        elements = new ArrayList<PropertyEditorElement>(2);
        elements.add(new PredefinedEditor());
        elements.add(new CustomEditor());
        initElements(elements);
    }

On the following picture each PropertyEditorElement bordered by red rectangle. Last one (for user code itseld) provided and handled by PropertyEditorUserCode infrastructure, first provided by PE developer.

Developer provides an implementation of following methods of PropertyEditorElement:

• void updateState(PropertyValue value) - this method passes current PV to PE before displaying it so PE can set some state, in our case in the PropertyEditorInputMode will be selected proper value of input state in the combobox (1st element) or, if combobox doesn't contain that value, it will be displayed in custom (2nd element) or, if it is PV with type "user code", it will be displayed in user code text area (3rd element).

1st element implementation (PredefinedEditor) :

        public void updateState(PropertyValue value) {
            if (!isCurrentValueANull() && value != null) {
                String inputMode;
                for (int i = 0; i < model.getSize(); i++) {
                    inputMode = (String) model.getElementAt(i);
                    if (inputMode.equals((String) value.getPrimitiveValue())) {
                        model.setSelectedItem(inputMode);
                        break;
                    }
                }
            }
        }

2nd element implementation (CustomEditor) :

        public void updateState(PropertyValue value) {
            if (!isCurrentValueANull() && value != null) {
                String str = (String) value.getPrimitiveValue();
                if (!isPredefined(str)) {
                    // if that value is not predefined
                    textField.setText(str);
                }
            } else {
                textField.setText(null);
            }
        }

• void setTextForPropertyValue(String text) - sets text from PE, i.e. (in terms of NetBeans PE) saves value to the model
• String getTextForPropertyValue() - returns text for saving to model, usage in our case:

    @Override
    public void customEditorOKButtonPressed() {
        super.customEditorOKButtonPressed();
        for (PropertyEditorElement element : elements) {
            if (element.getRadioButton().isSelected()) {
                saveValue(element.getTextForPropertyValue());
                break;
            }
        }
    }

• JComponent getCustomEditorComponent() - returns visual representation of element, for example JComboBox for our 1st element (PredefinedEditor)
• JRadioButton getRadioButton() - returns radio button for given element
• boolean isInitiallySelected() - determines whether that radio button should be selected by default
• boolean isVerticallyResizable() - determines whether visual representation of element should be vertically resizable (for example JComboBox should not be but JTextArea should be)

In other aspects PE with user code support works in the same manner as simple PE. Another good example of PE with user code using if PropertyEditorString. It provides only one PropertyEditorElement though.

PropertyEditorResource

This kind of PE extends functionality of PropertyEditorUserCode and allows user to manage so-called resources in the Visual Editor. Resources are such entities as fonts, images, etc. They are independent from other components and can be reused by several of them. For example one font object can be reused by different form or canvas elements in the design time (and in MIDP runtime correspondingly). The main problem what has been solved in PropertyEditorResource is that all resource changes should be committed to the model only after user pressed OK button. I.e. if user has changed one font's size or created another font and pressed "Cancel" then no changes should be done in the model. So changes are cached in memory by PropertyEditorResource. This PE except changing allows to create new or delete existing resource or resources. Let's see how to use PropertyEditorResource API by org.netbeans.modules.vmd.midp.propertyeditors.resource.elementsFontEditorElement class example. This PE is managing Font resources.

In the picture above PropertyEditorResourceElement is bordered by green rectangle, PropertyEditorElement is bordered by red one. So we can see so hierarchically out PEs and their elements are integrated into each other. Developer provides implementation of PropertyEditorResourceElement (org.netbeans.modules.vmd.midp.propertyeditors.resource.elements.FontEditorElement in our case) and PropertyEditorResource does all managing resources job for him. Let's see detailed methods of PropertyEditorResourceElement:

• public abstract JComponent getJComponent() - returns visual representation of our element (green rectangle in the picture above), since PropertyEditorResourceElement extends JPanel usually it just returns this pointer, but developer can change it in own implementation
• public abstract void setDesignComponentWrapper(DesignComponentWrapper component) - set special wrapper to element. PropertyEditorResourceElement.DesignComponentWrapper is a wrapper class for DesignComponent to keep all changes cached in memory before commiting to model. So this is a kind of model in MVC terms for element, data from which will be committed later on to VMD model (see more implementation detail in PrtopertyEditorResource.saveValue(String text) method)
• public abstract TypeID getTypeID() - returns TypeID (type of component in the model) which is used to identify model components. For our case:

    public TypeID getTypeID() {
        return FontCD.TYPEID;
    }

• public abstract List<String> getPropertyValueNames() - auxiliary method for determining whether each property supports user code type of PV. Developer should list all PV names like in FontEditorElement:

    public List<String> getPropertyValueNames() {
        return Arrays.asList(FontCD.PROP_FONT_KIND, FontCD.PROP_FACE, FontCD.PROP_STYLE, FontCD.PROP_SIZE);
    }

• public boolean isPostSetValueSupported(DesignComponent component) - determines whether this element needs some post action to be invoked after committing PVs to the model
• public void postSetValue(DesignComponent parentComponent, DesignComponent childComponent) - this will be invoked if previous method returns true
• public void setPropertyEditorMessageAwareness(PropertyEditorMessageAwareness messageAwareness) - allows to show warning/error message in custom PropertyEditor. Here is an example from org.netbeans.modules.vmd.midp.propertyeditors.PropertyEditorPreferredSize class how it been used:

        private void checkNumberStatus() {
            if (!radioButton.isSelected()) {
                clearErrorStatus();
                return;
            }
            if (!Pattern.matches("[\\d\\-]+", textField.getText())) { //NOI18N
                displayWarning(PropertyEditorNumber.NON_DIGITS_TEXT);
            } else {
                clearErrorStatus();
            }
            try {
                int number = Integer.valueOf(textField.getText());
                if (number < 0 && !unlockedCheckBox.isSelected()) {
                    displayWarning(NbBundle.getMessage(PropertyEditorPreferredSize.class, "MSG_POSITIVE_CHARS")); //NOI18N
                } else {
                    clearErrorStatus();
                }
            } catch (NumberFormatException ex) {
                displayWarning(PropertyEditorNumber.NON_DIGITS_TEXT);
            }
        }

• public String getResourceNameSuggestion() - returns name suggestion for newly created component (for example "font" for Font component)

Contact: Anton Chechel

Attachments

font_property_editor.png		18747 bytes
input_mode.PNG		12900 bytes
input_mode.png		12900 bytes
instanceName.png		12817 bytes