comparison java/src/uk/ac/qmul/eecs/ccmi/gui/GraphElement.java @ 3:9e67171477bc

PHANTOM Omni Heptic device release

 import java.awt.geom.Point2D;
 import java.awt.geom.Rectangle2D;
 
 
 /**
- * An interface implemented by {@link Node} and {@link Edge} and it defines methods that 
- * both the classes implements as they're object painted on a graph. The interface is used mainly
- * for convenience in treating the two types of object in a unified way.  
+ * An interface implemented by {@code Node}, {@code Edge} and {@code Edge.InnerPoint}. It defines methods that 
+ * all objects painted on a graph share. The interface is used mainly
+ * for convenience in treating the different types of object in a uniformly.  
  *
  */
 public interface GraphElement {
+	/**
+	 * Draw the graphic element on a canvas
+	 * 
+	 * @param g2 the graphics object. Use {@code g2.draw()} to get things painted on the graph. 
+	 */
 	public void draw(Graphics2D g2);
 
-	public void translate(Point2D p, double dx, double dy);
+	/**
+	 * Translates this graphic element on the graph 
+	 * 
+	 * @param p the starting point where the translation starts (normally where the user clicks
+	 * with their mouse)
+	 * @param dx the distance to translate along the x-axis
+	 * @param dy the distance to translate along the y-axis
+	 * @param source the source of the translate action
+	 */
+	public void translate(Point2D p, double dx, double dy, Object source);
 
-	public void stopMove();
+	/**
+	 * This method is to be called before translation or any other operation that changes the 
+	 * position of the graph element or any of its parts. 
+	 * 
+	 * @param p the starting point of the motion 
+	 * @param source the source of the motion action
+	 */
+	public void startMove(Point2D p, Object source);
+
+	/**
+	 * This method is to be called when the motion (e.g. a translation) is over. 
+	 * Note that for instance a translation might be composed on several calls to {@code translate}
+	 * 
+	 * @param source
+	 */
+	public void stopMove(Object source);
 	
-	public void startMove(Point2D p);
-	
+	/**
+	 * Gets the bounding {@code Rectangle} of this graph element.
+	 * 
+	 * @return a new {@code Rectangle} equals to the bounding {@code Rectangle} of this graph element
+	 */
 	public Rectangle2D getBounds();
 	
+	/**
+	 * Returns the point where an line, with a specified direction, would come in contact with the outline of this 
+	 * graph element. 
+	 * 
+	 * @param d the direction of the line 
+	 * @return a new point on the outline if this graph element where the line comes in contact with it
+ 	 */
 	public Point2D getConnectionPoint(Direction d);
 	
+	/**
+	 * Tests if a specified {@code Point2D} is inside the boundary of this graph element.
+	 * 
+	 * @param p the point to be tested
+	 * @return {@code true} if the point is inside the boundary, {@code false} otherwise
+	 */
 	public boolean contains(Point2D p);
 	
 }