Oculus Layout Builder Plugin API Documentation
November 25, 2002

Oculus Layout Builder Plugin API Documentation

Using the Plugin API, it is possible to add arbitrary custom components to the Oculus Layout Builder program.

See:
          Description

Other Packages
com.oculustech.layoutbuilder.pluginapi  

 

Using the Plugin API, it is possible to add arbitrary custom components to the Oculus Layout Builder program. Typically, this is quite simple to do, in fact. It requires little more than making a very simple Jar that includes both your custom component and a small metadata class, called a ComponentFactory, to tell the Layout Builder about your custom component. All the details of your custom components' fields, etc., will automatically be determined by inspection, and the default code generator will be able to handle almost all components without effort on the part of the user.

The basic form of an Oculus Layout Builder plugin is:


public class MyCustomComponentFactory implements ComponentFactory {
  public ComponentKind[] getComponentKinds() {
    return new ComponentKind[] {
      new DefaultComponentKind(MyComponent.class,
                               "com.myCompany.MyComponentKindName",
                               "My Component Human-readable name",
                               "This is a description of My Component",
                               myImageIconHere),
      new DefaultComponentKind(MyOtherComponent.class,
                               "com.myCompany.MyOtherComponentKindName",
                               "My Other Component Human-readable name",
                               "This is a description of My Other Component",
                               myOtherImageIconHere)
    };
  }
}

The above code is sufficient to add two custom components into the builder, one implemented by MyComponent.class, the other implemented by MyOtherComponent.class. The only requirements on these two classes are that they extend java.awt.Component, and that they have default constructors (constructors which take no arguments).

Once you have written and compiled your component factory, you must put it into a Jar along with your custom component and any additional classes and/or images that may be required. The Jar MANIFEST file should have a property called ComponentFactoryClass. Its value should be the fully qualified name of your ComponentFactory implementation (e.g., com.myCompany.MyCustomComponentFactory). Once this jar is made, just drop it into the plugins subdirectory under the directory containing the LayoutBuilder.jar (typically $(INSTALLDIR)/plugins).

Sample manifest file:
ComponentFactoryClass: com.myCompany.MyCustomComponentFactory
 
Note the required terminal newline.

In the above example, inspector fields for the custom components will be determined by inspection, and the default code generator will be used to generate the resulting code. This will be sufficient in nearly all cases. However, sometimes you may want to add a custom field to the Inspector, or have more control over code generation. In this case, you can manually extend ComponentKind, and implement its createComponent() method yourself. If you return a java.awt.Component instance, the builder will inspect the component and automatically generate Inspector fields for it and use the default code generator, just like above. However, instead of createComponent() returning a Component instance, it can also return a ComponentMetaInfo instance.

By implementing ComponentMetaInfo or extending DefaultComponentMetaInfo, you can control the fields the Inspector presents, as well as the details of code generation. The method doIncludeDefaultInspectorFields() controls whether default inspector fields are automatically generated by inspection or not; if this returns true, the automatic fields will be included in addition to any you define with your getFields() method. If you would like to include most default fields, but exclude a few specific ones, return the list of field names to exclude from defaultInspectorFieldsToExclude(). To define your own custom fields, implement getFields(). More on this below. Finally, canInlineConstruction(), generateDeclaration(), and generateCode() control code generation.

getFields() returns an array of FieldInfo instances. Each field is editable in the inspector, and is saved to the .obl XML file. getControlKind() determines the type of control that is used in the inspector. getControlProperties() determines drop-down options, among other things.

For code generation, canInlineConstruction() determines whether the builder will inline your constructor call in an layoutHelper.add() call or not. Generally, it should return false if there are any fields that need setting to non-default values (default implementation returns false except for trivial JLabel instances). generateDeclaration() should generate a declaration for your component. generateCode() is called to generate the code to create a component instance and initialize it's values as per the objects' field settings. generateCode will be told whether it is generating an inlined constructor call (one that is called inside a layoutHelper.add() call, and thus the returned object is never assigned to a variable); and whether the variable is a class variable (and hence already declared) or a local method variable (and hence has yet to be declared).


Oculus Layout Builder Plugin API Documentation
November 25, 2002

Copyright 2002 Oculus Technologies Corporation. 103 Broad Street, 6th Floor,
Boston, Massachusetts, 02110, U.S.A. All Rights Reserved.