Graphics class is the abstract base class for all graphics contexts that allow an application to draw onto components that are realized on various devices, as well as onto off-screen images. A Graphics object encapsulates state information needed for the basic rendering operations that Java supports. This state information includes the following properties:
Component object on which to draw. Coordinates are infinitely thin and lie between the pixels of the output device. Operations that draw the outline of a figure operate by traversing an infinitely thin path between pixels with a pixel-sized pen that hangs down and to the right of the anchor point on the path. Operations that fill a figure operate by filling the interior of that infinitely thin path. Operations that render horizontal text render the ascending portion of character glyphs entirely above the baseline coordinate.
The graphics pen hangs down and to the right from the path it traverses. This has the following implications:
All coordinates that appear as arguments to the methods of this Graphics object are considered relative to the translation origin of this Graphics object prior to the invocation of the method.
All rendering operations modify only pixels which lie within the area bounded by the current clip, which is specified by a {@link Shape}in user space and is controlled by the program using the Graphics object. This user clip is transformed into device space and combined with the device clip, which is defined by the visibility of windows and device extents. The combination of the user clip and device clip defines the composite clip, which determines the final clipping region. The user clip cannot be modified by the rendering system to reflect the resulting composite clip. The user clip can only be changed through the setClip or clipRect methods. All drawing or writing is done in the current color, using the current paint mode, and in the current font.
@author Sami Shaio
@author Arthur van Hoff
@see ae.java.awt.Component
@see ae.java.awt.Graphics#clipRect(int,int,int,int)
@see ae.java.awt.Graphics#setColor(ae.java.awt.Color)
@see ae.java.awt.Graphics#setPaintMode()
@see ae.java.awt.Graphics#setXORMode(ae.java.awt.Color)
@see ae.java.awt.Graphics#setFont(ae.java.awt.Font)
@since JDK1.0
A graphics instance is never created by the developer and is always accessed using either a paint callback or a mutable image. There is no way to create this object directly.
Graphics class is the abstract base class for all graphics contexts that allow an application to draw onto components that are realized on various devices, as well as onto off-screen images. A Graphics object encapsulates state information needed for the basic rendering operations that Java supports. This state information includes the following properties:
Component object on which to draw. Coordinates are infinitely thin and lie between the pixels of the output device. Operations that draw the outline of a figure operate by traversing an infinitely thin path between pixels with a pixel-sized pen that hangs down and to the right of the anchor point on the path. Operations that fill a figure operate by filling the interior of that infinitely thin path. Operations that render horizontal text render the ascending portion of character glyphs entirely above the baseline coordinate.
The graphics pen hangs down and to the right from the path it traverses. This has the following implications:
All coordinates that appear as arguments to the methods of this Graphics object are considered relative to the translation origin of this Graphics object prior to the invocation of the method.
All rendering operations modify only pixels which lie within the area bounded by the current clip, which is specified by a {@link Shape} in user space and is controlled by the program using the Graphics object. This user clip is transformed into device space and combined with the device clip, which is defined by the visibility of windows and device extents. The combination of the user clip and device clip defines the composite clip, which determines the final clipping region. The user clip cannot be modified by the rendering system to reflect the resulting composite clip. The user clip can only be changed through the setClip or clipRect methods. All drawing or writing is done in the current color, using the current paint mode, and in the current font.
@version 1.74, 02/14/06
@author Sami Shaio
@author Arthur van Hoff
@see java.awt.Component
@see java.awt.Graphics#clipRect(int,int,int,int)
@see java.awt.Graphics#setColor(java.awt.Color)
@see java.awt.Graphics#setPaintMode()
@see java.awt.Graphics#setXORMode(java.awt.Color)
@see java.awt.Graphics#setFont(java.awt.Font)
@since JDK1.0
Statement (1) fills a rectangle w pixels wide and h pixels high. Statement (2) draws a rectangle whose left and top edges are within the area filled by statement (1). However, the bottom and right edges lie one pixel outside the filled area. This is counterintuitive, but it preserves the invariant that
|
has an effect identical to statement (2) above.
The exact pixels painted by drawLine() and drawArc() are not specified. Pixels touched by a fill operation must either exactly overlap or directly abut pixels touched by the corresponding draw operation. A fill operation must never leave a gap between the filled area and the pixels touched by the corresponding draw operation, nor may the fill operation touch pixels outside the area bounded by the corresponding draw operation.
The clip is the set of pixels in the destination of the Graphics object that may be modified by graphics rendering operations.
There is a single clip per Graphics object. The only pixels modified by graphics operations are those that lie within the clip. Pixels outside the clip are not modified by any graphics operations.
Operations are provided for intersecting the current clip with a given rectangle and for setting the current clip outright. The application may specify the clip by supplying a clip rectangle using coordinates relative to the current coordinate system.
It is legal to specify a clip rectangle whose width or height is zero or negative. In this case the clip is considered to be empty, that is, no pixels are contained within it. Therefore, if any graphics operations are issued under such a clip, no pixels will be modified.
It is legal to specify a clip rectangle that extends beyond or resides entirely beyond the bounds of the destination. No pixels exist outside the bounds of the destination, and the area of the clip rectangle that is outside the destination is ignored. Only the pixels that lie both within the destination and within the specified clip rectangle are considered to be part of the clip.
Operations on the coordinate system, such as {@link Graphics#translate(int,int) translate()}, do not modify the clip. The methods {@link Graphics#getClipX() getClipX()}, {@link Graphics#getClipY() getClipY()}, {@link Graphics#getClipWidth() getClipWidth()} and{@link Graphics#getClipHeight() getClipHeight()}must return a rectangle that, if passed to setClip without an intervening change to the Graphics object's coordinate system, must result in the identical set of pixels in the clip. The rectangle returned from the getClip family of methods may differ from the clip rectangle that was requested in {@link Graphics#setClip(int,int,int,int) setClip()}. This can occur if the coordinate system has been changed or if the implementation has chosen to intersect the clip rectangle with the bounds of the destination of the Graphics object.
If a graphics operation is affected by the clip, the pixels touched by that operation must be the same ones that would be touched as if the clip did not affect the operation. For example, consider a clip represented by the rectangle (cx, cy, cw, ch) and a point (x1, y1) that lies outside this rectangle and a point (x2, y2) that lies within this rectangle. In the following code fragment,
|
The pixels touched by statement (4) must be identical to the pixels within (cx, cy, cw, ch) touched by statement (3).
The drawing of text is based on "anchor points". Anchor points are used to minimize the amount of computation required when placing text. For example, in order to center a piece of text, an application needs to call stringWidth() or charWidth() to get the width and then perform a combination of subtraction and division to compute the proper location. The method to draw text is defined as follows:
public void drawString(String text, int x, int y, int anchor); (x,y). The definition of the anchor point must be one of the horizontal constants (LEFT, HCENTER, RIGHT) combined with one of the vertical constants (TOP, BASELINE, BOTTOM) using the bit-wise OR operator. Zero may also be used as the value of an anchor point. Using zero for the anchor point value gives results identical to using TOP | LEFT. Vertical centering of the text is not specified since it is not considered useful, it is hard to specify, and it is burdensome to implement. Thus, the VCENTER value is not allowed in the anchor point parameter of text drawing calls.
The actual position of the bounding box of the text relative to the (x, y) location is determined by the anchor point. These anchor points occur at named locations along the outer edge of the bounding box. Thus, if f is g's current font (as returned by g.getFont(), the following calls will all have identical results:
|
For text drawing, the inter-character and inter-line spacing (leading) specified by the font designer are included as part of the values returned in the {@link Font#stringWidth(java.lang.String) stringWidth()}and {@link Font#getHeight() getHeight()}calls of class {@link Font Font}. For example, given the following code:
|
Code fragments (5) and (6) behave similarly if not identically. This occurs because f.stringWidth() includes the inter-character spacing. The exact spacing of may differ between these calls if the system supports font kerning.
Similarly, reasonable vertical spacing may be achieved simply by adding the font height to the Y-position of subsequent lines. For example:
|
draws string1 and string2 on separate lines with an appropriate amount of inter-line spacing.
The stringWidth() of the string and the fontHeight() of the font in which it is drawn define the size of the bounding box of a piece of text. As described above, this box includes inter-line and inter-character spacing. The implementation is required to put this space below and to right of the pixels actually belonging to the characters drawn. Applications that wish to position graphics closely with respect to text (for example, to paint a rectangle around a string of text) may assume that there is space below and to the right of a string and that there is no space above and to the left of the string.
Anchor points are also used for positioning of images. Similar to text drawing, the anchor point for an image specifies the point on the bounding rectangle of the destination that is to positioned at the (x,y) location given in the graphics request. Unlike text, vertical centering of images is well-defined, and thus the VCENTER value may be used within the anchor point parameter of image drawing requests. Because images have no notion of a baseline, the BASELINE value may not be used within the anchor point parameter of image drawing requests.
| |
| |
| |