1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.awt; 19 20 import java.awt.font.GlyphVector; 21 import java.awt.font.FontRenderContext; 22 import java.awt.geom.AffineTransform; 23 import java.awt.image.BufferedImage; 24 import java.awt.image.BufferedImageOp; 25 import java.awt.image.ImageObserver; 26 import java.awt.image.RenderedImage; 27 import java.awt.image.renderable.RenderableImage; 28 import java.text.AttributedCharacterIterator; 29 import java.util.Map; 30 31 /** 32 * The Graphics2D class extends Graphics class and provides more capabilities 33 * for rendering text, images, shapes. This provides methods to perform 34 * transformation of coordinate system, color management, and text layout. The 35 * following attributes exist for rendering: 36 * <ul> 37 * <li>Color - current Graphics2D color;</li> 38 * <li>Font - current Graphics2D font;</li> 39 * <li>Stroke - pen with a width of 1 pixel;</li> 40 * <li>Transform - current Graphics2D Transformation;</li> 41 * <li>Composite - alpha compositing rules for combining source and destination 42 * colors.</li> 43 * </ul> 44 * 45 * @since Android 1.0 46 */ 47 public abstract class Graphics2D extends Graphics { 48 49 /** 50 * Instantiates a new Graphics2D object. This constructor should never be 51 * called directly. 52 */ Graphics2D()53 protected Graphics2D() { 54 super(); 55 } 56 57 /** 58 * Adds preferences for the rendering algorithms. The preferences are 59 * arbitrary and specified by Map objects. All specified by Map object 60 * preferences can be modified. 61 * 62 * @param hints 63 * the rendering hints. 64 */ addRenderingHints(Map<?, ?> hints)65 public abstract void addRenderingHints(Map<?, ?> hints); 66 67 /** 68 * Intersects the current clipping area with the specified Shape and the 69 * result becomes a new clipping area. If current clipping area is not 70 * defined, the Shape becomes the new clipping area. No rendering operations 71 * are allowed outside the clipping area. 72 * 73 * @param s 74 * the specified Shape object which will be intersected with 75 * current clipping area. 76 */ clip(Shape s)77 public abstract void clip(Shape s); 78 79 /** 80 * Draws the outline of the specified Shape. 81 * 82 * @param s 83 * the Shape which outline is drawn. 84 */ draw(Shape s)85 public abstract void draw(Shape s); 86 87 /** 88 * Draws the specified GlyphVector object's text at the point x, y. 89 * 90 * @param g 91 * the GlyphVector object to be drawn. 92 * @param x 93 * the X position where the GlyphVector's text should be 94 * rendered. 95 * @param y 96 * the Y position where the GlyphVector's text should be 97 * rendered. 98 */ drawGlyphVector(GlyphVector g, float x, float y)99 public abstract void drawGlyphVector(GlyphVector g, float x, float y); 100 101 /** 102 * Draws the BufferedImage -- modified according to the operation 103 * BufferedImageOp -- at the point x, y. 104 * 105 * @param img 106 * the BufferedImage to be rendered. 107 * @param op 108 * the filter to be applied to the image before rendering. 109 * @param x 110 * the X coordinate of the point where the image's upper left 111 * corner will be placed. 112 * @param y 113 * the Y coordinate of the point where the image's upper left 114 * corner will be placed. 115 */ drawImage(BufferedImage img, BufferedImageOp op, int x, int y)116 public abstract void drawImage(BufferedImage img, BufferedImageOp op, int x, int y); 117 118 /** 119 * Draws BufferedImage transformed from image space into user space 120 * according to the AffineTransform xform and notifies the ImageObserver. 121 * 122 * @param img 123 * the BufferedImage to be rendered. 124 * @param xform 125 * the affine transformation from the image to the user space. 126 * @param obs 127 * the ImageObserver to be notified about the image conversion. 128 * @return true, if the image is successfully loaded and rendered, or it's 129 * null, otherwise false. 130 */ drawImage(Image img, AffineTransform xform, ImageObserver obs)131 public abstract boolean drawImage(Image img, AffineTransform xform, ImageObserver obs); 132 133 /** 134 * Draws a RenderableImage which is transformed from image space into user 135 * according to the AffineTransform xform. 136 * 137 * @param img 138 * the RenderableImage to be rendered. 139 * @param xform 140 * the affine transformation from image to user space. 141 */ drawRenderableImage(RenderableImage img, AffineTransform xform)142 public abstract void drawRenderableImage(RenderableImage img, AffineTransform xform); 143 144 /** 145 * Draws a RenderedImage which is transformed from image space into user 146 * according to the AffineTransform xform. 147 * 148 * @param img 149 * the RenderedImage to be rendered. 150 * @param xform 151 * the affine transformation from image to user space. 152 */ drawRenderedImage(RenderedImage img, AffineTransform xform)153 public abstract void drawRenderedImage(RenderedImage img, AffineTransform xform); 154 155 /** 156 * Draws the string specified by the AttributedCharacterIterator. The first 157 * character's position is specified by the X, Y parameters. 158 * 159 * @param iterator 160 * whose text is drawn. 161 * @param x 162 * the X position where the first character is drawn. 163 * @param y 164 * the Y position where the first character is drawn. 165 */ drawString(AttributedCharacterIterator iterator, float x, float y)166 public abstract void drawString(AttributedCharacterIterator iterator, float x, float y); 167 168 /** 169 * Draws the string specified by the AttributedCharacterIterator. The first 170 * character's position is specified by the X, Y parameters. 171 * 172 * @param iterator 173 * whose text is drawn. 174 * @param x 175 * the X position where the first character is drawn. 176 * @param y 177 * the Y position where the first character is drawn. 178 * @see java.awt.Graphics#drawString(AttributedCharacterIterator, int, int) 179 */ 180 @Override drawString(AttributedCharacterIterator iterator, int x, int y)181 public abstract void drawString(AttributedCharacterIterator iterator, int x, int y); 182 183 /** 184 * Draws the String whose the first character position is specified by the 185 * parameters X, Y. 186 * 187 * @param s 188 * the String to be drawn. 189 * @param x 190 * the X position of the first character. 191 * @param y 192 * the Y position of the first character. 193 */ drawString(String s, float x, float y)194 public abstract void drawString(String s, float x, float y); 195 196 /** 197 * Draws the String whose the first character coordinates are specified by 198 * the parameters X, Y. 199 * 200 * @param str 201 * the String to be drawn. 202 * @param x 203 * the X coordinate of the first character. 204 * @param y 205 * the Y coordinate of the first character. 206 * @see java.awt.Graphics#drawString(String, int, int) 207 */ 208 @Override drawString(String str, int x, int y)209 public abstract void drawString(String str, int x, int y); 210 211 /** 212 * Fills the interior of the specified Shape. 213 * 214 * @param s 215 * the Shape to be filled. 216 */ fill(Shape s)217 public abstract void fill(Shape s); 218 219 /** 220 * Gets the background color. 221 * 222 * @return the current background color. 223 */ getBackground()224 public abstract Color getBackground(); 225 226 /** 227 * Gets the current composite of the Graphics2D. 228 * 229 * @return the current composite which specifies the compositing style. 230 */ getComposite()231 public abstract Composite getComposite(); 232 233 /** 234 * Gets the device configuration. 235 * 236 * @return the device configuration. 237 */ getDeviceConfiguration()238 public abstract GraphicsConfiguration getDeviceConfiguration(); 239 240 /** 241 * Gets the rendering context of the Font. 242 * 243 * @return the FontRenderContext. 244 */ getFontRenderContext()245 public abstract FontRenderContext getFontRenderContext(); 246 247 /** 248 * Gets the current Paint of Graphics2D. 249 * 250 * @return the current Paint of Graphics2D. 251 */ getPaint()252 public abstract Paint getPaint(); 253 254 /** 255 * Gets the value of single preference for specified key. 256 * 257 * @param key 258 * the specified key of the rendering hint. 259 * @return the value of rendering hint for specified key. 260 */ getRenderingHint(RenderingHints.Key key)261 public abstract Object getRenderingHint(RenderingHints.Key key); 262 263 /** 264 * Gets the set of the rendering preferences as a collection of key/value 265 * pairs. 266 * 267 * @return the RenderingHints which contains the rendering preferences. 268 */ getRenderingHints()269 public abstract RenderingHints getRenderingHints(); 270 271 /** 272 * Gets current stroke of the Graphics2D. 273 * 274 * @return current stroke of the Graphics2D. 275 */ getStroke()276 public abstract Stroke getStroke(); 277 278 /** 279 * Gets current affine transform of the Graphics2D. 280 * 281 * @return current AffineTransform of the Graphics2D. 282 */ getTransform()283 public abstract AffineTransform getTransform(); 284 285 /** 286 * Determines whether or not the specified Shape intersects the specified 287 * Rectangle. If the onStroke parameter is true, this method checks whether 288 * or not the specified Shape outline intersects the specified Rectangle, 289 * otherwise this method checks whether or not the specified Shape's 290 * interior intersects the specified Rectangle. 291 * 292 * @param rect 293 * the specified Rectangle. 294 * @param s 295 * the Shape to check for intersection. 296 * @param onStroke 297 * the parameter determines whether or not this method checks for 298 * intersection of the Shape outline or of the Shape interior 299 * with the Rectangle. 300 * @return true, if there is a hit, false otherwise. 301 */ hit(Rectangle rect, Shape s, boolean onStroke)302 public abstract boolean hit(Rectangle rect, Shape s, boolean onStroke); 303 304 /** 305 * Performs a rotation transform relative to current Graphics2D Transform. 306 * The coordinate system is rotated by the specified angle in radians 307 * relative to current origin. 308 * 309 * @param theta 310 * the angle of rotation in radians. 311 */ rotate(double theta)312 public abstract void rotate(double theta); 313 314 /** 315 * Performs a translated rotation transform relative to current Graphics2D 316 * Transform. The coordinate system is rotated by the specified angle in 317 * radians relative to current origin and then moved to point (x, y). Is 318 * this right? 319 * 320 * @param theta 321 * the angle of rotation in radians. 322 * @param x 323 * the X coordinate. 324 * @param y 325 * the Y coordinate. 326 */ rotate(double theta, double x, double y)327 public abstract void rotate(double theta, double x, double y); 328 329 /** 330 * Performs a linear scale transform relative to current Graphics2D 331 * Transform. The coordinate system is rescaled vertically and horizontally 332 * by the specified parameters. 333 * 334 * @param sx 335 * the scaling factor by which the X coordinate is multiplied. 336 * @param sy 337 * the scaling factor by which the Y coordinate is multiplied. 338 */ scale(double sx, double sy)339 public abstract void scale(double sx, double sy); 340 341 /** 342 * Sets a new background color for clearing rectangular areas. The clearRect 343 * method uses the current background color. 344 * 345 * @param color 346 * the new background color. 347 */ setBackground(Color color)348 public abstract void setBackground(Color color); 349 350 /** 351 * Sets the current composite for Graphics2D. 352 * 353 * @param comp 354 * the Composite object. 355 */ setComposite(Composite comp)356 public abstract void setComposite(Composite comp); 357 358 /** 359 * Sets the paint for Graphics2D. 360 * 361 * @param paint 362 * the Paint object. 363 */ setPaint(Paint paint)364 public abstract void setPaint(Paint paint); 365 366 /** 367 * Sets a key-value pair in the current RenderingHints map. 368 * 369 * @param key 370 * the key of the rendering hint to set. 371 * @param value 372 * the value to set for the rendering hint. 373 */ setRenderingHint(RenderingHints.Key key, Object value)374 public abstract void setRenderingHint(RenderingHints.Key key, Object value); 375 376 /** 377 * Replaces the current rendering hints with the specified rendering 378 * preferences. 379 * 380 * @param hints 381 * the new Map of rendering hints. 382 */ setRenderingHints(Map<?, ?> hints)383 public abstract void setRenderingHints(Map<?, ?> hints); 384 385 /** 386 * Sets the stroke for the Graphics2D. 387 * 388 * @param s 389 * the Stroke object. 390 */ setStroke(Stroke s)391 public abstract void setStroke(Stroke s); 392 393 /** 394 * Overwrite the current Transform of the Graphics2D. The specified 395 * Transform should be received from the getTransform() method and should be 396 * used only for restoring the original Graphics2D transform after calling 397 * draw or fill methods. 398 * 399 * @param Tx 400 * the specified Transform. 401 */ setTransform(AffineTransform Tx)402 public abstract void setTransform(AffineTransform Tx); 403 404 /** 405 * Performs a shear transform relative to current Graphics2D Transform. The 406 * coordinate system is shifted by the specified multipliers relative to 407 * current position. 408 * 409 * @param shx 410 * the multiplier by which the X coordinates shift position along 411 * X axis as a function of Y coordinates. 412 * @param shy 413 * the multiplier by which the Y coordinates shift position along 414 * Y axis as a function of X coordinates. 415 */ shear(double shx, double shy)416 public abstract void shear(double shx, double shy); 417 418 /** 419 * Concatenates the AffineTransform object with current Transform of this 420 * Graphics2D. The transforms are applied in reverse order with the last 421 * specified transform applied first and the next transformation applied to 422 * the result of previous transformation. More precisely, if Cx is the 423 * current Graphics2D transform, the transform method's result with Tx as 424 * the parameter is the transformation Rx, where Rx(p) = Cx(Tx(p)), for p - 425 * a point in current coordinate system. Rx becomes the current Transform 426 * for this Graphics2D. 427 * 428 * @param Tx 429 * the AffineTransform object to be concatenated with current 430 * Transform. 431 */ transform(AffineTransform Tx)432 public abstract void transform(AffineTransform Tx); 433 434 /** 435 * Performs a translate transform relative to current Graphics2D Transform. 436 * The coordinate system is moved by the specified distance relative to 437 * current position. 438 * 439 * @param tx 440 * the translation distance along the X axis. 441 * @param ty 442 * the translation distance along the Y axis. 443 */ translate(double tx, double ty)444 public abstract void translate(double tx, double ty); 445 446 /** 447 * Moves the origin Graphics2D Transform to the point with x, y coordinates 448 * in current coordinate system. The new origin of coordinate system is 449 * moved to the (x, y) point accordingly. All rendering and transform 450 * operations are performed relative to this new origin. 451 * 452 * @param x 453 * the X coordinate. 454 * @param y 455 * the Y coordinate. 456 * @see java.awt.Graphics#translate(int, int) 457 */ 458 @Override translate(int x, int y)459 public abstract void translate(int x, int y); 460 461 /** 462 * Fills a 3D rectangle with the current color. The rectangle is specified 463 * by its width, height, and top left corner coordinates. 464 * 465 * @param x 466 * the X coordinate of the rectangle's top left corner. 467 * @param y 468 * the Y coordinate of the rectangle's top left corner. 469 * @param width 470 * the width of rectangle. 471 * @param height 472 * the height of rectangle. 473 * @param raised 474 * a boolean value that determines whether the rectangle is drawn 475 * as raised or indented. 476 * @see java.awt.Graphics#fill3DRect(int, int, int, int, boolean) 477 */ 478 @Override fill3DRect(int x, int y, int width, int height, boolean raised)479 public void fill3DRect(int x, int y, int width, int height, boolean raised) { 480 // According to the spec, color should be used instead of paint, 481 // so Graphics.fill3DRect resets paint and 482 // it should be restored after the call 483 Paint savedPaint = getPaint(); 484 super.fill3DRect(x, y, width, height, raised); 485 setPaint(savedPaint); 486 } 487 488 /** 489 * Draws the highlighted outline of a rectangle. 490 * 491 * @param x 492 * the X coordinate of the rectangle's top left corner. 493 * @param y 494 * the Y coordinate of the rectangle's top left corner. 495 * @param width 496 * the width of rectangle. 497 * @param height 498 * the height of rectangle. 499 * @param raised 500 * a boolean value that determines whether the rectangle is drawn 501 * as raised or indented. 502 * @see java.awt.Graphics#draw3DRect(int, int, int, int, boolean) 503 */ 504 @Override draw3DRect(int x, int y, int width, int height, boolean raised)505 public void draw3DRect(int x, int y, int width, int height, boolean raised) { 506 // According to the spec, color should be used instead of paint, 507 // so Graphics.draw3DRect resets paint and 508 // it should be restored after the call 509 Paint savedPaint = getPaint(); 510 super.draw3DRect(x, y, width, height, raised); 511 setPaint(savedPaint); 512 } 513 }