1. /*
  2. * @(#)Graphics.java 1.69 04/05/18
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt;
  8. import java.io.*;
  9. import java.lang.*;
  10. import java.util.*;
  11. import java.awt.image.ImageObserver;
  12. import java.text.AttributedCharacterIterator;
  13. /**
  14. * The <code>Graphics</code> class is the abstract base class for
  15. * all graphics contexts that allow an application to draw onto
  16. * components that are realized on various devices, as well as
  17. * onto off-screen images.
  18. * <p>
  19. * A <code>Graphics</code> object encapsulates state information needed
  20. * for the basic rendering operations that Java supports. This
  21. * state information includes the following properties:
  22. * <p>
  23. * <ul>
  24. * <li>The <code>Component</code> object on which to draw.
  25. * <li>A translation origin for rendering and clipping coordinates.
  26. * <li>The current clip.
  27. * <li>The current color.
  28. * <li>The current font.
  29. * <li>The current logical pixel operation function (XOR or Paint).
  30. * <li>The current XOR alternation color
  31. * (see {@link Graphics#setXORMode}).
  32. * </ul>
  33. * <p>
  34. * Coordinates are infinitely thin and lie between the pixels of the
  35. * output device.
  36. * Operations that draw the outline of a figure operate by traversing
  37. * an infinitely thin path between pixels with a pixel-sized pen that hangs
  38. * down and to the right of the anchor point on the path.
  39. * Operations that fill a figure operate by filling the interior
  40. * of that infinitely thin path.
  41. * Operations that render horizontal text render the ascending
  42. * portion of character glyphs entirely above the baseline coordinate.
  43. * <p>
  44. * The graphics pen hangs down and to the right from the path it traverses.
  45. * This has the following implications:
  46. * <p><ul>
  47. * <li>If you draw a figure that covers a given rectangle, that
  48. * figure occupies one extra row of pixels on the right and bottom edges
  49. * as compared to filling a figure that is bounded by that same rectangle.
  50. * <li>If you draw a horizontal line along the same <i>y</i> coordinate as
  51. * the baseline of a line of text, that line is drawn entirely below
  52. * the text, except for any descenders.
  53. * </ul><p>
  54. * All coordinates that appear as arguments to the methods of this
  55. * <code>Graphics</code> object are considered relative to the
  56. * translation origin of this <code>Graphics</code> object prior to
  57. * the invocation of the method.
  58. * <p>
  59. * All rendering operations modify only pixels which lie within the
  60. * area bounded by the current clip, which is specified by a {@link Shape}
  61. * in user space and is controlled by the program using the
  62. * <code>Graphics</code> object. This <i>user clip</i>
  63. * is transformed into device space and combined with the
  64. * <i>device clip</i>, which is defined by the visibility of windows and
  65. * device extents. The combination of the user clip and device clip
  66. * defines the <i>composite clip</i>, which determines the final clipping
  67. * region. The user clip cannot be modified by the rendering
  68. * system to reflect the resulting composite clip. The user clip can only
  69. * be changed through the <code>setClip</code> or <code>clipRect</code>
  70. * methods.
  71. * All drawing or writing is done in the current color,
  72. * using the current paint mode, and in the current font.
  73. *
  74. * @version 1.69, 05/18/04
  75. * @author Sami Shaio
  76. * @author Arthur van Hoff
  77. * @see java.awt.Component
  78. * @see java.awt.Graphics#clipRect(int, int, int, int)
  79. * @see java.awt.Graphics#setColor(java.awt.Color)
  80. * @see java.awt.Graphics#setPaintMode()
  81. * @see java.awt.Graphics#setXORMode(java.awt.Color)
  82. * @see java.awt.Graphics#setFont(java.awt.Font)
  83. * @since JDK1.0
  84. */
  85. public abstract class Graphics {
  86. /**
  87. * Constructs a new <code>Graphics</code> object.
  88. * This constructor is the default contructor for a graphics
  89. * context.
  90. * <p>
  91. * Since <code>Graphics</code> is an abstract class, applications
  92. * cannot call this constructor directly. Graphics contexts are
  93. * obtained from other graphics contexts or are created by calling
  94. * <code>getGraphics</code> on a component.
  95. * @see java.awt.Graphics#create()
  96. * @see java.awt.Component#getGraphics
  97. */
  98. protected Graphics() {
  99. }
  100. /**
  101. * Creates a new <code>Graphics</code> object that is
  102. * a copy of this <code>Graphics</code> object.
  103. * @return a new graphics context that is a copy of
  104. * this graphics context.
  105. */
  106. public abstract Graphics create();
  107. /**
  108. * Creates a new <code>Graphics</code> object based on this
  109. * <code>Graphics</code> object, but with a new translation and clip area.
  110. * The new <code>Graphics</code> object has its origin
  111. * translated to the specified point (<i>x</i>, <i>y</i>).
  112. * Its clip area is determined by the intersection of the original
  113. * clip area with the specified rectangle. The arguments are all
  114. * interpreted in the coordinate system of the original
  115. * <code>Graphics</code> object. The new graphics context is
  116. * identical to the original, except in two respects:
  117. * <p>
  118. * <ul>
  119. * <li>
  120. * The new graphics context is translated by (<i>x</i>, <i>y</i>).
  121. * That is to say, the point (<code>0</code>, <code>0</code>) in the
  122. * new graphics context is the same as (<i>x</i>, <i>y</i>) in
  123. * the original graphics context.
  124. * <li>
  125. * The new graphics context has an additional clipping rectangle, in
  126. * addition to whatever (translated) clipping rectangle it inherited
  127. * from the original graphics context. The origin of the new clipping
  128. * rectangle is at (<code>0</code>, <code>0</code>), and its size
  129. * is specified by the <code>width</code> and <code>height</code>
  130. * arguments.
  131. * </ul>
  132. * <p>
  133. * @param x the <i>x</i> coordinate.
  134. * @param y the <i>y</i> coordinate.
  135. * @param width the width of the clipping rectangle.
  136. * @param height the height of the clipping rectangle.
  137. * @return a new graphics context.
  138. * @see java.awt.Graphics#translate
  139. * @see java.awt.Graphics#clipRect
  140. */
  141. public Graphics create(int x, int y, int width, int height) {
  142. Graphics g = create();
  143. if (g == null) return null;
  144. g.translate(x, y);
  145. g.clipRect(0, 0, width, height);
  146. return g;
  147. }
  148. /**
  149. * Translates the origin of the graphics context to the point
  150. * (<i>x</i>, <i>y</i>) in the current coordinate system.
  151. * Modifies this graphics context so that its new origin corresponds
  152. * to the point (<i>x</i>, <i>y</i>) in this graphics context's
  153. * original coordinate system. All coordinates used in subsequent
  154. * rendering operations on this graphics context will be relative
  155. * to this new origin.
  156. * @param x the <i>x</i> coordinate.
  157. * @param y the <i>y</i> coordinate.
  158. */
  159. public abstract void translate(int x, int y);
  160. /**
  161. * Gets this graphics context's current color.
  162. * @return this graphics context's current color.
  163. * @see java.awt.Color
  164. * @see java.awt.Graphics#setColor(Color)
  165. */
  166. public abstract Color getColor();
  167. /**
  168. * Sets this graphics context's current color to the specified
  169. * color. All subsequent graphics operations using this graphics
  170. * context use this specified color.
  171. * @param c the new rendering color.
  172. * @see java.awt.Color
  173. * @see java.awt.Graphics#getColor
  174. */
  175. public abstract void setColor(Color c);
  176. /**
  177. * Sets the paint mode of this graphics context to overwrite the
  178. * destination with this graphics context's current color.
  179. * This sets the logical pixel operation function to the paint or
  180. * overwrite mode. All subsequent rendering operations will
  181. * overwrite the destination with the current color.
  182. */
  183. public abstract void setPaintMode();
  184. /**
  185. * Sets the paint mode of this graphics context to alternate between
  186. * this graphics context's current color and the new specified color.
  187. * This specifies that logical pixel operations are performed in the
  188. * XOR mode, which alternates pixels between the current color and
  189. * a specified XOR color.
  190. * <p>
  191. * When drawing operations are performed, pixels which are the
  192. * current color are changed to the specified color, and vice versa.
  193. * <p>
  194. * Pixels that are of colors other than those two colors are changed
  195. * in an unpredictable but reversible manner; if the same figure is
  196. * drawn twice, then all pixels are restored to their original values.
  197. * @param c1 the XOR alternation color
  198. */
  199. public abstract void setXORMode(Color c1);
  200. /**
  201. * Gets the current font.
  202. * @return this graphics context's current font.
  203. * @see java.awt.Font
  204. * @see java.awt.Graphics#setFont(Font)
  205. */
  206. public abstract Font getFont();
  207. /**
  208. * Sets this graphics context's font to the specified font.
  209. * All subsequent text operations using this graphics context
  210. * use this font.
  211. * @param font the font.
  212. * @see java.awt.Graphics#getFont
  213. * @see java.awt.Graphics#drawString(java.lang.String, int, int)
  214. * @see java.awt.Graphics#drawBytes(byte[], int, int, int, int)
  215. * @see java.awt.Graphics#drawChars(char[], int, int, int, int)
  216. */
  217. public abstract void setFont(Font font);
  218. /**
  219. * Gets the font metrics of the current font.
  220. * @return the font metrics of this graphics
  221. * context's current font.
  222. * @see java.awt.Graphics#getFont
  223. * @see java.awt.FontMetrics
  224. * @see java.awt.Graphics#getFontMetrics(Font)
  225. */
  226. public FontMetrics getFontMetrics() {
  227. return getFontMetrics(getFont());
  228. }
  229. /**
  230. * Gets the font metrics for the specified font.
  231. * @return the font metrics for the specified font.
  232. * @param f the specified font
  233. * @see java.awt.Graphics#getFont
  234. * @see java.awt.FontMetrics
  235. * @see java.awt.Graphics#getFontMetrics()
  236. */
  237. public abstract FontMetrics getFontMetrics(Font f);
  238. /**
  239. * Returns the bounding rectangle of the current clipping area.
  240. * This method refers to the user clip, which is independent of the
  241. * clipping associated with device bounds and window visibility.
  242. * If no clip has previously been set, or if the clip has been
  243. * cleared using <code>setClip(null)</code>, this method returns
  244. * <code>null</code>.
  245. * The coordinates in the rectangle are relative to the coordinate
  246. * system origin of this graphics context.
  247. * @return the bounding rectangle of the current clipping area,
  248. * or <code>null</code> if no clip is set.
  249. * @see java.awt.Graphics#getClip
  250. * @see java.awt.Graphics#clipRect
  251. * @see java.awt.Graphics#setClip(int, int, int, int)
  252. * @see java.awt.Graphics#setClip(Shape)
  253. * @since JDK1.1
  254. */
  255. public abstract Rectangle getClipBounds();
  256. /**
  257. * Intersects the current clip with the specified rectangle.
  258. * The resulting clipping area is the intersection of the current
  259. * clipping area and the specified rectangle. If there is no
  260. * current clipping area, either because the clip has never been
  261. * set, or the clip has been cleared using <code>setClip(null)</code>,
  262. * the specified rectangle becomes the new clip.
  263. * This method sets the user clip, which is independent of the
  264. * clipping associated with device bounds and window visibility.
  265. * This method can only be used to make the current clip smaller.
  266. * To set the current clip larger, use any of the setClip methods.
  267. * Rendering operations have no effect outside of the clipping area.
  268. * @param x the x coordinate of the rectangle to intersect the clip with
  269. * @param y the y coordinate of the rectangle to intersect the clip with
  270. * @param width the width of the rectangle to intersect the clip with
  271. * @param height the height of the rectangle to intersect the clip with
  272. * @see #setClip(int, int, int, int)
  273. * @see #setClip(Shape)
  274. */
  275. public abstract void clipRect(int x, int y, int width, int height);
  276. /**
  277. * Sets the current clip to the rectangle specified by the given
  278. * coordinates. This method sets the user clip, which is
  279. * independent of the clipping associated with device bounds
  280. * and window visibility.
  281. * Rendering operations have no effect outside of the clipping area.
  282. * @param x the <i>x</i> coordinate of the new clip rectangle.
  283. * @param y the <i>y</i> coordinate of the new clip rectangle.
  284. * @param width the width of the new clip rectangle.
  285. * @param height the height of the new clip rectangle.
  286. * @see java.awt.Graphics#clipRect
  287. * @see java.awt.Graphics#setClip(Shape)
  288. * @see java.awt.Graphics#getClip
  289. * @since JDK1.1
  290. */
  291. public abstract void setClip(int x, int y, int width, int height);
  292. /**
  293. * Gets the current clipping area.
  294. * This method returns the user clip, which is independent of the
  295. * clipping associated with device bounds and window visibility.
  296. * If no clip has previously been set, or if the clip has been
  297. * cleared using <code>setClip(null)</code>, this method returns
  298. * <code>null</code>.
  299. * @return a <code>Shape</code> object representing the
  300. * current clipping area, or <code>null</code> if
  301. * no clip is set.
  302. * @see java.awt.Graphics#getClipBounds
  303. * @see java.awt.Graphics#clipRect
  304. * @see java.awt.Graphics#setClip(int, int, int, int)
  305. * @see java.awt.Graphics#setClip(Shape)
  306. * @since JDK1.1
  307. */
  308. public abstract Shape getClip();
  309. /**
  310. * Sets the current clipping area to an arbitrary clip shape.
  311. * Not all objects that implement the <code>Shape</code>
  312. * interface can be used to set the clip. The only
  313. * <code>Shape</code> objects that are guaranteed to be
  314. * supported are <code>Shape</code> objects that are
  315. * obtained via the <code>getClip</code> method and via
  316. * <code>Rectangle</code> objects. This method sets the
  317. * user clip, which is independent of the clipping associated
  318. * with device bounds and window visibility.
  319. * @param clip the <code>Shape</code> to use to set the clip
  320. * @see java.awt.Graphics#getClip()
  321. * @see java.awt.Graphics#clipRect
  322. * @see java.awt.Graphics#setClip(int, int, int, int)
  323. * @since JDK1.1
  324. */
  325. public abstract void setClip(Shape clip);
  326. /**
  327. * Copies an area of the component by a distance specified by
  328. * <code>dx</code> and <code>dy</code>. From the point specified
  329. * by <code>x</code> and <code>y</code>, this method
  330. * copies downwards and to the right. To copy an area of the
  331. * component to the left or upwards, specify a negative value for
  332. * <code>dx</code> or <code>dy</code>.
  333. * If a portion of the source rectangle lies outside the bounds
  334. * of the component, or is obscured by another window or component,
  335. * <code>copyArea</code> will be unable to copy the associated
  336. * pixels. The area that is omitted can be refreshed by calling
  337. * the component's <code>paint</code> method.
  338. * @param x the <i>x</i> coordinate of the source rectangle.
  339. * @param y the <i>y</i> coordinate of the source rectangle.
  340. * @param width the width of the source rectangle.
  341. * @param height the height of the source rectangle.
  342. * @param dx the horizontal distance to copy the pixels.
  343. * @param dy the vertical distance to copy the pixels.
  344. */
  345. public abstract void copyArea(int x, int y, int width, int height,
  346. int dx, int dy);
  347. /**
  348. * Draws a line, using the current color, between the points
  349. * <code>(x1, y1)</code> and <code>(x2, y2)</code>
  350. * in this graphics context's coordinate system.
  351. * @param x1 the first point's <i>x</i> coordinate.
  352. * @param y1 the first point's <i>y</i> coordinate.
  353. * @param x2 the second point's <i>x</i> coordinate.
  354. * @param y2 the second point's <i>y</i> coordinate.
  355. */
  356. public abstract void drawLine(int x1, int y1, int x2, int y2);
  357. /**
  358. * Fills the specified rectangle.
  359. * The left and right edges of the rectangle are at
  360. * <code>x</code> and <code>x + width - 1</code>.
  361. * The top and bottom edges are at
  362. * <code>y</code> and <code>y + height - 1</code>.
  363. * The resulting rectangle covers an area
  364. * <code>width</code> pixels wide by
  365. * <code>height</code> pixels tall.
  366. * The rectangle is filled using the graphics context's current color.
  367. * @param x the <i>x</i> coordinate
  368. * of the rectangle to be filled.
  369. * @param y the <i>y</i> coordinate
  370. * of the rectangle to be filled.
  371. * @param width the width of the rectangle to be filled.
  372. * @param height the height of the rectangle to be filled.
  373. * @see java.awt.Graphics#clearRect
  374. * @see java.awt.Graphics#drawRect
  375. */
  376. public abstract void fillRect(int x, int y, int width, int height);
  377. /**
  378. * Draws the outline of the specified rectangle.
  379. * The left and right edges of the rectangle are at
  380. * <code>x</code> and <code>x + width</code>.
  381. * The top and bottom edges are at
  382. * <code>y</code> and <code>y + height</code>.
  383. * The rectangle is drawn using the graphics context's current color.
  384. * @param x the <i>x</i> coordinate
  385. * of the rectangle to be drawn.
  386. * @param y the <i>y</i> coordinate
  387. * of the rectangle to be drawn.
  388. * @param width the width of the rectangle to be drawn.
  389. * @param height the height of the rectangle to be drawn.
  390. * @see java.awt.Graphics#fillRect
  391. * @see java.awt.Graphics#clearRect
  392. */
  393. public void drawRect(int x, int y, int width, int height) {
  394. if ((width < 0) || (height < 0)) {
  395. return;
  396. }
  397. if (height == 0 || width == 0) {
  398. drawLine(x, y, x + width, y + height);
  399. } else {
  400. drawLine(x, y, x + width - 1, y);
  401. drawLine(x + width, y, x + width, y + height - 1);
  402. drawLine(x + width, y + height, x + 1, y + height);
  403. drawLine(x, y + height, x, y + 1);
  404. }
  405. }
  406. /**
  407. * Clears the specified rectangle by filling it with the background
  408. * color of the current drawing surface. This operation does not
  409. * use the current paint mode.
  410. * <p>
  411. * Beginning with Java 1.1, the background color
  412. * of offscreen images may be system dependent. Applications should
  413. * use <code>setColor</code> followed by <code>fillRect</code> to
  414. * ensure that an offscreen image is cleared to a specific color.
  415. * @param x the <i>x</i> coordinate of the rectangle to clear.
  416. * @param y the <i>y</i> coordinate of the rectangle to clear.
  417. * @param width the width of the rectangle to clear.
  418. * @param height the height of the rectangle to clear.
  419. * @see java.awt.Graphics#fillRect(int, int, int, int)
  420. * @see java.awt.Graphics#drawRect
  421. * @see java.awt.Graphics#setColor(java.awt.Color)
  422. * @see java.awt.Graphics#setPaintMode
  423. * @see java.awt.Graphics#setXORMode(java.awt.Color)
  424. */
  425. public abstract void clearRect(int x, int y, int width, int height);
  426. /**
  427. * Draws an outlined round-cornered rectangle using this graphics
  428. * context's current color. The left and right edges of the rectangle
  429. * are at <code>x</code> and <code>x + width</code>,
  430. * respectively. The top and bottom edges of the rectangle are at
  431. * <code>y</code> and <code>y + height</code>.
  432. * @param x the <i>x</i> coordinate of the rectangle to be drawn.
  433. * @param y the <i>y</i> coordinate of the rectangle to be drawn.
  434. * @param width the width of the rectangle to be drawn.
  435. * @param height the height of the rectangle to be drawn.
  436. * @param arcWidth the horizontal diameter of the arc
  437. * at the four corners.
  438. * @param arcHeight the vertical diameter of the arc
  439. * at the four corners.
  440. * @see java.awt.Graphics#fillRoundRect
  441. */
  442. public abstract void drawRoundRect(int x, int y, int width, int height,
  443. int arcWidth, int arcHeight);
  444. /**
  445. * Fills the specified rounded corner rectangle with the current color.
  446. * The left and right edges of the rectangle
  447. * are at <code>x</code> and <code>x + width - 1</code>,
  448. * respectively. The top and bottom edges of the rectangle are at
  449. * <code>y</code> and <code>y + height - 1</code>.
  450. * @param x the <i>x</i> coordinate of the rectangle to be filled.
  451. * @param y the <i>y</i> coordinate of the rectangle to be filled.
  452. * @param width the width of the rectangle to be filled.
  453. * @param height the height of the rectangle to be filled.
  454. * @param arcWidth the horizontal diameter
  455. * of the arc at the four corners.
  456. * @param arcHeight the vertical diameter
  457. * of the arc at the four corners.
  458. * @see java.awt.Graphics#drawRoundRect
  459. */
  460. public abstract void fillRoundRect(int x, int y, int width, int height,
  461. int arcWidth, int arcHeight);
  462. /**
  463. * Draws a 3-D highlighted outline of the specified rectangle.
  464. * The edges of the rectangle are highlighted so that they
  465. * appear to be beveled and lit from the upper left corner.
  466. * <p>
  467. * The colors used for the highlighting effect are determined
  468. * based on the current color.
  469. * The resulting rectangle covers an area that is
  470. * <code>width + 1</code> pixels wide
  471. * by <code>height + 1</code> pixels tall.
  472. * @param x the <i>x</i> coordinate of the rectangle to be drawn.
  473. * @param y the <i>y</i> coordinate of the rectangle to be drawn.
  474. * @param width the width of the rectangle to be drawn.
  475. * @param height the height of the rectangle to be drawn.
  476. * @param raised a boolean that determines whether the rectangle
  477. * appears to be raised above the surface
  478. * or sunk into the surface.
  479. * @see java.awt.Graphics#fill3DRect
  480. */
  481. public void draw3DRect(int x, int y, int width, int height,
  482. boolean raised) {
  483. Color c = getColor();
  484. Color brighter = c.brighter();
  485. Color darker = c.darker();
  486. setColor(raised ? brighter : darker);
  487. drawLine(x, y, x, y + height);
  488. drawLine(x + 1, y, x + width - 1, y);
  489. setColor(raised ? darker : brighter);
  490. drawLine(x + 1, y + height, x + width, y + height);
  491. drawLine(x + width, y, x + width, y + height - 1);
  492. setColor(c);
  493. }
  494. /**
  495. * Paints a 3-D highlighted rectangle filled with the current color.
  496. * The edges of the rectangle will be highlighted so that it appears
  497. * as if the edges were beveled and lit from the upper left corner.
  498. * The colors used for the highlighting effect will be determined from
  499. * the current color.
  500. * @param x the <i>x</i> coordinate of the rectangle to be filled.
  501. * @param y the <i>y</i> coordinate of the rectangle to be filled.
  502. * @param width the width of the rectangle to be filled.
  503. * @param height the height of the rectangle to be filled.
  504. * @param raised a boolean value that determines whether the
  505. * rectangle appears to be raised above the surface
  506. * or etched into the surface.
  507. * @see java.awt.Graphics#draw3DRect
  508. */
  509. public void fill3DRect(int x, int y, int width, int height,
  510. boolean raised) {
  511. Color c = getColor();
  512. Color brighter = c.brighter();
  513. Color darker = c.darker();
  514. if (!raised) {
  515. setColor(darker);
  516. }
  517. fillRect(x+1, y+1, width-2, height-2);
  518. setColor(raised ? brighter : darker);
  519. drawLine(x, y, x, y + height - 1);
  520. drawLine(x + 1, y, x + width - 2, y);
  521. setColor(raised ? darker : brighter);
  522. drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
  523. drawLine(x + width - 1, y, x + width - 1, y + height - 2);
  524. setColor(c);
  525. }
  526. /**
  527. * Draws the outline of an oval.
  528. * The result is a circle or ellipse that fits within the
  529. * rectangle specified by the <code>x</code>, <code>y</code>,
  530. * <code>width</code>, and <code>height</code> arguments.
  531. * <p>
  532. * The oval covers an area that is
  533. * <code>width + 1</code> pixels wide
  534. * and <code>height + 1</code> pixels tall.
  535. * @param x the <i>x</i> coordinate of the upper left
  536. * corner of the oval to be drawn.
  537. * @param y the <i>y</i> coordinate of the upper left
  538. * corner of the oval to be drawn.
  539. * @param width the width of the oval to be drawn.
  540. * @param height the height of the oval to be drawn.
  541. * @see java.awt.Graphics#fillOval
  542. */
  543. public abstract void drawOval(int x, int y, int width, int height);
  544. /**
  545. * Fills an oval bounded by the specified rectangle with the
  546. * current color.
  547. * @param x the <i>x</i> coordinate of the upper left corner
  548. * of the oval to be filled.
  549. * @param y the <i>y</i> coordinate of the upper left corner
  550. * of the oval to be filled.
  551. * @param width the width of the oval to be filled.
  552. * @param height the height of the oval to be filled.
  553. * @see java.awt.Graphics#drawOval
  554. */
  555. public abstract void fillOval(int x, int y, int width, int height);
  556. /**
  557. * Draws the outline of a circular or elliptical arc
  558. * covering the specified rectangle.
  559. * <p>
  560. * The resulting arc begins at <code>startAngle</code> and extends
  561. * for <code>arcAngle</code> degrees, using the current color.
  562. * Angles are interpreted such that 0 degrees
  563. * is at the 3 o'clock position.
  564. * A positive value indicates a counter-clockwise rotation
  565. * while a negative value indicates a clockwise rotation.
  566. * <p>
  567. * The center of the arc is the center of the rectangle whose origin
  568. * is (<i>x</i>, <i>y</i>) and whose size is specified by the
  569. * <code>width</code> and <code>height</code> arguments.
  570. * <p>
  571. * The resulting arc covers an area
  572. * <code>width + 1</code> pixels wide
  573. * by <code>height + 1</code> pixels tall.
  574. * <p>
  575. * The angles are specified relative to the non-square extents of
  576. * the bounding rectangle such that 45 degrees always falls on the
  577. * line from the center of the ellipse to the upper right corner of
  578. * the bounding rectangle. As a result, if the bounding rectangle is
  579. * noticeably longer in one axis than the other, the angles to the
  580. * start and end of the arc segment will be skewed farther along the
  581. * longer axis of the bounds.
  582. * @param x the <i>x</i> coordinate of the
  583. * upper-left corner of the arc to be drawn.
  584. * @param y the <i>y</i> coordinate of the
  585. * upper-left corner of the arc to be drawn.
  586. * @param width the width of the arc to be drawn.
  587. * @param height the height of the arc to be drawn.
  588. * @param startAngle the beginning angle.
  589. * @param arcAngle the angular extent of the arc,
  590. * relative to the start angle.
  591. * @see java.awt.Graphics#fillArc
  592. */
  593. public abstract void drawArc(int x, int y, int width, int height,
  594. int startAngle, int arcAngle);
  595. /**
  596. * Fills a circular or elliptical arc covering the specified rectangle.
  597. * <p>
  598. * The resulting arc begins at <code>startAngle</code> and extends
  599. * for <code>arcAngle</code> degrees.
  600. * Angles are interpreted such that 0 degrees
  601. * is at the 3 o'clock position.
  602. * A positive value indicates a counter-clockwise rotation
  603. * while a negative value indicates a clockwise rotation.
  604. * <p>
  605. * The center of the arc is the center of the rectangle whose origin
  606. * is (<i>x</i>, <i>y</i>) and whose size is specified by the
  607. * <code>width</code> and <code>height</code> arguments.
  608. * <p>
  609. * The resulting arc covers an area
  610. * <code>width + 1</code> pixels wide
  611. * by <code>height + 1</code> pixels tall.
  612. * <p>
  613. * The angles are specified relative to the non-square extents of
  614. * the bounding rectangle such that 45 degrees always falls on the
  615. * line from the center of the ellipse to the upper right corner of
  616. * the bounding rectangle. As a result, if the bounding rectangle is
  617. * noticeably longer in one axis than the other, the angles to the
  618. * start and end of the arc segment will be skewed farther along the
  619. * longer axis of the bounds.
  620. * @param x the <i>x</i> coordinate of the
  621. * upper-left corner of the arc to be filled.
  622. * @param y the <i>y</i> coordinate of the
  623. * upper-left corner of the arc to be filled.
  624. * @param width the width of the arc to be filled.
  625. * @param height the height of the arc to be filled.
  626. * @param startAngle the beginning angle.
  627. * @param arcAngle the angular extent of the arc,
  628. * relative to the start angle.
  629. * @see java.awt.Graphics#drawArc
  630. */
  631. public abstract void fillArc(int x, int y, int width, int height,
  632. int startAngle, int arcAngle);
  633. /**
  634. * Draws a sequence of connected lines defined by
  635. * arrays of <i>x</i> and <i>y</i> coordinates.
  636. * Each pair of (<i>x</i>, <i>y</i>) coordinates defines a point.
  637. * The figure is not closed if the first point
  638. * differs from the last point.
  639. * @param xPoints an array of <i>x</i> points
  640. * @param yPoints an array of <i>y</i> points
  641. * @param nPoints the total number of points
  642. * @see java.awt.Graphics#drawPolygon(int[], int[], int)
  643. * @since JDK1.1
  644. */
  645. public abstract void drawPolyline(int xPoints[], int yPoints[],
  646. int nPoints);
  647. /**
  648. * Draws a closed polygon defined by
  649. * arrays of <i>x</i> and <i>y</i> coordinates.
  650. * Each pair of (<i>x</i>, <i>y</i>) coordinates defines a point.
  651. * <p>
  652. * This method draws the polygon defined by <code>nPoint</code> line
  653. * segments, where the first <code>nPoint - 1</code>
  654. * line segments are line segments from
  655. * <code>(xPoints[i - 1], yPoints[i - 1])</code>
  656. * to <code>(xPoints[i], yPoints[i])</code>, for
  657. * 1 ≤ <i>i</i> ≤ <code>nPoints</code>.
  658. * The figure is automatically closed by drawing a line connecting
  659. * the final point to the first point, if those points are different.
  660. * @param xPoints a an array of <code>x</code> coordinates.
  661. * @param yPoints a an array of <code>y</code> coordinates.
  662. * @param nPoints a the total number of points.
  663. * @see java.awt.Graphics#fillPolygon
  664. * @see java.awt.Graphics#drawPolyline
  665. */
  666. public abstract void drawPolygon(int xPoints[], int yPoints[],
  667. int nPoints);
  668. /**
  669. * Draws the outline of a polygon defined by the specified
  670. * <code>Polygon</code> object.
  671. * @param p the polygon to draw.
  672. * @see java.awt.Graphics#fillPolygon
  673. * @see java.awt.Graphics#drawPolyline
  674. */
  675. public void drawPolygon(Polygon p) {
  676. drawPolygon(p.xpoints, p.ypoints, p.npoints);
  677. }
  678. /**
  679. * Fills a closed polygon defined by
  680. * arrays of <i>x</i> and <i>y</i> coordinates.
  681. * <p>
  682. * This method draws the polygon defined by <code>nPoint</code> line
  683. * segments, where the first <code>nPoint - 1</code>
  684. * line segments are line segments from
  685. * <code>(xPoints[i - 1], yPoints[i - 1])</code>
  686. * to <code>(xPoints[i], yPoints[i])</code>, for
  687. * 1 ≤ <i>i</i> ≤ <code>nPoints</code>.
  688. * The figure is automatically closed by drawing a line connecting
  689. * the final point to the first point, if those points are different.
  690. * <p>
  691. * The area inside the polygon is defined using an
  692. * even-odd fill rule, also known as the alternating rule.
  693. * @param xPoints a an array of <code>x</code> coordinates.
  694. * @param yPoints a an array of <code>y</code> coordinates.
  695. * @param nPoints a the total number of points.
  696. * @see java.awt.Graphics#drawPolygon(int[], int[], int)
  697. */
  698. public abstract void fillPolygon(int xPoints[], int yPoints[],
  699. int nPoints);
  700. /**
  701. * Fills the polygon defined by the specified Polygon object with
  702. * the graphics context's current color.
  703. * <p>
  704. * The area inside the polygon is defined using an
  705. * even-odd fill rule, also known as the alternating rule.
  706. * @param p the polygon to fill.
  707. * @see java.awt.Graphics#drawPolygon(int[], int[], int)
  708. */
  709. public void fillPolygon(Polygon p) {
  710. fillPolygon(p.xpoints, p.ypoints, p.npoints);
  711. }
  712. /**
  713. * Draws the text given by the specified string, using this
  714. * graphics context's current font and color. The baseline of the
  715. * leftmost character is at position (<i>x</i>, <i>y</i>) in this
  716. * graphics context's coordinate system.
  717. * @param str the string to be drawn.
  718. * @param x the <i>x</i> coordinate.
  719. * @param y the <i>y</i> coordinate.
  720. * @see java.awt.Graphics#drawBytes
  721. * @see java.awt.Graphics#drawChars
  722. */
  723. public abstract void drawString(String str, int x, int y);
  724. /**
  725. * Draws the text given by the specified iterator, using this
  726. * graphics context's current color. The iterator has to specify a font
  727. * for each character. The baseline of the
  728. * leftmost character is at position (<i>x</i>, <i>y</i>) in this
  729. * graphics context's coordinate system.
  730. * @param iterator the iterator whose text is to be drawn
  731. * @param x the <i>x</i> coordinate.
  732. * @param y the <i>y</i> coordinate.
  733. * @see java.awt.Graphics#drawBytes
  734. * @see java.awt.Graphics#drawChars
  735. */
  736. public abstract void drawString(AttributedCharacterIterator iterator,
  737. int x, int y);
  738. /**
  739. * Draws the text given by the specified character array, using this
  740. * graphics context's current font and color. The baseline of the
  741. * first character is at position (<i>x</i>, <i>y</i>) in this
  742. * graphics context's coordinate system.
  743. * @param data the array of characters to be drawn
  744. * @param offset the start offset in the data
  745. * @param length the number of characters to be drawn
  746. * @param x the <i>x</i> coordinate of the baseline of the text
  747. * @param y the <i>y</i> coordinate of the baseline of the text
  748. * @see java.awt.Graphics#drawBytes
  749. * @see java.awt.Graphics#drawString
  750. */
  751. public void drawChars(char data[], int offset, int length, int x, int y) {
  752. drawString(new String(data, offset, length), x, y);
  753. }
  754. /**
  755. * Draws the text given by the specified byte array, using this
  756. * graphics context's current font and color. The baseline of the
  757. * first character is at position (<i>x</i>, <i>y</i>) in this
  758. * graphics context's coordinate system.
  759. * @param data the data to be drawn
  760. * @param offset the start offset in the data
  761. * @param length the number of bytes that are drawn
  762. * @param x the <i>x</i> coordinate of the baseline of the text
  763. * @param y the <i>y</i> coordinate of the baseline of the text
  764. * @see java.awt.Graphics#drawChars
  765. * @see java.awt.Graphics#drawString
  766. */
  767. public void drawBytes(byte data[], int offset, int length, int x, int y) {
  768. drawString(new String(data, 0, offset, length), x, y);
  769. }
  770. /**
  771. * Draws as much of the specified image as is currently available.
  772. * The image is drawn with its top-left corner at
  773. * (<i>x</i>, <i>y</i>) in this graphics context's coordinate
  774. * space. Transparent pixels in the image do not affect whatever
  775. * pixels are already there.
  776. * <p>
  777. * This method returns immediately in all cases, even if the
  778. * complete image has not yet been loaded, and it has not been dithered
  779. * and converted for the current output device.
  780. * <p>
  781. * If the image has completely loaded and its pixels are
  782. * no longer being changed, then
  783. * <code>drawImage</code> returns <code>true</code>.
  784. * Otherwise, <code>drawImage</code> returns <code>false</code>
  785. * and as more of
  786. * the image becomes available
  787. * or it is time to draw another frame of animation,
  788. * the process that loads the image notifies
  789. * the specified image observer.
  790. * @param img the specified image to be drawn. This method does
  791. * nothing if <code>img</code> is null.
  792. * @param x the <i>x</i> coordinate.
  793. * @param y the <i>y</i> coordinate.
  794. * @param observer object to be notified as more of
  795. * the image is converted.
  796. * @return <code>false</code> if the image pixels are still changing;
  797. * <code>true</code> otherwise.
  798. * @see java.awt.Image
  799. * @see java.awt.image.ImageObserver
  800. * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  801. */
  802. public abstract boolean drawImage(Image img, int x, int y,
  803. ImageObserver observer);
  804. /**
  805. * Draws as much of the specified image as has already been scaled
  806. * to fit inside the specified rectangle.
  807. * <p>
  808. * The image is drawn inside the specified rectangle of this
  809. * graphics context's coordinate space, and is scaled if
  810. * necessary. Transparent pixels do not affect whatever pixels
  811. * are already there.
  812. * <p>
  813. * This method returns immediately in all cases, even if the
  814. * entire image has not yet been scaled, dithered, and converted
  815. * for the current output device.
  816. * If the current output representation is not yet complete, then
  817. * <code>drawImage</code> returns <code>false</code>. As more of
  818. * the image becomes available, the process that loads the image notifies
  819. * the image observer by calling its <code>imageUpdate</code> method.
  820. * <p>
  821. * A scaled version of an image will not necessarily be
  822. * available immediately just because an unscaled version of the
  823. * image has been constructed for this output device. Each size of
  824. * the image may be cached separately and generated from the original
  825. * data in a separate image production sequence.
  826. * @param img the specified image to be drawn. This method does
  827. * nothing if <code>img</code> is null.
  828. * @param x the <i>x</i> coordinate.
  829. * @param y the <i>y</i> coordinate.
  830. * @param width the width of the rectangle.
  831. * @param height the height of the rectangle.
  832. * @param observer object to be notified as more of
  833. * the image is converted.
  834. * @return <code>false</code> if the image pixels are still changing;
  835. * <code>true</code> otherwise.
  836. * @see java.awt.Image
  837. * @see java.awt.image.ImageObserver
  838. * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  839. */
  840. public abstract boolean drawImage(Image img, int x, int y,
  841. int width, int height,
  842. ImageObserver observer);
  843. /**
  844. * Draws as much of the specified image as is currently available.
  845. * The image is drawn with its top-left corner at
  846. * (<i>x</i>, <i>y</i>) in this graphics context's coordinate
  847. * space. Transparent pixels are drawn in the specified
  848. * background color.
  849. * <p>
  850. * This operation is equivalent to filling a rectangle of the
  851. * width and height of the specified image with the given color and then
  852. * drawing the image on top of it, but possibly more efficient.
  853. * <p>
  854. * This method returns immediately in all cases, even if the
  855. * complete image has not yet been loaded, and it has not been dithered
  856. * and converted for the current output device.
  857. * <p>
  858. * If the image has completely loaded and its pixels are
  859. * no longer being changed, then
  860. * <code>drawImage</code> returns <code>true</code>.
  861. * Otherwise, <code>drawImage</code> returns <code>false</code>
  862. * and as more of
  863. * the image becomes available
  864. * or it is time to draw another frame of animation,
  865. * the process that loads the image notifies
  866. * the specified image observer.
  867. * @param img the specified image to be drawn. This method does
  868. * nothing if <code>img</code> is null.
  869. * @param x the <i>x</i> coordinate.
  870. * @param y the <i>y</i> coordinate.
  871. * @param bgcolor the background color to paint under the
  872. * non-opaque portions of the image.
  873. * @param observer object to be notified as more of
  874. * the image is converted.
  875. * @return <code>false</code> if the image pixels are still changing;
  876. * <code>true</code> otherwise.
  877. * @see java.awt.Image
  878. * @see java.awt.image.ImageObserver
  879. * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  880. */
  881. public abstract boolean drawImage(Image img, int x, int y,
  882. Color bgcolor,
  883. ImageObserver observer);
  884. /**
  885. * Draws as much of the specified image as has already been scaled
  886. * to fit inside the specified rectangle.
  887. * <p>
  888. * The image is drawn inside the specified rectangle of this
  889. * graphics context's coordinate space, and is scaled if
  890. * necessary. Transparent pixels are drawn in the specified
  891. * background color.
  892. * This operation is equivalent to filling a rectangle of the
  893. * width and height of the specified image with the given color and then
  894. * drawing the image on top of it, but possibly more efficient.
  895. * <p>
  896. * This method returns immediately in all cases, even if the
  897. * entire image has not yet been scaled, dithered, and converted
  898. * for the current output device.
  899. * If the current output representation is not yet complete then
  900. * <code>drawImage</code> returns <code>false</code>. As more of
  901. * the image becomes available, the process that loads the image notifies
  902. * the specified image observer.
  903. * <p>
  904. * A scaled version of an image will not necessarily be
  905. * available immediately just because an unscaled version of the
  906. * image has been constructed for this output device. Each size of
  907. * the image may be cached separately and generated from the original
  908. * data in a separate image production sequence.
  909. * @param img the specified image to be drawn. This method does
  910. * nothing if <code>img</code> is null.
  911. * @param x the <i>x</i> coordinate.
  912. * @param y the <i>y</i> coordinate.
  913. * @param width the width of the rectangle.
  914. * @param height the height of the rectangle.
  915. * @param bgcolor the background color to paint under the
  916. * non-opaque portions of the image.
  917. * @param observer object to be notified as more of
  918. * the image is converted.
  919. * @return <code>false</code> if the image pixels are still changing;
  920. * <code>true</code> otherwise.
  921. * @see java.awt.Image
  922. * @see java.awt.image.ImageObserver
  923. * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  924. */
  925. public abstract boolean drawImage(Image img, int x, int y,
  926. int width, int height,
  927. Color bgcolor,
  928. ImageObserver observer);
  929. /**
  930. * Draws as much of the specified area of the specified image as is
  931. * currently available, scaling it on the fly to fit inside the
  932. * specified area of the destination drawable surface. Transparent pixels
  933. * do not affect whatever pixels are already there.
  934. * <p>
  935. * This method returns immediately in all cases, even if the
  936. * image area to be drawn has not yet been scaled, dithered, and converted
  937. * for the current output device.
  938. * If the current output representation is not yet complete then
  939. * <code>drawImage</code> returns <code>false</code>. As more of
  940. * the image becomes available, the process that loads the image notifies
  941. * the specified image observer.
  942. * <p>
  943. * This method always uses the unscaled version of the image
  944. * to render the scaled rectangle and performs the required
  945. * scaling on the fly. It does not use a cached, scaled version
  946. * of the image for this operation. Scaling of the image from source
  947. * to destination is performed such that the first coordinate
  948. * of the source rectangle is mapped to the first coordinate of
  949. * the destination rectangle, and the second source coordinate is
  950. * mapped to the second destination coordinate. The subimage is
  951. * scaled and flipped as needed to preserve those mappings.
  952. * @param img the specified image to be drawn. This method does
  953. * nothing if <code>img</code> is null.
  954. * @param dx1 the <i>x</i> coordinate of the first corner of the
  955. * destination rectangle.
  956. * @param dy1 the <i>y</i> coordinate of the first corner of the
  957. * destination rectangle.
  958. * @param dx2 the <i>x</i> coordinate of the second corner of the
  959. * destination rectangle.
  960. * @param dy2 the <i>y</i> coordinate of the second corner of the
  961. * destination rectangle.
  962. * @param sx1 the <i>x</i> coordinate of the first corner of the
  963. * source rectangle.
  964. * @param sy1 the <i>y</i> coordinate of the first corner of the
  965. * source rectangle.
  966. * @param sx2 the <i>x</i> coordinate of the second corner of the
  967. * source rectangle.
  968. * @param sy2 the <i>y</i> coordinate of the second corner of the
  969. * source rectangle.
  970. * @param observer object to be notified as more of the image is
  971. * scaled and converted.
  972. * @return <code>false</code> if the image pixels are still changing;
  973. * <code>true</code> otherwise.
  974. * @see java.awt.Image
  975. * @see java.awt.image.ImageObserver
  976. * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  977. * @since JDK1.1
  978. */
  979. public abstract boolean drawImage(Image img,
  980. int dx1, int dy1, int dx2, int dy2,
  981. int sx1, int sy1, int sx2, int sy2,
  982. ImageObserver observer);
  983. /**
  984. * Draws as much of the specified area of the specified image as is
  985. * currently available, scaling it on the fly to fit inside the
  986. * specified area of the destination drawable surface.
  987. * <p>
  988. * Transparent pixels are drawn in the specified background color.
  989. * This operation is equivalent to filling a rectangle of the
  990. * width and height of the specified image with the given color and then
  991. * drawing the image on top of it, but possibly more efficient.
  992. * <p>
  993. * This method returns immediately in all cases, even if the
  994. * image area to be drawn has not yet been scaled, dithered, and converted
  995. * for the current output device.
  996. * If the current output representation is not yet complete then
  997. * <code>drawImage</code> returns <code>false</code>. As more of
  998. * the image becomes available, the process that loads the image notifies
  999. * the specified image observer.
  1000. * <p>
  1001. * This method always uses the unscaled version of the image
  1002. * to render the scaled rectangle and performs the required
  1003. * scaling on the fly. It does not use a cached, scaled version
  1004. * of the image for this operation. Scaling of the image from source
  1005. * to destination is performed such that the first coordinate
  1006. * of the source rectangle is mapped to the first coordinate of
  1007. * the destination rectangle, and the second source coordinate is
  1008. * mapped to the second destination coordinate. The subimage is
  1009. * scaled and flipped as needed to preserve those mappings.
  1010. * @param img the specified image to be drawn. This method does
  1011. * nothing if <code>img</code> is null.
  1012. * @param dx1 the <i>x</i> coordinate of the first corner of the
  1013. * destination rectangle.
  1014. * @param dy1 the <i>y</i> coordinate of the first corner of the
  1015. * destination rectangle.
  1016. * @param dx2 the <i>x</i> coordinate of the second corner of the
  1017. * destination rectangle.
  1018. * @param dy2 the <i>y</i> coordinate of the second corner of the
  1019. * destination rectangle.
  1020. * @param sx1 the <i>x</i> coordinate of the first corner of the
  1021. * source rectangle.
  1022. * @param sy1 the <i>y</i> coordinate of the first corner of the
  1023. * source rectangle.
  1024. * @param sx2 the <i>x</i> coordinate of the second corner of the
  1025. * source rectangle.
  1026. * @param sy2 the <i>y</i> coordinate of the second corner of the
  1027. * source rectangle.
  1028. * @param bgcolor the background color to paint under the
  1029. * non-opaque portions of the image.
  1030. * @param observer object to be notified as more of the image is
  1031. * scaled and converted.
  1032. * @return <code>false</code> if the image pixels are still changing;
  1033. * <code>true</code> otherwise.
  1034. * @see java.awt.Image
  1035. * @see java.awt.image.ImageObserver
  1036. * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  1037. * @since JDK1.1
  1038. */
  1039. public abstract boolean drawImage(Image img,
  1040. int dx1, int dy1, int dx2, int dy2,
  1041. int sx1, int sy1, int sx2, int sy2,
  1042. Color bgcolor,
  1043. ImageObserver observer);
  1044. /**
  1045. * Disposes of this graphics context and releases
  1046. * any system resources that it is using.
  1047. * A <code>Graphics</code> object cannot be used after
  1048. * <code>dispose</code>has been called.
  1049. * <p>
  1050. * When a Java program runs, a large number of <code>Graphics</code>
  1051. * objects can be created within a short time frame.
  1052. * Although the finalization process of the garbage collector
  1053. * also disposes of the same system resources, it is preferable
  1054. * to manually free the associated resources by calling this
  1055. * method rather than to rely on a finalization process which
  1056. * may not run to completion for a long period of time.
  1057. * <p>
  1058. * Graphics objects which are provided as arguments to the
  1059. * <code>paint</code> and <code>update</code> methods
  1060. * of components are automatically released by the system when
  1061. * those methods return. For efficiency, programmers should
  1062. * call <code>dispose</code> when finished using
  1063. * a <code>Graphics</code> object only if it was created
  1064. * directly from a component or another <code>Graphics</code> object.
  1065. * @see java.awt.Graphics#finalize
  1066. * @see java.awt.Component#paint
  1067. * @see java.awt.Component#update
  1068. * @see java.awt.Component#getGraphics
  1069. * @see java.awt.Graphics#create
  1070. */
  1071. public abstract void dispose();
  1072. /**
  1073. * Disposes of this graphics context once it is no longer referenced.
  1074. * @see #dispose
  1075. */
  1076. public void finalize() {
  1077. dispose();
  1078. }
  1079. /**
  1080. * Returns a <code>String</code> object representing this
  1081. * <code>Graphics</code> object's value.
  1082. * @return a string representation of this graphics context.
  1083. */
  1084. public String toString() {
  1085. return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
  1086. }
  1087. /**
  1088. * Returns the bounding rectangle of the current clipping area.
  1089. * @return the bounding rectangle of the current clipping area
  1090. * or <code>null</code> if no clip is set.
  1091. * @deprecated As of JDK version 1.1,
  1092. * replaced by <code>getClipBounds()</code>.
  1093. */
  1094. @Deprecated
  1095. public Rectangle getClipRect() {
  1096. return getClipBounds();
  1097. }
  1098. /**
  1099. * Returns true if the specified rectangular area might intersect
  1100. * the current clipping area.
  1101. * The coordinates of the specified rectangular area are in the
  1102. * user coordinate space and are relative to the coordinate
  1103. * system origin of this graphics context.
  1104. * This method may use an algorithm that calculates a result quickly
  1105. * but which sometimes might return true even if the specified
  1106. * rectangular area does not intersect the clipping area.
  1107. * The specific algorithm employed may thus trade off accuracy for
  1108. * speed, but it will never return false unless it can guarantee
  1109. * that the specified rectangular area does not intersect the
  1110. * current clipping area.
  1111. * The clipping area used by this method can represent the
  1112. * intersection of the user clip as specified through the clip
  1113. * methods of this graphics context as well as the clipping
  1114. * associated with the device or image bounds and window visibility.
  1115. *
  1116. * @param x the x coordinate of the rectangle to test against the clip
  1117. * @param y the y coordinate of the rectangle to test against the clip
  1118. * @param width the width of the rectangle to test against the clip
  1119. * @param height the height of the rectangle to test against the clip
  1120. * @return <code>true</code> if the specified rectangle intersects
  1121. * the bounds of the current clip; <code>false</code>
  1122. * otherwise.
  1123. */
  1124. public boolean hitClip(int x, int y, int width, int height) {
  1125. // Note, this implementation is not very efficient.
  1126. // Subclasses should override this method and calculate
  1127. // the results more directly.
  1128. Rectangle clipRect = getClipBounds();
  1129. if (clipRect == null) {
  1130. return true;
  1131. }
  1132. return clipRect.intersects(x, y, width, height);
  1133. }
  1134. /**
  1135. * Returns the bounding rectangle of the current clipping area.
  1136. * The coordinates in the rectangle are relative to the coordinate
  1137. * system origin of this graphics context. This method differs
  1138. * from {@link #getClipBounds() getClipBounds} in that an existing
  1139. * rectangle is used instead of allocating a new one.
  1140. * This method refers to the user clip, which is independent of the
  1141. * clipping associated with device bounds and window visibility.
  1142. * If no clip has previously been set, or if the clip has been
  1143. * cleared using <code>setClip(null)</code>, this method returns the
  1144. * specified <code>Rectangle</code>.
  1145. * @param r the rectangle where the current clipping area is
  1146. * copied to. Any current values in this rectangle are
  1147. * overwritten.
  1148. * @return the bounding rectangle of the current clipping area.
  1149. */
  1150. public Rectangle getClipBounds(Rectangle r) {
  1151. // Note, this implementation is not very efficient.
  1152. // Subclasses should override this method and avoid
  1153. // the allocation overhead of getClipBounds().
  1154. Rectangle clipRect = getClipBounds();
  1155. if (clipRect != null) {
  1156. r.x = clipRect.x;
  1157. r.y = clipRect.y;
  1158. r.width = clipRect.width;
  1159. r.height = clipRect.height;
  1160. } else if (r == null) {
  1161. throw new NullPointerException("null rectangle parameter");
  1162. }
  1163. return r;
  1164. }
  1165. }