Java Glossary : Canvas

Java definitions: 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

You are here : home : Java Glossary : C words : Canvas.

Canvas

a rectangular region on which you can draw lines and geometric shapes or text. Think of it as a blank canvas where you can roll your own drawing with precise positioning.

In contrast, a panel is used to place components very roughly with the layout manager figuring out the precise positions. Panels invisibly handle all sorts of events inside the native GUI where you can't get at them. Canvasses let you process them raw. A Canvas is the raw material upon which you can build your own custom components. It receives all the raw mousing events. Panels, in contrast, see only a few. Conversely, you could also think of a Canvas as a stripped down panel with the Container baggage taken off it.

If you simply draw on your Canvas in the Applet init method, on the very next repaint event, all your work will be lost. You need to create a subclass of Canvas, and put your drawing code in its paint(Graphics g) method. Don't use Canvas.setForeground or Canvas.setBackground in your repaint code. That will just trigger another repaint event in a frantic loop, and it won't let you use a variety of colours on your Canvas in the way you expect. Canvas.setForeground or Canvas.setBackground are used outside the paint method to set the default background and foreground colours. Instead, inside paint use Graphics.setColor to load up your brush with ink for whatever custom painting (forground or background) you are about to do.

Canvas Co-ordinate System

The co-ordinate system is not the usual x,y you learned in high school. The origin 0,0 is in the top left corner of the canvas, not the entire screen, not the bottom left where Descartes put it. x gets larger as you go right, as you would expect, but y gets larger as you go down, which is not such a surprise if you have used PostScript and think about the order you write text on a page, top to bottom. The units for both x and y are pixels.

coordinate_system

Canvas Clip Regions

It is considered perfectly legitimate to draw outside the boundary of your Canvas. Only the parts inside the Canvas will be displayed. The rest will be automatically clipped. Take advantage of that when you intend to display just part of something. You can also define your own clip regions, to paint sections of the Canvas. This is often easier than trying to figure out how to paint just the necessary part.

Why Canvases Don't Show Anything

The most common newbie error is to do all your drawing offscreen, and then, of course, it looks as if nothing happened.

If you forget increasing y is down you will get a reflection of the desired image, or something even more mangled if you get it right sometimes and other times forget. When you do relative positioning, you also have to remember that positive y displacement is down.

When you paint text, you position the lower left corner, not the upper left like everything else. If you forget, text near the top of the image will be offscreen.

If you don't see anything, make sure you did a Canvas.repaint() after all was setVisible and validated.

You must call Canvas.repaint() after any of the data used to compute the Canvas changes. The Canvas has no way of knowing about those changes on its own. Just calling Applet.repaint() won't do, because the repaint process will assume the Canvas does not need repainting.

Canvases don't have a natural size. Layouts tend to given them no screen real estate at all. If you see nothing, consider using these techniques to force the layout manager to give your Canvas a decent amount of space.

Use GridBagConstraints.weightx and weighty to gobble up spare space.
Use GridBagConstraints.ipadx and ipady to force the layout manager to give the Canvas extra space above what it demands with Canvas.getMinimumSize.
Override Canvas.getMinimumSize and Canvas.getPreferredSize with your own versions to demand a reasonable amount of space.
Canvas.setSize sort of works. The problem is the size you set is only temporary. On the next validate, it will be overridden by the layout manager.

Sample Canvas.Paint Method

/**
 * paint method in your own class that extends Canvas
 *
 * @param g where to paint e.g. printer, screen, RAM
 */
public void paint ( Graphics g )
   {
   // don't call super.paint().  update() has already cleared the screen.
   // You might want to override update to just call paint() if that clearing is not needed.

   // display word "today" centred at x,y
   FontMetrics fm = getFontMetrics( g.getFont() );
   String wording = "today";
   int xadj = fm.stringWidth( wording ) / 2;

   // position bottom left corner of the text
   g.drawString(wording , x-xadj, y );

   // draw a red line from x1,y1 to x2,y2
   g.setColor( Color.red );
   g.drawLine( x1 , y1, x2, y2);

   // draw an pre-existing Image.imX, imY is top left corner of the Image.
   g.drawImage ( image , imX, imY , imWidth, imHeight , this);

   } // end paint

Learning More About Canvases

If you are building your own AWT Component, you would use similar coding techniques, but would extend Component instead of Canvas. You have to use Canvas for JDK 1.0.2.

There is no such thing as a JCanvas in Swing. You don't need one since you can paint on any JComponent, e.g. a JPanel. However, you can use Canvases in Swing when you definitely want a heavyweight component.

documentation on Canvas : available:

on the web at java.Sun.com
on J: in the JDK 1.4.2_04: J:\j2sdk1.4.2_04\docs\api\java\awt\Canvas.html
on J: in the JDK 1.5 beta: J:\Program Files\Java\j2sdk1.5.0\docs\api\java\awt\Canvas.html

AWT ¤ co-ordinates ¤ FontMetrics ¤ Image ¤ ImageViewer ¤ invalidate ¤ JPanel ¤ Layout ¤ paint ¤ Panel ¤ repaint ¤ Screws: a simple Canvas application with source ¤ setVisible ¤ Swing ¤ validate ¤ window differences

home	Canadian Mind Products
	mindprod.com IP:[24.87.56.253]
	Your IP:[80.134.30.163]
	You are visitor number 5025.
	Please send errors, omissions and suggestions
	to improve this page to Roedy Green.
	You can get a fresh copy of this page from:	or possibly from your local J: drive mirror:
	http://mindprod.com/jgloss/canvas.html	J:\mindprod\jgloss\canvas.html