Writing Java code for a user-defined editor

Write Java™ code to define the appearance and function of your user-defined editor.

Before you begin

Create a code project and a Java class. You can create a code project and an example Java class for a user-defined editor when you configure your user-defined editor; see Configuring a user-defined editor.

Read the reference information about the Java interfaces required to write code for user-defined editors; see Java interfaces for user-defined editors.

About this task

Enter Java code for your user-defined editor in the Java class you want to use. You must assign the Java class and the code project to your user-defined editor when you configure the editor; see Configuring a user-defined editor. Pattern users edit an instance of your user-defined pattern by using the pattern instance editor. The code for your user-defined editor passes values to and receives values from the pattern instance editor by using two Java interfaces, PatternPropertyEditor and PatternPropertyEditorSite. You must write code to override the methods in these interfaces.

If an exception is thrown by user-defined editor code, the exception is caught and displayed in the Pattern Instance Editor Exception window, which opens automatically.

Procedure

To write the code for your user-defined editor:

  1. Write code for your main user-defined editor class. Be aware of the following points:
    • The user-defined editor main class is created when the pattern user opens an instance of your user-defined pattern.
    • Your user-defined editor must extend the BasePatternPropertyEditor super class.
    • The main class must provide a default public constructor with no arguments.
  2. In your main user-defined editor class, write code to override the configureEditor() method. Use this method to set up your user-defined editor after it is created. Be aware of the following points:
    • The configureEditor() method takes a PatternPropertyEditorSite object, a boolean value, and a string value. These values are passed automatically from the pattern instance editor.
    • The PatternPropertyEditorSite object acts as the interface between your user-defined editor code and the pattern instance editor. You can access this object by using the getSite() method anywhere in your user-defined editor code.
    • The boolean value indicates whether the pattern parameter for the user-defined editor has been flagged as mandatory. If it has, your code must set a value for the pattern parameter.
    • The string value contains the configuration values that are entered when configuring the user-defined editor. If required, you can write code to parse this string to use the values in your editor code.
    • In your configureEditor() method, call configureEditor() on the superclass, and pass the PatternPropertyEditorSite object, boolean value, and string value that were passed to your configureEditor() method. For example: 
      @Override
	public void configureEditor(PatternPropertyEditorSite site, boolean required, String configurationValues) {
	   super.configureEditor(site, required, configurationValues);
	}
  3. In your main user-defined editor class, write code to override the createControls() method. Use this method to define the controls of your user-defined editor. Be aware of the following points:
    • You can create the controls in the createControls() method or write one or more new classes for the controls and instantiate these new classes from the createControls() method.
    • You must call the valueChanged() method on the PatternPropertySite object when the value of your pattern parameter changes. This call notifies the pattern instance editor of the change, which then updates any XPath expressions or user-defined editors which use this pattern parameter. You can access the PatternPropertySite object for your user-defined editor by using the getSite() method, for example, PatternPropertyEditorSite site = getSite().
    • In the createControls() method, you must initialize your controls before defining any listeners for those controls.
  4. In your main user-defined editor class, write code to override the setValue() method. Use this method to set initial values in your user-defined editor, for example, to populate a text box with the default value of the pattern parameter. The setValue() method takes a string value that is the current value of the pattern parameter, which is passed automatically from the pattern instance editor. The value passed from the pattern instance editor is the default value of the parameter, or the value that was saved after the pattern instance is configured.
  5. In your main user-defined editor class, write code to override the getValue() method. Use this method to provide the value of the pattern parameter to the pattern instance editor. The getValue() method is automatically called after the valueChanged() method is called.
  6. In your main user-defined editor class, write code to override the setEnabled() method. Use this method to enable or disable your user-defined editor. The setEnabled() method is passed a boolean value from the pattern instance editor to indicate whether the pattern parameter is enabled or disabled by an enabling XPath expression. When the parameter is enabled, the value is true; when the parameter is disabled the value is false.
  7. Optional: In your main user-defined editor class, write code to override the isValid() method. Use this method to validate entries in your editor and return an error message to the pattern instance editor if required. The error message is displayed to pattern users in the pattern instance editor.
  8. Optional: In your main user-defined editor class, write code to override the notifyChanged() method. Use this method to handle change notifications from other parameters in your user-defined pattern and change the value of your pattern parameter or the behavior of your editor, if required. The notifyChanged() method takes the parameter ID of the changed parameter and the new value of that parameter.

Example

See the following examples of Java code for user-defined editors:

What to do next

If you have not configured your user-defined editor, see Configuring a user-defined editor.