oracle.jdevimpl.uieditor
Interface LayoutAssistant

All Known Implementing Classes:

BasicLayoutAssistant

public interface LayoutAssistant

A LayoutAssistant is a design time only object representing a LayoutManager and is used by the UIEditor 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 UIEditor's toolbar and/or have an associated accelerator, must register the actions with the UIEditorAddin from within a static initializer. The reasons for this 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.

Field Summary

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

void	cleanupRemovedComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode parent) A child of this node's container has been removed.
void	constrainAdd(oracle.jdevimpl.uieditor.uicanvas.ModelNode 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(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, oracle.jdevimpl.uieditor.uicanvas.ModelNode 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.
Explorer	getConstraintsEditor(Context context) Get an Explorer implementation with which to modify the constraints settings, else null.
java.lang.String	getConstraintsType()
javax.swing.JComponent[]	getContextMenuItems(Context context) Get an array of JComponent for population onto a ContextMenu.
javax.swing.JComponent	getEffects(java.awt.Container host) Get a JComponent whose redering provides any special effects applicable during object creation, object resize or object move for the LayoutManager being represented.
java.beans.PropertyEditor	getPropertyEditor()
java.lang.String	getToolbarPrefix() Get the prefix to use in combination with the TOOLBAR_ITEM_COUNT and TOOLBAR_ITEM suffixes in order to fetch Toolbar related properties for this LayoutAssistant from the IDE settings.
boolean	handleEvent(IdeAction action, Context context) Respond to the given user action within the given context.
void	layoutChanged(oracle.jdevimpl.uieditor.uicanvas.ModelNode container) Layout has been switched.
void	prepareAddComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, oracle.jdevimpl.uieditor.uicanvas.ModelNode 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(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, oracle.jdevimpl.uieditor.uicanvas.ModelNode toNode, java.awt.Point location, java.awt.Dimension size) Return a string for display during the add process.
void	prepareChangeLayout(oracle.jdevimpl.uieditor.uicanvas.ModelNode container) Perform changes on children of a container to best handle a layout type change.
java.lang.String	prepareMouseMoveStatus(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, oracle.jdevimpl.uieditor.uicanvas.ModelNode toNode, java.awt.Point location) Return a string for display while the user is moving the mouse over a component.
void	prepareMoveComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, oracle.jdevimpl.uieditor.uicanvas.ModelNode toNode, java.awt.Point location, java.awt.Point offset) Child is being moved.
void	prepareResizeComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, oracle.jdevimpl.uieditor.uicanvas.SelectNib nib) Perform a requested resize on a child.
java.lang.String	prepareResizeStatus(oracle.jdevimpl.uieditor.uicanvas.ModelNode node, java.awt.Point location, java.awt.Dimension size) Return a string for display during the resize process.
void	prepareSelectComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode child, oracle.jdevimpl.uieditor.uicanvas.UICanvas canvas) An immedate child node has been selected.
void	prepareSelectDescendant(oracle.jdevimpl.uieditor.uicanvas.ModelNode parent, oracle.jdevimpl.uieditor.uicanvas.ModelNode child) A descendant node has been selected.
java.lang.String	resizeAction(java.awt.Point newNibLocation, oracle.jdevimpl.uieditor.uicanvas.UICanvas canvas, oracle.jdevimpl.uieditor.uicanvas.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

public 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

public 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

public java.lang.String getConstraintsType()

Returns:

The class name of the constraints type, else null.

getConstraintsEditor

public 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

public java.beans.PropertyEditor getPropertyEditor()

Returns:

A JavaBean property editor that can edit the constraints.

handleEvent

public 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

public 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

public java.lang.String getToolbarPrefix()

Get the prefix to use in combination with the TOOLBAR_ITEM_COUNT and TOOLBAR_ITEM suffixes in order to fetch Toolbar related properties for this LayoutAssistant from the IDE settings.

prepareAddComponent

public void prepareAddComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode node,
                                oracle.jdevimpl.uieditor.uicanvas.ModelNode 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 - ModelNode 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

public void prepareResizeComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode node,
                                   oracle.jdevimpl.uieditor.uicanvas.SelectNib nib)

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

Parameters:

node - the ModelNode that is being re-sized.

nib - the SelectNib that is being manipulated.

prepareMoveComponent

public void prepareMoveComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode node,
                                 oracle.jdevimpl.uieditor.uicanvas.ModelNode toNode,
                                 java.awt.Point location,
                                 java.awt.Point offset)

Child is being moved. Often implemented by calling prepareAddComponent

Parameters:

node - the ModelNode that has moved.

toNode - ModelNode receiving the node.

location - the new location.

offset - the mouse down position relative to the node.

prepareMouseMoveStatus

public java.lang.String prepareMouseMoveStatus(oracle.jdevimpl.uieditor.uicanvas.ModelNode node,
                                               oracle.jdevimpl.uieditor.uicanvas.ModelNode 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

public void prepareChangeLayout(oracle.jdevimpl.uieditor.uicanvas.ModelNode 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 ModelNode for the container that has changed.

layoutChanged

public void layoutChanged(oracle.jdevimpl.uieditor.uicanvas.ModelNode 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.

resizeAction

public java.lang.String resizeAction(java.awt.Point newNibLocation,
                                     oracle.jdevimpl.uieditor.uicanvas.UICanvas canvas,
                                     oracle.jdevimpl.uieditor.uicanvas.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 nib.

Returns:

String to display as a status message.

prepareSelectComponent

public void prepareSelectComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode child,
                                   oracle.jdevimpl.uieditor.uicanvas.UICanvas canvas)

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.

canvas - provides access back to the class that owns the nibs.

See Also:

prepareSelectDescendant(oracle.jdevimpl.uieditor.uicanvas.ModelNode, oracle.jdevimpl.uieditor.uicanvas.ModelNode)

prepareSelectDescendant

public void prepareSelectDescendant(oracle.jdevimpl.uieditor.uicanvas.ModelNode parent,
                                    oracle.jdevimpl.uieditor.uicanvas.ModelNode child)

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

prepareAddStatus

public java.lang.String prepareAddStatus(oracle.jdevimpl.uieditor.uicanvas.ModelNode node,
                                         oracle.jdevimpl.uieditor.uicanvas.ModelNode 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

public java.lang.String prepareResizeStatus(oracle.jdevimpl.uieditor.uicanvas.ModelNode 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

public void cleanupRemovedComponent(oracle.jdevimpl.uieditor.uicanvas.ModelNode parent)

A child of this node's 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

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

Get an array of JComponent for population onto a ContextMenu. Implementations are expected to return a non null 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:

ContextMenu

getEffects

public javax.swing.JComponent getEffects(java.awt.Container host)

Get a JComponent whose redering 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 UIEditor design surface between the glass paen 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:

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

constrainMove

public java.lang.String constrainMove(oracle.jdevimpl.uieditor.uicanvas.ModelNode node,
                                      oracle.jdevimpl.uieditor.uicanvas.ModelNode 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.

constrainAdd

public void constrainAdd(oracle.jdevimpl.uieditor.uicanvas.ModelNode 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.

usesReverseZOrder

public 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).