org.graphstream.ui.spriteManager

Class Sprite

java.lang.Object

org.graphstream.ui.spriteManager.Sprite

All Implemented Interfaces:

Element

public class Sprite
extends java.lang.Object
implements Element

A gentle little sprite.

Sprite objects allow to add data representations in a graphic display of a graph. A sprite is a graphical representation that can double anywhere in the graph drawing surface, or be "attached" to nodes or edges. When attached to an edge, a sprite can be positioned easily at any point along the edge, or perpendicular to it with one or two coordinates. When attached to a node, a sprite "orbits" around the node at any given radius and angle around it.

Sprites can have many shapes. Most of the CSS nodes shapes are available for sprites, but more are possible. Some shapes follow the form of the element (node or edge) they are attached to.

Sprites can be moved and animated easily along edges, around nodes, or anywhere on the graph surface. Their shape can change. Some sprites allows to draw pie charts or statistics, or images.

Sprites are not part of a graph so to speak. Furthermore they make sense only when a graph is displayed with a viewer that supports sprites. Therefore they are handled by a SpriteManager which is always associated to a graph and is in charge of handling the whole set of sprites, creating them, enumerating them, and destroying them.

Implementation note: sprites do not exist ! In fact the sprite class only handles a set of attributes that are stored in the graph (the one associated with the sprite manager that created the sprite). These special attributes are handled for you by the sprite class. This technique allows to pass sprites informations through the I/O system of GraphStream. Indeed sprites appearing in a graph can therefore be stored in files and retrieved if the graph file format supports attributes. If this is a dynamic graph format, like DGS, the whole sprite history is remembered: when it moved, when it changed, etc.

Second implementation node : often you will need to extend the sprite class. This is easily possible, but you must remember that you cannot create sprites yourself, you must use the SpriteManager. In order to create a sprite of a special kind, you can either use a SpriteFactory with the SpriteManager or the special SpriteManager.addSprite(String, Class) method of the SpriteManager. In both cases, the init(String, SpriteManager, Values) method of the sprite will be called. Override this method to initialise your sprite.

See Also:

SpriteManager, SpriteFactory

Method Summary

Modifier and Type	Method and Description
boolean	attached() True if attached to an edge or node.
void	attachToEdge(java.lang.String id) Attach the sprite to an edge with the given identifier.
void	attachToNode(java.lang.String id) Attach the sprite to a node with the given identifier.
java.util.stream.Stream<java.lang.String>	attributeKeys() Stream over the attribute keys of the element.
void	clearAttributes() Remove all registered attributes.
void	detach() Detach the sprite from the element it is attached to (if any).
java.lang.Object[]	getArray(java.lang.String key) Get the array of objects bound to key.
Element	getAttachment() The element the sprite is attached to or null if the sprite is not attached.
java.lang.Object	getAttribute(java.lang.String key) Get the attribute object bound to the given key.
<T> T	getAttribute(java.lang.String key, java.lang.Class<T> clazz) Get the attribute object bound to the given key if it is an instance of the given class.
int	getAttributeCount() Quite expensive operation !.
java.util.Map<java.lang.String,java.lang.Object>	getAttributeMap()
<T> T	getFirstAttributeOf(java.lang.Class<T> clazz, java.lang.String... keys) Like Element.getAttribute(String, Class), but returns the first existing attribute in a list of keys, instead of only one key.
java.lang.Object	getFirstAttributeOf(java.lang.String... keys) Like Element.getAttribute(String), but returns the first existing attribute in a list of keys, instead of only one key.
java.lang.String	getId() Unique identifier of this element.
int	getIndex() The current index of this element
java.lang.CharSequence	getLabel(java.lang.String key) Get the label string bound to the given key key.
java.util.Map<?,?>	getMap(java.lang.String key) Get the map bound to key.
double	getNumber(java.lang.String key) Get the number bound to key.
StyleConstants.Units	getUnits()
java.util.List<? extends java.lang.Number>	getVector(java.lang.String key) Get the vector of number bound to key.
double	getX() X position.
double	getY() Y position.
double	getZ() Z position.
boolean	hasArray(java.lang.String key) Does this element store an array value for the given key?
boolean	hasAttribute(java.lang.String key) Does this element store a value for the given attribute key?
boolean	hasAttribute(java.lang.String key, java.lang.Class<?> clazz) Does this element store a value for the given attribute key and this value is an instance of the given class?
boolean	hasLabel(java.lang.String key) Does this element store a label value for the given key?
boolean	hasMap(java.lang.String key) Does this element store a map value for the given key?
boolean	hasNumber(java.lang.String key) Does this element store a number for the given key?
boolean	hasVector(java.lang.String key) Does this element store a vector value for the given key?
void	removeAttribute(java.lang.String attribute) Remove an attribute.
void	setAttribute(java.lang.String attribute, java.lang.Object... values) Add or replace the value of an attribute.
void	setAttributes(java.util.Map<java.lang.String,java.lang.Object> attributes) Add or replace each attribute found in attributes.
void	setPosition(double percent)
void	setPosition(double x, double y, double z)
void	setPosition(StyleConstants.Units units, double x, double y, double z)

Methods inherited from class java.lang.Object

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

Method Detail

getAttachment

public Element getAttachment()

The element the sprite is attached to or null if the sprite is not attached.

Returns:

An element the sprite is attached to or null.

attached

public boolean attached()

True if attached to an edge or node.

Returns:

False if not attached.

getX

public double getX()

X position.

Returns:

The position in abscissa.

getY

public double getY()

Y position.

Returns:

The position in ordinate.

getZ

public double getZ()

Z position.

Returns:

The position in depth.

getUnits

public StyleConstants.Units getUnits()

attachToNode

public void attachToNode(java.lang.String id)

Attach the sprite to a node with the given identifier. If needed the sprite is first detached. If the given node identifier does not exist, the sprite stays in detached state.

Parameters:

id - Identifier of the node to attach to.

attachToEdge

public void attachToEdge(java.lang.String id)

Attach the sprite to an edge with the given identifier. If needed the sprite is first detached. If the given edge identifier does not exist, the sprite stays in detached state.

Parameters:

id - Identifier of the edge to attach to.

detach

public void detach()

Detach the sprite from the element it is attached to (if any).

setPosition

public void setPosition(double percent)

setPosition

public void setPosition(double x,
                        double y,
                        double z)

setPosition

public void setPosition(StyleConstants.Units units,
                        double x,
                        double y,
                        double z)

getId

public java.lang.String getId()

Description copied from interface: Element

Unique identifier of this element.

Specified by:

getId in interface Element

Returns:

The identifier value.

getLabel

public java.lang.CharSequence getLabel(java.lang.String key)

Description copied from interface: Element

Get the label string bound to the given key key. Labels are special attributes whose value is a character sequence. If an attribute with the same name exists but is not a character sequence, null is returned.

Specified by:

getLabel in interface Element

Parameters:

key - The label to search.

Returns:

The label string value or null if not found.

getAttribute

public java.lang.Object getAttribute(java.lang.String key)

Description copied from interface: Element

Get the attribute object bound to the given key. The returned value may be null to indicate the attribute does not exists or is not supported.

Specified by:

getAttribute in interface Element

Parameters:

key - Name of the attribute to search.

Returns:

The object bound to the given key or null if no object match this attribute name.

getAttribute

public <T> T getAttribute(java.lang.String key,
                          java.lang.Class<T> clazz)

Description copied from interface: Element

Get the attribute object bound to the given key if it is an instance of the given class. Some The returned value maybe null to indicate the attribute does not exists or is not an instance of the given class.

Specified by:

getAttribute in interface Element

Parameters:

key - The attribute name to search.

clazz - The expected attribute class.

Returns:

The object bound to the given key or null if no object match this attribute.

getAttributeCount

public int getAttributeCount()

Quite expensive operation !.

Specified by:

getAttributeCount in interface Element

Returns:

the number of attributes.

attributeKeys

public java.util.stream.Stream<java.lang.String> attributeKeys()

Description copied from interface: Element

Stream over the attribute keys of the element. If no attribute exist, method will return empty stream.

Specified by:

attributeKeys in interface Element

Returns:

a String stream corresponding to the keys of the attributes.

getAttributeMap

public java.util.Map<java.lang.String,java.lang.Object> getAttributeMap()

getFirstAttributeOf

public java.lang.Object getFirstAttributeOf(java.lang.String... keys)

Description copied from interface: Element

Like Element.getAttribute(String), but returns the first existing attribute in a list of keys, instead of only one key. The key list order matters.

Specified by:

getFirstAttributeOf in interface Element

Parameters:

keys - Several strings naming attributes.

Returns:

The first attribute that exists.

getFirstAttributeOf

public <T> T getFirstAttributeOf(java.lang.Class<T> clazz,
                                 java.lang.String... keys)

Description copied from interface: Element

Like Element.getAttribute(String, Class), but returns the first existing attribute in a list of keys, instead of only one key. The key list order matters.

Specified by:

getFirstAttributeOf in interface Element

Parameters:

clazz - The class the attribute must be instance of.

keys - Several string naming attributes.

Returns:

The first attribute that exists.

getArray

public java.lang.Object[] getArray(java.lang.String key)

Description copied from interface: Element

Get the array of objects bound to key. Arrays of objects are special attributes whose value is a sequence of objects. If an attribute with the same name exists but is not an array, null is returned.

Specified by:

getArray in interface Element

Parameters:

key - The name of the array to search.

Returns:

The array of objects or null if not found.

getMap

public java.util.Map<?,?> getMap(java.lang.String key)

Description copied from interface: Element

Get the map bound to key. Maps are special attributes whose value is a set of pairs (name,object). Instances of object implementing the CompoundAttribute interface are considered like maps since they can be transformed to a map. If an attribute with the same name exists but is not a map, null is returned. We cannot enforce the type of the key. It is considered a string and you should use "Object.toString()" to get it.

Specified by:

getMap in interface Element

Parameters:

key - The name of the map to search.

Returns:

The map or null if not found.

getNumber

public double getNumber(java.lang.String key)

Description copied from interface: Element

Get the number bound to key. Numbers are special attributes whose value is an instance of Number. If an attribute with the same name exists but is not a Number, NaN is returned.

Specified by:

getNumber in interface Element

Parameters:

key - The name of the number to search.

Returns:

The number value or NaN if not found.

getVector

public java.util.List<? extends java.lang.Number> getVector(java.lang.String key)

Description copied from interface: Element

Get the vector of number bound to key. Vectors of numbers are special attributes whose value is a sequence of numbers. If an attribute with the same name exists but is not a vector of number, null is returned. A vector of number is a non-empty List of Number objects.

Specified by:

getVector in interface Element

Parameters:

key - The name of the number to search.

Returns:

The vector of numbers or null if not found.

hasAttribute

public boolean hasAttribute(java.lang.String key)

Description copied from interface: Element

Does this element store a value for the given attribute key? Note that returning true here does not mean that calling getAttribute with the same key will not return null since attribute values can be null. This method just checks if the key is present, with no test on the value.

Specified by:

hasAttribute in interface Element

Parameters:

key - The name of the attribute to search.

Returns:

True if a value is present for this attribute.

hasArray

public boolean hasArray(java.lang.String key)

Description copied from interface: Element

Does this element store an array value for the given key? Only object arrays (instance of Object[]) are considered as array here.

Specified by:

hasArray in interface Element

Parameters:

key - The name of the array.

Returns:

True if a value is present for this attribute and can contain an array object.

hasAttribute

public boolean hasAttribute(java.lang.String key,
                            java.lang.Class<?> clazz)

Description copied from interface: Element

Does this element store a value for the given attribute key and this value is an instance of the given class?

Specified by:

hasAttribute in interface Element

Parameters:

key - The name of the attribute to search.

clazz - The expected class of the attribute value.

Returns:

True if a value is present for this attribute.

hasMap

public boolean hasMap(java.lang.String key)

Description copied from interface: Element

Does this element store a map value for the given key? A map is a set of pairs (key,value) (Map) or objects that implement the CompoundAttribute class.

Specified by:

hasMap in interface Element

Parameters:

key - The name of the hash.

Returns:

True if a value is present for this attribute and can contain a hash.

hasLabel

public boolean hasLabel(java.lang.String key)

Description copied from interface: Element

Does this element store a label value for the given key? A label is an attribute whose value is a char sequence.

Specified by:

hasLabel in interface Element

Parameters:

key - The name of the label.

Returns:

True if a value is present for this attribute and implements CharSequence.

hasNumber

public boolean hasNumber(java.lang.String key)

Description copied from interface: Element

Does this element store a number for the given key? A number is an attribute whose value is an instance of Number.

Specified by:

hasNumber in interface Element

Parameters:

key - The name of the number.

Returns:

True if a value is present for this attribute and can contain a double (inherits from Number).

hasVector

public boolean hasVector(java.lang.String key)

Description copied from interface: Element

Does this element store a vector value for the given key? A vector is an attribute whose value is a sequence of numbers.

Specified by:

hasVector in interface Element

Parameters:

key - The name of the vector.

Returns:

True if a value is present for this attribute and can contain a sequence of numbers.

setAttribute

public void setAttribute(java.lang.String attribute,
                         java.lang.Object... values)

Description copied from interface: Element

Add or replace the value of an attribute. Existing attributes are overwritten silently. All classes inheriting from Number can be considered as numbers. All classes inheriting from CharSequence can be considered as labels. You can pass zero, one or more arguments for the attribute values. If no value is given, a boolean with value "true" is added. If there is more than one value, an array is stored. If there is only one value, the value is stored (but not in an array).

Specified by:

setAttribute in interface Element

Parameters:

attribute - The attribute name.

values - The attribute value or set of values.

setAttributes

public void setAttributes(java.util.Map<java.lang.String,java.lang.Object> attributes)

Description copied from interface: Element

Add or replace each attribute found in attributes. Existing attributes are overwritten silently. All classes inheriting from Number can be considered as numbers. All classes inheriting from CharSequence can be considered as labels.

Specified by:

setAttributes in interface Element

Parameters:

attributes - A set of (key,value) pairs.

clearAttributes

public void clearAttributes()

Description copied from interface: Element

Remove all registered attributes. This includes numbers, labels and vectors.

Specified by:

clearAttributes in interface Element

removeAttribute

public void removeAttribute(java.lang.String attribute)

Description copied from interface: Element

Remove an attribute. Non-existent attributes errors are ignored silently.

Specified by:

removeAttribute in interface Element

Parameters:

attribute - Name of the attribute to remove.

getIndex

public int getIndex()

Description copied from interface: Element

The current index of this element

Specified by:

getIndex in interface Element

Returns:

The index value