frameworks/base/tools/layoutlib/bridge/src/android/graphics/Path.java

   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
  17 package android.graphics;
  18
  19 import java.awt.Shape;
  20 import java.awt.geom.AffineTransform;
  21 import java.awt.geom.Ellipse2D;
  22 import java.awt.geom.GeneralPath;
  23 import java.awt.geom.PathIterator;
  24 import 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  */
  33 public 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 }