Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.awt;
   27   
   28   import java.beans.ConstructorProperties;
   29   
   30   /**
   31    * The <code>BasicStroke</code> class defines a basic set of rendering
   32    * attributes for the outlines of graphics primitives, which are rendered
   33    * with a {@link Graphics2D} object that has its Stroke attribute set to
   34    * this <code>BasicStroke</code>.
   35    * The rendering attributes defined by <code>BasicStroke</code> describe
   36    * the shape of the mark made by a pen drawn along the outline of a
   37    * {@link Shape} and the decorations applied at the ends and joins of
   38    * path segments of the <code>Shape</code>.
   39    * These rendering attributes include:
   40    * <dl compact>
   41    * <dt><i>width</i>
   42    * <dd>The pen width, measured perpendicularly to the pen trajectory.
   43    * <dt><i>end caps</i>
   44    * <dd>The decoration applied to the ends of unclosed subpaths and
   45    * dash segments.  Subpaths that start and end on the same point are
   46    * still considered unclosed if they do not have a CLOSE segment.
   47    * See {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE}
   48    * for more information on the CLOSE segment.
   49    * The three different decorations are: {@link #CAP_BUTT},
   50    * {@link #CAP_ROUND}, and {@link #CAP_SQUARE}.
   51    * <dt><i>line joins</i>
   52    * <dd>The decoration applied at the intersection of two path segments
   53    * and at the intersection of the endpoints of a subpath that is closed
   54    * using {@link java.awt.geom.PathIterator#SEG_CLOSE SEG_CLOSE}.
   55    * The three different decorations are: {@link #JOIN_BEVEL},
   56    * {@link #JOIN_MITER}, and {@link #JOIN_ROUND}.
   57    * <dt><i>miter limit</i>
   58    * <dd>The limit to trim a line join that has a JOIN_MITER decoration.
   59    * A line join is trimmed when the ratio of miter length to stroke
   60    * width is greater than the miterlimit value.  The miter length is
   61    * the diagonal length of the miter, which is the distance between
   62    * the inside corner and the outside corner of the intersection.
   63    * The smaller the angle formed by two line segments, the longer
   64    * the miter length and the sharper the angle of intersection.  The
   65    * default miterlimit value of 10.0f causes all angles less than
   66    * 11 degrees to be trimmed.  Trimming miters converts
   67    * the decoration of the line join to bevel.
   68    * <dt><i>dash attributes</i>
   69    * <dd>The definition of how to make a dash pattern by alternating
   70    * between opaque and transparent sections.
   71    * </dl>
   72    * All attributes that specify measurements and distances controlling
   73    * the shape of the returned outline are measured in the same
   74    * coordinate system as the original unstroked <code>Shape</code>
   75    * argument.  When a <code>Graphics2D</code> object uses a
   76    * <code>Stroke</code> object to redefine a path during the execution
   77    * of one of its <code>draw</code> methods, the geometry is supplied
   78    * in its original form before the <code>Graphics2D</code> transform
   79    * attribute is applied.  Therefore, attributes such as the pen width
   80    * are interpreted in the user space coordinate system of the
   81    * <code>Graphics2D</code> object and are subject to the scaling and
   82    * shearing effects of the user-space-to-device-space transform in that
   83    * particular <code>Graphics2D</code>.
   84    * For example, the width of a rendered shape's outline is determined
   85    * not only by the width attribute of this <code>BasicStroke</code>,
   86    * but also by the transform attribute of the
   87    * <code>Graphics2D</code> object.  Consider this code:
   88    * <blockquote><tt>
   89    *      // sets the Graphics2D object's Tranform attribute
   90    *      g2d.scale(10, 10);
   91    *      // sets the Graphics2D object's Stroke attribute
   92    *      g2d.setStroke(new BasicStroke(1.5f));
   93    * </tt></blockquote>
   94    * Assuming there are no other scaling transforms added to the
   95    * <code>Graphics2D</code> object, the resulting line
   96    * will be approximately 15 pixels wide.
   97    * As the example code demonstrates, a floating-point line
   98    * offers better precision, especially when large transforms are
   99    * used with a <code>Graphics2D</code> object.
  100    * When a line is diagonal, the exact width depends on how the
  101    * rendering pipeline chooses which pixels to fill as it traces the
  102    * theoretical widened outline.  The choice of which pixels to turn
  103    * on is affected by the antialiasing attribute because the
  104    * antialiasing rendering pipeline can choose to color
  105    * partially-covered pixels.
  106    * <p>
  107    * For more information on the user space coordinate system and the
  108    * rendering process, see the <code>Graphics2D</code> class comments.
  109    * @see Graphics2D
  110    * @author Jim Graham
  111    */
  112   public class BasicStroke implements Stroke {
  113   
  114       /**
  115        * Joins path segments by extending their outside edges until
  116        * they meet.
  117        */
  118       public final static int JOIN_MITER = 0;
  119   
  120       /**
  121        * Joins path segments by rounding off the corner at a radius
  122        * of half the line width.
  123        */
  124       public final static int JOIN_ROUND = 1;
  125   
  126       /**
  127        * Joins path segments by connecting the outer corners of their
  128        * wide outlines with a straight segment.
  129        */
  130       public final static int JOIN_BEVEL = 2;
  131   
  132       /**
  133        * Ends unclosed subpaths and dash segments with no added
  134        * decoration.
  135        */
  136       public final static int CAP_BUTT = 0;
  137   
  138       /**
  139        * Ends unclosed subpaths and dash segments with a round
  140        * decoration that has a radius equal to half of the width
  141        * of the pen.
  142        */
  143       public final static int CAP_ROUND = 1;
  144   
  145       /**
  146        * Ends unclosed subpaths and dash segments with a square
  147        * projection that extends beyond the end of the segment
  148        * to a distance equal to half of the line width.
  149        */
  150       public final static int CAP_SQUARE = 2;
  151   
  152       float width;
  153   
  154       int join;
  155       int cap;
  156       float miterlimit;
  157   
  158       float dash[];
  159       float dash_phase;
  160   
  161       /**
  162        * Constructs a new <code>BasicStroke</code> with the specified
  163        * attributes.
  164        * @param width the width of this <code>BasicStroke</code>.  The
  165        *         width must be greater than or equal to 0.0f.  If width is
  166        *         set to 0.0f, the stroke is rendered as the thinnest
  167        *         possible line for the target device and the antialias
  168        *         hint setting.
  169        * @param cap the decoration of the ends of a <code>BasicStroke</code>
  170        * @param join the decoration applied where path segments meet
  171        * @param miterlimit the limit to trim the miter join.  The miterlimit
  172        *        must be greater than or equal to 1.0f.
  173        * @param dash the array representing the dashing pattern
  174        * @param dash_phase the offset to start the dashing pattern
  175        * @throws IllegalArgumentException if <code>width</code> is negative
  176        * @throws IllegalArgumentException if <code>cap</code> is not either
  177        *         CAP_BUTT, CAP_ROUND or CAP_SQUARE
  178        * @throws IllegalArgumentException if <code>miterlimit</code> is less
  179        *         than 1 and <code>join</code> is JOIN_MITER
  180        * @throws IllegalArgumentException if <code>join</code> is not
  181        *         either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
  182        * @throws IllegalArgumentException if <code>dash_phase</code>
  183        *         is negative and <code>dash</code> is not <code>null</code>
  184        * @throws IllegalArgumentException if the length of
  185        *         <code>dash</code> is zero
  186        * @throws IllegalArgumentException if dash lengths are all zero.
  187        */
  188       @ConstructorProperties({ "lineWidth", "endCap", "lineJoin", "miterLimit", "dashArray", "dashPhase" })
  189       public BasicStroke(float width, int cap, int join, float miterlimit,
  190                          float dash[], float dash_phase) {
  191           if (width < 0.0f) {
  192               throw new IllegalArgumentException("negative width");
  193           }
  194           if (cap != CAP_BUTT && cap != CAP_ROUND && cap != CAP_SQUARE) {
  195               throw new IllegalArgumentException("illegal end cap value");
  196           }
  197           if (join == JOIN_MITER) {
  198               if (miterlimit < 1.0f) {
  199                   throw new IllegalArgumentException("miter limit < 1");
  200               }
  201           } else if (join != JOIN_ROUND && join != JOIN_BEVEL) {
  202               throw new IllegalArgumentException("illegal line join value");
  203           }
  204           if (dash != null) {
  205               if (dash_phase < 0.0f) {
  206                   throw new IllegalArgumentException("negative dash phase");
  207               }
  208               boolean allzero = true;
  209               for (int i = 0; i < dash.length; i++) {
  210                   float d = dash[i];
  211                   if (d > 0.0) {
  212                       allzero = false;
  213                   } else if (d < 0.0) {
  214                       throw new IllegalArgumentException("negative dash length");
  215                   }
  216               }
  217               if (allzero) {
  218                   throw new IllegalArgumentException("dash lengths all zero");
  219               }
  220           }
  221           this.width      = width;
  222           this.cap        = cap;
  223           this.join       = join;
  224           this.miterlimit = miterlimit;
  225           if (dash != null) {
  226               this.dash = (float []) dash.clone();
  227           }
  228           this.dash_phase = dash_phase;
  229       }
  230   
  231       /**
  232        * Constructs a solid <code>BasicStroke</code> with the specified
  233        * attributes.
  234        * @param width the width of the <code>BasicStroke</code>
  235        * @param cap the decoration of the ends of a <code>BasicStroke</code>
  236        * @param join the decoration applied where path segments meet
  237        * @param miterlimit the limit to trim the miter join
  238        * @throws IllegalArgumentException if <code>width</code> is negative
  239        * @throws IllegalArgumentException if <code>cap</code> is not either
  240        *         CAP_BUTT, CAP_ROUND or CAP_SQUARE
  241        * @throws IllegalArgumentException if <code>miterlimit</code> is less
  242        *         than 1 and <code>join</code> is JOIN_MITER
  243        * @throws IllegalArgumentException if <code>join</code> is not
  244        *         either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
  245        */
  246       public BasicStroke(float width, int cap, int join, float miterlimit) {
  247           this(width, cap, join, miterlimit, null, 0.0f);
  248       }
  249   
  250       /**
  251        * Constructs a solid <code>BasicStroke</code> with the specified
  252        * attributes.  The <code>miterlimit</code> parameter is
  253        * unnecessary in cases where the default is allowable or the
  254        * line joins are not specified as JOIN_MITER.
  255        * @param width the width of the <code>BasicStroke</code>
  256        * @param cap the decoration of the ends of a <code>BasicStroke</code>
  257        * @param join the decoration applied where path segments meet
  258        * @throws IllegalArgumentException if <code>width</code> is negative
  259        * @throws IllegalArgumentException if <code>cap</code> is not either
  260        *         CAP_BUTT, CAP_ROUND or CAP_SQUARE
  261        * @throws IllegalArgumentException if <code>join</code> is not
  262        *         either JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER
  263        */
  264       public BasicStroke(float width, int cap, int join) {
  265           this(width, cap, join, 10.0f, null, 0.0f);
  266       }
  267   
  268       /**
  269        * Constructs a solid <code>BasicStroke</code> with the specified
  270        * line width and with default values for the cap and join
  271        * styles.
  272        * @param width the width of the <code>BasicStroke</code>
  273        * @throws IllegalArgumentException if <code>width</code> is negative
  274        */
  275       public BasicStroke(float width) {
  276           this(width, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
  277       }
  278   
  279       /**
  280        * Constructs a new <code>BasicStroke</code> with defaults for all
  281        * attributes.
  282        * The default attributes are a solid line of width 1.0, CAP_SQUARE,
  283        * JOIN_MITER, a miter limit of 10.0.
  284        */
  285       public BasicStroke() {
  286           this(1.0f, CAP_SQUARE, JOIN_MITER, 10.0f, null, 0.0f);
  287       }
  288   
  289   
  290       /**
  291        * Returns a <code>Shape</code> whose interior defines the
  292        * stroked outline of a specified <code>Shape</code>.
  293        * @param s the <code>Shape</code> boundary be stroked
  294        * @return the <code>Shape</code> of the stroked outline.
  295        */
  296       public Shape createStrokedShape(Shape s) {
  297           sun.java2d.pipe.RenderingEngine re =
  298               sun.java2d.pipe.RenderingEngine.getInstance();
  299           return re.createStrokedShape(s, width, cap, join, miterlimit,
  300                                        dash, dash_phase);
  301       }
  302   
  303       /**
  304        * Returns the line width.  Line width is represented in user space,
  305        * which is the default-coordinate space used by Java 2D.  See the
  306        * <code>Graphics2D</code> class comments for more information on
  307        * the user space coordinate system.
  308        * @return the line width of this <code>BasicStroke</code>.
  309        * @see Graphics2D
  310        */
  311       public float getLineWidth() {
  312           return width;
  313       }
  314   
  315       /**
  316        * Returns the end cap style.
  317        * @return the end cap style of this <code>BasicStroke</code> as one
  318        * of the static <code>int</code> values that define possible end cap
  319        * styles.
  320        */
  321       public int getEndCap() {
  322           return cap;
  323       }
  324   
  325       /**
  326        * Returns the line join style.
  327        * @return the line join style of the <code>BasicStroke</code> as one
  328        * of the static <code>int</code> values that define possible line
  329        * join styles.
  330        */
  331       public int getLineJoin() {
  332           return join;
  333       }
  334   
  335       /**
  336        * Returns the limit of miter joins.
  337        * @return the limit of miter joins of the <code>BasicStroke</code>.
  338        */
  339       public float getMiterLimit() {
  340           return miterlimit;
  341       }
  342   
  343       /**
  344        * Returns the array representing the lengths of the dash segments.
  345        * Alternate entries in the array represent the user space lengths
  346        * of the opaque and transparent segments of the dashes.
  347        * As the pen moves along the outline of the <code>Shape</code>
  348        * to be stroked, the user space
  349        * distance that the pen travels is accumulated.  The distance
  350        * value is used to index into the dash array.
  351        * The pen is opaque when its current cumulative distance maps
  352        * to an even element of the dash array and transparent otherwise.
  353        * @return the dash array.
  354        */
  355       public float[] getDashArray() {
  356           if (dash == null) {
  357               return null;
  358           }
  359   
  360           return (float[]) dash.clone();
  361       }
  362   
  363       /**
  364        * Returns the current dash phase.
  365        * The dash phase is a distance specified in user coordinates that
  366        * represents an offset into the dashing pattern. In other words, the dash
  367        * phase defines the point in the dashing pattern that will correspond to
  368        * the beginning of the stroke.
  369        * @return the dash phase as a <code>float</code> value.
  370        */
  371       public float getDashPhase() {
  372           return dash_phase;
  373       }
  374   
  375       /**
  376        * Returns the hashcode for this stroke.
  377        * @return      a hash code for this stroke.
  378        */
  379       public int hashCode() {
  380           int hash = Float.floatToIntBits(width);
  381           hash = hash * 31 + join;
  382           hash = hash * 31 + cap;
  383           hash = hash * 31 + Float.floatToIntBits(miterlimit);
  384           if (dash != null) {
  385               hash = hash * 31 + Float.floatToIntBits(dash_phase);
  386               for (int i = 0; i < dash.length; i++) {
  387                   hash = hash * 31 + Float.floatToIntBits(dash[i]);
  388               }
  389           }
  390           return hash;
  391       }
  392   
  393       /**
  394        * Returns true if this BasicStroke represents the same
  395        * stroking operation as the given argument.
  396        */
  397      /**
  398       * Tests if a specified object is equal to this <code>BasicStroke</code>
  399       * by first testing if it is a <code>BasicStroke</code> and then comparing
  400       * its width, join, cap, miter limit, dash, and dash phase attributes with
  401       * those of this <code>BasicStroke</code>.
  402       * @param  obj the specified object to compare to this
  403       *              <code>BasicStroke</code>
  404       * @return <code>true</code> if the width, join, cap, miter limit, dash, and
  405       *            dash phase are the same for both objects;
  406       *            <code>false</code> otherwise.
  407       */
  408       public boolean equals(Object obj) {
  409           if (!(obj instanceof BasicStroke)) {
  410               return false;
  411           }
  412   
  413           BasicStroke bs = (BasicStroke) obj;
  414           if (width != bs.width) {
  415               return false;
  416           }
  417   
  418           if (join != bs.join) {
  419               return false;
  420           }
  421   
  422           if (cap != bs.cap) {
  423               return false;
  424           }
  425   
  426           if (miterlimit != bs.miterlimit) {
  427               return false;
  428           }
  429   
  430           if (dash != null) {
  431               if (dash_phase != bs.dash_phase) {
  432                   return false;
  433               }
  434   
  435               if (!java.util.Arrays.equals(dash, bs.dash)) {
  436                   return false;
  437               }
  438           }
  439           else if (bs.dash != null) {
  440               return false;
  441           }
  442   
  443           return true;
  444       }
  445   }

Home » openjdk-7 » java » awt » [javadoc | source]