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.SVGImpl; 026import org.tquadrat.foundation.svg.type.SVGNumber; 027import org.tquadrat.foundation.svg.type.SVGPreserveAspectRatio; 028import jakarta.activation.MimeType; 029 030/** 031 * <p>{@summary The definition of the SVG element 032 * <code><svg></code>.}</p> 033 * <p>The <code><svg></code> element is the root element for any SVG 034 * document, either stand-alone (in a file with the {@code *.svg} extension) 035 * or embedded in an HTML file (or elsewhere - including another SVG 036 * document). Therefore the definition for the namespaces is different for 037 * each usage. This is reflected by the type 038 * {@link SVG.Usage}.</p> 039 * 040 * @extauthor Thomas Thrien - thomas.thrien@tquadrat.org 041 * @version $Id: SVG.java 1139 2024-06-16 19:50:41Z tquadrat $ 042 * @since 0.0.5 043 * 044 * @see "https://www.w3.org/TR/SVG/single-page.html#struct-SVGElement" 045 * 046 * @UMLGraph.link 047 */ 048@SuppressWarnings( "NewClassNamingConvention" ) 049@ClassVersion( sourceVersion = "$Id: SVG.java 1139 2024-06-16 19:50:41Z tquadrat $" ) 050@API( status = STABLE, since = "0.0.5" ) 051public sealed interface SVG extends SVGElementWithChildren, AllowsConditionalProcessingAttributes, AllowsDocumentEventAttributes, AllowsDocumentElementEventAttributes, AllowsGraphicalEventAttributes, AllowsPresentationAttributes, AllowsStyleAttributes 052 permits SVGImpl 053{ 054 /*---------------*\ 055 ====** Inner Classes **==================================================== 056 \*---------------*/ 057 /** 058 * The different usages for an {@code <svg>} element. 059 * 060 * @extauthor Thomas Thrien - thomas.thrien@tquadrat.org 061 * @version $Id: SVG.java 1139 2024-06-16 19:50:41Z tquadrat $ 062 * @since 0.0.5 063 * 064 * @UMLGraph.link 065 */ 066 @ClassVersion( sourceVersion = "$Id: SVG.java 1139 2024-06-16 19:50:41Z tquadrat $" ) 067 @API( status = STABLE, since = "0.0.5" ) 068 public static enum Usage 069 { 070 /*------------------*\ 071 ====** Enum Declaration **============================================= 072 \*------------------*/ 073 /** 074 * The {@code <svg>} element is used as the root for a stand-alone 075 * document. 076 */ 077 @API( status = STABLE, since = "0.0.5" ) 078 STANDALONE_DOCUMENT, 079 080 /** 081 * The {@code <svg>} element will be embedded into HTML (but not 082 * HTML 5 - see 083 * {@link #EMBED_HTML5}). 084 */ 085 @API( status = STABLE, since = "0.0.5" ) 086 EMBED_HTML, 087 088 /** 089 * The {@code <svg>} element will be embedded into HTML 5; as 090 * SVG is somehow part of the definition of HTML 5, no further 091 * namespace declarations are required. 092 */ 093 @API( status = STABLE, since = "0.0.5" ) 094 EMBED_HTML5, 095 096 /** 097 * The {@code <svg>} element will be embedded into another 098 * {@code <svg>} element. 099 */ 100 @API( status = STABLE, since = "0.0.5" ) 101 EMBED_SVG 102 } 103 // enum Usage 104 105 /*---------*\ 106 ====** Methods **========================================================== 107 \*---------*/ 108 /** 109 * Adds a child to the definitions of this {@code <svg>} element. 110 * 111 * @param <E> The implementation type for the {@code children}. 112 * @param child The child to add. 113 * @throws IllegalArgumentException The given child is not valid to be 114 * added to a {@code <defs>} element, or it does not have an id. 115 * @throws IllegalStateException The child has already a parent that is 116 * not this element. 117 */ 118 public <E extends SVGElement> void addDefinition( final E child ) throws IllegalArgumentException, IllegalStateException; 119 120 /** 121 * Adds an SVG {@code <style>} element to the definitions of this 122 * {@code <svg>} element. If there exists already a {@code <style>} 123 * element, the new one will be merged into the existing one. 124 * 125 * @param style The style to add. 126 * @throws IllegalStateException The child has already a parent that is 127 * not this element. 128 */ 129 public void addStyle( final SVGStyle style ) throws IllegalStateException; 130 131 /** 132 * <p>{@summary Sets the default scripting language used to process the 133 * type strings in event attributes.} This language must be used for all 134 * instances of script that do not specify their own scripting 135 * language.</p> 136 * <p>The type specifies a media type as a MIME document identifier; the 137 * default type is {@code application/ecmascript}.</p> 138 * 139 * @param value The default scripting language for this {@code <svg>} 140 * element. 141 */ 142 public void setContentScriptType( final MimeType value ); 143 144 /** 145 * Sets the dimension for this {@code <svg>} element. 146 * 147 * @param width The width of the element. 148 * @param height The height of the element. 149 */ 150 @SuppressWarnings( "UseOfConcreteClass" ) 151 public default void setDimension( final SVGNumber width, final SVGNumber height ) 152 { 153 setHeight( requireNonNullArgument( height, "height" ) ); 154 setWidth( requireNonNullArgument( width, "width" ) ); 155 } // setDimension() 156 157 /** 158 * Sets the height of the embedded {@code <svg>} element. 159 * 160 * @param value The type; if {@code null} the 161 * attribute will be removed. 162 */ 163 @SuppressWarnings( "UseOfConcreteClass" ) 164 public void setHeight( final SVGNumber value ); 165 166 /** 167 * Sets the mode for the aspect ratio preservation for this {@code <svg>} 168 * element. 169 * 170 * @param value The type; if {@code null} the 171 * attribute will be removed. 172 */ 173 public void setPreserveAspectRatio( final SVGPreserveAspectRatio value ); 174 175 /** 176 * <p>{@summary Sets the given CSS style definitions as a style sheet in 177 * an SVG {@code style} element to the <code><defs></code> element 178 * of this <code><svg></code> element.}</p> 179 * <p>This is <i>not</i> an attribute; instead an SVG {@code <style>} 180 * element will be created.</p> 181 * <p>Consecutive calls to this method will not create additional 182 * {@code <style>} elements, instead the new styles will be added to the 183 * existing ones.</p> 184 * 185 * @param styles The CSS style definitions. 186 * @return The SVG {@code <style>} element with the style sheet 187 * definitions. 188 */ 189 public SVGStyle setStyleSheet( final CharSequence... styles ); 190 191 /** 192 * Defines the visible area in this SVG drawing area. 193 * 194 * @param x The x coordinate of top left corner of the area. 195 * @param y The y coordinate of top left corner of the area. 196 * @param width The width of the area. 197 * @param height The height of the area. 198 */ 199 @SuppressWarnings( "UseOfConcreteClass" ) 200 public void setViewBox( final SVGNumber x, final SVGNumber y, final SVGNumber width, final SVGNumber height ); 201 202 /** 203 * Sets the width of the embedded {@code <svg>} element. 204 * 205 * @param value The type; if {@code null} the 206 * attribute will be removed. 207 */ 208 @SuppressWarnings( "UseOfConcreteClass" ) 209 public void setWidth( final SVGNumber value ); 210 211 /** 212 * Sets the x coordinate for the top left corner of the embedded 213 * {@code <svg>} element. 214 * 215 * @param value The type; if {@code null} the 216 * attribute will be removed. 217 */ 218 @SuppressWarnings( "UseOfConcreteClass" ) 219 public void setX( final SVGNumber value ); 220 221 /** 222 * Sets the y coordinate for the top left corner of the embedded 223 * {@code <svg>} element. 224 * 225 * @param value The type; if {@code null} the 226 * attribute will be removed. 227 */ 228 @SuppressWarnings( "UseOfConcreteClass" ) 229 public void setY( final SVGNumber value ); 230 231 /** 232 * Sets the 'Zoom-and-Pan' flag; if enabled on a stand-alone instance of 233 * the {@code <svg>} element, it allows panning and zooming the image. 234 * 235 * @param flag {@code true} enables the feature by setting 236 * "{@code magnify}" to the attribute 237 * {@value SVGUtils#SVGATTRIBUTE_ZoomAndPan}, {@code false} disables 238 * it by setting the attribute to "{@code disable}". 239 */ 240 public void setZoomAndPan( final boolean flag ); 241} 242// interface SVG 243 244/* 245 * End of File 246 */