001/**********************************************
002 * Copyright (C) 2010 Lukas Laag
003 * This file is part of lib-gwt-svg.
004 * 
005 * libgwtsvg is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Lesser General Public License as published by
007 * the Free Software Foundation, either version 3 of the License, or
008 * (at your option) any later version.
009 * 
010 * libgwtsvg is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public License
016 * along with libgwtsvg.  If not, see http://www.gnu.org/licenses/
017 **********************************************/
018/*
019 * Copyright (c) 2004 World Wide Web Consortium,
020 *
021 * (Massachusetts Institute of Technology, European Research Consortium for
022 * Informatics and Mathematics, Keio University). All Rights Reserved. This
023 * work is distributed under the W3C(r) Software License [1] in the hope that
024 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
025 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
026 *
027 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
028 */
029
030package org.vectomatic.dom.svg.itf;
031
032import org.vectomatic.dom.svg.OMSVGElement;
033import org.vectomatic.dom.svg.OMSVGMatrix;
034import org.vectomatic.dom.svg.OMSVGRect;
035
036import com.google.gwt.core.client.JavaScriptException;
037
038  /**
039   * Interface {@link org.vectomatic.dom.svg.itf.ISVGLocatable} is for all elements
040   * which either have a <code>transform</code> attribute or don't have a <code>transform</code>
041   * attribute but whose content can have a bounding box in current user space.
042   */
043public interface ISVGLocatable {
044  /**
045   * The element which established the current viewport. Often, the nearest
046   * ancestor <a href='http://www.w3.org/TR/SVG11/struct.html#SVGElement' title='svg
047   * element specification'>svg</a> element. Null if the current element is
048   * the outermost <a href='http://www.w3.org/TR/SVG11/struct.html#SVGElement'
049   * title='svg element specification'>svg</a> element.
050   */
051  public OMSVGElement getNearestViewportElement();
052  /**
053   * The farthest ancestor <a href='http://www.w3.org/TR/SVG11/struct.html#SVGElement'
054   * title='svg element specification'>svg</a> element. Null if the current
055   * element is the outermost <a href='http://www.w3.org/TR/SVG11/struct.html#SVGElement'
056   * title='svg element specification'>svg</a> element.
057   */
058  public OMSVGElement getFarthestViewportElement();
059  /**
060   * Returns the tight bounding box in current user space (i.e., after application
061   * of the <code>transform</code> attribute, if any) on the geometry of all
062   * contained graphics elements, exclusive of stroking, clipping, masking and
063   * filter effects). Note that getBBox must return the actual bounding box
064   * at the time the method was called, even in case the element has not yet
065   * been rendered.
066   * @return An {@link org.vectomatic.dom.svg.OMSVGRect} object that defines
067   * the bounding box.
068   */
069  public OMSVGRect getBBox();
070  /**
071   * Returns the transformation matrix from current user units (i.e., after
072   * application of the <code>transform</code> attribute, if any) to the viewport
073   * coordinate system for the {@link org.vectomatic.dom.svg.itf.ISVGLocatable#getNearestViewportElement()}.
074   * @return An {@link org.vectomatic.dom.svg.OMSVGMatrix} object that defines
075   * the CTM.
076   */
077  public OMSVGMatrix getCTM();
078  /**
079   * Returns the transformation matrix from current user units (i.e., after
080   * application of the <code>transform</code> attribute, if any) to the parent
081   * user agent's notice of a "pixel". For display devices, ideally this represents
082   * a physical screen pixel. For other devices or environments where physical
083   * pixel sizes are not known, then an algorithm similar to the CSS2 definition
084   * of a "pixel" can be used instead.  Note that null is returned if this element
085   * is not hooked into the document tree. This method would have been more
086   * aptly named as <code>getClientCTM</code>, but the name <code>getScreenCTM</code>
087   * is kept for historical reasons.
088   * @return An {@link org.vectomatic.dom.svg.OMSVGMatrix} object that defines
089   * the given   transformation matrix.
090   */
091  public OMSVGMatrix getScreenCTM();
092  /**
093   * Returns the transformation matrix from the user coordinate system on the
094   * current element (after application of the <code>transform</code> attribute,
095   * if any) to the user coordinate system on parameter <var>element</var> (after
096   * application of its <code>transform</code> attribute, if any).
097   * @param element The target element.
098   * @return An {@link org.vectomatic.dom.svg.OMSVGMatrix} object that defines
099   * the transformation.
100   * @throws SVGException(SVG_MATRIX_NOT_INVERTABLE) Raised if the currently
101   * defined transformation matrices make it impossible to compute the   given
102   * matrix (e.g., because one of the transformations is singular).
103   */
104  public OMSVGMatrix getTransformToElement(OMSVGElement element) throws JavaScriptException;
105}