ilog.views.prototypes
Class IlvGroup

java.lang.Object
  ilog.views.prototypes.IlvGroupElement
      ilog.views.prototypes.IlvGroup

All Implemented Interfaces:

IlvPersistentObject, Serializable

Direct Known Subclasses:

IlvPrototype, IlvPrototypeInstance

public class IlvGroup
extends IlvGroupElement

An IlvGroup is a logical, hierarchical collection of objects.

The elements of a group are instances of subclasses of IlvGroupElement. Existing subclasses of IlvGroupElement are IlvGraphicElement that contain IlvGraphic objects and IlvGroup.

Since IlvGroup objects can contain any kind of object, they provide a generic programming interface based on named properties. This interface is defined in the superclass IlvGroupElement. The actual effect of changing a property of a group depends on the objects contained in the group and on the IlvBehavior objects attached to this group.

Most groups contain graphic elements. The following properties of a group let you set or get the corresponding properties of all its graphic elements:

• baseLayer
• layer
• grapherNode
• visible

Examples:

The following code:

     group.set("visible", false);
 

will make all the graphic elements of the group invisible.

The following code:

     group.set("baseLayer", 10);
 

will move each graphic element to the layer 10+n, where n is the value of the layer property of the graphic element.

The following code:

     group.set("layer", 5);
 

will set the relative layer of all the graphic elements to 5.

The following code:

     group.set("grapherNode", true);
 

will make each graphic element of the group a grapher node.

See Also:

IlvGroupElement, IlvGraphicElement, IlvBehavior, IlvPrototype, IlvPrototypeInstance, Serialized Form

Field Summary

static String

indeterminate This value is returned by the get methods when a graphic property has different values for different graphic elements of the group.

Constructor Summary

IlvGroup(IlvGroup source)
Creates a copy of an existing group.

IlvGroup(IlvInputStream in)
Reads an IlvGroup from an IlvInputStream.

IlvGroup(String name)
Creates a new, empty IlvGroup with the given name.

Method Summary

void	addBehavior(IlvBehavior acc) Adds a behavior object to this group.
void	addElement(IlvGroupElement element) Adds an element to this group.
void	clear() Removes all the elements and behavior objects attached to this group.
IlvGroupElement	copy() Returns a copy of the group.
void	copy(IlvGroup source) Makes this group a copy of another group.
IlvGroupElement	findElement(String name) Finds an element in the group from its name.
Enumeration	getBehaviors() Returns all the behavior objects that are attached to the group.
Enumeration	getElements() Returns the elements in the group.
IlvGroupBag	getGroupBag() Returns the IlvGroupBag object that contains the group or null if the group does not belong to a group bag.
IlvGroupFrame	getGroupFrame() Returns the IlvGroupFrame used to select this group in a manager.
IlvGroup	getTopGroup() Returns the top level ancestor of this group by going up the parent chain until a null parent is found.
String[]	getValueNames(boolean publicOnly) Returns the names of the properties handled by the behavior objects attached to the group.
boolean	isABehaviorValue(String valueName, boolean publicOnly) Tests if a property exists and is handled by a behavior object.
boolean	isOutput(String name) Returns true if the specified property is an output property.
boolean	isPrivate(String name) Returns true if the specified property is private.
void	removeBehavior(IlvBehavior acc) Removes a behavior object from the group.
void	removeElement(IlvGroupElement element) Removes an element from this group.
void	renameValue(String oldName, String newName) Renames the oldName property handled by all the behavior objects associated with this group as newName.
static void	setMessageWriter(PrintWriter writer) Changes the writer object used by the library to print messages.
void	setPrivate(String name, boolean priv) Marks a property of this group as private.
void	swapBehaviors(IlvBehavior b1, IlvBehavior b2) Swaps the positions of the behavior objects b1 and b2.
boolean	traverse(IlvGroupTraverser traverser) Recursively traverses all the elements in a group.
void	unsubscribe(IlvGroupElement subscriber, String sourceValue, String subscriberValue) This method is overridden from the IlvGroupElement class to handle subscriptions to group elements (using the same dot notation as for set/get).
void	write(IlvOutputStream out) Writes an IlvGroup to an IlvOutputStream.

Methods inherited from class ilog.views.prototypes.IlvGroupElement

applyTransform, applyTransform, boundingBox, boundingBox, get, get, get, getBoolean, getDouble, getFloat, getInt, getLong, getName, getParent, getRelativePath, getString, getSubscribers, getSubscriptionValues, move, pushValue, pushValues, set, set, set, set, set, set, set, setName, subscribe

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

indeterminate

public static final String indeterminate

This value is returned by the get methods when a graphic property has different values for different graphic elements of the group.

Constructor Detail

IlvGroup

public IlvGroup(String name)

Creates a new, empty IlvGroup with the given name.

Parameters:

name - the name of the new group.

IlvGroup

public IlvGroup(IlvGroup source)
         throws IlvValueException

Creates a copy of an existing group.

Parameters:

source - the group to be copied.

Throws:

IlvValueException - if an error occurred while copying the group.

IlvGroup

public IlvGroup(IlvInputStream in)
         throws IlvReadFileException

Reads an IlvGroup from an IlvInputStream.

Parameters:

in - the stream from which the group is read.

Throws:

IlvReadFileException - if the file format is not correct.

Method Detail

write

public void write(IlvOutputStream out)
           throws IOException

Writes an IlvGroup to an IlvOutputStream.

Specified by:

write in interface IlvPersistentObject

Specified by:

write in class IlvGroupElement

Parameters:

out - the stream to which the group is written.

Throws:

IOException - if an I/O error or a value error occurred.

See Also:

write(ilog.views.io.IlvOutputStream)

copy

public void copy(IlvGroup source)
          throws IlvValueException

Makes this group a copy of another group.

The elements and behavior objects of the source group are copied into the receiving group. The result is equivalent to calling the copy method of the source group, except that the elements and behaviors are copied "in place" into the receiving group, not into a newly allocated group.

Parameters:

source - the group from which elements and behaviors are copied.

Throws:

IlvValueException - if an error occurred while copying the group.

clear

public void clear()

Removes all the elements and behavior objects attached to this group.

copy

public IlvGroupElement copy()
                     throws IlvValueException

Returns a copy of the group.

Specified by:

copy in class IlvGroupElement

Returns:

a copy of the group.

Throws:

IlvValueException - if a value error occurred.

See Also:

copy(ilog.views.prototypes.IlvGroup)

getTopGroup

public IlvGroup getTopGroup()

Returns the top level ancestor of this group by going up the parent chain until a null parent is found.

addElement

public void addElement(IlvGroupElement element)

Adds an element to this group.

Parameters:

element - the element to be added.

removeElement

public void removeElement(IlvGroupElement element)

Removes an element from this group.

Parameters:

element - the element to be removed.

getElements

public Enumeration getElements()

Returns the elements in the group. Only the elements in the group are returned, not the elements in its subgroups.

Returns:

an enumeration of IlvGroupElement objects.

findElement

public IlvGroupElement findElement(String name)
                            throws IlvGroupException

Finds an element in the group from its name. The element name can contain dot ('.') characters. These characters denote subgroup elements (for example, car.wheel.tire). The special names "this" or "[all]" can be used to designate the receiving group itself.

Parameters:

name - the full name of the group element.

Returns:

the group element.

Throws:

IlvGroupException - if the element could not be found.

traverse

public boolean traverse(IlvGroupTraverser traverser)

Recursively traverses all the elements in a group.

For each element of the group:

1. The preOrder method of the IlvGroupTraverser object is called.
2. The traverse method of the element is called and, for sub-group elements, the sub-group is recursively traversed.
3. The postOrder method of the IlvGroupTraverser object is called.

If any of these three methods returns false, the operation is immediately stopped and the method returns false.

Overrides:

traverse in class IlvGroupElement

Parameters:

traverser - the IlvGroupTraverser object whose preOrder and postOrder methods will be called for each element in the group.

Returns:

true if the whole group was traversed (that is, if all the traverse methods returned true) and false if the operation was aborted.

See Also:

IlvGroupTraverser, IlvGroupElement.traverse(ilog.views.prototypes.IlvGroupTraverser)

addBehavior

public void addBehavior(IlvBehavior acc)

Adds a behavior object to this group. The new behavior object is added to the list of behavior objects associated with the group and the attach method of the behavior object is called.

Parameters:

acc - the behavior object to be added.

See Also:

IlvBehavior.attach(ilog.views.prototypes.IlvGroup)

removeBehavior

public void removeBehavior(IlvBehavior acc)

Removes a behavior object from the group. The behavior object is removed from the list of behavior objects associated with the group and the detach method of the behavior object is called.

Parameters:

acc - the behavior object to be removed.

See Also:

IlvBehavior.detach(ilog.views.prototypes.IlvGroup)

swapBehaviors

public void swapBehaviors(IlvBehavior b1,
                          IlvBehavior b2)

Swaps the positions of the behavior objects b1 and b2. This method can be used by graphical editors to reorder the behavior objects attached to a group. The order of behavior objects can be important if one of the behavior objects uses a value stored in a preceding behavior object. Behavior objects are always called in the order in which they are stored in the group.

Parameters:

b1 - the first behavior object to be swapped.

b2 - the second behavior object to be swapped.

getBehaviors

public Enumeration getBehaviors()

Returns all the behavior objects that are attached to the group.

Returns:

an enumeration of IlvBehavior objects.

getValueNames

public String[] getValueNames(boolean publicOnly)
                       throws IlvValueException

Returns the names of the properties handled by the behavior objects attached to the group.

Overrides:

getValueNames in class IlvGroupElement

Parameters:

publicOnly - if true, only the values handled by the behavior objects that are not marked as private will be returned. If false, all the values are returned.

Returns:

an array of value names.

Throws:

IlvValueException - if an error occurred while reading a property.

isABehaviorValue

public boolean isABehaviorValue(String valueName,
                                boolean publicOnly)

Tests if a property exists and is handled by a behavior object.

Parameters:

valueName - the name of the property to check.

publicOnly - if true only the values handled by the behavior objects that are not marked as private will be checked. If false, all the values are checked.

setPrivate

public void setPrivate(String name,
                       boolean priv)

Marks a property of this group as private. Private properties are not listed by the function getValueNames and are not saved to files.

Parameters:

name - the name of the property.

priv - the new private status.

See Also:

isPrivate(java.lang.String)

isPrivate

public boolean isPrivate(String name)

Returns true if the specified property is private. Otherwise, returns false.

See Also:

setPrivate(java.lang.String, boolean)

isOutput

public boolean isOutput(String name)

Returns true if the specified property is an output property.

Overrides:

isOutput in class IlvGroupElement

See Also:

IlvBehavior.isOutput()

renameValue

public void renameValue(String oldName,
                        String newName)

Renames the oldName property handled by all the behavior objects associated with this group as newName.

This method is intended to be used by GUI editors.

Parameters:

oldName - the old property name.

newName - the new property name.

getGroupFrame

public IlvGroupFrame getGroupFrame()

Returns the IlvGroupFrame used to select this group in a manager.

Returns:

the IlvGroupFrame used to select this group in a manager or null if this group has no graphic group.

See Also:

IlvGroupFrame, IlvGroupBag.selectGroup(ilog.views.prototypes.IlvGroup, boolean)

getGroupBag

public IlvGroupBag getGroupBag()

Returns the IlvGroupBag object that contains the group or null if the group does not belong to a group bag.

unsubscribe

public void unsubscribe(IlvGroupElement subscriber,
                        String sourceValue,
                        String subscriberValue)

This method is overridden from the IlvGroupElement class to handle subscriptions to group elements (using the same dot notation as for set/get).

Overrides:

unsubscribe in class IlvGroupElement

Parameters:

subscriber - the destination object of the connection.

sourceValue - the name of the source property of the new connection. If this parameter is null, all the connections between the group element and the subscriber object are broken regardless of their source property.

subscriberValue - the name of the source property of the new connection. If this parameter is null, all the connections between the group element and the subscriber object are broken regardless of their destination property.

setMessageWriter

public static void setMessageWriter(PrintWriter writer)

Changes the writer object used by the library to print messages. By default, messages are printed to the system console through the System.out stream. This method can be used to redirect messages.

Parameters:

writer - the new writer used to print messages. Messages will be printed by calling the println method of writer.