|
Oculus Layout Builder Plugin API Documentation November 25, 2002 |
|||||||||
PREV NEXT | FRAMES NO FRAMES |
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 |
|||||||||
PREV NEXT | FRAMES NO FRAMES |