001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.svg;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import org.apiguardian.api.API;
023import org.tquadrat.foundation.annotation.ClassVersion;
024import org.tquadrat.foundation.svg.internal.SVGTSpanImpl;
025import org.tquadrat.foundation.svg.type.SVGNumber;
026import org.tquadrat.foundation.svg.type.SVGNumber.SVGDegree;
027import org.tquadrat.foundation.xml.builder.XMLElement;
028
029/**
030 *  The definition of the SVG {@code <tspan>} element.
031 *
032 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
033 *  @version $Id: SVGTSpan.java 1074 2023-10-02 12:05:06Z tquadrat $
034 *  @since 0.0.5
035 *
036 *  @UMLGraph.link
037 */
038@ClassVersion( sourceVersion = "$Id: SVGTSpan.java 1074 2023-10-02 12:05:06Z tquadrat $" )
039@API( status = STABLE, since = "0.0.5" )
040public sealed interface SVGTSpan extends SVGElementWithChildren, AllowsConditionalProcessingAttributes, AllowsGraphicalEventAttributes, AllowsPresentationAttributes, AllowsStyleAttributes
041    permits SVGElementAdapter, SVGTSpanImpl
042{
043        /*---------*\
044    ====** Methods **==========================================================
045        \*---------*/
046    /**
047     *  Adds a {@code CDATA} element to this {@code <tspan>} element.
048     *
049     *  @param  text    The text.
050     *  @return This instance.
051     */
052    public XMLElement addCDATA( final CharSequence text );
053
054    /**
055     *  Adds text to this {@code <tspan>} element. Special characters will be
056     *  escaped.
057     *
058     *  @param  text    The text.
059     *  @return This instance.
060     *  @throws IllegalArgumentException    No text allowed for this element.
061     */
062    public XMLElement addText( final CharSequence text );
063
064    /**
065     *  Sets a list of lengths which move the characters relative to the
066     *  absolute position of the last glyph drawn. The n<sup>th</sup> length is
067     *  given to n<sup>th</sup> character in the text. If there are additional
068     *  characters after the positions run out, the last length is applied to
069     *  them.
070     *
071     *  @param  values  The lengths.
072     */
073    public void setDx( @SuppressWarnings( "UseOfConcreteClass" ) final SVGNumber... values );
074
075    /**
076     *  Sets a list of heights which move the characters relative to the
077     *  absolute position of the last glyph drawn. The n<sup>th</sup> height is
078     *  given to n<sup>th</sup> character in the text. If there are additional
079     *  characters after the positions run out, the last height is applied to
080     *  them.
081     *
082     *  @param  values  The heights.
083     */
084    public void setDy( @SuppressWarnings( "UseOfConcreteClass" ) final SVGNumber... values );
085
086    /**
087     *  Sets the way the text length will be adjusted in order to meet the
088     *  target length set by
089     *  {@link #setTextLength(SVGNumber)}.
090     *
091     *  @param  flag    {@code true} means that both, spacing and glyph size
092     *      will be adjusted to match, {@code false} indicates that only the
093     *      spacing will be changed.
094     */
095    public void setLengthAdjust( final boolean flag );
096
097    /**
098     *  Sets a list of rotations for the glyphs. The n<sup>th</sup> rotation is
099     *  given to n<sup>th</sup> character in the text. Additional characters
100     *  are <em>not</em> given the last rotation (although some browsers may
101     *  handle that differently).
102     *
103     *  @param  values  The rotations.
104     */
105    public void setRotate( @SuppressWarnings( "UseOfConcreteClass" ) final SVGDegree... values );
106
107    /**
108     *  Sets the target length for the text that an SVG viewer will attempt to
109     *  display the text between by adjusting the spacing and/or the glyphs.
110     *
111     *  @param  value   The intended text length.
112     */
113    public void setTextLength( @SuppressWarnings( "UseOfConcreteClass" ) final SVGNumber value );
114
115    /**
116     *  Sets a list of x-axis position. The n<sup>th</sup> x-axis position is
117     *  given to n<sup>th</sup> character in the text. If there are additional
118     *  characters after the positions run out, they are placed after the last
119     *  character.
120     *
121     *  @param  values  The x-axis positions.
122     */
123    public void setX( @SuppressWarnings( "UseOfConcreteClass" ) final SVGNumber... values );
124
125    /**
126     *  Sets a list of y-axis position. The n<sup>th</sup> y-axis position is
127     *  given to n<sup>th</sup> character in the text. If there are additional
128     *  characters after the positions run out, they are placed after the last
129     *  character.
130     *
131     *  @param  values  The y-axis positions.
132     */
133    public void setY( @SuppressWarnings( "UseOfConcreteClass" ) final SVGNumber... values );
134}
135//  interface SVGTSpan
136
137/*
138 *  End of File
139 */