com.tensegrity.composite
Interface BaseComposite

All Superinterfaces:

Attributable, AttributableOnSet, BaseInteractable

All Known Subinterfaces:

Composite, CompositeControl, CompositeGroup, CompositeLabel, CompositeLine, CompositeSwimLane, CompositeSwimLanePool, CompositeTable, VisualEdgeComposite, VisualGraphObjectComposite, VisualNodeComposite, VisualSubgraphComposite

public interface BaseComposite

extends AttributableOnSet, BaseInteractable

The BaseComposite interface is an aggregated interface that combines multiple roles and responsibilities. Apart from those roles which are inherited, this interface defines new methods that deal with the containment, management and drawing of Primitive objects to a Device.

It is very unlikely that you will create your own class that implements this abstract interface. More likely, you will use classes that already implement derived interfaces, such as Composite and CompositeLine, two concrete specifications that define the behavioral contracts for rectangular and line-based composites respectively.

This interface exists because client code does not always have to differentiate between rectangular and line composites, two types which exhibit deviant runtime behaviors.

A far more comfortable way to add multiple Primitive objects to this container is by using an instance of interface GeometryDescriptor. These named objects are instantiated from an XML file and can be more easily defined and assembled. Moreover, a runtime object of this type provides the configuration data for several Primitive objects anyways. So instead of writing Java code to create the Primitive objects, you can define them as a GeometryDescriptor written in an XML file, load them at system startup and apply them by calling method applyGeometry(GeometryDescriptor)

Similarly, the appearance of a BaseComposite can be set by applying a StyleDescriptor. This object specifies how a Geometry is represented on the screen in terms of line styles, area fill and more. You can invoke the following method multiple times: applyStyle(StyleDescriptor)

A BaseComposite must be representable on the screen. Therefore, it uses a Renderer and a Device object to do so, as you can see in the following draw methods:

• draw(Renderer, Device, int, int, int, int)
• draw(Renderer, Device, Transform2D)
• drawComposite(Renderer, Device, Transform2D)

A BaseComposite is able to manage an InfoValue object. This value object can be used in many different ways. Therefore, the following constants are defined within the BaseComposite interface:

Name	Description
NON_INFOVALUE	No InfoValue is associated with the BaseComposite
GENERAL_INFOVALUE	Defines an InfoValue that is used with no special purpose
DELEGATE_INFOVALUE	Defines an InfoValue for a delegate object. Although delegation is sometimes used instead of generalization, it comes with some problems because the methods of the delegation object do not override the InfoValue. If the InfoValue is marked with this constant, it is used instead of the BaseComposite instance.

Note:

1. When implementing a BaseComposite, you have to support the constants listed above.
2. Because the composite framework is under construction, the definition of more constants is likely.
3. The InfoValue is not deep-copied.

• getInfoValueIdentifier()
• getInfoValue()
• setInfoValue(Object)
• setInfoValue(int, Object)

The control over Primitive object containment is exposed to clients with the following interface methods:

• addPrimitive(Primitive)
• removePrimitive(Primitive)
• getPrimitiveIterator()
• removeAllPrimitives()

A BaseComposite must support the EventMediator protocol introduced by the top-level CompositeView container. The method to do this is

• void registerEventMediator(EventMediator)

We recommend that you do not register your own EventMediator since this is done by the CompositeView, which automatically contains all BaseComposite instances. Please read the class documentation for CompositeView for more information.

The event-throwing mechanism of a BaseComposite can be turned on and off. By invoking the enableEvents method and supplying the specific event mask, you can control which events are thrown. A call to disableEvents, on the other hand, suitably turns off the specified events marked by the event mask parameter.

By default all events are turned on. To determine which events are enabled or disabled, you can invoke the areEventsEnabled method. The event masks are defined by an enumeration in this interface or in an interface that extends this one. Event mask names always start with the EVENT_MASK prefix. The methods a BaseComposite exposes to support the event mechanism are:

• void enableEvents(int)
• void disableEvents(int)
• int getEventMask()
• boolean areEventsEnabled(int)

Because the BaseComposite interface extends the AttributableOnSet interface, an instance will notify registered listeners about changes to the managed Attribute objects. As explained in the AttributableOnSet interface, notifications can be turned on and off by using the appropriate methods.

Note: When turning on or off the attribute change notification of a BaseComposite, the attribute change notification of all contained Primitive objects is updated as well.

Instances of this class draw to a Device using a Renderer component. This interface therefore depends on these two other interfaces in order to fulfill its drawing responsibilities.

By extending the BaseInteractable interface, BaseComposite objects may be selected, repositioned and generally manipulated by mouse actions. Please read the BaseInteractable interface for more information.

By extending the AttributableOnSet interface, BaseComposite objects maintain a set of manipulatable attributes. A common characteristic for a BaseComposite is that its Attribute objects are grouped into categories. Please read the AttributableOnSet interface for more information.

Version:

$Id: BaseComposite.java,v 1.71 2005/09/14 11:27:57 BurkhardWick Exp $

Author:

MichaelKegel

See Also:

Composite, CompositeLine

Field Summary

static int	DELEGATE_INFOVALUE constant that identifies the type of the info value set to the BaseComposite
static int	EVENT_MASK_MOUSE constant that tells about the different events or groups of events and can be used with enableEvents(int) to turn them on and disableEvents(int) to turn them off.
static int	EVENT_MASK_SELECT constant that tells about the different events or groups of events and can be used with enableEvents(int) to turn them on and disableEvents(int) to turn them off.
static int	GENERAL_INFOVALUE constant that identifies the type of the info value set to the BaseComposite
static int	NON_INFOVALUE constant that identifies the type of the info value set to the BaseComposite

Fields inherited from interface com.tensegrity.generic.attribute.AttributableOnSet

TREE_SUBSET_POSTFIX

Method Summary

void	addPrimitive(Primitive primitive) Adds the given Primitive to the composites list of primitives.
void	adjustGeometry() Adjusts the geometry of the BaseComposite.
void	adjustGeometry(Transform2D xform_context, ScaleValues scalevalues) Adjusts the geometry of the BaseComposite.
void	applyGeometry(GeometryDescriptor geometry) Applies the GeometryDescriptor given by geometry to the BaseComposite.
void	applyStyle(StyleDescriptor style) Applies the StyleDescriptor given by style to the Composite.
boolean	areEventsEnabled(int eventmask) Returns a flag that indicates weather the event or group of events specified by the given mask is actually turned on or not.
void	disableEvents(int eventmask) Turns off the event or a group of events specified by the given mask.
void	draw(Renderer renderer, Device device, int bBoxLeft, int bBoxTop, int bBoxRight, int bBoxBottom) This method is called from outside when it is not possible to create a transformation for the context the BaseComposite lies within (This occurs for instance when using a coordinate system, that is not able to create a linear transformation).
void	draw(Renderer renderer, Device device, Transform2D xform_context) This method is called from the context the BaseComposite lies within.
void	drawComposite(Renderer renderer, Device device, Transform2D xform_composite) This method is called from draw(Renderer, Device, Transform2D) or from draw(Renderer, Device, int, int, int, int).
void	enableEvents(int eventmask) Turns on the event or a group of events specified by the given mask.
BaseCompositeContainer	getBaseCompositeContainer() Returns the current parent container the BaseComposite is added to.
int	getEventMask() Returns the actual event mask of the BaseComposite.
java.lang.String	getGeometryName() Returns the name of the GeometryDescriptor that has been applied to the BaseComposite at last.
java.lang.Object	getInfoValue() Returns the InfoValue assigned to the BaseComposite or null if no InfoValue has been assigned.
int	getInfoValueIdentifier() Returns the identifier that specifies the usage of the InfoValue.
java.lang.String	getName() Returns a String that represents the name for the BaseComposite.
PrimitiveIterator	getPrimitiveIterator() Returns a PrimitiveIterator that can be used to walk through the BaseComposite's list of Primitives.
int	getShadowColor()
double	getShadowDirection()
java.lang.String	getStyleName() Returns the name of the StyleDescriptor that has been applied to the BaseComposite at last.
void	internalSetGeometryName(java.lang.String name) Sets the name for the geometry of the BaseComposite to the value given by name.
void	internalSetStyleName(java.lang.String name) Sets the name for the style of the BaseComposite to the value given by name.
boolean	isDeletable()
boolean	isShadowVisible() Returns true if a shadow is drawn, false o.w..
void	registerAttributeConstraint(java.lang.String attributename, Constraint constraint) Registers the Constraint given by constraint at the BaseComposite's attribute constraint registry.
void	registerEventMediator(EventMediator mediator) Registers the EventMediator object given by mediator to the BaseComposite.
void	registerVetoableEventMediator(VetoableEventMediator vmediator) Registers the VetoableEventMediator object given by vmediator to the BaseComposite.
void	removeAllPrimitives() Removes all Primitives from the BaseComposite's list of Primitives.
void	removePrimitive(Primitive primitive) Removes the given Primitive from the composites list of primitives.
void	setBaseCompositeContainer(BaseCompositeContainer parent) Sets the BaseCompositeContainer given by parent as the new parent container for the BaseComposite.
void	setDeletable(boolean deletable)
void	setEventMask(int eventmask)
void	setInfoValue(int identifier, java.lang.Object infovalue) Sets the given Object as the new InfoValue of this BaseComposite.
void	setInfoValue(java.lang.Object infovalue) Sets the given Object as the new InfoValue of this BaseComposite.
void	setName(java.lang.String name) Sets the name for the BaseComposite to the value given by name.
void	setShadowColor(int shadowcolor)
void	setShadowDirection(double direction)
void	setShadowVisible(boolean visible) Sets whether or not a shadow is drawn.
void	unregisterAttributeConstraint(java.lang.String attributename) Removes the Constraint that is identified through the key given by attributename from the BaseComposite's attribute constraint registry.

Methods inherited from interface com.tensegrity.generic.attribute.AttributableOnSet

addAttributableOnSetListener, areAttributableEventsEnabled, disableAttributableEvents, enableAttributableEvents, getAttributes, getAttributesTree, removeAttributableOnSetListener, setAttributes, setAttributesTree

Methods inherited from interface com.tensegrity.generic.attribute.Attributable

getAttribute, getAttributeType, getAttributeValue, setAttribute, setAttributeValue

Methods inherited from interface com.tensegrity.graphics.interaction.BaseInteractable

getBoundingBox, getInteractionDescriptor, getMoveItem, hits, internalEnableSelection, internalSelect, internalSetSelected, isMovable, isSelectable, isSelected, mouseClick, mouseDown, mouseEnter, mouseExit, mouseUp, postActing, preActing, select, setMovable, setSelectable, setSelected, startAction, stopAction

Field Detail

EVENT_MASK_MOUSE

public static final int EVENT_MASK_MOUSE

constant that tells about the different events or groups of events and can be used with enableEvents(int) to turn them on and disableEvents(int) to turn them off.

See Also:

Constant Field Values

EVENT_MASK_SELECT

public static final int EVENT_MASK_SELECT

constant that tells about the different events or groups of events and can be used with enableEvents(int) to turn them on and disableEvents(int) to turn them off.

See Also:

Constant Field Values

NON_INFOVALUE

public static final int NON_INFOVALUE

constant that identifies the type of the info value set to the BaseComposite

See Also:

Constant Field Values

GENERAL_INFOVALUE

public static final int GENERAL_INFOVALUE

constant that identifies the type of the info value set to the BaseComposite

See Also:

Constant Field Values

DELEGATE_INFOVALUE

public static final int DELEGATE_INFOVALUE

constant that identifies the type of the info value set to the BaseComposite

See Also:

Constant Field Values

Method Detail

isDeletable

public boolean isDeletable()

setDeletable

public void setDeletable(boolean deletable)

isShadowVisible

public boolean isShadowVisible()

Returns true if a shadow is drawn, false o.w..

Returns:

true if a shadow is drawn, false o.w..

setShadowVisible

public void setShadowVisible(boolean visible)

Sets whether or not a shadow is drawn.

Parameters:

visible - true if a shadow should be drawn.

getShadowColor

public int getShadowColor()

setShadowColor

public void setShadowColor(int shadowcolor)

getShadowDirection

public double getShadowDirection()

setShadowDirection

public void setShadowDirection(double direction)

getName

public java.lang.String getName()

Returns a String that represents the name for the BaseComposite.

Returns:

String the name of the BaseComposite

setName

public void setName(java.lang.String name)

Sets the name for the BaseComposite to the value given by name.

Parameters:

name - the new name for the BaseComposite

adjustGeometry

public void adjustGeometry()

Adjusts the geometry of the BaseComposite. Notice that a call to this method has an effect only when the BaseComposite has already been added to a CompositeView.

adjustGeometry

public void adjustGeometry(Transform2D xform_context,
                           ScaleValues scalevalues)

Adjusts the geometry of the BaseComposite.
To do so the Composite uses the context transformation and the zoom values given by xform_context, scalevalues. The given scalevalues must reflect the current scale value of the CompositeView. They are not meant as scale values for the BaseComposite itself.

Notice that this method can be used when the BaseComposite has not been added to a CompositeView.

Parameters:

xform_context - the context transformation

scalevalues - the scale values for the different directions the CompositeView has been set to

addPrimitive

public void addPrimitive(Primitive primitive)

Adds the given Primitive to the composites list of primitives.

Parameters:

primitive - the Primitive to add

Find more information in the class documentation

removePrimitive

public void removePrimitive(Primitive primitive)

Removes the given Primitive from the composites list of primitives.

Parameters:

primitive - the Primitive to remove

Find more information in the class documentation

getPrimitiveIterator

public PrimitiveIterator getPrimitiveIterator()

Returns a PrimitiveIterator that can be used to walk through the BaseComposite's list of Primitives.

Returns:

PrimitiveIterator to walk through the BaseComposite's list of Primitives

Find more information in the class documentation

removeAllPrimitives

public void removeAllPrimitives()

Removes all Primitives from the BaseComposite's list of Primitives.

Find more information in the class documentation

getInfoValueIdentifier

public int getInfoValueIdentifier()

Returns the identifier that specifies the usage of the InfoValue.

Returns:

int constant that specifies the usage of the InfoValue

See Also:

GENERAL_INFOVALUE, DELEGATE_INFOVALUE

Find more information in the class documentation

getInfoValue

public java.lang.Object getInfoValue()

Returns the InfoValue assigned to the BaseComposite or null if no InfoValue has been assigned. It is recommended to read the documentation of this interface to get a deeper understanding of how the InfoValue is used.

Returns:

the InfoValue associated with the BaseComposite.

Find more information in the class documentation

setInfoValue

public void setInfoValue(java.lang.Object infovalue)

Sets the given Object as the new InfoValue of this BaseComposite. Setting the InfoValue with this method identifies it as a GENERAL_INFOVALUE. It is recommended to read the documentation of this interface to get a deeper understanding of how a InfoValue can be used.

Parameters:

infovalue - the Object to associate with the BaseComposite

See Also:

GENERAL_INFOVALUE, DELEGATE_INFOVALUE

Find more information in the class documentation

setInfoValue

public void setInfoValue(int identifier,
                         java.lang.Object infovalue)

Sets the given Object as the new InfoValue of this BaseComposite. The InfoValue is identified by the constant that is given by identifier. It is recommended to read the documentation of this interface to get a deeper understanding of how the InfoValue is used.

Parameters:

identifier - that specifies the usage of the InfoValue

infovalue - the Object to associate with the BaseComposite

See Also:

GENERAL_INFOVALUE, DELEGATE_INFOVALUE

Find more information in the class documentation

registerAttributeConstraint

public void registerAttributeConstraint(java.lang.String attributename,
                                        Constraint constraint)

Registers the Constraint given by constraint at the BaseComposite's attribute constraint registry. This Constraint is later on referred to through the key given by attributename.

Registered Constraints are matched to composite attributes through the key they are registered with by the following rule. The key must be the concatenation of the name of the category and the name of the attribute seperated by '.'. For example there is a category 'Geometry' and an attribute 'X' in the that category. In order to register a Constraint for that attribute one has to register it with the key 'Geometry.X'.

NOTICE:If for an attribute a Constraint is registered at the global CompositeAttributeConstraintRegistry and also at the BaseComposite's attribute constraint registry the one from the BaseComposite's attribute constraint registry is used.

Parameters:

attributename - the key of the Constraint to register. A Constraint that has been registered under the same key will be overridden. This value must not be null.

constraint - the Constraint to register. This value must not be null.

unregisterAttributeConstraint

public void unregisterAttributeConstraint(java.lang.String attributename)

Removes the Constraint that is identified through the key given by attributename from the BaseComposite's attribute constraint registry.

Parameters:

attributename - the key of the Constraint to remove

getGeometryName

public java.lang.String getGeometryName()

Returns the name of the GeometryDescriptor that has been applied to the BaseComposite at last. If no GeometryDescriptor has been applied 'none' is returned.

Returns:

the name of the current GeometryDescriptor or 'none'

internalSetGeometryName

public void internalSetGeometryName(java.lang.String name)

Sets the name for the geometry of the BaseComposite to the value given by name. NOTICE:A Call to this method does not apply the GeometryDescriptor specified by the given name to the BaseComposite. It only sets the value for the name of the GeometryDescriptor to the given name. The name is returned later on by getGeometryName().
Normally this method is only called by the Composite API itself and it is recommended not to use it.

Parameters:

name - the new name for the BaseComposite's geometry

applyGeometry

public void applyGeometry(GeometryDescriptor geometry)
                   throws GeometryNotSupportedException

Applies the GeometryDescriptor given by geometry to the BaseComposite.

Parameters:

geometry - the geometry to apply

Throws:

GeometryNotSupportedException - is thrown when the GeometryDescriptor given by geometry is invalid or not suitable for the BaseComposite

getStyleName

public java.lang.String getStyleName()

Returns the name of the StyleDescriptor that has been applied to the BaseComposite at last. If no StyleDescriptor has been applied 'none' is returned.

Returns:

the name of the current StyleDescriptor or 'none'

internalSetStyleName

public void internalSetStyleName(java.lang.String name)

Sets the name for the style of the BaseComposite to the value given by name. NOTICE:A Call to this method does not apply the StyleDescriptor specified by the given name to the BaseComposite. It only sets the value for the name of the style to the given name. The name is returned later on by getStyleName().
Normally this method is only called by the Composite API itself and it is recommended not to use it.

Parameters:

name - the new name for the BaseComposite's style

applyStyle

public void applyStyle(StyleDescriptor style)
                throws StyleNotApplicableException

Applies the StyleDescriptor given by style to the Composite.

Parameters:

style - the style to apply

Throws:

StyleNotApplicableException - is thrown when the StyleDescriptor given by style is invalid or not suitable for the Composite

enableEvents

public void enableEvents(int eventmask)

Turns on the event or a group of events specified by the given mask. The event masks are defined by an enumeration in this interface. Their names are always starts width EVENT_MASK_. It is possible to combine several event masks like EVENT_MASK_MOVE | EVENT_MASK_RESIZE.

Parameters:

eventmask - the specifying mask for the event or group of events to turn on

Find more information in the class documentation

disableEvents

public void disableEvents(int eventmask)

Turns off the event or a group of events specified by the given mask. The event masks are defined by an enumeration in this interface. Their names are always starts width EVENT_MASK_. It is possible to combine several event masks like EVENT_MASK_CHANGE | EVENT_MASK_MOVE.

Parameters:

eventmask - the specifying mask for the event or group of events to turn off

Find more information in the class documentation

areEventsEnabled

public boolean areEventsEnabled(int eventmask)

Returns a flag that indicates weather the event or group of events specified by the given mask is actually turned on or not. The event masks are defined by an enumeration in this interface. Their names are always starts width EVENT_MASK_. It is NOT possible to combine several event masks like EVENT_MASK_CHANGE | EVENT_MASK_MOVE.

Parameters:

eventmask - the specifying mask for the event or group of events to check enabling for

Returns:

boolean flag that indicates the enabled state

Find more information in the class documentation

getEventMask

public int getEventMask()

Returns the actual event mask of the BaseComposite. The event mask specifies which events are turned on and which events are turned of. It is an OR combination of the EVENT_MASK_ constants that are defined in this interface or in an interface that extends this one.

Returns:

int the actual event mask

Find more information in the class documentation

setEventMask

public void setEventMask(int eventmask)

registerEventMediator

public void registerEventMediator(EventMediator mediator)

Registers the EventMediator object given by mediator to the BaseComposite. Subsequently the mediator will be informed about all events that occurs at the Composite. Notice that this method is an internal method used by the framework and forceful recommended not to work with!!

Parameters:

mediator - the EventMediator to register

Find more information in the class documentation

registerVetoableEventMediator

public void registerVetoableEventMediator(VetoableEventMediator vmediator)

Registers the VetoableEventMediator object given by vmediator to the BaseComposite. Subsequently the vmediator will be informed about all events that occurs at the BaseComposite. NOTICE that this method is an internal method used by the framework and it is forceful recommended not to work with!!

Parameters:

vmediator - the VetoableEventMediator to register

getBaseCompositeContainer

public BaseCompositeContainer getBaseCompositeContainer()

Returns the current parent container the BaseComposite is added to. If the BaseComposite is not added to a BaseCompositeContainer null is returned.

Returns:

BaseCompositeContainer the BaseCompositeContainer the BaseComposite is added to or null

setBaseCompositeContainer

public void setBaseCompositeContainer(BaseCompositeContainer parent)

Sets the BaseCompositeContainer given by parent as the new parent container for the BaseComposite.

NOTICE: This this method is an internal method used by the framework and it is forceful recommended not to work with!!

Parameters:

parent - the new BaseCompositeContainer of the BaseComposite

draw

public void draw(Renderer renderer,
                 Device device,
                 Transform2D xform_context)

This method is called from the context the BaseComposite lies within. The Transform2D given by xform_context is the transformation needed to draw within the context and is used to draw the BaseComposite.

Parameters:

renderer - instance to render the BaseComposite

device - instance to output the BaseComposite onto

xform_context - the context transformation

Find more information in the class documentation

draw

public void draw(Renderer renderer,
                 Device device,
                 int bBoxLeft,
                 int bBoxTop,
                 int bBoxRight,
                 int bBoxBottom)

This method is called from outside when it is not possible to create a transformation for the context the BaseComposite lies within (This occurs for instance when using a coordinate system, that is not able to create a linear transformation). In this case the bounding box of the BaseComposite has to be created from the context the BaseComposite lies within.

Parameters:

renderer - instance to render the BaseComposite

device - instance to output the BaseComposite onto

bBoxLeft - the x component of the left/top coordinate

bBoxTop - the y component of the left/top coordinate

bBoxRight - the x component of the right/bottom coordinate

bBoxBottom - the y component of the right/bottom coordinate

Find more information in the class documentation

drawComposite

public void drawComposite(Renderer renderer,
                          Device device,
                          Transform2D xform_composite)

This method is called from draw(Renderer, Device, Transform2D) or from draw(Renderer, Device, int, int, int, int). The Transform2D given by xform_composite is the transformation of the composite which is needed to draw the Primitives added to the BaseComposite.

Parameters:

renderer - instance to render the BaseComposite

device - instance to output the BaseComposite onto

xform_composite - the transformation of the BaseComposite