🚀 go-pugleaf

AWT graphics clip API


------------------------------------------------------------------------
last updated: October 30, 1996


The Issue

Currently the AWT Graphics object has methods to implement an
ever-decreasing clip area. There is a single clipRect() method to
manipulate the clip area. This method will intersect the current clipping
area with the indicated rectangle and set a new clip area to the
intersection of the two. This operation is convenient for many graphics
algorithms that might wish to use clipping to control paint distribution
while operating within a Graphics object set up to clip rendering to a
contextual "repaint region". Unfortunately, when clipping is used in the
rendering process, it is usually only used for a small number of rendering
operations. Without the ability to enlarge the clip area back to the
original contextual clip established by the repaint process, clipping for
rendering purposes becomes a one-shot process. 

If a programmer wants to temporarily set the clip to a smaller area for one
or two rendering operations and then restore it later, then another
mechanism must be used. The currently available work-around is to copy the
Graphics object using one of the create() methods and then set the
temporary clip on the new Graphics object using the clipRect method and
dispose of it when done. The original Graphics object will still have its
original clip unmodified and can be used for further rendering. 

Furthermore, all of the other attributes of the Graphics object can be
queried, changed, and then restored to their original values. The clip
area, when viewed as a rendering attribute, only partially follows this
design model. There is a getClipRect() method to query the clip area as a
Rectangle object, but that method is not extensible in the future when
non-rectangular clip areas may be provided. In addition, even if you
queried the current clip area there was no way to explicitly set the clip
to this value after you have installed a more restrictive clip. 

The new clip API

To resolve this problem, 1 new class: 

	java.awt.Shape


is being added to the AWT and 3 new methods: 

	getClip()
	setClip(Shape)
	setClip(int x, int y, int w, int h)


are being added to the AWT Graphics class. 

In addition, the getClipRect() method is now deprecated in favor of the
more general getClip() method detailed above and a new method: 

	getClipBounds()


which returns the bounding box of the current clip area as a Rectangle
regardless of its shape. This method is also named consistently with the
recent terminology updates that were implemented across the AWT classes. 

Sample Code

Following is sample code showing the use of the old API to perform
temporary clipping: 



    import java.awt.*;
    import java.applet.*;

    public class TempClipExample extends Applet {
	Image bgimg, img2;
	public void paint(Graphics g) {
	    // Draw a background image
	    g.drawImage(bgimg, 0, 0, this);
	    // Draw the upper left 100x100 portion of another image at 10,10
	    Graphics g2 = g.create();
	    g2.clipRect(10, 10, 100, 100);
	    g2.drawImage(img2, 10, 10, this);
	    g2.dispose();	// reclaims resources more quickly
	    // Now continue drawing with original clip area
	    g.fillRect(0, 0, 10, 10);
	}
    }





Following is sample code showing the use of the new API to perform
temporary clipping: 



    import java.awt.*;
    import java.applet.*;

    public class TempClipExample extends Applet {
	Image bgimg, img2;
	public void paint(Graphics g) {
	    // Draw a background image
	    g.drawImage(bgimg, 0, 0, this);
	    // Draw the upper left 100x100 portion of another image at 10,10
	    Shape oldclip = g.getClip();
	    g.clipRect(10, 10, 100, 100);
	    g.drawImage(img2, 10, 10, this);
	    g.setClip(oldclip);
	    // Now continue drawing with original clip area
	    g.fillRect(0, 0, 10, 10);
	}
    }

Jesus Marquez <jmarquez@rtools.com> wrote in article
<35236CFA.FE4CB9CF@rtools.com>...
> Hola a todos.
> 
> Tengo un problema con la funci�n clipRect:
> Utilizo esta funci�n para definir el area sobre el que se voy a realizar
> modificaciones en un objeto Graphics.
> Mi problema es que no s� como volver al tama�o original, porque una vez
> llamada esta funci�n no te permite acceder a todo el gr�fico.
> 
> Gracias y un saludo.
> 
> --
> _____________________________
> 
>          Jesus Marquez Sanchez
>            Relational Tools.
>        e-mail: jmarquez@rtools.com
> _____________________________
> 
> 
>