Add stroke-dashcorner and stroke-dashadjust properties. (ACTION-3421)
authorCameron McCormack <cam@mcc.id.au>
Thu, 03 Apr 2014 17:56:16 +1100
changeset 649 f2678313d917
parent 648 9d332c4d7eb5
child 650 bdc014530367
child 668 33dcba7ebbde
Add stroke-dashcorner and stroke-dashadjust properties. (ACTION-3421)
master/changes.html
master/definitions.xml
master/images/painting/dashadjust.svg
master/images/painting/dashcorner.svg
master/painting.html
--- a/master/changes.html	Wed Apr 02 10:58:29 2014 -0500
+++ b/master/changes.html	Thu Apr 03 17:56:16 2014 +1100
@@ -215,6 +215,9 @@
 
   <li>Extended the definitions of <a>'fill'</a> and
   <a>'stroke'</a> <a>&lt;paint&gt;</a> so that they can take multiple paints.</li>
+
+  <li class="added-since-last-wd">Added the <a>'stroke-dashcorner'</a> and
+  <a>'stroke-dashadjust'</a> properties.</li>
 </ul>
 
 <h3 id="color">Color chapter</h3>
--- a/master/definitions.xml	Wed Apr 02 10:58:29 2014 -0500
+++ b/master/definitions.xml	Thu Apr 03 17:56:16 2014 +1100
@@ -1017,7 +1017,7 @@
   <attributecategory
     name='presentation'
     href='intro.html#TermPresentationAttribute'
-    presentationattributes='alignment-baseline, baseline-shift, buffered-rendering, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-rendering, cursor, direction, display, dominant-baseline, enable-background, fill, fill-opacity, fill-rule, filter, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, glyph-orientation-horizontal, glyph-orientation-vertical, hanging-punctuation, hyphens, image-rendering, letter-spacing, lighting-color, line-break, line-height, marker-end, marker-mid, marker-pattern, marker-segment, marker-start, mask, opacity, overflow, overflow-wrap, paint-order, pointer-events, shape-inside, shape-margin, shape-padding, shape-rendering, shape-outside, solid-color, solid-opacity, stop-color, stop-opacity, stroke, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke-width, tab-size, text-align, text-anchor, text-decoration, text-indent, text-overflow, text-rendering, transform, unicode-bidi, vector-effect, visibility, white-space, word-break, word-spacing, word-wrap, writing-mode'/>
+    presentationattributes='alignment-baseline, baseline-shift, buffered-rendering, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-rendering, cursor, direction, display, dominant-baseline, enable-background, fill, fill-opacity, fill-rule, filter, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, glyph-orientation-horizontal, glyph-orientation-vertical, hanging-punctuation, hyphens, image-rendering, letter-spacing, lighting-color, line-break, line-height, marker-end, marker-mid, marker-pattern, marker-segment, marker-start, mask, opacity, overflow, overflow-wrap, paint-order, pointer-events, shape-inside, shape-margin, shape-padding, shape-rendering, shape-outside, solid-color, solid-opacity, stop-color, stop-opacity, stroke, stroke-dashadjust, stroke-dasharray, stroke-dashcorner, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke-width, tab-size, text-align, text-anchor, text-decoration, text-indent, text-overflow, text-rendering, transform, unicode-bidi, vector-effect, visibility, white-space, word-break, word-spacing, word-wrap, writing-mode'/>
 
   <attributecategory
       name='document event'
@@ -1161,7 +1161,9 @@
   <property name='stop-color' href='pservers.html#StopColorProperty'/>
   <property name='stop-opacity' href='pservers.html#StopOpacityProperty'/>
   <property name='stroke' href='painting.html#StrokeProperty'/>
+  <property name='stroke-dashadjust' href='painting.html#StrokeDashadjustProperty'/>
   <property name='stroke-dasharray' href='painting.html#StrokeDasharrayProperty'/>
+  <property name='stroke-dashcorner' href='painting.html#StrokeDashcornerProperty'/>
   <property name='stroke-dashoffset' href='painting.html#StrokeDashoffsetProperty'/>
   <property name='stroke-linecap' href='painting.html#StrokeLinecapProperty'/>
   <property name='stroke-linejoin' href='painting.html#StrokeLinejoinProperty'/>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/master/images/painting/dashadjust.svg	Thu Apr 03 17:56:16 2014 +1100
@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+     width="600" height="200" viewBox="0 0 600 200">
+
+  <!-- dash array "4 4 16 4 4 16" -->
+  <g fill="deeppink" fill-opacity="0.25" stroke="black" stroke-width="2px">
+    <!-- length = 376.991118, scale factor 1.170985383 -->
+    <circle cx="100" cy="100" r="60"
+      stroke-dasharray="4.68394 4.68394 18.735766 4.68394 4.68394 18.735766"/>
+
+    <!-- length = 400, scale factor 1.041666667 -->
+    <rect x="250" y="50" width="100" height="100"
+      stroke-dasharray="4.166666667 4.166666667 16.666666667 4.166666667 4.166666667 16.666666667"
+      stroke-dashoffset="-2"/>
+
+    <!-- length = 701.63525390625, scale factor 1.04410008 -->
+    <path d="M 436,20 c 2.408549,9.42613 -12.983686,14.71063 -7.730043,25.24988 4.536116,6.77556 14.333519,7.63607 21.760859,9.16241 9.517786,-1.24524 15.711878,6.35061 14.294792,15.3982 0.27166,10.93797 2.042351,23.3104 -5.747338,32.30758 -4.994998,8.56148 -13.327083,15.03017 -17.14287,24.17533 -1.289945,7.54888 -2.835406,15.46803 -2.039063,23.07663 3.976511,10.1708 16.132713,11.837 25.390356,14.2603 10.362691,4.042 18.905303,-4.4596 19.235058,-14.6539 2.782791,-9.6512 -0.610768,-19.93933 2.709299,-29.39752 4.815776,-10.28115 13.556443,1.4717 15.445363,7.76852 8.13915,13.202 17.30453,26.1912 29.28373,36.2665 8.45148,5.9843 17.55039,-1.0727 24.08191,-6.4036 10.20252,-6.5615 20.95367,-15.9684 21.26163,-29.0514 -0.58,-9.23056 -10.63156,-12.97712 -17.98478,-15.90328 -8.38326,-3.32978 -18.00259,-8.25057 -19.54451,-18.16091 -1.97295,-7.55348 -0.6407,-18.23459 7.99701,-20.82977 8.37765,-3.46227 19.5001,-0.58741 25.78554,-8.38877 5.8282,-10.31759 3.00896,-23.49721 -2.59629,-33.33595 -3.06268,-8.63819 -11.41908,-13.44316 -20.40706,-12.3559 -9.12649,-1.62859 -17.67912,2.69742 -24.93493,7.78488 -10.94153,7.0203 -20.83063,16.48061 -33.972689,19.20183 -7.50619,3.92219 -16.793117,2.61806 -18.268954,-7.05962 -3.336794,-8.075 -5.305736,-16.84134 -9.673804,-24.38533 -7.062387,-5.20866 -18.393771,-3.45871 -25.695367,0.82991 -1.906924,0.80664 -1.728902,2.79273 -1.507849,4.44398 z"
+          stroke-dasharray="4.176400321 4.176400321 16.705601283 4.176400321 4.176400321 16.705601283"/>
+  </g>
+</svg>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/master/images/painting/dashcorner.svg	Thu Apr 03 17:56:16 2014 +1100
@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+     width="300" height="150" viewBox="0 0 300 150">
+
+  <g fill="none" stroke-width="4px" stroke="deeppink" stroke-linecap="round">
+    <path d="M 110,35 h 80 v 80 h -80 z"
+          stroke-dashoffset="16px" stroke-dasharray="32 48"/>
+    <g stroke-dasharray="0 8">
+      <path d="M 110,35 m 16,0 h 48"/>
+      <path d="M 190,35 m 0,16 v 48"/>
+      <path d="M 190,115 m -16,0 h -48"/>
+      <path d="M 110,115 m 0,-16 v -48"/>
+    </g>
+  </g>
+</svg>
--- a/master/painting.html	Wed Apr 02 10:58:29 2014 -0500
+++ b/master/painting.html	Thu Apr 03 17:56:16 2014 +1100
@@ -953,8 +953,9 @@
 <p>See the definition of the <a>line join shape</a> below for a more precise
 description of the shape a line join will have.</p>
 
-<h3 id="StrokeDashing">Dashing strokes: the <span class="property">'stroke-dasharray'</span>
-and <span class="property">'stroke-dashoffset'</span> properties</h3>
+<h3 id="StrokeDashing">Dashing strokes: the <span class="property">'stroke-dasharray'</span>,
+<span class="property">'stroke-dashoffset'</span>, <span class="property">'stroke-dashcorner'</span>
+and <span class="property">'stroke-dashadjust'</span> properties</h3>
 
 <table class="propdef">
   <tr>
@@ -1110,7 +1111,224 @@
 
 <p>See the definition of <a>dash positions</a> below for a more precise
 description of positions along a path that dashes will be placed.</p>
-
+</div>
+
+<table class="propdef">
+  <tr>
+    <th>Name:</th>
+    <td><dfn id="StrokeDashcornerProperty">stroke-dashcorner</dfn></td>
+  </tr>
+  <tr>
+    <th>Value:</th>
+    <td>none | <a>&lt;length&gt;</a></td>
+  </tr>
+  <tr>
+    <th>Initial:</th>
+    <td>none</td>
+  </tr>
+  <tr>
+    <th>Applies to:</th>
+    <td><a>shapes</a> and <a>text content elements</a></td>
+  </tr>
+  <tr>
+    <th>Inherited:</th>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <th>Percentages:</th>
+    <td>refer to the size of the current viewport (see <a href="coords.html#Units">Units</a>)</td>
+  </tr>
+  <tr>
+    <th>Media:</th>
+    <td>visual</td>
+  </tr>
+  <tr>
+    <th>Computed&#160;value:</th>
+    <td>as specified</td>
+  </tr>
+  <tr>
+    <th><a>Animatable</a>:</th>
+    <td>yes</td>
+  </tr>
+</table>
+
+<p class="note">New in SVG 2.  Added to allow better control of dashing
+at the vertices of a shape, such as at the four corners of a rectangle.</p>
+
+<p>The <a>'stroke-dashcorner'</a> property controls whether a dash
+is always painted at the vertices of a stroked shape.  The points at which
+a dash corner is painted include the start and end points of every
+segment within the shape's <a>equivalent path</a>.</p>
+
+<p class="issue">This will not help with placing a corner dash on a
+<a>'rect'</a> with rounded corners, as they will also be placed at
+the points between the arcs forming the rounded corners and the
+straight line segments.</p>
+
+<dl>
+  <dt><span class='prop-value'>none</span></dt>
+  <dd>Indicates that no dashes are required to be painted at the
+  vertices of the shape.</dd>
+
+  <dt><span class='prop-value'>&lt;length&gt;</span></dt>
+  <dd>Specifies that a dash of the given length is to be painted
+  at each vertex of the shape.  For an open shape, the first
+  corner dash is positioned so that it begins at the start of
+  the path, and the last corner dash so that it ends at the
+  end of the path.  The other corner dashes of an open shape,
+  and all corner dashes of a closed shape, are positioned so that
+  they are centered on their vertex.</dd>
+</dl>
+
+<p class="issue">Should the corner dash at the first and last vertex
+of an open shape be half the length of the others?  Should this be
+author controllable?</p>
+
+<p class="issue">Should there be a way to specify a padding, so that
+any dash pattern between the corner dashes does not not run up against them?</p>
+
+<p>The <a>'stroke-dashcorner'</a> property also controls how
+the dash pattern given by <a>'stroke-dasharray'</a> is repeated.
+When <span class='prop-value'>none</span> is used, the dash pattern
+is repeated over the entire length of the subpath.  When any
+other value is used, the dash pattern is repeated separately
+on each path segment in the space between the segement's
+two adjacent corner dashes.</p>
+
+<p class="issue">Need to define what happens when corner dashes would overlap.</p>
+
+<div class="figure">
+  <img class="bordered" src="images/painting/dashcorner.svg"
+       alt="Image showing a rectangle at each corner and short dashes in between."/>
+  <p class="caption">A rectangle painted with a dashed stroke and with
+  corner dashes.  The dashing pattern is <span class="prop-value">0,8</span>
+  and the corner dash length is <span class="prop-value">32</span>.</p>
+</div>
+
+<table class="propdef">
+  <tr>
+    <th>Name:</th>
+    <td><dfn id="StrokeDashadjustProperty">stroke-dashadjust</dfn></td>
+  </tr>
+  <tr>
+    <th>Value:</th>
+    <td>none | [stretch | compress] [dashes | gaps]?</td>
+  </tr>
+  <tr>
+    <th>Initial:</th>
+    <td>none</td>
+  </tr>
+  <tr>
+    <th>Applies to:</th>
+    <td><a>shapes</a> and <a>text content elements</a></td>
+  </tr>
+  <tr>
+    <th>Inherited:</th>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <th>Percentages:</th>
+    <td>N/A</td>
+  </tr>
+  <tr>
+    <th>Media:</th>
+    <td>visual</td>
+  </tr>
+  <tr>
+    <th>Computed&#160;value:</th>
+    <td>as specified</td>
+  </tr>
+  <tr>
+    <th><a>Animatable</a>:</th>
+    <td>yes</td>
+  </tr>
+</table>
+
+<p class="note">New in SVG 2.  Added to allow for more visually
+pleasing stroke dash patterns.</p>
+
+<p>The <a>'stroke-dashadjust'</a> property specifies whether and
+how a stroke's dash pattern will be adjusted so that it is repeated
+a whole number of times along an element's subpaths.</p>
+
+<dl>
+  <dt><span class='prop-value'>none</span></dt>
+  <dd>Indicates that no adjustment of the dash pattern takes place.</dd>
+
+  <dt><span class='prop-value'>stretch</span></dt>
+  <dd>Indicates that when the dash pattern does not fit into a subpath
+  a whole number times, the dashes or gaps (or both) will be lengthened
+  so that it does.</dd>
+
+  <dt><span class='prop-value'>compress</span></dt>
+  <dd>Indicates that when the dash pattern does not fit into a subpath
+  a whole number times, the dashes or gaps (or both) will be shortened
+  so that it does.</dd>
+
+  <dt><span class='prop-value'>dashes</span></dt>
+  <dd>Indicates that when a dash pattern is to be stretched or compressed,
+  only the length of the dashes will be adjusted; the gaps will remain
+  as specified.</dd>
+
+  <dt><span class='prop-value'>gaps</span></dt>
+  <dd>Indicates that when a dash pattern is to be stretched or compressed,
+  only the length of the gaps will be adjusted; the dashes will remain
+  as specified.</dd>
+</dl>
+
+<p class="issue">Do we need to be able to choose to stretch or compress?</p>
+
+<p>If neither the <span class='prop-value'>dashes</span> or
+<span class='prop-value'>gaps</span> keyword is given, both the
+dashes and the gaps will be adjusted.</p>
+
+<p>The target length that a dash pattern will be adjusted to depends
+on the value of the <a>'stroke-dashcorner'</a> property:</p>
+
+<ol>
+  <li>If <a>'stroke-dashcorner'</a> is <span class='prop-value'>none</span>,
+  then the dash pattern will be adjusted to fit within the length of
+  the subpath a whole number of times.</li>
+
+  <li>If <a>'stroke-dashcorner'</a> has any other value, including a zero
+  length, then the dash pattern will be adjusted differently for each
+  segment of the subpath such that it fits between the two corner
+  dashes at the ends of the segment a whole number of times.</li>
+</ol>
+
+<p>The adjustment of dash and gap length in a dash pattern is done by
+scaling the lengths by a factor, which is the number closest to 1 that
+will result in the dash pattern fitting in the target length a whole
+number of times.  If <span class='prop-value'>stretch</span> is used,
+the factor is a number between 1 and 2, while if <span class='prop-value'>compress</span>
+is used, the factor is a number between 0 and 1.  If there
+is no appropriate factor that can be chosen – for example if
+<span class='prop-value'>stretch</span> is used but the
+dash pattern is longer than the target length, or if <span class='prop-value'>gaps</span>
+was specified but all of the gaps in the dash pattern are zero – then
+no adjustment is performed.</p>
+
+<p class="issue">Should there be an <span class='prop-value'>auto</span>
+value which means round to the closest number of whole repetitions?</p>
+
+<p class="issue">Does the compression or expansion of the dashes and gaps
+happen after an odd-lengthed dash array is doubled so that it has an even
+number of entries or before? Probably after.</p>
+
+<p class="issue">Do we want to allow control of whether the stroke ends with a
+dash or with a gap? For a closed path, you probably want a gap at the end,
+while for a non-closed path, a dash at the end is probably better. Omit control
+for this, but just do it automatically based on whether the path is closed?</p>
+
+<div class="figure">
+  <img class="bordered" src="images/painting/dashadjust.svg"
+       alt="Image showing three shapes stroked with the same dash pattern, all adjusted to their individual path lengths."/>
+  <p class="caption">The same dash stroke used on three
+  different paths, adjusted to fit a whole number of
+  times on each.</p>
+</div>
+
+<div class="ready-for-wider-review">
 <h3 id="StrokeShape">Computing the shape of the stroke</h3>
 
 <div class="annotation svg2-requirement">
@@ -1138,6 +1356,9 @@
 <a>'path/pathLength'</a> so that dash lengths are in the author's
 path length space.</p>
 
+<p class="issue">This section doesn't handle <a>'stroke-dashcorner'</a>
+and <a>'stroke-dashadjust'</a> yet.</p>
+
 <p>The <dfn id="TermStrokeShape">stroke shape</dfn> of an element is the
 shape that is filled by the <a>'stroke'</a> property.  The following algorithm
 describes what the stroke shape of a <a>'path'</a> or <a>basic shape</a> is,