css-shapes-2/Overview.src.html

﻿<!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN' 'http://www.w3.org/TR/html4/strict.dtd'>
<html lang="en">
<head profile="http://www.w3.org/2006/03/hcard">
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" >
  <title>CSS Shapes Module Level 2</title>
  <!--<script src='http://test.csswg.org/harness/annotate.js#css-shapes_DEV' type='text/javascript' defer></script>-->
  <link rel="stylesheet" type="text/css" href="../shared/style/default.css" >


  <style type="text/css">
    .singleImgExample {
    	display: block;
    	margin: auto;
    }

    .example-table {
    	table-layout: fixed;
    	width: 100%;
    }

    .example-table tr td img {
    	width: 90%;
    }
  </style>

    <link rel="stylesheet" type="text/css"
      href="issues.css">
    <link rel="stylesheet" type="text/css"
      href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
    <link id="st" href="../shared/style/alternate-spec-style.css" rel="stylesheet"
      type="text/css" title="alternate spec style">

</head>
<body>
  <div id="div-head" class="head">
    <!--begin-logo-->
    <p><a href="http://www.w3.org/"><img id="mobile-logo" alt="W3C" height="53" src=
    "http://www.w3.org/2008/site/images/logo-w3c-mobile-lg" width="90"></a>


    <p><a href="http://www.w3.org/"><img id="logo" alt="W3C" height="48" src=
    "http://www.w3.org/Icons/w3c_home" width="72"></a> <!--end-logo--></p>
    <h1 id="css-shapes-module">CSS Shapes Module Level 2</h1>
    <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
    <dl>
      <dt>This version:</dt>
      <dd><a href="[VERSION]">[VERSION]</a></dd>

      <dt>Latest version:</dt>
      <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
      </dd>

      <dt>Editor's Draft:</dt>
      <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
      </dd>

      <dt>Previous version:</dt>
      <dd>None</dd>

      <dt>Editors:</dt>
      <dd class="vcard"><span class="fn">Alan Stearns</span>, <span class="org">Adobe Systems, Inc.</span>, <span class="email">stearns@adobe.com</span></dd>

      <!--<dt>Issues List:</dt>
      <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&amp;product=CSS&amp;component=Shapes&amp;resolution=---&amp;cmdtype=doit">in Bugzilla</a></dd>-->

      <dt>Feedback:</dt>
      <dd><a href="mailto:www-style@w3.org?subject=%5B[css-shapes]%5D%20feedback"
       >www-style@w3.org</a>
       with subject line &ldquo;<kbd>[css-shapes]
       <var>&hellip; message topic &hellip;</var></kbd>&rdquo;
       (<a rel="discussion" href="http://lists.w3.org/Archives/Public/www-style/"
         >archives</a>)

    </dl>
    <!--copyright-->
    <hr title="Separator for header">
  </div>

  <h2 class="no-num no-toc" id="abstract">Abstract</h2>

  <p>This draft contains the features of CSS
    relating to wrapping content around and inside shapes.
    It (implicitly for now) includes and extends
    the functionality of CSS Shapes Level 1 [[CSS-SHAPES]].
    The main points of extension compared to level 1
    include additional ways of defining shapes,
    defining an exclusion area using a shape,
    and restricting an element's content area using a shape.
  </p>

  <h2 class="no-num no-toc" id="status">Status of this document</h2>
  <!--status-->

  <h2 class="no-num no-toc" id="contents">Table of contents</h2>
  <!--toc-->

  <h2 id="intro">Introduction</h2>
  <p><em>This section is not normative.</em></p>

  <p>
    Level 1 of this specification
    defined properties to control
    the geometry of an element's
    <span>float area</span>.
    This level defines how shapes apply to exclusions.
    It also includes a 'shape-inside' property
    for applying a shape
    to an element's content area.
    And finally it defines new ways
    of specifying shapes for all
    of these applications.
  </p>

  <h2 id="terminology">Terminology</h2>

  <dfn>Exclusion area</dfn>

  <p>
    The area used for excluding
    inline flow content
    around an exclusion box.
    The <span>exclusion area</span>
    is equivalent to the
    <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">border box</a>
    for an exclusion box.
    This specification's 'shape-outside' property
    can be used to define arbitrary,
    non-rectangular <span>exclusion areas</span>.
    The 'shape-inside' property also defines
    an <span>exclusion area</span>,
    but in this case it is the area outside the shape
    that inline content avoids.
  </p>

  <p><dfn>Float area</dfn>

  <p>
    The area used for wrapping content
    around a float element.
    By default,
    the float area is
    the float element's
    <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">margin box</a>.
    This specification's 'shape-outside' property
    can be used to define arbitrary,
    non-rectangular float areas.
  </p>

  <dfn>Content area</dfn>
  <p>
    The <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">content area</a>
    is normally used for layout of the inline flow content of a box.
  </p>

  <div class="issue-marker" data-bug_id="15089" data-bug_status="NEW">
    <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15089">Issue-15089</a>
    <div class="issue-details">
      <p class="short-desc">shrink-to-fit circle / shape</p>
    </div>
  </div>

  <h2 id="shapes">Shapes</h2>

  <p>
    Shapes define arbitrary geometric contours
    around which inline content flows.
    The shape-outside property defines
    the <span>float area</span> for a float,
    and the exclusion area for an exclusion.
  </p>

  <h3 id="basic-shapes-from-svg-syntax">Basic Shapes</h3>
  <p>Add the final
    <a href="http://www.w3.org/TR/css-shapes/#basic-shapes-from-svg-syntax">level 1</a>
    section with a possible addition of path() and a rejiggered rectangle().
  </p>

  <dl>
    <dt><dfn>rectangle()</dfn> =
      rectangle( <<shape-arg>>{4} [ round <<'border-radius'>> ]? )
    </dt>
    <dd>
      <ul>
        <li>
          The first four arguments represent
          <strong>x, y, width</strong> and
          <strong>height</strong>
          of the rectangle.
          Negative values for width and height are invalid.
        </li>
        <li>
          The optional <<'border-radius'>> argument(s)
          define rounded corners for the rectangle
          using the 'border-radius' shorthand syntax.
        </li>
      </ul>
    </dd>
  </dl>

<div class="issue-marker wrapper">
    <div class="issue-marker" data-bug_id="16448" data-bug_status="ASSIGNED">
      <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16448">Issue-16448</a>
      <div class="issue-details">
          <p class="short-desc">Should we revisit the decision to not allow SVG path syntax in the shape-inside, shape-outside properties</p>
      </div>
    </div>
</div>

  <h3 id='referencing-svg-shapes'>Referencing SVG shapes</h4>

  <p>An SVG shape can be referenced using the <code>url()</code> syntax.
    The shape can be any
    of the <a href="http://www.w3.org/TR/SVG/shapes.html">SVG basic shapes</a>
    or a <a href="http://www.w3.org/TR/SVG/paths.html">path element</a>.
  </p>

  <div class="example">
    <div style="float:right">
      <img alt="results of referencing SVG shapes" src="images/svg-shape-reference.png">
    </div>
    <code class="html"><pre>
&lt;style&gt;
div {
    height: 400px;
    width: 400px;
}
.in-a-circle {
    shape-outside: url(#circle_shape);
}

.in-a-path {
    shape-outside: url(#path-shape);
}

&lt;/style&gt;

&lt;svg ...&gt;
&lt;circle id="circle_shape" cx="50%" cy="50%" r="50%" /&gt;
&lt;path id="path-shape" d="M 100 100 L 300 100 L 200 300 z" /&gt;
&lt;/svg&gt;

&lt;div class="around-a-circle"&gt;...&lt;/div&gt;
&lt;div class="around-a-path"&gt;...&lt;/div&gt;
</pre></code>
  </div>
  <!-- End section "Shapes from SVG Syntax -->

  <h3 id="shapes-from-image">Shapes from Image</h3>
    <p>Add the final
      <a href="http://www.w3.org/TR/css-shapes/#shapes-from-image">level 1</a>
      section.
  <!-- End section "Shapes from image" -->

  <p class="issue">
    One <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16716">suggestion</a>
    is to define a shape based on an element's rendered content. This could have security implications.
  </p>

  <p class="issue">
    Another <a href="http://lists.w3.org/Archives/Public/www-style/2013Jun/0282.html">suggestion</a>
    is to use an element's border box as a shape.
  </p>

  <h3 id="declaring-shapes">Declaring Shapes</h3>
    <p>
      A shape can be declared with
      the 'shape-outside' property,
      with possible modifications
      from the 'shape-margin' property.
      The shape defined by
      the 'shape-outside'
      and 'shape-margin' properties
      changes the geometry
      of a float element's
      <span>float area</span>
      and an exclusion element's
      <span>exclusion area</span>.
    </p>
    <p>
      A shape can be declared with
      the 'shape-inside' property,
      with possible modifications
      from the 'shape-padding' property.
      The shape defined by
      the 'shape-inside'
      and 'shape-padding' properties
      defines an <span>exclusion area</span>
      that contributes
      to the element's <span>wrapping context</span>.
      The 'shape-inside' property applies
      to all block-level elements.
    </p>

  <div class="example">
    <p>
      The red box illustrates
      an exclusion element's content box,
      which is unmodified and subject
      to normal CSS positioning
      (here absolute positioning).
    </p>
    <pre><code class="html">
&lt;style type="text/css"&gt;
  .exclusion  {
      wrap-flow: both;
      position: absolute;
      top: 25%;
      left: 25%;
      width: 50%;
      height: 50%;
      shape-outside: circle(50%, 50%, 50%);
      border: 1px solid red;
  }
&lt;/style&gt;

&lt;div style=”position: relative;”&gt;
  &lt;div class=”exclusion”&gt;&lt;/div&gt;
  Lorem ipsum dolor sit amet...
&lt;/div&gt;
</code></pre>
    <img class="singleImgExample" src="images/shapes_CSS2.1_MBP.png" alt="Example rendering of circle shape and box model."  style="max-width:40%"/>
  </div>

  <h4 id="shape-outside-property">The 'shape-outside' Property</h4>
    <p>Add the final
      <a href="http://www.w3.org/TR/css-shapes/#shape-outside-property">level 1</a>
      section with the change that
      shape-outside applies
      to block-level elements
      and has an effect
      if the element
      is an exclusion.
    </p>
  <!-- End section "The shape-outside Property" -->

  <h4 id="shape-inside-property">The 'shape-inside' Property</h4>
    <p>
      The 'shape-inside' property adds
      one or more exclusion areas
      to the element's wrapping context.
      This modifies the normal rectangular shape
      of the content area
      to a possibly non-rectangular wrapping area.
      The exclusion areas
      are defined by subtracting the shape
      from the element's content area.
      Any part of the shape outside
      the element's content area
      has no effect.
    </p>

    <table class="propdef">
      <tr>
        <th>Name:</th>
        <td><dfn title="shape-inside">shape-inside</dfn></td>
      </tr>
      <tr>
        <th>Value:</th>
        <td><var>outside-shape</var> | <var>auto</var> | <var>&lt;basic-shape&gt;</var> | <var>&lt;uri&gt;</var></td>
      </tr>
      <tr>
        <th>Initial:</th>
        <td>auto</td>
      </tr>
      <tr>
        <th>Applies to:</th>
        <td>block-level elements</td>
      </tr>
      <tr>
        <th>Inherited:</th>
        <td>no</td>
      </tr>
      <tr>
        <th>Percentages:</th>
        <td>N/A</td>
      </tr>
      <tr>
        <th>Media:</th>
        <td>visual</td>
      </tr>
      <tr>
        <th>Computed&nbsp;value:</th>
        <td>computed lengths for &lt;basic-shape&gt;, the absolute URI for &lt;uri&gt;, otherwise as specified</td>
      </tr>
    </table>

  <p>The values of this property have the following meanings:</p>
  <dl>
    <dt><dfn>auto</dfn></dt>
    <dd>
      The shape is computed based on the content box of the element.
    </dd>
  </dl>
  <dl>
    <dt><dfn>&lt;basic-shape&gt;</dfn></dt>
    <dd>
      The shape is computed based
      on the values of one of
      'rectangle', 'inset-rectangle',
      'circle', 'ellipse' or 'polygon'.
    </dd>
  </dl>
  <dl>
    <dt><dfn>&lt;uri&gt;</dfn></dt>
    <dd>
      If the &lt;uri&gt; references an SVG shape element,
      that element defines the shape.
      Otherwise, if the &lt;uri&gt; references an image,
      the shape is extracted and computed
      based on the alpha channel
      of the specified image.

      If the &lt;uri&gt; does not reference
      an SVG shape element or an image,
      the effect is as if the value 'auto' had been specified.
    </dd>
  </dl>

  <p>The 'shape-inside' property applies to floats.</p>

  <p>The 'shape-inside' property may not apply on some elements such as elements with a
      computed 'display' value of 'table'.</p>

  <div class='figure'>
      <img alt="Content flowing with and without a shape-inside" src="images/shape-inside-content.png"/>
      <p class="caption">Effect of shape-inside on inline content.</p>
  </div>

  <p>Overflow content avoids
      the exclusion area(s) added
      by 'shape-inside' and 'shape-padding'
      (as well as any other exclusion areas
      in the element's wrapping context).</p>

  <div class='figure'>
          <img alt="Overflow interacting with rounded rect" style="display:inline-block;vertical-align:top" src="images/rounded-rect-overflow.png"/>
          <img alt="Overflow interacting with ellipse" style="display:inline-block;vertical-align:top" src="images/ellipse-overflow.png"/>
      <p class="caption">Overflow interacting with exclusion areas defined by 'shape-inside' and 'shape-padding'.</p>
  </div>

  <p>
    When a shape-inside has a definite size
    (no percentages used in the shape's definition)
    an auto-sized element should use the shape
    as a constraint in determining its maximum size.
  </p>

  <!-- End section "The shape-inside property" -->

  <h4 id="shape-image-threshold-property">The 'shape-image-threshold' Property</h4>
    <p>Add the final
      <a href="http://www.w3.org/TR/css-shapes/#shape-image-threshold-property">level 1</a>
      section with the change that
      it applies to both <span>shape-inside</span>
      and <span>shape-outside</span>.
    </p>
  <!-- End section "The shape-image-threshold property" -->

  <h4 id="shape-image-source-type-property">The 'shape-image-source-type' Property</h4>
    <p>
      Should we add an alpha/luminance switch to determine which values we use from the shape-image source?
    </p>
  <!-- End section "The shape-image-source-type-property" -->

  <h4 id="shape-margin-property">The 'shape-margin' property</h4>
    <p>Add the final
      <a href="http://www.w3.org/TR/css-shapes/#shape-margin-property">level 1</a>
      section with the change that it applies to exclusions.
    </p>
  <!-- End secion "shape-margin property" -->

  <h4 id="shape-padding-property">The 'shape-padding' Property</h4>
  <p>
      The 'shape-padding' property adds padding to a shape-inside.
      This defines a new shape where every point
      is the specified distance from the shape-inside.
      This property takes on positive values only.
  </p>
  <table class="propdef">
    <tr>
      <th>Name:</th>
      <td><dfn title="shape-padding">shape-padding</dfn></td>
    </tr>
    <tr>
      <th>Value:</th>
      <td><var>&lt;length&gt;</var></td>
    </tr>
    <tr>
      <th>Initial:</th>
      <td>0</td>
    </tr>
    <tr>
      <th>Applies to:</th>
      <td>block-level elements</td>
    </tr>
    <tr>
      <th>Inherited:</th>
      <td>no</td>
    </tr>
    <tr>
      <th>Percentages:</th>
      <td>N/A</td>
    </tr>
    <tr>
      <th>Media:</th>
      <td>visual</td>
    </tr>
    <tr>
      <th>Computed&nbsp;value:</th>
      <td>the absolute length</td>
    </tr>
  </table>

  <div class="example">
    <p>A 'shape-padding' creating an offset
      from a circlular shape-inside.
      The light blue rectangles represent
      inline content affected
      by the shape created
      by the padding.</p>
    <img src="images/shape-padding.png"
      alt="Example of a shape-padding offset"/>
  </div>
  <!-- End section "shape-padding property" -->

  <p class="note">Note that the 'shape-padding' property
    only affects layout of content
    inside the element it applies to
    while the 'shape-margin' property
    only affects layout of content
    outside the element.
  </p>
  <!-- End section "Declaring Shapes" -->
  <!-- End section "Shapes" -->

  <h2 id="conformance">Conformance</h2>
  <!--conformance-->

  <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
    <!--<p>This specification is made possible by input from

        and the CSS Working Group members.
    </p>-->
  <h2 class="no-num" id="references">References</h2>
  <h3 class="no-num" id="normative-references">Normative references</h3>
  <!--normative-->
  <h3 class="no-num" id="other-references">Other references</h3>
  <!--informative-->
  <h2 class="no-num" id="index">Index</h2>
  <!--index-->
  <h2 class="no-num" id="property-index">Property index</h2>
  <!-- properties -->

      <!-- template markup for issues pulled from Bugzilla -->
      <!-- issue template and script need a new API to access bugzilla
      <script type="text/template" id="issue-template">
  <div class="issue-marker" data-bug_id="{{bug_id}}" data-bug_status="{{bug_status}}">
      <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id={{bug_id}}">Issue-{{bug_id}}</a>
      <div class="issue-details">
          <p class="short-desc">{{short_desc}}</p>
      </div>
  </div>
      </script>

      <script type="text/javascript" src="../shared/scripts/BugzillaTrackerUtil.js"></script>
      <script type="text/javascript" src="../shared/scripts/BugzillaTracker.js"></script>
      <script type="text/javascript">
          checkSpecificationIssues('CSS', 'Shapes');
      </script>
      -->
  <h2 class="no-num" id="change-log">Change Log</h2>

  </body>
</html>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-declaration:"~/SGML/HTML4.decl"
sgml-default-doctype-name:"html"
sgml-minimize-attributes:t
sgml-nofill-elements:("pre" "style" "br")
sgml-live-element-indicator:t
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-always-quote-attributes:t
sgml-indent-step:nil
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->