Canvas : Java Glossary

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 (Graphic User Interface) 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 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 coordinate 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.

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

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

TestCanvas Sample Code

There is a complete example you can use as a base for your own canvas experiments. It produces a pixel grid you can see under coordinates.

Learning More

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.