oracle.jdeveloper.uieditor.uicanvas

Interface LayoutAssistant

All Known Implementing Classes:

AbstractAssistant

public interface LayoutAssistant

A LayoutAssistant is a design time only object representing a LayoutManager and is used by the UICanvas to simplify UI design operations. This might include the offering of convenience functions such as alignment, sizing and spacing, and z-order manipulations, as well as providing textual and/or visual feedback during such operations as adding, moving and resizing of controls. Feedback typically is in the form of a text message on the status line and a bounding box displayed on the design surface to indicate to the user the location and dimensions to be applied for a given add, move or resize operation.

Only a single instance of each LayoutAssitant implementation will ever be constructed. Thus, implementations should be stateless as their single instance will be used for all instances of the represented LayoutManager found in the user's UI construction.

Implementations that wish to provide convenience functions which are available to be exposed on the UICanvas' toolbar and/or have an associated accelerator, must register the actions with the appropriate ModelFactory from within a static initializer. Registration is made via the ModelFactory that produces the UICanvas and can be fetched via UIManager.getFactory passing UIModel.class as the argument. The reasons for static registration are twofold: 1) The IdeAction instances must have been constructed and retrievable from the IdeAction.find method for toolbar item creation during initialization of each UIEditor toolbar. 2) The IdeAction instances must have been constructed and retrievable from the IdeAction.find method for accelerator key mappings during initialization of each UIEditor glass pane.

See Also:

ModelFactory, UIManager, UICanvas, UIModel

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TOOLBAR_ITEM Property suffix to use in combination with getToolbarPrefix() for fetching individual Toolbar items for this LayoutAssistant from the IDE settings.
static java.lang.String	TOOLBAR_ITEM_COUNT Property suffix to use in combination with getToolbarPrefix() for fetching the number of available Toolbar items for this LayoutAssistant from the IDE settings.

Method Summary

Methods

Modifier and Type	Method and Description
void	cleanupRemovedComponent(CmtModelNode parent) A child of a container has been removed.
void	constrainAdd(CmtModelNode toNode, java.awt.Point mouseOrigin, java.awt.Point mousePos, java.awt.Point newPos, java.awt.Dimension newSize) Optionally modify size and position of an object being added to conform to the constraints imposed by the LayoutManager being represented.
java.lang.String	constrainMove(CmtModelNode node, CmtModelNode toNode, java.awt.Point mousePos, java.awt.Point mouseOffset, java.awt.Point newPos, java.awt.Dimension newSize) Optionally modify size and position of an object being moved to conform to the constraints imposed by the LayoutManager being represented.
void	drawGrid(java.awt.Container host, java.awt.Graphics g) Gives some special effects to the container based on the LayoutManager.
Explorer	getConstraintsEditor(Context context) Get an Explorer implementation with which to modify the constraints settings, else null.
java.lang.String	getConstraintsType() Get the fully qualified class name of the type of the constraints used by the LayoutManager being represented.
javax.swing.JComponent[]	getContextMenuItems(Context context) Get an array of JComponent for population onto a ContextMenu.
javax.swing.JComponent	getEffects(UICanvas canvas, java.awt.Container host) Get a JComponent whose rendering provides any special effects applicable during object creation, object resize or object move for the LayoutManager being represented.
java.lang.String	getInitializer() Get initialization string for use in declaration allocation, else null.
java.beans.PropertyEditor	getPropertyEditor() Get a PropertyEditor for use when editing instances of the constraints used by the LayoutManager being represented.
java.lang.String	getToolbarPrefix() Get the toolbar to use for this layout assistant.
boolean	handleEvent(IdeAction action, Context context) Respond to the given user action within the given context.
boolean	hasInitializer() Determine whether or not this assistant generates an initialization string for use in the declaration allocation.
void	layoutChanged(CmtModelNode container) Layout has been switched.
void	prepareAddComponent(CmtModelNode node, CmtModelNode toNode, java.awt.Point location, java.awt.Point offset, java.awt.Dimension size) Perform any preparation on a child component that will be added into to a container.
java.lang.String	prepareAddStatus(CmtModelNode node, CmtModelNode toNode, java.awt.Point location, java.awt.Dimension size) Return a string for display during the add process.
void	prepareChangeLayout(CmtModelNode container) Perform changes on children of a container to best handle a layout type change.
java.lang.String	prepareMouseMoveStatus(CmtModelNode node, CmtModelNode toNode, java.awt.Point location) Return a string for display while the user is moving the mouse over a component.
void	prepareMoveComponent(CmtModelNode node, CmtModelNode toNode, java.awt.Point location, java.awt.Point offset) Child is being moved.
void	prepareResizeComponent(CmtModelNode node, SelectionEffects effects, SelectNib nib) Perform a requested resize on a child.
java.lang.String	prepareResizeStatus(CmtModelNode node, java.awt.Point location, java.awt.Dimension size) Return a string for display during the resize process.
void	prepareSelectComponent(CmtModelNode child, SelectionEffects effects) An immedate child node has been selected.
void	prepareSelectDescendant(CmtModelNode parent, CmtModelNode child, SelectionEffects effects) A descendant node has been selected.
java.lang.String	resizeAction(java.awt.Point newNibLocation, SelectionEffects effects, SelectNib nib) Return a status message string that will be displayed while the user is dragging the nib.
boolean	update(IdeAction action, Context context) Update the enabled state of the given action within the given context.
boolean	usesReverseZOrder() Determine whether or not z-order is reversed.

Field Detail

TOOLBAR_ITEM_COUNT

static final java.lang.String TOOLBAR_ITEM_COUNT

Property suffix to use in combination with getToolbarPrefix() for fetching the number of available Toolbar items for this LayoutAssistant from the IDE settings.

See Also:

Constant Field Values

TOOLBAR_ITEM

static final java.lang.String TOOLBAR_ITEM

Property suffix to use in combination with getToolbarPrefix() for fetching individual Toolbar items for this LayoutAssistant from the IDE settings.

See Also:

Constant Field Values

Method Detail

getConstraintsType

java.lang.String getConstraintsType()

Get the fully qualified class name of the type of the constraints used by the LayoutManager being represented.

Returns:

The class name of the constraints type, else null.

getConstraintsEditor

Explorer getConstraintsEditor(Context context)

Get an Explorer implementation with which to modify the constraints settings, else null.

Parameters:

context - the Context describing the selection to be edited.

Returns:

an Explorer implementation for editing the constraints of the selected objects.

getPropertyEditor

java.beans.PropertyEditor getPropertyEditor()

Get a PropertyEditor for use when editing instances of the constraints used by the LayoutManager being represented.

Returns:

A JavaBean property editor that can edit the constraints.

hasInitializer

boolean hasInitializer()

Determine whether or not this assistant generates an initialization string for use in the declaration allocation. Implementations of this method should not display any UI. Default is false.

getInitializer

java.lang.String getInitializer()

Get initialization string for use in declaration allocation, else null. Implementing subclasses may display any necessary UI for gathering data before returning a value. A value of null will be interpreted to mean that the declaration should just use the default constructor without any initialization arguments. Default is null.

handleEvent

boolean handleEvent(IdeAction action,
                  Context context)

Respond to the given user action within the given context.

Parameters:

action - user action to be responded to.

context - context in which action was initiated.

Returns:

true if the action was recognized and handled.

update

boolean update(IdeAction action,
             Context context)

Update the enabled state of the given action within the given context.

Parameters:

action - action whose availability is to be updated.

context - the current context.

Returns:

true if the action was recognized and updated.

getToolbarPrefix

java.lang.String getToolbarPrefix()

Get the toolbar to use for this layout assistant.

Returns:

the toolbar id. This should correspond to a toolbar defined in the extension/menu-hook/toolbars section of an extension manifest.

prepareAddComponent

void prepareAddComponent(CmtModelNode node,
                       CmtModelNode toNode,
                       java.awt.Point location,
                       java.awt.Point offset,
                       java.awt.Dimension size)

Perform any preparation on a child component that will be added into to a container. Typically this involves setting the node's constraint value. The new component has already been added to the container via container.add(component). After the constraint is set by this method and/or the add order of the components manipulated, it will be re-added with the supplied constraint.

Parameters:

node - the node being added.

toNode - CmtModelNode receiving the node.

location - the location in the parent.

offset - the mouse down position relative to the node.

size - the size of the component.

prepareResizeComponent

void prepareResizeComponent(CmtModelNode node,
                          SelectionEffects effects,
                          SelectNib nib)

Perform a requested resize on a child. Sets a new constraint value for the node

Parameters:

node - the CmtModelNode that is being resized.

effects - the SelectionEffects associated with the UIEditor upon which the SelectNib appears

nib - the SelectNib that is being manipulated.

prepareMoveComponent

void prepareMoveComponent(CmtModelNode node,
                        CmtModelNode toNode,
                        java.awt.Point location,
                        java.awt.Point offset)

Child is being moved. Often implemented by calling prepareAddComponent

Parameters:

node - the CmtModelNode that has moved.

toNode - CmtModelNode receiving the node.

location - the new location.

offset - the mouse down position relative to the node.

prepareMouseMoveStatus

java.lang.String prepareMouseMoveStatus(CmtModelNode node,
                                      CmtModelNode toNode,
                                      java.awt.Point location)

Return a string for display while the user is moving the mouse over a component. Typically used to identify the node and display the constraint for the component that would be selected if the user were to release the mouse.

Parameters:

node - the node that the mouse is over.

toNode - the parent of the node that the mouse is over.

location - Point relative to parent's upper left corner.

Returns:

A status message.

prepareChangeLayout

void prepareChangeLayout(CmtModelNode container)

Perform changes on children of a container to best handle a layout type change. Should set the contraints for each Component in the container. The layout of the container has already been switched when this call is made.

Parameters:

container - the CmtModelNode for the container that has changed.

layoutChanged

void layoutChanged(CmtModelNode container)

Layout has been switched. Chance for the old Container to clean up its mess. For instance; when switching from null layout, the NullLayoutAssistant uses this call to remove the Bounds property settings for each component in the Container.

Parameters:

container - teh CmtModelNode for the container that has changed.

resizeAction

java.lang.String resizeAction(java.awt.Point newNibLocation,
                            SelectionEffects effects,
                            SelectNib nib)

Return a status message string that will be displayed while the user is dragging the nib. Called once for each mouse dragged event processed during a resize operation

Parameters:

newNibLocation - new position of the SelectNib being manipulated.

effects - the SelectionEffects associated with the UICanvas upon which the SelectNib appears.

nib - the SelectNib being manipulated.

Returns:

String to display as a status message.

prepareSelectComponent

void prepareSelectComponent(CmtModelNode child,
                          SelectionEffects effects)

An immedate child node has been selected. Display selection nibs as desired and raise child to view as necessary via prepareSelectDescendant such that the child will be visible.

Parameters:

child - the selected node.

effects - the SelectionEffects associated with the UICanvas upon which the selection has taken place.

See Also:

prepareSelectDescendant(oracle.jdeveloper.cmt.CmtModelNode, oracle.jdeveloper.cmt.CmtModelNode, oracle.jdeveloper.uieditor.uicanvas.SelectionEffects)

prepareSelectDescendant

void prepareSelectDescendant(CmtModelNode parent,
                           CmtModelNode child,
                           SelectionEffects effects)

A descendant node has been selected. Recursively call up the hierarchy passing the parent as the child and its parent as the parent, then raise the original child within the original parent as necessary such that it will be visible for selection.

Parameters:

parent - the root of the selection path

child - the branch of the selection path stemming from parent

effects - the SelectionEffects associated with the UICanvas upon which the selection has taken place.

prepareAddStatus

java.lang.String prepareAddStatus(CmtModelNode node,
                                CmtModelNode toNode,
                                java.awt.Point location,
                                java.awt.Dimension size)

Return a string for display during the add process.

Parameters:

node - the node about to be added.

toNode - the parent that the node will be added to.

location - new Point relative to parent's upper left corner.

size - the size of the new node.

Returns:

A status message.

prepareResizeStatus

java.lang.String prepareResizeStatus(CmtModelNode node,
                                   java.awt.Point location,
                                   java.awt.Dimension size)

Return a string for display during the resize process.

Parameters:

node - the node being resized.

location - new Point relative to parent's upper left corner.

size - the size of the new node.

Returns:

A status message.

cleanupRemovedComponent

void cleanupRemovedComponent(CmtModelNode parent)

A child of a container has been removed. This offers the LayoutAssistant the chance to clean up any data structures that it keeps for the container.

Parameters:

parent - The node that had a child removed.

getContextMenuItems

javax.swing.JComponent[] getContextMenuItems(Context context)

Get an array of JComponent for population onto a ContextMenu. Implementations are expected to return an array which may contain zero or more instances of JComponent. Implementations are expected to handle all associated listener registration on those items.

Parameters:

context - the current context.

Returns:

An array of JComponent that will be added to the ContextMenu on behalf of this LayoutAssistant.

See Also:

oracle.ide.ContextMenu

getEffects

javax.swing.JComponent getEffects(UICanvas canvas,
                                java.awt.Container host)

Get a JComponent whose rendering provides any special effects applicable during object creation, object resize or object move for the LayoutManager being represented. The effects object will be added to the UICanvas design surface between the glass pane and the content pane such that the effects will overlap the content. An example might be a simple transparent JPanel whose paint method renders equally spaced grid points in support of an XYLayout or Null layout.

Parameters:

canvas - UICanvas displaying the GUI

host - Container upon which an object is being added, resized or moved.

Returns:

a special effects object.

constrainMove

java.lang.String constrainMove(CmtModelNode node,
                             CmtModelNode toNode,
                             java.awt.Point mousePos,
                             java.awt.Point mouseOffset,
                             java.awt.Point newPos,
                             java.awt.Dimension newSize)

Optionally modify size and position of an object being moved to conform to the constraints imposed by the LayoutManager being represented. This method may be called from the UIEditor during a move operation such that it may provide dynamic feedback to the user depicting the expected bounds of the object throughout the operation.

Parameters:

node - node being manipulated.

toNode - parent of node being manipulated.

mousePos - current mouse position relative to toNode.

mouseOffset - mouse position relative to node at beginning of move.

newPos - output parameter for receiving constrained drop location.

newSize - output parameter for receiving constrained drop size.

Returns:

a descriptive message describing the move.

constrainAdd

void constrainAdd(CmtModelNode toNode,
                java.awt.Point mouseOrigin,
                java.awt.Point mousePos,
                java.awt.Point newPos,
                java.awt.Dimension newSize)

Optionally modify size and position of an object being added to conform to the constraints imposed by the LayoutManager being represented. This method may be called from the UIEditor during an add operation such that it may provide dynamic feedback to the user depicting the expected bounds of the object throughout the operation.

Parameters:

toNode - parent of node being added.

mouseOrigin - mouse position at start of move operation.

mousePos - current mouse position.

newPos - output parameter for receiving constrained add position.

newSize - output parameter for receiving constrained add size.

usesReverseZOrder

boolean usesReverseZOrder()

Determine whether or not z-order is reversed. Normally, z-order is based on addition order in that the most recently added child is at the top of the z-order (i.e. would obscure any lower z-order sibling with whom it's bounds overlapped). However, some layouts reverse this in that the most recently added child is at the bottom of the z-order (i.e. would be obscured by any higher z-order siblings with whom it's bounds overlapped).

Returns:

true if uses reverse z-order.

drawGrid

void drawGrid(java.awt.Container host,
            java.awt.Graphics g)

Gives some special effects to the container based on the LayoutManager. In case of a FormLayout manager which is based on rows and columns, this method will give the visual effects of rows and column by drawing gird. this is acheived by the paint mehtod of the host container.

Parameters:

host - Container upon which the grid is being drawn.

g - Graphics object to draw the gird.