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;
021import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
022
023import org.apiguardian.api.API;
024import org.tquadrat.foundation.annotation.ClassVersion;
025import org.tquadrat.foundation.svg.internal.SVGMarkerImpl;
026import org.tquadrat.foundation.svg.type.SVGMarkerOrientation;
027import org.tquadrat.foundation.svg.type.SVGNumber;
028import org.tquadrat.foundation.svg.type.SVGNumber.SVGDegree;
029import org.tquadrat.foundation.svg.type.SVGPreserveAspectRatio;
030import org.tquadrat.foundation.svg.type.SVGTransform;
031
032/**
033 *  The definition for the SVG {@code <marker>} element.
034 *
035 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
036 *  @version $Id: SVGMarker.java 1074 2023-10-02 12:05:06Z tquadrat $
037 *  @since 0.0.5
038 *
039 *  @UMLGraph.link
040 */
041@ClassVersion( sourceVersion = "$Id: SVGMarker.java 1074 2023-10-02 12:05:06Z tquadrat $" )
042@API( status = STABLE, since = "0.0.5" )
043public sealed interface SVGMarker extends SVGElementWithChildren, AllowsPresentationAttributes
044    permits SVGPositionedMarker, SVGMarkerImpl
045{
046        /*---------*\
047    ====** Methods **==========================================================
048        \*---------*/
049    /**
050     *  Sets the attribute that indicates whether external resources are
051     *  required to render this {@code <marker>} element.
052     *
053     *  @param  flag    {@code true} if external resources are needed,
054     *      {@code false} if all required resources are local to the current
055     *      context.
056     */
057    public void setExternalResourcesRequired( final boolean flag );
058
059    /**
060     *  Sets the width and the height of the viewport into which the
061     *  {@code <marker>} is to be fitted when it is rendered.
062     *
063     *  @param  width   The width.
064     *  @param  height   The height.
065     *
066     *  @see org.tquadrat.foundation.svg.SVGUtils#SVGATTRIBUTE_MarkerHeight
067     *  @see org.tquadrat.foundation.svg.SVGUtils#SVGATTRIBUTE_MarkerWidth
068     */
069    @SuppressWarnings( "UseOfConcreteClass" )
070    public default void setMarkerDimensions( final SVGNumber width, final SVGNumber height )
071    {
072        setMarkerHeight( requireNonNullArgument( height, "height" ) );
073        setMarkerWidth( requireNonNullArgument( width, "width" ) );
074    }   //  setMarkerDimensions()
075
076    /**
077     *  Sets the height of the viewport into which the {@code <marker>} is to
078     *  be fitted when it is rendered.
079     *
080     *  @param  value   The height.
081     *
082     *  @see org.tquadrat.foundation.svg.SVGUtils#SVGATTRIBUTE_MarkerHeight
083     */
084    @SuppressWarnings( "UseOfConcreteClass" )
085    public void setMarkerHeight( final SVGNumber value );
086
087    /**
088     *  Sets the marker units attribute that defines the coordinate system for
089     *  the attributes
090     *  {@value org.tquadrat.foundation.svg.SVGUtils#SVGATTRIBUTE_MarkerWidth}
091     *  and
092     *  {@value org.tquadrat.foundation.svg.SVGUtils#SVGATTRIBUTE_MarkerHeight}.
093     *
094     *  @param  flag    {@code true} if the user space should be used,
095     *      {@code false} for the stroke width.
096     */
097    public void setMarkerUnits( final boolean flag );
098
099    /**
100     *  Sets the width of the viewport into which the {@code <marker>} is to be
101     *  fitted when it is rendered.
102     *
103     *  @param  value   The width.
104     *
105     *  @see org.tquadrat.foundation.svg.SVGUtils#SVGATTRIBUTE_MarkerWidth
106     */
107    @SuppressWarnings( "UseOfConcreteClass" )
108    public void setMarkerWidth( final SVGNumber value );
109
110    /**
111     *  Sets the orientation of the marker. Basically, this means how it is
112     *  rotated when it is placed at its position on the markable element.
113     *
114     *  @param  value   The orientation.
115     */
116    public void setOrientation( final SVGMarkerOrientation value );
117
118    /**
119     *  Sets the orientation of the marker. Basically, this means how it is
120     *  rotated when it is placed at its position on the markable element.
121     *
122     *  @param  value   The orientation.
123     */
124    @SuppressWarnings( "UseOfConcreteClass" )
125    public void setOrientation( final SVGDegree value );
126
127    /**
128     *  Sets the mode for the aspect ratio preservation for this
129     *  {@code <marker>} element.
130     *
131     *  @param  value   The type; if {@code null} the
132     *      attribute will be removed.
133     */
134    public void setPreserveAspectRatio( final SVGPreserveAspectRatio value );
135
136    /**
137     *  Sets the reference point for the marker.<br>
138     *  <br>This is the location on the marker where it will be joined to its
139     *  markable element. Coordinates are relative to the marker's coordinate
140     *  system, and not the markable element it is placed on.
141     *
142     *  @param  x   The x coordinate for the point.
143     *  @param  y   The y coordinate for the point.
144     *
145     *  @see #setMarkerUnits(boolean)
146     */
147    @SuppressWarnings( "UseOfConcreteClass" )
148    public default void setReferencePoint( final SVGNumber x, final SVGNumber y )
149    {
150        setReferenceX( requireNonNullArgument( x, "x" ) );
151        setReferenceY( requireNonNullArgument( y, "y" ) );
152    }   //  setReferencePoint()
153
154    /**
155     *  Sets the x coordinate of the marker reference point.
156     *
157     *  @param  value   The coordinate type.
158     *
159     *  @see #setReferencePoint(SVGNumber, SVGNumber)
160     */
161    @SuppressWarnings( "UseOfConcreteClass" )
162    public void setReferenceX( final SVGNumber value );
163
164    /**
165     *  Sets the y coordinate of the marker reference point.
166     *
167     *  @param  value   The coordinate type.
168     *
169     *  @see #setReferencePoint(SVGNumber, SVGNumber)
170     */
171    @SuppressWarnings( "UseOfConcreteClass" )
172    public void setReferenceY( final SVGNumber value );
173
174    /**
175     *  Sets the transformations for this {@code <marker>} element.
176     *
177     *  @param  values  The transformations; if {@code null} or empty, the
178     *      attribute will be removed.
179     */
180    @Override
181    public void setTransform( final SVGTransform... values );
182
183    /**
184     *  Defines the visible area for this {@code <marker>} element.
185     *
186     *  @param  x   The x coordinate of top left corner of the area.
187     *  @param  y   The y coordinate of top left corner of the area.
188     *  @param  width   The width of the area.
189     *  @param  height  The height of the area.
190     */
191    @SuppressWarnings( "UseOfConcreteClass" )
192    public void setViewBox( final SVGNumber x, final SVGNumber y, final SVGNumber width, final SVGNumber height );
193}
194//  interface SVGMarker
195
196/*
197 *  End of File
198 */