org.w3c.dom.svg
Interface SVGLocatableElement

All Superinterfaces:

Element, EventTarget, Node, SVGElement

All Known Subinterfaces:

SVGSVGElement

public interface SVGLocatableElement
extends SVGElement

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>. Note that animations will have an effect on the values of bounding box.


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:

[elementId] : {x, y, width, height} | {null}

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).

Example #1: Simple groups and bounds

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.

<g id="group1" transform="translate(10, 20)" fill="red" >
<rect id="rect1" transform="scale(2)" x="10" y="10" width="50" height="50"/>
<rect id="rect2" x="10" y="10" width="100" height="100"/>
<g id="group2" transform="translate(10, 20)" >
<rect id="rect3" x="0" y="10" width="150" height="50"/>
<circle id="circle1" cx="20" cy="20" r="100" />
</g>
</g>

[group1] : {-70.0, -60.0, 230.0, 200.0}
[rect1] : {10.0, 10.0, 50.0, 50.0}
[rect2] : {10.0, 10.0, 100.0, 100.0}
[group2] : {-80.0, -80.0, 230.0, 200.0}
[rect3] : {0.0, 10.0, 150.0, 50.0}
[circle1] : {-80.0, -80.0, 200.0, 200.0}

Example #2: Bounding box on zero width or height rectangle

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.

<g id="group1" transform="translate(10, 20)" fill="red" >

   <rect id="rect2" x="10" y="10" width="400" height="0"/>

   <g id="group2" transform="translate(10, 20)" >
      <rect id="rect3" x="0" y="10" width="150" height="50"/>
   </g>
</g>

[group1] : {10.0, 10.0, 400.0, 70.0}
[rect2] : {10.0, 10.0, 400.0, 0.0}
[group2] : {0.0, 10.0, 150.0, 50.0}
[rect3] : {0.0, 10.0, 150.0, 50.0}

Example #3: Bounding Box on zero radius ellipses.

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.

<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>

[mySVG] : {20.0, -30.0, 100.0, 160.0}
[group1] : {10.0, -50.0, 100.0, 160.0}
[rect1] : {10.0, 10.0, 100.0, 100.0}
[ellipse1] : {20.0, -50.0, 0.0, 140.0}

Example #4: Viewports do not clip bounding boxes

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.

<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>

[mySVG] : {-460.0, -440.0, 1000.0, 1000.0}
[group1] : {-470.0, -460.0, 1000.0, 1000.0}
[rect1] : {10.0, 10.0, 50.0, 50.0}
[group2] : {-480.0, -480.0, 1000.0, 1000.0}
[rect2] : {0.0, 10.0, 150.0, 0.0}
[circle1] : {-480.0, -480.0, 1000.0, 1000.0}

Example #5: getBBox on <use>

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.

<svg>
<defs>
<rect id="myRect" x="0" y="0" width="60" height="40" />
</defs>
<use id="myUse" xlink:href="#myRect" x="-30" y="-20" />
</svg>

[myRect] : {0.0, 0.0, 60.0, 40.0}
[myUse] : {-30.0, -20.0, 60.0, 40.0}

Example #6: Empty group

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.

<g id="emptyG" />

[emptyG] : {null}

Example #7: Impact of display='none' and visibility='hidden'

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.

<g id="g1">
<g id="g1.1.display.none" display="none">
<rect id="rect1" x="10" y="10" width="40" height="40"/>
<g/>
<rect id="rect2.visibility.hidden" visibility="hidden"
x="30" y="60" width="10" height="20"/>
</g>

[g1] : {30.0, 60.0, 10.0, 20.0}
[g1.1.display.none] : {10.0, 10.0, 40.0, 40.0}
[rect1] : {10.0, 10.0, 40.0, 40.0}
[rec2.visibility.hidden] : {30.0, 60.0, 10.0, 20.0}

Example #8: Concatenating bounding boxes in the container's user space.

This example shows how the concatenation and computation of bounding boxes for container element happens in the container's user space.

<g id="g1">
<line id="line1" x2="100" y2="100" transform="rotate(-45)"/>
</g>

[g1] : {0.0, 0.0, 141.42136, 0}
[line1] : {0.0, 0.0, 100.0, 100.0}

Example #9: No influence of stroke-width.

This example illustrates that stroking has no impact on the computation of bounding boxes.

<g>
<line id="thickLine" stroke-width="10" x2="100" y2="0" />
</g>

[thickLine] : {0.0, 0.0, 100.0, 0.0}

Example #10: No influence of viewBox.

This example illustrates that viewBox has no impact on the computation of bounding boxes.

<svg id="rootSvg" width="500" height="300" viewBox="0 0 200 100" >
<rect x="-100" y="-200" width="500" height="100" />
</svg>

[rootSVG] : {-100, -200, 500, 100}

Method Summary

SVGRect	getBBox() Returns the tight bounding box in current user coordinate space.
SVGRect	getScreenBBox() Returns the tight bounding box in screen coordinate space.
SVGMatrix	getScreenCTM() 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".

Methods inherited from interface org.w3c.dom.svg.SVGElement

getFirstElementChild, getFloatTrait, getId, getMatrixTrait, getNextElementSibling, getPathTrait, getRectTrait, getRGBColorTrait, getTrait, getTraitNS, setFloatTrait, setId, setMatrixTrait, setPathTrait, setRectTrait, setRGBColorTrait, setTrait, setTraitNS

Methods inherited from interface org.w3c.dom.Node

appendChild, getLocalName, getNamespaceURI, getParentNode, insertBefore, removeChild

Methods inherited from interface org.w3c.dom.events.EventTarget

addEventListener, removeEventListener

Method Detail

getBBox

SVGRect getBBox()

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 SVG spec.

Returns:

the tight bounding box in current user coordinate space. The returned object is a copy of the current bounding box value and will not change if the corresponding bounding box changes.

getScreenCTM

SVGMatrix getScreenCTM()

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 null is returned if this element is not hooked into the document tree.

Returns:

the transformation matrix from current user units to the parent user agent's notion of a "pixel". The returned object is a copy of the current screen CTM value and will not change if the corresponding screen CTM changes.

getScreenBBox

SVGRect getScreenBBox()

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 getScreenCTM method. Note that null is returned if this element is not hooked into the document tree.

Returns:

the tight bounding box in screen coordinate space. The returned object is a copy of the current screen bounding box value and will not change if the corresponding screen bounding box changes.