/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/
package org.w3c.dom.svg;
/**
* This interface represents an SVGLocatableElement. It is implemented by all drawable SVG elements
* in the document tree. Drawable elements are: <rect>, <circle>, <ellipse>,
* <line>, <path> <use> <image> <text>, <svg>, <a>,
* and <g>. <b>Note</b> that animations will have an effect on the values of bounding box.
*
* <br>
* <br>
* <br>
*The following example further clarify the behavior of the getBBox()
*method. The example have a short explanation, an SVG fragment and are
*followed by a set of bounding box values which have the following
*format:<br>
*<tt><br>
*[elementId] : {x, y, width, height} | {null}</tt><br>
*<br>
*where x, y, width and height define the values of the SVGRect object's
*returned from a getBBox call on the element with the specified id.
*There are a few cases where the bounding box may be null (see example
*6).<br>
*<br>
*<h3>Example #1: Simple groups and bounds</h3>
*<br>
*This first example shows the values returned by the getBBox method for
*various simple basic shapes and groups. In particular, it shows that
*the transform, on an element, does not change the value of its user
*space bounding box.<br>
*<br>
*<tt><g id="group1" transform="translate(10, 20)" fill="red" >
*<br>
* <rect id="rect1" transform="scale(2)" x="10" y="10" width="50"
*height="50"/>
*<br>
* <rect id="rect2" x="10" y="10" width="100" height="100"/>
*<br>
* <g id="group2" transform="translate(10, 20)" >
*<br>
* <rect id="rect3" x="0" y="10" width="150" height="50"/>
*<br>
* <circle id="circle1" cx="20" cy="20" r="100" />
*<br>
* </g>
*<br>
*</g>
*<br>
*</tt><br>
*<tt>[group1] : {-70.0, -60.0, 230.0, 200.0}
*<br>
*[rect1] : {10.0, 10.0, 50.0, 50.0}
*<br>
*[rect2] : {10.0, 10.0, 100.0, 100.0}
*<br>
*[group2] : {-80.0, -80.0, 230.0, 200.0}
*<br>
*[rect3] : {0.0, 10.0, 150.0, 50.0}
*<br>
*[circle1] : {-80.0, -80.0, 200.0, 200.0}
*</tt><br>
*<br>
*<h3>Example #2: Bounding box on zero width or height rectangle<br>
*</h3>
*This example illustrates that the bounding box on elements is based on
*the element's geometry coordinates. For example, the bounding box on a
*zero-width rectangle is defined (see below), even though the rectangle
*is not rendered.<br>
*<pre><tt><g id="group1" transform="translate(10, 20)" fill="red" ></tt></pre>
*<pre><tt> </tt><rect id="rect2" x="10" y="10" width="400" height="0"/></pre>
*<pre wrap=""><tt> <g id="group2" transform="translate(10, 20)" >
* <rect id="rect3" x="0" y="10" width="150" height="50"/>
* </g></tt><tt>
*</g>
*</tt></pre>
*<pre><tt>[group1] : {10.0, 10.0, 400.0, 70.0}
*</tt>[rect2] : {10.0, 10.0, 400.0, 0.0}<tt>
*</tt>[group2] : {0.0, 10.0, 150.0, 50.0}<tt>
*[rect3] : {0.0, 10.0, 150.0, 50.0}</tt>
*</pre>
*<h3>Example #3: Bounding Box on zero radius ellipses.</h3>
*This is another example of how bounding boxes are based on the
*element's geometry. Here, the bounding box of an ellipse with a zero
*x-axis radius is still defined, even though the ellipse is not rendered.<br>
*<pre wrap=""><svg id="mySVG" width="10" height="20">
*<g id="group1" transform="translate(10, 20)" fill="red" >
* <rect id="rect1" x="10" y="10" width="100" height="100"/>
* <ellipse id="ellipse1" cx="20" cy="20" rx="0" ry="70" />
*</g></pre>
*<tt>[mySVG] : {20.0, -30.0, 100.0, 160.0}
*<br>
*[group1] : {10.0, -50.0, 100.0, 160.0}
*<br>
*[rect1] : {10.0, 10.0, 100.0, 100.0}
*<br>
*[ellipse1] : {20.0, -50.0, 0.0, 140.0}
*</tt><br>
*<h3>Example #4: Viewports do not clip bounding boxes</h3>
*This example shows that no matter what the viewport is on the root SVG
*element, the bounding boxes, based on the geometry, are still defined.
*Here, even though the root svg has a zero width, the bounding boxes for
*the root itself and its children is precisely defined.<br>
*<pre wrap=""><svg id="mySVG" width="0" height="50">
* <g id="group1" transform="translate(10, 20)" fill="red" >
* <rect id="rect1" x="10" y="10" width="50" height="50"/>
* <g id="group2" transform="translate(10, 20)" >
* <rect id="rect2" x="0" y="10" width="150" height="0"/>
* <circle id="circle1" cx="20" cy="20" r="500" />
* </g>
* </g>
*</svg>
*</pre>
*<tt>[mySVG] : {-460.0, -440.0, 1000.0, 1000.0}
*<br>
*[group1] : {-470.0, -460.0, 1000.0, 1000.0}
*<br>
*[rect1] : {10.0, 10.0, 50.0, 50.0}
*<br>
*[group2] : {-480.0, -480.0, 1000.0, 1000.0}
*<br>
*[rect2] : {0.0, 10.0, 150.0, 0.0}
*<br>
*[circle1] : {-480.0, -480.0, 1000.0, 1000.0}
*</tt><br>
*<h3>Example #5: getBBox on <use></h3>
*This example shows that the bounding box for a <use> element
*accounts for the x and y attributes defined on the element, just like
*the x and y attributes impact the bounding box computation on a
*<rect> or on an <image> element.<br>
*<br>
*<tt><svg>
*<br>
* <defs>
*<br>
* <rect id="myRect" x="0" y="0" width="60" height="40" />
*<br>
* </defs>
*<br>
* <use id="myUse" xlink:href="#myRect" x="-30" y="-20" />
*<br>
*</svg>
*<br>
*</tt>
*<br>
*<tt>[myRect] : {0.0, 0.0, 60.0, 40.0}
*<br>
*[myUse] : {-30.0, -20.0, 60.0, 40.0}
*</tt><br>
*<h3>Example #6: Empty group</h3>
*This example shows that the bounding box for an empty group is null. By
*the same token, the bounding box of a <path> with an empty
*SVGPath (i.e., one with no path commands, which may happen after
*creating a new <path> element with a Document.createElementNS
*call) is also null.<br>
*<br>
*<tt><g id="emptyG" />
*<br>
*<br>
*[emptyG] : {null}
*</tt><br>
*<br>
*<h3>Example #7: Impact of display='none' and visibility='hidden'<br>
*</h3>
*This example shows how the bounding box of children with display='none'
*are not accounted for in the computation of their parent's bounding
*box. This reflects the definition of the display property and its
*impact on rendering and bounding box computation. The example also
*shows that elements with a 'hidden' visibility still contribute to
*their parent's bounding box computation.<br>
*<br>
*<tt><g id="g1"> <br>
* <g id="g1.1.display.none" display="none"> <br>
* <rect id="rect1" x="10" y="10" width="40" height="40"/><br>
* <g/>
*<br>
* <rect id="rect2.visibility.hidden" visibility="hidden" <br>
* x="30" y="60" width="10" height="20"/>
*<br>
*</g></tt><br>
*<br>
*<tt>[g1] : {30.0, 60.0, 10.0, 20.0} <br>
*[g1.1.display.none] : {10.0, 10.0, 40.0, 40.0}<br>
*[rect1] : {10.0, 10.0, 40.0, 40.0}<br>
*[rec2.visibility.hidden] : {30.0, 60.0, 10.0, 20.0}</tt><br>
*<h3>Example #8: Concatenating bounding boxes in the container's user
*space.<br>
*</h3>
*This example shows how the concatenation and computation of bounding
*boxes for container element happens in the container's user space.<br>
*<br>
*<tt><g id="g1"><br>
* <line id="line1" x2="100" y2="100" transform="rotate(-45)"/><br>
*</g></tt><br>
*<tt><br>
*[g1] : {0.0, 0.0, 141.42136, 0}<br>
*[line1] : {0.0, 0.0, 100.0, 100.0}</tt><br>
*<h3>Example #9: No influence of stroke-width.</h3>
*This example illustrates that stroking has no impact on the computation
*of bounding boxes.<br>
*<tt><br>
*<g><br>
* <line id="thickLine" stroke-width="10" x2="100" y2="0" /><br>
*</g></tt><br>
*<br>
*[thickLine] : {0.0, 0.0, 100.0, 0.0}<br>
*<br>
*<h3>Example #10: No influence of viewBox.</h3>
*This example illustrates that viewBox has no impact on the computation
*of bounding boxes.<br>
*<tt><br>
*<svg id="rootSvg" width="500" height="300" viewBox="0 0 200 100" ><br>
* <rect x="-100" y="-200" width="500" height="100" /><br>
*</svg></tt><br>
*<br>
*[rootSVG] : {-100, -200, 500, 100}<br>
*
*
*/
public interface SVGLocatableElement extends SVGElement
{
/**
* <p>
* Returns the tight bounding box in current user coordinate space. Tight bounding box is the smallest
* possible rectangle that includes the geometry of all contained graphics elements excluding stroke.
* The calculation is done in the user coordinate space of the element. When bounding box
* is calculated elements with display property (trait) set to none are ignored. Exact rules for the bounding
* box calculation are given in the <a href="http://www.w3.org/TR/SVG/coords.html#ObjectBoundingBox">SVG spec</a>.
* </p>
*
* @return the tight bounding box in current user coordinate space.
*/
public SVGRect getBBox();
/**
* <p>
* Returns the transformation matrix from current user units (i.e., after application of the transform attribute, if any)
* to the parent user agent's notion of a "pixel". For display devices, ideally this represents a physical screen pixel.
* For other devices or environments where physical pixel sizes are not known, then an algorithm similar to the CSS2
* definition of a "pixel" can be used instead. Note that <code>null</code> is returned if this element is not hooked into the
* document tree.
* </p>
*
* @return the transformation matrix from current user units to the parent user agent's notion of a "pixel".
*/
public SVGMatrix getScreenCTM();
/**
* <p>
* Returns the tight bounding box in screen coordinate space. Tight bounding box is the smallest
* possible rectangle that includes the geometry of all contained graphics elements excluding stroke.
* The box coordinates are in the screen coordinate space, which is connected to the current user
* coordinate space by the matrix returned by {@link org.w3c.dom.svg.SVGLocatableElement#getScreenCTM getScreenCTM} method.
* Note that <code>null</code> is returned if this element is not hooked into the
* document tree.
* </p>
*
* @return the tight bounding box in screen coordinate space.
*/
public SVGRect getScreenBBox();
}