A component created by the wizard and later managed by the visual editor has a
very specific structure that allows you to insert your user interface logic in
the component while keeping a minimal amount of code off-limits. You need to
know what you can edit yourself and what exactly is managed by the editor. The
managed member variables and methods are marked with the
AutoGenerated annotation, as you can see later.
A visually editable component consists of:
Member variables containing sub-component references
Sub-component builder methods
The constructor
The structure of a composite component is hierarchical, a nested hierarchy of
layout components containing other layout components as well as regular
components. The root layout of the component tree, or the
composition root of the
CustomComponent, is named
mainLayout. See Section 5.23, “Component Composition with CustomComponent” for a detailed description of the
structure of custom (composite) components.
The CustomComponent class will include a reference
to each contained component as a member variable. The most important of
these is the mainLayout reference to the composition
root layout. Such automatically generated member variables are marked with
the @AutoGenerated annotation. They are managed by
the editor, so you should not edit them manually, unless you know what you
are doing.
A composite component with an AbsoluteLayout as the
composition root, containing a Button and a
Table would have the references as follows:
public class MyComponent extends CustomComponent {
@AutoGenerated
private AbsoluteLayout mainLayout;
@AutoGenerated
private Button myButton;
@AutoGenerated
private Table myTable;
...
The names of the member variables are defined in the component properties
panel of the visual editor, in the Component name
field, as described in the section called “Basic Properties”. While you can
change the name of any other components, the name of the root layout is
always mainLayout. It is fixed because the editor does
not make changes to the constructor, as noted in Section 7.4.3, “The Constructor”. You can, however, change the
type of the root layout, which is an AbsoluteLayout
by default.
Certain typically static components, such as the
Label label component, will not have a reference as
a member variable. See the description of the builder methods below for
details.
Every managed layout component will have a builder method that creates the layout and all its contained components. The builder puts references to the created components in their corresponding member variables, and it also returns a reference to the created layout component.
Below is an example of an initial main layout:
@AutoGenerated
private AbsoluteLayout buildMainLayout() {
// common part: create layout
mainLayout = new AbsoluteLayout();
// top-level component properties
setHeight("100.0%");
setWidth("100.0%");
return mainLayout;
}
Notice that while the builder methods return a reference to the created component, they also write the reference directly to the member variable. The returned reference might not be used by the generated code at all (in the constructor or in the builder methods), but you can use it for your purposes.
The builder of the main layout is called in the constructor, as explained in Section 7.4.3, “The Constructor”. When you have a layout with nested layout components, the builders of each layout will call the appropriate builder methods of their contained layouts to create their contents.
When you create a new composite component using the wizard, it will create a constructor for the component and fill its basic content.
public MyComponent() {
buildMainLayout();
setCompositionRoot(mainLayout);
// TODO add user code here
}
The most important thing to do in the constructor is to set the
composition root of the CustomComponent with the
setCompositionRoot() (see Section 5.23, “Component Composition with CustomComponent” for more details on the composition
root). The generated constructor first builds the root layout of the
composite component with buildMainLayout() and
then uses the mainLayout reference.
The editor will not change the constructor afterwards, so you can safely
change it as you want. The editor does not allow changing the member
variable holding a reference to the root layout, so it is always named
mainLayout.