/*

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

import org.w3c.dom.DOMException;

/**

 * This interface represents an "SVGPath" datatype used to define the path geometry.

 * Corresponds to SVG path specification or the "d" attribute.

 *

 *

 * <p>The native implementations must support the following simplifications or

 * canonicalization of path segments. Any simplifications should be lossless.

 *

 * <ul>

 * <li>Relative commands (c, h, l, m, q, s, t, and v) must be converted to their absolute counterparts·</li>

 * <li>Horizontal and Vertical lines (H, h, V, and v) must be converted to general lines (L and l)·</li>

 * <li>Translate command S to command C·</li>

 * <li>Translate command T to command Q.</li>

 * </ul>

 * </p>

 */

public interface SVGPath

{

    /**

     * Numeric value is ASCII code of the letter 'M'.

     */

    public static final short MOVE_TO = 77;

    /**

     * Numeric value is ASCII code of the letter 'L'.

     */

    public static final short LINE_TO = 76;

    /**

     * Numeric value is ASCII code of the letter 'C'.

     */

    public static final short CURVE_TO = 67;

    /**

     * Numeric value is ASCII code of the letter 'Q'.

     */

    public static final short QUAD_TO = 81;

    /**

     * Numeric value is ASCII code of the letter 'Z'.

     */

    public static final short CLOSE = 90;

    /**

     * Return number of segments in this path.

     *

     * @return the number of segments in this path.

     */

    public int getNumberOfSegments();

    /**

     * Returns segment command by zero-based command index. Returns one of MOVE_TO, LINE_TO, CURVE_TO, QUAD_TO or CLOSE.

     *

     * @param cmdIndex the command index for the segment command to retrieve.

     * @return the segment command for the specified cmdIndex.

     * @throws DOMException with error code INDEX_SIZE_ERR if segment index out of bounds.

     *

     */

    public short getSegment(int cmdIndex)

    throws DOMException;

    /**

     * Returns segment parameter by zero-based command index and zero-based parametr index.

     *

     * @param cmdIndex the command index for the segment parameter to retrieve.

     * @param paramIndex the parameter index for the segment parameter to retrieve.

     * @return the segment parameter for the specified cmdIndex and paramIndex.

     * @throws DOMException with error code INDEX_SIZE_ERR if segment index out of bounds or param index out of bounds for this segment's type.

     */

    public float getSegmentParam(int cmdIndex, int paramIndex)

    throws DOMException;

    /**

     * Appends 'M' (absolute move) segment to the path with the specified coordinates.

     *

     * @param x the x-axis coordinate for the specified point.

     * @param y the y-axis coordinate for the specified point.

     */

    public void moveTo(float x, float y);

    /**

     * Appends 'L' (absolute line) segment to the path with the specified coordinates.

     *

     * @param x the x-axis coordinate of the specified point.

     * @param y the y-axis coordinate of the specified point.

     */

    public void lineTo(float x, float y);

    /**

     * Appends 'Q' (absolute quadratic curve) segment to the path.

     *

     * @param x1 the x-axis coordinate of the first control point.

     * @param y1 the y-axis coordinate of the first control point.

     * @param x2 the x-axis coordinate of the final end point.

     * @param y2 the y-axis coordinate of the final end point.

     *

     */

    public void quadTo(float x1, float y1, float x2, float y2);

    /**

     * Appends 'C' (absolute cubic curve) segment to the path.

     *

     * @param x1 the x-axis coordinate of the first control point.

     * @param y1 the y-axis coordinate of the first control point.

     * @param x2 the x-axis coordinate of the second end point.

     * @param y2 the y-axis coordinate of the second end point.

     * @param x3 the x-axis coordinate of the final end point.

     * @param y3 the y-axis coordinate of the final end point.

     *

     */

    public void curveTo(float x1, float y1, float x2, float y2, float x3, float y3);

    /**

     * Appends 'Z' (close path) segment to the path

     */

    public void close();

}