1/* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.graphics; 18 19import java.awt.Shape; 20import java.awt.geom.AffineTransform; 21import java.awt.geom.Ellipse2D; 22import java.awt.geom.GeneralPath; 23import java.awt.geom.PathIterator; 24import java.awt.geom.Rectangle2D; 25 26/** 27 * The Path class encapsulates compound (multiple contour) geometric paths 28 * consisting of straight line segments, quadratic curves, and cubic curves. 29 * It can be drawn with canvas.drawPath(path, paint), either filled or stroked 30 * (based on the paint's Style), or it can be used for clipping or to draw 31 * text on a path. 32 */ 33public class Path { 34 35 private FillType mFillType = FillType.WINDING; 36 private GeneralPath mPath = new GeneralPath(); 37 38 private float mLastX = 0; 39 private float mLastY = 0; 40 41 //---------- Custom methods ---------- 42 43 public Shape getAwtShape() { 44 return mPath; 45 } 46 47 //---------- 48 49 /** 50 * Create an empty path 51 */ 52 public Path() { 53 } 54 55 /** 56 * Create a new path, copying the contents from the src path. 57 * 58 * @param src The path to copy from when initializing the new path 59 */ 60 public Path(Path src) { 61 mPath.append(src.mPath, false /* connect */); 62 } 63 64 /** 65 * Clear any lines and curves from the path, making it empty. 66 * This does NOT change the fill-type setting. 67 */ 68 public void reset() { 69 mPath = new GeneralPath(); 70 } 71 72 /** 73 * Rewinds the path: clears any lines and curves from the path but 74 * keeps the internal data structure for faster reuse. 75 */ 76 public void rewind() { 77 // FIXME 78 throw new UnsupportedOperationException(); 79 } 80 81 /** Replace the contents of this with the contents of src. 82 */ 83 public void set(Path src) { 84 mPath.append(src.mPath, false /* connect */); 85 } 86 87 /** Enum for the ways a path may be filled 88 */ 89 public enum FillType { 90 // these must match the values in SkPath.h 91 WINDING (GeneralPath.WIND_NON_ZERO, false), 92 EVEN_ODD (GeneralPath.WIND_EVEN_ODD, false), 93 INVERSE_WINDING (GeneralPath.WIND_NON_ZERO, true), 94 INVERSE_EVEN_ODD(GeneralPath.WIND_EVEN_ODD, true); 95 96 FillType(int rule, boolean inverse) { 97 this.rule = rule; 98 this.inverse = inverse; 99 } 100 101 final int rule; 102 final boolean inverse; 103 } 104 105 /** 106 * Return the path's fill type. This defines how "inside" is 107 * computed. The default value is WINDING. 108 * 109 * @return the path's fill type 110 */ 111 public FillType getFillType() { 112 return mFillType; 113 } 114 115 /** 116 * Set the path's fill type. This defines how "inside" is computed. 117 * 118 * @param ft The new fill type for this path 119 */ 120 public void setFillType(FillType ft) { 121 mFillType = ft; 122 mPath.setWindingRule(ft.rule); 123 } 124 125 /** 126 * Returns true if the filltype is one of the INVERSE variants 127 * 128 * @return true if the filltype is one of the INVERSE variants 129 */ 130 public boolean isInverseFillType() { 131 return mFillType.inverse; 132 } 133 134 /** 135 * Toggles the INVERSE state of the filltype 136 */ 137 public void toggleInverseFillType() { 138 switch (mFillType) { 139 case WINDING: 140 mFillType = FillType.INVERSE_WINDING; 141 break; 142 case EVEN_ODD: 143 mFillType = FillType.INVERSE_EVEN_ODD; 144 break; 145 case INVERSE_WINDING: 146 mFillType = FillType.WINDING; 147 break; 148 case INVERSE_EVEN_ODD: 149 mFillType = FillType.EVEN_ODD; 150 break; 151 } 152 } 153 154 /** 155 * Returns true if the path is empty (contains no lines or curves) 156 * 157 * @return true if the path is empty (contains no lines or curves) 158 */ 159 public boolean isEmpty() { 160 return mPath.getCurrentPoint() == null; 161 } 162 163 /** 164 * Returns true if the path specifies a rectangle. If so, and if rect is 165 * not null, set rect to the bounds of the path. If the path does not 166 * specify a rectangle, return false and ignore rect. 167 * 168 * @param rect If not null, returns the bounds of the path if it specifies 169 * a rectangle 170 * @return true if the path specifies a rectangle 171 */ 172 public boolean isRect(RectF rect) { 173 // FIXME 174 throw new UnsupportedOperationException(); 175 } 176 177 /** 178 * Compute the bounds of the path, and write the answer into bounds. If the 179 * path contains 0 or 1 points, the bounds is set to (0,0,0,0) 180 * 181 * @param bounds Returns the computed bounds of the path 182 * @param exact If true, return the exact (but slower) bounds, else return 183 * just the bounds of all control points 184 */ 185 public void computeBounds(RectF bounds, boolean exact) { 186 Rectangle2D rect = mPath.getBounds2D(); 187 bounds.left = (float)rect.getMinX(); 188 bounds.right = (float)rect.getMaxX(); 189 bounds.top = (float)rect.getMinY(); 190 bounds.bottom = (float)rect.getMaxY(); 191 } 192 193 /** 194 * Hint to the path to prepare for adding more points. This can allow the 195 * path to more efficiently allocate its storage. 196 * 197 * @param extraPtCount The number of extra points that may be added to this 198 * path 199 */ 200 public void incReserve(int extraPtCount) { 201 // pass 202 } 203 204 /** 205 * Set the beginning of the next contour to the point (x,y). 206 * 207 * @param x The x-coordinate of the start of a new contour 208 * @param y The y-coordinate of the start of a new contour 209 */ 210 public void moveTo(float x, float y) { 211 mPath.moveTo(mLastX = x, mLastY = y); 212 } 213 214 /** 215 * Set the beginning of the next contour relative to the last point on the 216 * previous contour. If there is no previous contour, this is treated the 217 * same as moveTo(). 218 * 219 * @param dx The amount to add to the x-coordinate of the end of the 220 * previous contour, to specify the start of a new contour 221 * @param dy The amount to add to the y-coordinate of the end of the 222 * previous contour, to specify the start of a new contour 223 */ 224 public void rMoveTo(float dx, float dy) { 225 dx += mLastX; 226 dy += mLastY; 227 mPath.moveTo(mLastX = dx, mLastY = dy); 228 } 229 230 /** 231 * Add a line from the last point to the specified point (x,y). 232 * If no moveTo() call has been made for this contour, the first point is 233 * automatically set to (0,0). 234 * 235 * @param x The x-coordinate of the end of a line 236 * @param y The y-coordinate of the end of a line 237 */ 238 public void lineTo(float x, float y) { 239 mPath.lineTo(mLastX = x, mLastY = y); 240 } 241 242 /** 243 * Same as lineTo, but the coordinates are considered relative to the last 244 * point on this contour. If there is no previous point, then a moveTo(0,0) 245 * is inserted automatically. 246 * 247 * @param dx The amount to add to the x-coordinate of the previous point on 248 * this contour, to specify a line 249 * @param dy The amount to add to the y-coordinate of the previous point on 250 * this contour, to specify a line 251 */ 252 public void rLineTo(float dx, float dy) { 253 if (isEmpty()) { 254 mPath.moveTo(mLastX = 0, mLastY = 0); 255 } 256 dx += mLastX; 257 dy += mLastY; 258 mPath.lineTo(mLastX = dx, mLastY = dy); 259 } 260 261 /** 262 * Add a quadratic bezier from the last point, approaching control point 263 * (x1,y1), and ending at (x2,y2). If no moveTo() call has been made for 264 * this contour, the first point is automatically set to (0,0). 265 * 266 * @param x1 The x-coordinate of the control point on a quadratic curve 267 * @param y1 The y-coordinate of the control point on a quadratic curve 268 * @param x2 The x-coordinate of the end point on a quadratic curve 269 * @param y2 The y-coordinate of the end point on a quadratic curve 270 */ 271 public void quadTo(float x1, float y1, float x2, float y2) { 272 mPath.quadTo(x1, y1, mLastX = x2, mLastY = y2); 273 } 274 275 /** 276 * Same as quadTo, but the coordinates are considered relative to the last 277 * point on this contour. If there is no previous point, then a moveTo(0,0) 278 * is inserted automatically. 279 * 280 * @param dx1 The amount to add to the x-coordinate of the last point on 281 * this contour, for the control point of a quadratic curve 282 * @param dy1 The amount to add to the y-coordinate of the last point on 283 * this contour, for the control point of a quadratic curve 284 * @param dx2 The amount to add to the x-coordinate of the last point on 285 * this contour, for the end point of a quadratic curve 286 * @param dy2 The amount to add to the y-coordinate of the last point on 287 * this contour, for the end point of a quadratic curve 288 */ 289 public void rQuadTo(float dx1, float dy1, float dx2, float dy2) { 290 if (isEmpty()) { 291 mPath.moveTo(mLastX = 0, mLastY = 0); 292 } 293 dx1 += mLastX; 294 dy1 += mLastY; 295 dx2 += mLastX; 296 dy2 += mLastY; 297 mPath.quadTo(dx1, dy1, mLastX = dx2, mLastY = dy2); 298 } 299 300 /** 301 * Add a cubic bezier from the last point, approaching control points 302 * (x1,y1) and (x2,y2), and ending at (x3,y3). If no moveTo() call has been 303 * made for this contour, the first point is automatically set to (0,0). 304 * 305 * @param x1 The x-coordinate of the 1st control point on a cubic curve 306 * @param y1 The y-coordinate of the 1st control point on a cubic curve 307 * @param x2 The x-coordinate of the 2nd control point on a cubic curve 308 * @param y2 The y-coordinate of the 2nd control point on a cubic curve 309 * @param x3 The x-coordinate of the end point on a cubic curve 310 * @param y3 The y-coordinate of the end point on a cubic curve 311 */ 312 public void cubicTo(float x1, float y1, float x2, float y2, 313 float x3, float y3) { 314 mPath.curveTo(x1, y1, x2, y2, mLastX = x3, mLastY = y3); 315 } 316 317 /** 318 * Same as cubicTo, but the coordinates are considered relative to the 319 * current point on this contour. If there is no previous point, then a 320 * moveTo(0,0) is inserted automatically. 321 */ 322 public void rCubicTo(float dx1, float dy1, float dx2, float dy2, 323 float dx3, float dy3) { 324 if (isEmpty()) { 325 mPath.moveTo(mLastX = 0, mLastY = 0); 326 } 327 dx1 += mLastX; 328 dy1 += mLastY; 329 dx2 += mLastX; 330 dy2 += mLastY; 331 dx3 += mLastX; 332 dy3 += mLastY; 333 mPath.curveTo(dx1, dy1, dx2, dy2, mLastX = dx3, mLastY = dy3); 334 } 335 336 /** 337 * Append the specified arc to the path as a new contour. If the start of 338 * the path is different from the path's current last point, then an 339 * automatic lineTo() is added to connect the current contour to the 340 * start of the arc. However, if the path is empty, then we call moveTo() 341 * with the first point of the arc. The sweep angle is tread mod 360. 342 * 343 * @param oval The bounds of oval defining shape and size of the arc 344 * @param startAngle Starting angle (in degrees) where the arc begins 345 * @param sweepAngle Sweep angle (in degrees) measured clockwise, treated 346 * mod 360. 347 * @param forceMoveTo If true, always begin a new contour with the arc 348 */ 349 public void arcTo(RectF oval, float startAngle, float sweepAngle, 350 boolean forceMoveTo) { 351 throw new UnsupportedOperationException(); 352 } 353 354 /** 355 * Append the specified arc to the path as a new contour. If the start of 356 * the path is different from the path's current last point, then an 357 * automatic lineTo() is added to connect the current contour to the 358 * start of the arc. However, if the path is empty, then we call moveTo() 359 * with the first point of the arc. 360 * 361 * @param oval The bounds of oval defining shape and size of the arc 362 * @param startAngle Starting angle (in degrees) where the arc begins 363 * @param sweepAngle Sweep angle (in degrees) measured clockwise 364 */ 365 public void arcTo(RectF oval, float startAngle, float sweepAngle) { 366 throw new UnsupportedOperationException(); 367 } 368 369 /** 370 * Close the current contour. If the current point is not equal to the 371 * first point of the contour, a line segment is automatically added. 372 */ 373 public void close() { 374 mPath.closePath(); 375 } 376 377 /** 378 * Specifies how closed shapes (e.g. rects, ovals) are oriented when they 379 * are added to a path. 380 */ 381 public enum Direction { 382 /** clockwise */ 383 CW (0), // must match enum in SkPath.h 384 /** counter-clockwise */ 385 CCW (1); // must match enum in SkPath.h 386 387 Direction(int ni) { 388 nativeInt = ni; 389 } 390 final int nativeInt; 391 } 392 393 /** 394 * Add a closed rectangle contour to the path 395 * 396 * @param rect The rectangle to add as a closed contour to the path 397 * @param dir The direction to wind the rectangle's contour 398 */ 399 public void addRect(RectF rect, Direction dir) { 400 if (rect == null) { 401 throw new NullPointerException("need rect parameter"); 402 } 403 404 addRect(rect.left, rect.top, rect.right, rect.bottom, dir); 405 } 406 407 /** 408 * Add a closed rectangle contour to the path 409 * 410 * @param left The left side of a rectangle to add to the path 411 * @param top The top of a rectangle to add to the path 412 * @param right The right side of a rectangle to add to the path 413 * @param bottom The bottom of a rectangle to add to the path 414 * @param dir The direction to wind the rectangle's contour 415 */ 416 public void addRect(float left, float top, float right, float bottom, 417 Direction dir) { 418 moveTo(left, top); 419 420 switch (dir) { 421 case CW: 422 lineTo(right, top); 423 lineTo(right, bottom); 424 lineTo(left, bottom); 425 break; 426 case CCW: 427 lineTo(left, bottom); 428 lineTo(right, bottom); 429 lineTo(right, top); 430 break; 431 } 432 433 close(); 434 } 435 436 /** 437 * Add a closed oval contour to the path 438 * 439 * @param oval The bounds of the oval to add as a closed contour to the path 440 * @param dir The direction to wind the oval's contour 441 */ 442 public void addOval(RectF oval, Direction dir) { 443 if (oval == null) { 444 throw new NullPointerException("need oval parameter"); 445 } 446 447 // FIXME Need to support direction 448 Ellipse2D ovalShape = new Ellipse2D.Float(oval.left, oval.top, oval.width(), oval.height()); 449 450 mPath.append(ovalShape, false /* connect */); 451 } 452 453 /** 454 * Add a closed circle contour to the path 455 * 456 * @param x The x-coordinate of the center of a circle to add to the path 457 * @param y The y-coordinate of the center of a circle to add to the path 458 * @param radius The radius of a circle to add to the path 459 * @param dir The direction to wind the circle's contour 460 */ 461 public void addCircle(float x, float y, float radius, Direction dir) { 462 // FIXME 463 throw new UnsupportedOperationException(); 464 } 465 466 /** 467 * Add the specified arc to the path as a new contour. 468 * 469 * @param oval The bounds of oval defining the shape and size of the arc 470 * @param startAngle Starting angle (in degrees) where the arc begins 471 * @param sweepAngle Sweep angle (in degrees) measured clockwise 472 */ 473 public void addArc(RectF oval, float startAngle, float sweepAngle) { 474 if (oval == null) { 475 throw new NullPointerException("need oval parameter"); 476 } 477 // FIXME 478 throw new UnsupportedOperationException(); 479 } 480 481 /** 482 * Add a closed round-rectangle contour to the path 483 * 484 * @param rect The bounds of a round-rectangle to add to the path 485 * @param rx The x-radius of the rounded corners on the round-rectangle 486 * @param ry The y-radius of the rounded corners on the round-rectangle 487 * @param dir The direction to wind the round-rectangle's contour 488 */ 489 public void addRoundRect(RectF rect, float rx, float ry, Direction dir) { 490 if (rect == null) { 491 throw new NullPointerException("need rect parameter"); 492 } 493 // FIXME 494 throw new UnsupportedOperationException(); 495 } 496 497 /** 498 * Add a closed round-rectangle contour to the path. Each corner receives 499 * two radius values [X, Y]. The corners are ordered top-left, top-right, 500 * bottom-right, bottom-left 501 * 502 * @param rect The bounds of a round-rectangle to add to the path 503 * @param radii Array of 8 values, 4 pairs of [X,Y] radii 504 * @param dir The direction to wind the round-rectangle's contour 505 */ 506 public void addRoundRect(RectF rect, float[] radii, Direction dir) { 507 if (rect == null) { 508 throw new NullPointerException("need rect parameter"); 509 } 510 if (radii.length < 8) { 511 throw new ArrayIndexOutOfBoundsException("radii[] needs 8 values"); 512 } 513 // FIXME 514 throw new UnsupportedOperationException(); 515 } 516 517 /** 518 * Add a copy of src to the path, offset by (dx,dy) 519 * 520 * @param src The path to add as a new contour 521 * @param dx The amount to translate the path in X as it is added 522 */ 523 public void addPath(Path src, float dx, float dy) { 524 PathIterator iterator = src.mPath.getPathIterator(new AffineTransform(0, 0, dx, 0, 0, dy)); 525 mPath.append(iterator, false /* connect */); 526 } 527 528 /** 529 * Add a copy of src to the path 530 * 531 * @param src The path that is appended to the current path 532 */ 533 public void addPath(Path src) { 534 addPath(src, 0, 0); 535 } 536 537 /** 538 * Add a copy of src to the path, transformed by matrix 539 * 540 * @param src The path to add as a new contour 541 */ 542 public void addPath(Path src, Matrix matrix) { 543 // FIXME 544 throw new UnsupportedOperationException(); 545 } 546 547 /** 548 * Offset the path by (dx,dy), returning true on success 549 * 550 * @param dx The amount in the X direction to offset the entire path 551 * @param dy The amount in the Y direction to offset the entire path 552 * @param dst The translated path is written here. If this is null, then 553 * the original path is modified. 554 */ 555 public void offset(float dx, float dy, Path dst) { 556 GeneralPath newPath = new GeneralPath(); 557 558 PathIterator iterator = mPath.getPathIterator(new AffineTransform(0, 0, dx, 0, 0, dy)); 559 560 newPath.append(iterator, false /* connect */); 561 562 if (dst != null) { 563 dst.mPath = newPath; 564 } else { 565 mPath = newPath; 566 } 567 } 568 569 /** 570 * Offset the path by (dx,dy), returning true on success 571 * 572 * @param dx The amount in the X direction to offset the entire path 573 * @param dy The amount in the Y direction to offset the entire path 574 */ 575 public void offset(float dx, float dy) { 576 offset(dx, dy, null /* dst */); 577 } 578 579 /** 580 * Sets the last point of the path. 581 * 582 * @param dx The new X coordinate for the last point 583 * @param dy The new Y coordinate for the last point 584 */ 585 public void setLastPoint(float dx, float dy) { 586 mLastX = dx; 587 mLastY = dy; 588 } 589 590 /** 591 * Transform the points in this path by matrix, and write the answer 592 * into dst. If dst is null, then the the original path is modified. 593 * 594 * @param matrix The matrix to apply to the path 595 * @param dst The transformed path is written here. If dst is null, 596 * then the the original path is modified 597 */ 598 public void transform(Matrix matrix, Path dst) { 599 // FIXME 600 throw new UnsupportedOperationException(); 601 } 602 603 /** 604 * Transform the points in this path by matrix. 605 * 606 * @param matrix The matrix to apply to the path 607 */ 608 public void transform(Matrix matrix) { 609 transform(matrix, null /* dst */); 610 } 611} 612