Author: scooter
Date: 2012-09-25 10:43:25 -0700 (Tue, 25 Sep 2012)
New Revision: 30477
Modified:
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CustomGraphicLayer.java
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphics.java
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphicsFactory.java
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/ImageCustomGraphicLayer.java
Log:
Remove extraneous getBounds from api and update documentation
Modified:
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CustomGraphicLayer.java
===================================================================
---
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CustomGraphicLayer.java
2012-09-25 17:43:03 UTC (rev 30476)
+++
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CustomGraphicLayer.java
2012-09-25 17:43:25 UTC (rev 30477)
@@ -14,14 +14,6 @@
public interface CustomGraphicLayer {
/**
* Return the bounds of the area covered by this
- * CustomGraphicLayer as a {@link java.awt.Rectangle}
- *
- * @return the {@link java.awt.Rectangle}
- */
- public Rectangle getBounds();
-
- /**
- * Return the bounds of the area covered by this
* CustomGraphicLayer as a {@link java.awt.Rectangle2D}
*
* @return the {@link java.awt.Rectangle2D}
Modified:
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphics.java
===================================================================
---
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphics.java
2012-09-25 17:43:03 UTC (rev 30476)
+++
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphics.java
2012-09-25 17:43:25 UTC (rev 30477)
@@ -8,7 +8,10 @@
/**
- * Base interface for all Custom Graphics.
+ * Base interface for all Custom Graphics. Fundamentally, a {@link
CyCustomGraphics}
+ * object is a container for one or more {@link CustomGraphicLayer} objects.
It is
+ * the layer objects that will actually create the graphics that are used by
the
+ * renderer.
*
*/
public interface CyCustomGraphics<T extends CustomGraphicLayer> {
@@ -23,17 +26,17 @@
public Long getIdentifier();
/**
- * Set the session-unique identifier of this custom graphics.
+ * Set the session-unique identifier of this custom graphics. This
method is used by
+ * the renderer to track custom graphics objects for
serialization/deserialization. Your
+ * implementation should not generate or set this value.
*
- * NOT globally unique. Uniqueness is guaranteed in a session.
- *
* @param id Immutable ID as Long.
*/
public void setIdentifier(Long id);
/**
- * Display name is a simple description of this image object.
- * May not be unique and mutable.
+ * Display name is a simple description of this image object. For
discrete mappings, this
+ * is the name that the user will see.
*
* @return display name as String.
*/
@@ -49,30 +52,37 @@
/**
* Generate a string suitable for serializing the state of this
- * custom graphic.
+ * custom graphic. Note that the first part of this
+ * <b>must</b> be the class of the implementing object followed by a
+ * comma. This is used by the deserialization logic to recreate the
+ * factory objects that are used for discrete mappings. If your
implementation
+ * doesn't support discrete mappings, just return null. This method is
the
+ * mirror of {@link CyCustomGraphicsFactory#parseSerializableString()}.
*
- * @return serialized custom graphic state. Note that the first part
of this
- * <b>must</b> be the class of the implementing object followed
by a
- * comma. This is used by the deserialization logic to
recreate the
- * factory objects.
+ * @return serialized custom graphic state, or null if discrete
mappings aren't supported
*/
public String toSerializableString();
/**
- * Get layers that belong to this object.
+ * Get layers that belong to this object. Get the list of layers to be
rendered. Each
+ * layer is rendered in list order, which means that the layers at the
end of the list are
+ * rendered last, and are therefore on top. The {@link CyNetwork} and
{@link CyIdentifiable}
+ * graph object are passed in case there is information about the
network that is required
+ * to render the layer. For example, a pie chart layer might need to
extract data from the
+ * {@link CyRow} for this graph object. For other layer types, this
can be safely ignored.
*
- * @param network the node we want the layers for
- * @param node the node we want the layers for (currently, only nodes
are supported
- * @return Collection of layer objects (in this version, it's
CustomGraphicLayers from Ding)
+ * @param network the network the Renderer is rendering
+ * @param grObject the graph object the Renderer is rendering
(currently only nodes are supported)
+ * @return List of layer objects
*
*/
- public List<T> getLayers(CyNetwork network, CyIdentifiable node);
+ public List<T> getLayers(CyNetwork network, CyIdentifiable grObject);
/**
* Returns width of current object.
*
- * @return
+ * @return the current width
*/
public int getWidth();
@@ -80,32 +90,47 @@
/**
* Returns height of current object.
*
- * @return
+ * @return the height of the current object
*/
public int getHeight();
/**
- * Set width of Custom Graphics.
+ * Set width of Custom Graphics. This is used by discrete mappers to
support the creation
+ * of a sample image.
*
* @param width
*/
public void setWidth(final int width);
/**
- * Set height of Custom Graphics.
+ * Set height of Custom Graphics. This is used by discrete mappers to
support the creation
+ * of a sample image.
*
* @param height
*/
public void setHeight(final int height);
+ /**
+ * Get the fit ratio for this custom graphic. This is used to set the
proportion of the
+ * node to fill when sizing the graphic. For example, if your custom
graphic should leave
+ * a border round the fill, set this to <1 -- if you want your cutom
graphic to be
+ * larger than the node, set this to > 1.
+ *
+ * @return the fit ratio
+ */
public float getFitRatio();
+
+
+ /**
+ * Set the fit ratio for this custom graphic.
+ *
+ * @param ratio the fit ratio
+ */
public void setFitRatio(float ratio);
/**
- * From layers of graphics objects, render scaled Image object.
- * Usually done by Java2D low level code.
- *
+ * From layers of graphics objects, render a composite scaled Image
object.
* Usually, the image returned by this method is used in GUI components
(as icons).
*
* @return rendered image object.
Modified:
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphicsFactory.java
===================================================================
---
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphicsFactory.java
2012-09-25 17:43:03 UTC (rev 30476)
+++
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/CyCustomGraphicsFactory.java
2012-09-25 17:43:25 UTC (rev 30477)
@@ -7,14 +7,23 @@
/**
* This interface provides the factory to create CyCustomGraphics objects.
- * Implementations of CyCustomGraphicsFactory are the objects that should
- * be registered as OSGi services and will be utilized by the renderers to
- * create CyCustomGraphics objects.
+ * CyCustomGraphicsFactory objects should be registered as services in
+ * OSGi and will be used by Renderers to create the actual custom graphics
+ * implementations. Note that the type of a CyCustomGraphicsFactory is
+ * the type of the underlying {@link CustomGraphicLayer} not the type
+ * of the resulting {@link CyCustomGraphic} object this creates. In general,
+ * the pattern is to add to your CyActivator class:
*
+ * <pre>
+ CyCustomGraphicsFactory myCustomGraphicsFactory = new
MyCustomGraphicsFactory();
+ registerService(bundleContext, myCustomGraphicsFactory,
CyCustomGraphicsFactory.class, new Properites());
+ </pre>
+ *
+ *
*/
public interface CyCustomGraphicsFactory<T extends CustomGraphicLayer> {
/**
- * Return the prefix to delineate this custom graphics factory. This
+ * Return the prefix to identify this custom graphics factory. This
* is used by the passthrough mapping logic to figure out if a
* given String value should be mapped to this factory.
*
@@ -34,10 +43,11 @@
/**
* Get a new instance of the CyCustomGraphics based on pulling the data
- * from a URL.
+ * from a URL. If this {@link CyCustomGraphics} type doesn't support
+ * URLs, this should always return null.
*
* @param url the url that points to the CyCustomGraphics data
- * @return the new instance
+ * @return the new instance, or null if URL references are not supported
*/
public CyCustomGraphics<T> getInstance(URL url);
@@ -45,7 +55,10 @@
* Get a new instance of the CyCustomGraphics. The string argument may
* be used by some implementations to create the initial graphics
objects.
* For example, a bitmap graphic implementation might use the input
argument
- * as a URI that gives the location of an image file.
+ * as a URI that gives the location of an image file. This is the
method
+ * that will be used to take a String passthrough mapping and create the
+ * correct {@link CyCustomGraphics} instance. Note that the prefix
defined
+ * above will get removed from the string before this method is called.
*
* @param input a possible input string that may be used to create the
* instance. Not all implementations will use this.
@@ -55,7 +68,8 @@
/**
* Create a new CyCustomGraphics object by parsing the string
- * resulting from the toSerializableString() method.
+ * resulting from the toSerializableString() method. This method
+ * will be used to suport serialization of discrete mappings.
*/
public CyCustomGraphics<T> parseSerializableString(String string);
Modified:
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/ImageCustomGraphicLayer.java
===================================================================
---
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/ImageCustomGraphicLayer.java
2012-09-25 17:43:03 UTC (rev 30476)
+++
core3/api/trunk/presentation-api/src/main/java/org/cytoscape/view/presentation/customgraphics/ImageCustomGraphicLayer.java
2012-09-25 17:43:25 UTC (rev 30477)
@@ -4,8 +4,8 @@
import java.awt.geom.Rectangle2D;
/**
- * This interface defines a the mimimum interface to
- * add a custom graphics to a {@link org.cytoscape.model.CyNode}.
+ * This interface defines a {@link CustomGraphicLayer} that
+ * paints an image on a node.
*/
public interface ImageCustomGraphicLayer extends CustomGraphicLayer {
/**
--
You received this message because you are subscribed to the Google Groups
"cytoscape-cvs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/cytoscape-cvs?hl=en.
