Geometric properties

The boundingBox method

The bounding box defines the smallest rectangle encompassing the graphic object. It is returned by the following method:

public IlvRect boundingBox(IlvTransformer t)

The IlvTransformer parameter is the 2D transformation matrix used to draw the object in a particular drawing port (see transformer). This transformation may correspond to a zoom, a rotation, or a translation of the graphic object in the destination drawing port. The method must then return the rectangle that contains the graphic object when it is drawn using the specified transformation.

The Bounding Box of a Graphic Object

The following example defines the shape of a graphic object with the drawrect field. In order to return the bounding box of the object, the boundingBox method simply applies the transformer to the rectangle:

class MyRectangle extends IlvGraphic
{
   // The geometric rectangle that defines the object.
   final IlvRect drawrect = new IlvRect();
 
   //constructor
   public MyRectangle(float x, float y, float width, float height)
   {
    drawrect.reshape(x, y, width, height);
   }
    // The bounding box method.
   public IlvRect boundingBox(IlvTransformer t)
   {
      //Copies the original rectangle to avoid its modification
      IlvRect rect = new IlvRect(drawrect);
      if (t != null)
        t.apply(rect);
      return rect;
   }
}

The method boundingBox is a very important method. Since it is called very frequently, it must be written in a highly optimized way.

Note

For the MyRectangle class to compile correctly you need to overload the draw , copy and applyTransform methods. For an example of how this is done, see The ShadowEllipse class.

The draw method

The draw method is used to draw the graphic object. The signature of the method is as follows:

public void draw(Graphics dst, IlvTransformer t)

The dst parameter is the destination Graphics where the object is drawn. As in the boundingBox method, the IlvTransformer parameter is the 2D transformation matrix used to draw the object in the drawing port.

Note

Everything that is drawn with this method must be drawn inside the bounding rectangle of the object (the bounding rectangle of the object being the result of the call to the method boundingBox with the same transformation parameter). This is why these two methods should be defined jointly.

In order to draw the object, you will use the drawing methods of the AWT Graphics class. If you use Java™ 2 and need to perform Java2D™ drawings, you can cast the dst parameter in a Graphics2D object and then use the drawing methods of this class.

Zoomable and nonzoomable objects

A graphic object is said to be zoomable if its bounding box follows the zoom level. In other words, the result of calling the method boundingBox with a transformer is the same as when calling boundingBox with a null transformer and then applying the transformer to the resulting rectangle. That is:

obj.boundingBox(t) = t.apply(obj.boundingBox(null))

A zoomable object follows the zoom factor. When a view is magnified by 2, a zoomable object is drawn twice as big. When a view is reduced by 1/2, a zoomable object is drawn half as big. A nonzoomable object does not follow the zoom factor, that is, it may be drawn at its original size in a reduced view.

More precisely, a graphic object is zoomable if and only if for every transformer t , the rectangle obtained by calling obj.boundingBox(t) is contained in the rectangle obtained by applying the transformer to obj.boundingBox(null) . Equality of both rectangles is not necessary.

Important

If you define your own graphic objects, you must define zoomable() correctly. If zoomable() returns true , but the object does not follow the zoom factor, the object may be drawn incorrectly.

Zoomable and nonzoomable objects are managed in very different ways in Rogue Wave JViews: zoomable objects are managed in a more optimized way. To know whether an object is zoomable, call the zoomable method:

public boolean zoomable()

The returned value for the class IlvGraphic is true .

Testing whether a point is part of an object shape

The method contains is called by interactors to check whether a point is part of an object shape.

public boolean contains(IlvPoint p, IlvPoint tp, IlvTransformer t)

The default implementation of this method checks whether the specified point lies inside the bounding rectangle of the object. You may override this method so that it returns false for the transparent area of your object.

Moving and resizing a graphic object

The class IlvGraphic provides many methods for moving and resizing a graphic object:

move

Moves the upper-left corner of the bounding rectangle of the object to ( x , y ).
move

Moves the upper-left corner of the bounding rectangle of the object to the point p .
moveResize

Sets the bounding rectangle of the object to the IlvRect parameter.
translate

Translates the bounding rectangle of the object by the vector ( dx , dy ).
rotate

Rotates the object around the point center by an angle of angle degrees.
scale

Resizes the bounding rectangle of the object by a factor ( scalex , scalex ).
resize

Modifies the bounding rectangle of the object with the new size ( neww , newh ).

All of these methods call applyTransform to modify the bounding rectangle of the graphic object.

public void applyTransform(IlvTransformer t)

This is the only method that needs to be overridden in order to handle the transformation of an object correctly. The following code example shows how the applyTransform method may be used in the example class, MyRectangle :

class MyRectangle extends IlvGraphic 
{
   // The rectangle that defines the object.
   final IlvRect drawrect = new IlvRect();
 
   ...
 
   public void applyTransform(IlvTransformer t)
   {
      t.apply(drawrect);
   }
}

The method simply applies the transformation to the rectangle.

Note

Graphic objects stored in a manager (class IlvManager and its subclasses) are located in a quadtree. This means that you cannot simply call move on a graphic object because the quadtree must be notified of the modification of the graphic object. Every method that modifies the bounding rectangle of the object must call applyToObject. This method applies a function to an object and notifies the quadtree of the modification to the bounding rectangle. The class IlvManager also includes several convenient methods to move and reshape a graphic object managed by this manager. These are as follows:

moveObjectpublic void moveObject(IlvGraphic, float, float, boolean)

reshapeObjectpublic void reshapeObject(IlvGraphic, IlvRect, boolean)

For more information, see Modifying geometric properties of objects.