Name: atR10191 Date: 04/17/2002


specification for the method
 public abstract void clipRect(int x, int y, int width, int height) of
class Graphics states:
"Intersects the current clip with the specified rectangle.
 The resulting clipping area is the intersection of the current clipping area
 and the specified rectangle.
 ..."

Trying to test the method,
I set the clip passing Rectangle object to the setClip() method.
After that I expect that clipping area behaves as Rectangle.
I consider Rectangle.intersection() for the case as corresponding
to the "intersection" term in the text of specification.
And I treat Rectangle.equals() for the case as standing for the "is" term of the
spec.
I thought I could do this due to the obect-orienting nature of the Java
language. There should be some sort of consistency in notion of intersection
between clipping functions and general-purpose classes, such as Rectangle.
There is test below (Test106).

But the Personal Basis Profile RI team insists that it is wrong
interpretation of the spec. They say:
"...
The spec for clipRect says that the "resulting clipping area..." and does
not state anywhere that the resulting clip area will be equal to the
intersection as defined by the Rectangle class. As long as the resulting
clipping area is the same (i.e. graphics functions perform the same)
that is all the spec claims.
...
  The spec does not say that the
 resulting clip rect will be identical (as far as Rectangle.equals is
 concerned) only that the resulting clipping area is the intersection of
 the existing clip with the supplied clip. As long as this is true then
 we are conforming to the spec. aren't we?
...
 Well an empty clipping rectangle implies no drawing will take place.
 This is what the spec defines (drawing is confined to clip rectangle).
 Therefore I would say that the spec does claim they are the same (for
 drawing purposes). As the spec only talks about the result of drawing
 operations in respect to the clip rectangle I think this is fine.
...
 The spec does not consider two empty Rectangles the same if the origin
 is different and this is specified (in Rectangle class). However, the
 spec never claims that the clipping area behaves the same as the
 Rectangle class - It only talks about clipping areas and intersections
 and the result of drawing operations with respect to the clipping area.
 If we behave as specified surely this is ok?
"

The question is: can the specification be treated as in the test?
If not, it should be rephrased in such a way that eliminate ambiguities
and make possible to test it.

============ Test106.java ==============================================
import java.awt.*;

public class Test106 {
    public static void main(String argv[]) {

        Frame frm = new Frame();
        frm.setVisible(true);

        Graphics g = frm.getGraphics();

        Rectangle[] rectClip = {
            new Rectangle(1, 1, 5, 5),
            new Rectangle(1, 1, 5, 5),
            new Rectangle(1, 1, 5, 5),
            new Rectangle(0,0,1,1),
            new Rectangle(1,0,5,5),
            new Rectangle(0,0,1,1),
            new Rectangle(0,0,0,0),
            new Rectangle(0,-10,0,10),
            new Rectangle(0,10,20,10),
            new Rectangle(0,Integer.MIN_VALUE,0,Integer.MAX_VALUE),
            new Rectangle(Integer.MIN_VALUE,0,Integer.MAX_VALUE,Integer.MAX_VALUE),
            new Rectangle(Integer.MIN_VALUE,Integer.MIN_VALUE,
                          Integer.MAX_VALUE,Integer.MAX_VALUE),
            new Rectangle(Integer.MAX_VALUE,Integer.MAX_VALUE,
                          Integer.MAX_VALUE,Integer.MAX_VALUE)
        };
    
        Rectangle[] rect = {
            new Rectangle(1, -4, 5, 5),
            new Rectangle(6, 1, 0, 5),
            new Rectangle(6, 0, 0, 1),
            new Rectangle(0,0,1,1),
            new Rectangle(0,0,10,10),
            new Rectangle(1,1,5,5),
            new Rectangle(5,5,1,1),
            new Rectangle(0,-10,0,10),
            new Rectangle(0,10,20,10),
            new Rectangle(1,0,5,5),
            new Rectangle(0,0,1,1),
            new Rectangle(Integer.MIN_VALUE + 2, Integer.MIN_VALUE + 2,
                          Integer.MAX_VALUE,Integer.MAX_VALUE),
            new Rectangle(1,1,0,0)
        };
    
        Rectangle[] clipRects = {new Rectangle(10,10), new Rectangle(1,1,5,5)};
    
        int nErrors = 0;
        for (int i = 0; i < rectClip.length; i++) {
            g.setClip(rectClip[i]);
            g.clipRect(rect[i].x, rect[i].y, rect[i].width, rect[i].height);
            if (!rectClip[i].intersection(rect[i]).equals(g.getClip())) {
                System.out.println("");
                System.out.println("clipRect(" + rect[i].x + "," + rect[i].y + "," +
                            rect[i].width + "," + rect[i].height + ")");
                System.out.println("resulting clip bounds: " + g.getClipBounds());
                System.out.println("intersection: " +
                            rectClip[i].intersection(rect[i]));
                nErrors++;
            }
        }

        if (nErrors > 0) {
            System.out.println("");
            System.out.println("failed");
            System.exit(1);
        }

        g.finalize();

        System.out.println("OKAY");
        System.exit(0);
    }
}
============ end of Test106.java ===========================================
======================================================================

The same reasoning applies also to specification for Graphics.create(..)

###@###.### 2002-05-29