Drawing Shapes and Text with Graphics

A common first attempt at drawing a border around a panel is to ask for a rectangle the same size as the panel. Inside a paint method, the size of the component is available through getWidth() and getHeight(), so the call looks like it should outline the whole panel. This article follows what actually happens when that call runs, and why the answer depends on how a rectangle's pixels are counted.

When you write a paintComponent() method for a Swing component, the method header already contains a parameter of type Graphics. It is easy to treat that parameter as a convenient detail and move on, but it is the key to all drawing in this style of programming. Whatever you draw, from a rectangle to a line of text, is requested through an object that knows where the drawing should go. The useful question to keep in mind is: where did this object come from, and what is it allowed to draw on?

A graphics context has a limited scope. A single Graphics object can draw to only one location, and in the programs covered here that location is always a GUI component that belongs to some subclass of JPanel. A graphics context is therefore not a general-purpose drawing surface. It is a handle tied to one component.

A natural question follows: could you create one yourself? The Graphics class is abstract, so you cannot make a graphics context by calling a constructor directly. Because you cannot construct one, it has to be handed to you. Java supplies it, and the program's job is to use it.

There are exactly two routes for getting a graphics context that can draw on a component. The first is the one you will use most of the time: the Graphics parameter of paintComponent(). The second is the getGraphics() method on a component, which exists but comes with an important caveat. Both routes produce the same kind of object. The difference lies in when and where you receive it, and whether the system is managing the situation for you.

The paintComponent() route hands you the context at the moment the component is painted. You do not ask for it; it arrives as the parameter. The getGraphics() route is different: your program asks the component for a context at a time you choose. Because that context is one you requested yourself, the source treats the release step as your responsibility, which leads to the next section.

A graphics context obtained from getGraphics() may hold operating system resources. The source recommends calling g.dispose() once you have finished using it. That call releases whatever resources the context is holding. The source describes calling dispose() as good form, meaning it is a sound habit. The program might sometimes run without it, but releasing the context is the disciplined way to finish with it.

The rectangle method draws the outline of a rectangle. Its upper left corner sits at the point (x, y), and its width and height are the values you pass in. That description is only part of the story. The rectangle is drawn with the same pen used for lines, and that pen colors pixels one pixel to the right of the geometric line and one pixel below it.

The consequence is that the outline's real width is width plus one, and its real height is height plus one. The extra pixel column lies past the right edge, and the extra pixel row lies past the bottom edge. This corrects the belief that a rectangle with width 100 and height 50 covers exactly 100 by 50 pixels. The pixels you see extend one beyond the numbers you typed.

The diagram shows the x axis only, but the same reasoning applies to the y axis. Column 10 is the extra pixel that the width value of 10 does not account for, because the outline is drawn one pixel wider than the width passed in. The row logic follows the same rule with the height value.

The four methods drawString, drawLine, drawRect, and drawOval belong to the Graphics class, so each is called through a graphics context such as g. Each one takes integer coordinates or sizes. The table summarizes what each parameter controls, following the source's descriptions of the methods.

The source explains that coordinates refer to the lines between pixels rather than to the pixels themselves. The pen that draws a line extends one pixel to the right and one pixel down from the (x, y) point where the pen sits. Keeping that picture in mind explains why a single point is not invisible. For text, the y value is the baseline rather than the top of the characters, because some characters such as the tail of a lowercase y or g extend below it.

The source gives the standard fix for drawing a border around a component. Subtract one from the width and height, so the drawn outline's extra pixel lands on the last pixel inside the component. The source's example is g.drawRect(0, 0, getWidth()-1, getHeight()-1).

All of the drawing commands in this group respect the boundaries of the component. Any drawing done outside those boundaries is ignored, so pixels placed past the component's right or bottom edge are simply not shown. This is why the getWidth() - 1 adjustment matters. Without it, the extra pixel column and row of a border fall outside the panel and vanish.