Drawing Shapes with Graphics2D

Suppose you already draw lines and shapes on a Graphics2D object, and every line comes out at the same default thickness with the same plain appearance. You want more control: a heavier line for emphasis, or a line whose ends look different. Java lets you attach a description of the line's appearance to the drawing context. That description is called a stroke. This article explains how to create a stroke, attach it, and reason about what it changes, and then turns to the rectangle, line, oval, and text methods whose coordinates often cause confusion.

Keep a simple question in mind as you read: when a drawing call runs, which settings is it using? The answer depends on the order of your code, and the rest of the article traces that order step by step.

Stroke is an interface. An interface describes what a stroke object must be able to do, but it is not something you instantiate directly. The class that actually produces stroke objects is BasicStroke, and it implements the Stroke interface. So when you want a stroke, your code names BasicStroke in the constructor call, and the resulting object can be used anywhere a Stroke is expected.

Because the interface only describes behavior, the concrete work of storing thickness, end style, and corner style happens inside BasicStroke. Your code therefore constructs a BasicStroke, while the variable that holds it can be typed as the general Stroke interface when that is all the receiving code needs.

A stroke becomes useful only after it is attached to the Graphics2D object that performs the drawing. The usual sequence has two steps. First you construct a BasicStroke object and keep a reference to it. Then you pass that object to the setStroke method of the Graphics2D object. The code below builds a stroke for solid lines whose thickness is the integer 3.

The inline form is also valid. You can write g2.setStroke(new BasicStroke(3)) and skip the named variable. The named-variable form is easier to reuse across several drawing calls, while the inline form is shorter when the stroke is needed only once.

The width argument is not limited to whole numbers. The thickness is a value of type float, so a fractional thickness is also valid. An integer like 3 is accepted because Java can widen it to the float type. When you need a value such as two and a half, write the float literal with the F suffix, as in 2.5F.

A thick line raises a question that a thin one hides: what should happen at its two endpoints? Think of drawing with a wide piece of chalk on a board. The end of the mark would naturally be rounded. On a screen, you can also choose a squared-off cut. BasicStroke leaves that decision to you, and the choice is made through the cap style argument. Corners work similarly. Where two thick segments meet, there are several ways to fill the corner, and the join style argument chooses among them.

The constructor used so far takes only a width. A fuller constructor accepts every option at once. Because all options must be supplied when the object is built, this constructor is the one place where you control the complete appearance of a stroke. Once the object exists, none of its options can be altered, so if you need a different style you create a new stroke.

Each argument answers one question about the line. The first asks how thick. The next two ask how the line ends and how its corners are joined. The miter limit and the dash arguments then govern the remaining details. Read the constructor from left to right, and you are reading the appearance decisions in the order a designer would make them. The source does not list the named cap and join values individually, so consult the BasicStroke documentation for those constants.

The four methods in this group are methods of the Graphics object, so each one is called through a Graphics variable. The examples refer to that object as g, but the programmer chooses the actual name. Each method takes integer coordinates or sizes, and the table below summarizes what each parameter controls for the methods the source describes.

A line is drawn from the point (x1, y1) to the point (x2, y2). The pen that draws it extends one pixel to the right and one pixel down from the point where the pen sits. The source also notes that coordinates refer to the lines between pixels, not to the pixels themselves. Keeping that picture in mind explains why a single point is not invisible.

The drawString method draws text using the current color and font of the graphics context. The x coordinate marks the left end of the string, and the y coordinate marks the baseline. That is why the y value is not the top of the text.

All of the drawing commands in this group respect the boundaries of the component. Any drawing done outside those boundaries is ignored. This is the reason the getWidth()-1 adjustment matters: pixels placed past the component's right or bottom edge are simply not shown.