Authors: Ian Formanek, Jesse Glick
Version: 1.1; @DATE@
This document describes an API for writing design-time support for custom Layout Managers. With design-time support, the Layout Manager can be used during design-time in the Form Editor and it can provide drag'n'drop support, code generation, properties, component constraints properties and other special design-time support.Disclaimer: This document descibes the current state of LayoutManager support in F.f.J. CE 1.0 and is released as a part of the EAP program. It represents ongoing development of LayoutManager support and is subject to change without notice.
The design time support is created by writing a class which extends org.netbeans.modules.form.compat2.layouts.DesignLayout and its ConstraintsDescription innerclass (it is a static innerclass, so its subclass is not required to be an innerclassof the DesignLayout's subclass). This class is then installed into the ComponentPalette and used during design-time to provide components manipulation, properties and code generation for the specific layout manager.This mechanism can also be used for containers which do not allow setting their layouts and use special Java code for adding components into them, such as JTabbedPane and JSplitPane.
- The required methods to implement are:
Method of DesignLayout Description getLayoutClass () returns the class of the layout represented by this design-time support (e.g. FlowLayout.class for design-time support of FlowLayout) getDisplayName () returns the name to be used as the name of the layout during design-time (e.g. "FlowLayout") generateInitCode () returns the Java code used for layout initialization and setting the layout on the container.
e.g. "container1.setLayout (new java.awt.FlowLayout (java.awt.FlowLayout.CENTER, 2, 2));" for a FlowLayout initialization.
The code should reflect all layout properties modified by the user.
The string can provide multiple lines of Java code.generateComponentCode () returns the Java code used for adding a component to its parent container
e.g. "container1.add (button1);" for a FlowLayout initialization.
The code should reflect all layout properties modified by the user.getConstraintsDescription () returns an instance of ContraintsDescription according to passed coordinates within its parent container. The parameters can be ignored and this method can return one shared instance if the layout manager does not support drag'n'drop.
The ConstraintsDescription class describes a constraints properties of one component within the layout (e.g. for BorderLayout it represents the "Center", "North", ... strings)
- Advanced (optional) design-time support:
Category Description Icon Icon displayed in the ComponentPalette and in the ComponentInspector.
Design support provides the icon from method getIcon().LayoutManager's properties The properties of LayoutManager displayed if the LayoutManager's node is selected in the ComponentInspector.
Returned from method getPropertySet(). The DesignLayout can provide multiple sets of properties via Node.PropertySet class. Each of these sets will be displayed as a standalone tab in the ComponentInspector. Every single property is described by a subclass of Node.Property class (which copies most of the functionality of JavaBean's properties).Component's constraints properties The constraints properties of Components managed by the layout manager (i.e. added to the parent container with this LayoutManager). These properties are displayed on the "Layout" tab in the ComponentInspector if the component is selected. An example of this is the "Direction" property of the BorderLayout's constraints.
Returned from method getConstraintsProperties (). The DesignLayout provides an array of Node.Property objects.Drag'n'drop What happens when the user moves a component in a Container with this layout manager.
Enabled if the design support returns true from canMove().
Implemented by method moveTo().
The DesignLayout can provide visual feedback of this operation in method markMoveTo().Drag'n'drop What happens when the user resizes a component in a Container with this layout manager.
Enabled if the design support returns true from canResize().
Implemented by method resizeTo().
The DesignLayout can provide visual feedback of this operation in method markResizeTo().Drag'n'drop If the layout supports both moving and resizing components, it should implement method resizeToBounds (), which combines moving and resizing if the user drags the upper-left corner of the component. Design Mode The layout manager can provide different looks (layouts) for design mode (suitable for development) and for real mode (should be the same layout as during run-time) of the form. If the mode is switched, the Design Layout is notified via method setMode(). Possible parameters are DesignLayout.DESIGN_MODE or DesignLayout.REAL_MODE.
- Support methods, which can be used by the DesignLayout to obtain various information about the container and its components:
Every JavaBean component is represented by an instance of RADNode (non-visual), RADVisualNode (visual), RADContainerNode (visual container) or RADFormNode (the top-level container - the form itself). These classes inherit from each other in the order they are mentioned (RADVisualNode is a subclass of RADNode, etc.).There is one instance of FormManager for every form, which provides the management of code generation, components manipulation, adding and removing and persistence of the form.
Methods of those classes can be used to obtain various information about the form and its components.
RADVisualNode.getConstraints()/setConstraints() Are used for storing constraints of specific design layouts.
The design layout can, for example, use constraints of other layout managers to synthesize its constraints. This is used by the GridBagLayout to perform the AbsoluteLayout -> GridBagLayout conversion.RADNode.getName() The name of the variable generated for component represented by the RADNode. RADVisualNode.getComponent() Returns the JavaBean component represented by this RADVisualNode RADVisualNode.getComponentIndex() Returns the index of the JavaBean component represented by this RADVisualNode within its parent container RADContainerNode.getDesignLayout() Returns the DesignLayout used for the container represented by this RADContainerNode RADContainerNode.getPreviousDesignLayout() Returns the DesignLayout that was used before the current DesignLayout RADContainerNode.getSubComponents() Returns the RADVisualNodes representing the subcomponents of the container represented by this RADContainerNode RADContainerNode.getContainerGenName() Helper method which can be used for obtaining the name of the container which should be generated into the source code - returns "" for the top-level container or the container variable name + "." RADContainerNode.getContainer() Returns the JavaBean container represented by this RADContainerNode FormManager.getMode() Returns current mode of the form (DesignLayout.DESIGN_MODE or DesignLayout.REAL_MODE). FormManager.isTestMode() Returns true if the form is currently in the Test Mode
TwoColumnLayout.java
is a simple layout manager.
DesignTwoColumnLayout.java
is the main design-time support.
DesignTwoColumnLayoutBeanInfo.java
is a standard BeanInfo for it.
TestDialog.java
is an example form using the layout. It can be opened by the Form
Editor using the design-time support.