## [s]CALABLE [v]ECTOR [g]GRAPHICS

The goal of this class is to reduce the complexity of code to create and manipulate svg images/documents.
This class will be augmented according to my needs but you are strongly encouraged to participate yourself through pull request.

## Summary

⚠️ svg extends the <a href="xml.md">`xml`</a>class

## Properties:

|Properties|Type|Description|Initial value|
|---------|:----:|------|:------:|
|**.root**|Text|The DOM tree reference in memory of the document virtual structure|**Null**|
|**.autoClose**|Boolean|Indicates whether the XML tree should be automatically closed after a call to one of the functions: `.exportPicture()`, `.exportText()`, `.picture()`, `.getText()`, `.save()` or `.preview()`|**True\*** 🚨|
|**.file**|**4D**.File|The disk file of the last `.save()` or `.load()`call|**Null**|
|**.success**|Boolean|Indicates whether a function call was successfully executed|
|**.errors**|Collection|The list of errors encoutered, if so|[ ]|
|**.latest**|Text|The DOM reference of the last element created|**Null**|
|**.graphic**|Picture|The image generated by the last call to the `.picture()` function.|**Null**|
|**.xml**|Text|The SVG tree as text generated during the last call to the `.getText()` function.|**Null**|
|**.store**|Collection|The element references memorized (see below)|[ ]|
|**.cursor**|Text|Current target reference (stored id or DOM reference) used by subsequent calls.|**""**|
|**.autoExtendCanvas**|Boolean|If `True`, automatically extends root `width`/`viewBox` for `text` and `textArea` when rendered content exceeds current canvas width.|**True**|

\* 🚨 If `.autoClose` is set to **False** (or if you don't call a function that automatically closes the structure), once you no longer need the structure, remember to call the function `.close()` in order to free up the memory.

> 📌 `Point` type is a collection of 2 reals `[ x , y ]`  
> 
> 📌 With the exception of functions that return a specific result (getter function), each call returns the original `cs.svg` object, and you can include one call after another.

> 📌 If a function is called, without passing the `applyTo` parameter, the target is the last created path. If the `applyTo` parameter is passed, it must be a DOM reference or a stored name ("root", "latest", symbol name,…).  

> 📌 If creation or a setting function is called, without passing the `applyTo` parameter, before the creation of an object in the canvas, the target is canvas itself, otherwise the target is the last created object. If the `applyTo` parameter is passed, it can be: a DOM reference, an id, the name of a reference stored with the `.push()` function or a reserved name (`"root"`, `"latest"`, `"parent"`).    

> 📌 Remember that you can still add unmanaged attributes with the functions `.setAttribute()` or `.setAttributes()`     

> 📌 Remember that you can always use DOM XML commands to manipulate the SVG tree `.root`, object `.latest` or reference retrieved with the `.fetch()` function.

### Document & structure functions

|Function|Action|
|--------|------|
|.**load** ( source : `4D.File` \| `Text` \| `Blob` {; validate : `Boolean` {; schema : `Text` }} ) → `cs.svg` | Loads a SVG tree from a file or a variable (TEXT or BLOB)
|.**picture** ( { exportType : `Integer`} {; keepStructure : `Boolean` } ) → `Picture`  | Returns the picture described by the SVG structure & populates the `.graphic` property if success.
|.**content** ( { keepStructure : `Boolean` } ) → `Text`  | Returns the SVG tree as text & populates the `.xml` property if success.
|.**exportToBase64** ( {withDataPrefix : `Boolean`} ) → `Text` | Returns the SVG tree encoded in base64. If `withDataPrefix` is `True`, the result is prefixed with `data:image/svg+xml;base64,`.
|.**exportPicture** ( file : `4D.file` {; keepStructure : `Boolean`} ) → `cs.svg` | Saves the SVG tree as a picture file.
|.**exportText** ( file : `4D.file` {; keepStructure : `Boolean`} ) → `cs.svg` | Writes the content of the SVG tree into a disk file.
|.**newCanvas** ( { attributes : `Object` } ) → `cs.svg` | Close the current tree if any & create a new svg default structure.
|.**close** () → `cs.svg` | Frees the memory taken up by the SVG tree \*
|.**save** ( { keepStructure : `Boolean` } ) → `cs.svg` | Saves the content of the SVG tree into the initially loaded file or the last created file by calling `exportText()`
|.**group** ( { id : `Text` {; attachTo }} ) → `cs.svg` | Defines a `g` element who is a container element for grouping together related graphics elements.
|.**defineFilter** ( id : `Text` {; options: `Object` }) → ref: `Text` | Sets a new filter container in the current canvas
|.**linearGradient** ( id : `Text` {; startColor : `Text` {; stopColor : `Text` {; options: `Object` }}}) → ref: `Text` | Sets a new linear gradient in the current canvas
|.**radialGradient** ( id : `Text` {; startColor : `Text` {; stopColor : `Text` {; options: `Object` }}}) → ref: `Text` | Sets a new radial gradient in the current canvas
|.**pattern** ( id : `Text` {; options: `Object` }) → ref: `Text` | Defines a new pattern container in the current canvas and returns its reference
|.**solidColor** ( id : `Text` ; color : `Text` {; opacity : `Real` } ) → `cs.svg` | Defines a `solidColor` paint server (a single color with opacity) that can be referenced like a gradient.
|.**symbol** ( id : `Text` {; applyTo } ) → `cs.svg` | To define a symbol
|.**marker** ( id : `Text` {; applyTo } {; options : `Object` } ) → `cs.svg` | Defines a `marker` (in the canvas defs) or, when applied to an element/position (`start`/`mid`/`end`), references an existing marker on it.
|.**use** ( id : `Text` {; attachTo } ) → `cs.svg` | To place an occurence of a symbol
|.**clipPath** ( id : `Text` {; applyTo } ) → `cs.svg` | Define a clipPath and apply to the root element
|.**style** ( style : `Text` {; applyTo } ) → `cs.svg` | Creates an internal CSS style sheet if applied to the root
|.**styleSheet** ( file : `4D.File` ) → `cs.svg` | Attach a style sheet
|.**import** ( file : `4D.File` {; applyTo } ) → `cs.svg` | Imports the content of an external SVG file into the current container.
|.**title** ( title : `Text` ) → `cs.svg` | Adds a `title` element to the document.
|.**desc** ( description : `Text` ) → `cs.svg` | Adds a `desc` (description) element to the document.
|.**comment** ( comment : `Text` {; attachTo } ) → `cs.svg` | Inserts an XML comment node.
|.**viewbox** ( left : `Real`; top : `Real` ; width : `Real` ; height : `Real` {; attachTo } ) → `cs.svg` | Sets the `viewBox` attribute of a SVG viewport.
|.**relative**() → `cs.svg` | Defines the following coordinates as relative
|.**absolute**() → `cs.svg` | Defines the following coordinates as absolute
|.**feGaussianBlur**(filter : Text {; stdDeviation : Integer {; in : Text {; result : Text}}}) |  Sets a Gaussian blur for a filter
|.**feOffset**(filter : Text {; dx : Integer{; dy : Integer {; in : Text {; result : Text}}}}) |  Sets an offset filter for a filter
|.**feBlend**(filter : Text {; in : Text {; in2 : Text {; mode : Text {; result : Text}}}}) |  Sets a blend filter for a filter
|.**feColorMatrix**(filter : Text {; type : Text {; value {; in : Text {; result : Text}}}}) |  Sets a color matrix transformation for a filter

\* After the execution,`.root`is null but `.graphic` & `.xml` are always available

### Basic elements

|Function|Action|
|--------|------|   
|.**rect** ( height : `Real` {; width : `Real` } {; attachTo} ) → `cs.svg` | Creates a rectangle<br>Rounded rectangles can be obtained using `.rx()` & `.ry()`
|.**circle** ( radius : `Real` {; cx : `Real` {; cy : `Real`}} {; attachTo } ) → `cs.svg` | Creates a circle based on a center point and a radius.
|.**ellipse** ( radiusX : `Real`; radiusY : `Real`; cx : `Real`; cy : `Real` {; attachTo } ) → `cs.svg` | Creates an ellipse based on a center point and two radii  
|.**line** ( x1 : `Real`; y1 : `Real`; x2 : `Real`; y2 : `Real` {; attachTo } ) → `cs.svg` | Creates a line segment that starts at one point (`x1`,`y1`) and ends at another (`x2`,`y2`) 
|.**polyline** ( points : `Text` \| `Collection` {; attachTo } ) → `cs.svg` | Creates a set of connected straight line segments. Typically, `polyline` elements define open shapes.
|.**polygon** ( points : `Text` \| `Collection` {; attachTo } ) → `cs.svg` | Creates a closed shape consisting of a set of connected straight line segments.
|.**text** ( text : `Text` {; attachTo } ) → `cs.svg` | Creates a graphics element consisting of text. Supports plain text and 4D multi-style text fragment (converted to `tspan`).
|.**textArea** ( text : `Text` {; attachTo } ) → `cs.svg` | Creates a `textArea` element that allows simplistic wrapping of a text content within a given region. Supports plain text and 4D multi-style text fragment (converted to `tspan`) with `br` line breaks.\*
|.**image** ( picture : `Picture` \| `4D.File` \| `Text` {; attachTo } ) → `cs.svg` | Creates an image element.<br>Accepts an embedded picture (`Picture`), an image file (`4D.File`), a relative URL or a remote `http(s)` URL (`Text`).<br>⚠️ The 4D SVG renderer does not fetch remote resources: a remote `http(s)` URL is **downloaded and embedded as a base64 data URI** (one `HTTP Get` is performed, hence a slight latency). The real image format is detected from the file's magic bytes, so a mislabeled URL (e.g. a JPEG served as `.png`) still renders. If the download fails, a plain `href` is kept (browser-renderable) and an error is pushed.
|.**appendText** ( text : `Text` {; applyTo } ) → `cs.svg` | Appends text to a `textArea` element. Adds text content with each line separated by a carriage return, creating new `tspan` elements for each line. Line breaks are preserved using internal `tbreak` nodes.
|.**tspan** ( text : `Text` {; attachTo } ) → `cs.svg` | Creates a `tspan` element (styled text span) inside a `text` element.

\* The `textArea` elements are well rendered by 4D widgets but may not be supported by some browsers.

### path

|Function|Action|
|--------|------|   
|.**path** ( data : `Text` \| `Collection` {; attachTo } ) → `cs.svg` | Creates a `path` element.<br>The element definition can be given in text form (path data string), a Collection of points {x, y}, or the path can be constructed using the high level functions below.<br>When passing a Collection, points are converted to SVG path commands (M for initial moveTo, L for lineTo).
||
|**# High-level**\* |
|.**moveTo**\** ( point : `Point` {; applyTo } ) → `cs.svg` | Starts a new sub-path at the given `point` [x,y] coordinate
|.**lineTo** ( point : `Point` {; applyTo } ) → `cs.svg` | Draws a line from the current point to the given `point` [x,y] coordinate which becomes the new current point<br>A number of coordinates pairs may be specified to draw a polyline
|.**horizontalLineto** ( x : `Real` {; applyTo } ) → `cs.svg` | Draws an horizontal line from the current point (cpx, cpy) to (x, cpy)
|.**verticalLineto** ( y : `Real` {; applyTo } ) → `cs.svg` |  Draws a vertical line from the current point (cpx, cpy) to (cpx, y)
|.**arc** ( to : `Point`; radii  : `Integer` \| `[rx,ry]`; rotation : `Real`; flags : `[ large-arc-flag , sweep-flag ]` {; applyTo } ) → `cs.svg` |  Draws a section of an ellipse from the current point `to` [x, y]<br>The ellipse has two `radii` [ rx , ry ]. If only one radius is given, both radii will be equal<br>The x-axis of the ellipse is rotated by `rotation`<br>`flags` [large-arc-flag , sweep-flag] indicate how the arc is drawn (4 different arcs could be drawn.
|.**cubicBezierCurveto** ( to : `Point`; beginCtrlPoint :`Point`; endCtrlPoint :`Point` {; applyTo } ) → `cs.svg` |  Draws a cubic Bézier curve from the current point to [x,y] using `beginCtrlPoint` [x1,y1] as the control point at the beginning of the curve and `endCtrlPoint` [x2,y2] as the control point at the end of the curve.
|.**smoothCubicBezierCurveto** ( to : `Point`; endCtrlPoint :`Point` {; applyTo } ) → `cs.svg` |  Draws a cubic Bézier curve from the current point to [x,y] using `endCtrlPoint` as the control point at the end of the curve.<br>The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point.
|.**quadraticBezierCurveto** ( to : `Point`; controlPoint :`Point` {; applyTo } ) → `cs.svg` |  Draws a quadratic Bézier curve from the current point to [x,y] using `controlPoint` [x1,y1] as the control point.
|.**smoothQuadraticBezierCurveto** ( to : `Point` {; applyTo } ) → `cs.svg` |  Draws a quadratic Bézier curve from the current point to [x,y].<br>The control point is assumed to be the reflection of the control point on the previous command relative to the current point.
|.**closePath** ( ) → `cs.svg` | Close a path element
|.**d** ( points : `Text` {; applyTo } ) → `cs.svg` | Sets the "d" property of a path element
||
|# **Low-level**|
|.**M** / **m** ( points : `Text` \| `Collection` {; applyTo } ) → `cs.svg` | Absolute/Relative moveTo
|.**L**\** / **l**\** ( points : `Text` \| `Collection` {; applyTo } ) → `cs.svg` | Absolute/Relative lineTo
|.**H** / **h** ( x : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative horizontal lineTo
|.**V** / **v** ( y : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative vertical lineTo
|.**A** / **a** ( rx : `Real`; ry : `Real`; rotation : `Real`; largeArcFlag : `Integer`; sweepFlag : `Integer`; x : `Real`; y : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative  elliptical arc
|.**C** / **c** ( x1 : `Real`; y1 : `Real`; x2 : `Real`; y2 : `Real`; x : `Real`; y : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative  cubic Bézier curvTo
|.**S** / **s** ( x2 : `Real`; y2 : `Real`; x : `Real`; y : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative  shorthand/smooth cubic Bézier curvTo
|.**Q** / **q** ( x1 : `Real`; y1 : `Real`; x : `Real`; y : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative  quadratic Bézier curvTo
|.**T** / **t** ( x : `Real`; y : `Real` {; applyTo } ) → `cs.svg` | Absolute/Relative  shorthand/smooth quadratic Bézier curvTo
|.**Z** ( ) → `cs.svg` | Close a path element

\* Theses functions use **absolute** or **relative** coordinates according to the `absolute` property. Default is **absolute**. 
> 📌 To switch to relative coordinates, call the .**relative**() function: All subsequent coordinates will be interpreted as relative. To return to absolute coordinates, call the .**absolute**() function.

\** These functions can also be applied to `polyline` and `poligon` elements.

### Setting functions

|Function|Action|
|--------|------|
|.**setID** ( id : `Text` {; applyTo } ) → `cs.svg` | Sets the `id` attribute of the SVG object (standard XML attribute).<br>If this attribute already exists, its value is replaced by the value passed in parameter.
|.**x** ( x : `Real` {; applyTo } ) → `cs.svg` | Sets the x
|.**y** ( y : `Real` {; applyTo } ) → `cs.svg` | Sets the y
|.**width** ( width : `Real` {; applyTo } ) → `cs.svg` | Sets the width
|.**height** ( height : `Real` {; applyTo } ) → `cs.svg` | Sets the height
|.**translate** (tx : `Real` {; ty : `Real`} {; applyTo } ) →` cs.svg` | Specifies a translation by `tx` and `ty`. If the `ty` value is not provided, it is assumed to be zero
|.**scale** ( sx : `Real` {; sy : `Real` } {; applyTo } ) → `cs.svg` | Specifies a scaling operation by `sx` and `sy`. If the value `sy` is not provided, it is assumed to be equal to `sx`
|.**rotate** ( angle : `Integer` {; cx : `Real` ; cy : `Real`} {; applyTo } ) → `cs.svg` | Specifies a rotation of the `angle` value in degrees of a given point ;<br> • If the optional parameters `cx` and `cy` are not supplied, the rotation is performed with respect to the origin of the current user coordinate system.<br> • If the optional parameters `cx` and `cy` are supplied, the rotation is performed with respect to the point (`cx`,`cy`).
|.**rotateRad** ( radians : `Real` {; cx : `Real` ; cy : `Real`} {; applyTo } ) → `cs.svg` | Same as `.rotate()` but the angle is expressed in radians.
|.**rotateTAU** ( fraction : `Real` {; cx : `Real` ; cy : `Real`} {; applyTo } ) → `cs.svg` | Same as `.rotate()` but the angle is given as a fraction of a full turn (TAU): `0.25` = 90°, `0.5` = 180°…
|.**transform** ( node : `Text` ; transform : `Text` {; stack : `Boolean` } ) | Sets (or, if `stack` is `True`, appends to) the `transform` attribute of `node`.
|.**fillColor** ( color : `Text` {; applyTo } ) → `cs.svg` | Sets the fill color
|.**fillOpacity** ( opacity : `Real` {; applyTo } ) → `cs.svg` | Sets the fill opacity
|.**strokeColor** ( color : `Text` {; applyTo } ) → `cs.svg` | Sets the stroke color
|.**strokeWidth** ( width : `Real` {; applyTo } ) → `cs.svg` | Sets the stroke width
|.**strokeOpacity** ( opacity : `Real` {; applyTo } ) → `cs.svg` | Sets the stroke opacity
|.**linecap** ( value : `Text` \| `Integer` {; applyTo } ) → `cs.svg` | Sets the `stroke-linecap` attribute (`butt`, `round`, `square`).
|.**linejoin** ( value : `Text` \| `Integer` {; applyTo } ) → `cs.svg` | Sets the `stroke-linejoin` attribute (`miter`, `round`, `bevel`).
|.**nonScalingStroke** ( mode : `Boolean | Text` {; applyTo } ) → `cs.svg` | Sets the vector-effect attribute to the current (or passed) element
|.**dasharray** ( dash : Real;  ...  : Integer)  → `cs.svg` | Defines the pattern of dashes and blanks used for the object's outline border<br>The integer value of the dash parameter indicates the length of the first dash of the dotted pattern. If the value parameters are omitted, the dotted line will consists of a series of dashes and gaps of the same length.<br>The decimal value of the dash parameter, if it is not null, indicates the distance into the pattern from which the dashes will start.
|.**fontFamily** ( fonts : `Text` {; applyTo } ) → `cs.svg` | Sets the font family
|.**fontSize** ( size : `Integer` {; applyTo } ) → `cs.svg` | Sets the font size. For `text`/`textArea`, can trigger automatic canvas width/viewBox extension when needed.
|.**fontStyle** ( style : `Integer` {; applyTo } ) → `cs.svg` | Sets teh font style
|.**alignment** ( alignment : `Integer` {; applyTo } ) → `cs.svg` | Sets the text alignment
|.**dx** ( value : `Real` \| `Text` {; applyTo } ) → `cs.svg` | Sets the `dx` attribute (horizontal shift) of a `text`/`tspan`.
|.**dy** ( value : `Real` \| `Text` {; applyTo } ) → `cs.svg` | Sets the `dy` attribute (vertical shift) of a `text`/`tspan`.
|.**textRendering** ( rendering : `Text` {; applyTo } ) → `cs.svg` | Fix the text rendering
|.**visible** ( visible : `Boolean` {;applyTo } ) → `cs.svg` | Sets object visibility
|.**class** ( class : `Text` {; applyTo } ) → `cs.svg` | Sets the node class
|.**style** ( style : `Text` {; applyTo } ) → `cs.svg` | Assigns an embedded style
|.**preserveAspectRatio** ( value : `Text` {; applyTo} ) → `cs.svg` | Sets the attribute "preserveAspectRatio"
|.**r** ( r : `Real` {; applyTo } ) → `cs.svg` | Sets the radius of a circle
|.**rx** ( rx : `Real` {; applyTo } ) → `cs.svg` | Sets the rx of a rect or an ellipse
|.**ry** ( ry : `Real` {; applyTo } ) → `cs.svg` | Sets the ry of an ellipse
|.**cx** ( cx : `Real` {; applyTo } ) → `cs.svg` | Sets the cx of a circle or ellipse
|.**cy** ( cy : `Real` {; applyTo } ) → `cs.svg` | Sets the cy of a rect or an ellipse
|.**points** ( points : `Text` \| `Collection` {; applyTo } ) → `cs.svg` | Sets the "points" property of a polyline/polygon
|.**setAttribute** ( name : `Text`; value : `Variant` {; applyTo } ) → `cs.svg` | Sets one attribute
|.**setAttributes** ( attributes : `Text` \| `Collection` \| `Object`; value : `Variant` {; applyTo})  → `cs.svg` | Defines multiple attributes

### Shortcuts & utilities functions
 
|Function|Action|
|--------|------| 
|.**square** ( side : `Real` {; attachTo } ) → `cs.svg` | To draw a square
|.**regularPolygon** ( diameter : `Real` ; sides : `Integer`{; cx : `Real` ; cy : `Real` {; attachTo }} ) → `cs.svg` | Draws a regular polygon, with the given number of sides, fits into the circle set by `diameter`, `cx` & `cy`.
|.**fivePointStar** ( diameter : `Real` {; cx : `Real` ; cy : `Real` {; attachTo }} ) → `cs.svg` | Draws a five pointed star fits into the circle set by `diameter`, `cx` & `cy`.
|.**Star** ( nBranches : `Integer` ; outerRadius : `Real` ; cx : `Real` ; cy : `Real` {; ratio : `Real` } ) → `cs.svg` | Draws a star with `nBranches` branches. `ratio` (default `0.5`) sets the inner/outer radius ratio (lower = more pointed).
|.**Triangle** ( cx : `Real` ; cy : `Real` ; r : `Real` {; rotation : `Real` } ) → `cs.svg` | Draws an equilateral triangle inscribed in the circle of center (`cx`,`cy`) and radius `r`, optionally rotated by `rotation` degrees.
|.**boundedEllipse** ( x : `Real` ; y : `Real` ; width : `Real` ; height : `Real`{; attachTo }} ) → `cs.svg` | Draws an ellipse fits into the rectangle set by `x`, `y`, `width` and `height`.
|.**color** ( color : `Text` {; applyTo } ) → `cs.svg` | Defines the color of both the line and the fill (`stroke` & `fill` attributes)
|.**opacity** ( opacity : `Real` {; applyTo } ) → `cs.svg` | Sets stroke and fill opacity
|.**fill** ( value `Text` \| `Boolean` \| `Object` {; applyTo } ) → `cs.svg` |  To define the painting of the inside of a shape (`fill` attributes) or the winding rule: the `fill-rule` property
|.**filter** ( id `Text` {; applyTo }} ) → `cs.svg` |  Apply a filter to the current (or passed) element
|.**blend** ({alpha `Boolean`}) → `cs.svg` |  Apply a blend filter to current element using picture (or background if the `alpha` parameter is true) 
|.**blur** ({deviation `Integer`}) → `cs.svg` |  Apply a blur filter to current element.<br>Optional `deviation` parameter set the standard deviation for the blur operation.  Default value is `2`. 
|.**colorMatrix** ({type:`Integer` {; value}}) → `cs.svg` |  Applies a color matrix transformation to each pixel of the current element type & values are defined in .**feColorMatrix**(). 
|.**offset**(dx:`Integer`{;dy:`Integer`}) → `cs.svg` |  Apply an offset filter to the current reference. `dx` is is the value of the horizontal (& vertical if `dy`is ommitted) offset. 
|.**gradient** ( id `Text` {; stroke} {; applyTo }} ) → `cs.svg` |  Sets fill or stroke attribute of the current (or passed) element with a gradient
|.**pattern** ( id `Text` {; stroke} {; applyTo }} ) → `cs.svg` |  Sets fill or stroke attribute of the current (or passed) element  with a pattern
|.**dropShadow** ({ deviation : `Integer` {; dx : `Integer` {; dy : `Integer` }}} ) → `cs.svg` |  Set a drop shadow for the current element.<br>• The optional `deviation` parameter sets the intensity of the shadow dispersion. Default value: 2.<br>• The optional `dx` and `dy` parameters specify, respectively, the horizontal and vertical offset of the shadow with respect to the object. Default value: 2.
|.**convertToGrayScale** ({ value : `Real` {; applyTo } ) → `cs.svg` |  Transform colours into greyscale.<br>• You can pass the gray scale value to be applied in the optional value parameter\*. If you do not pass this parameter, the transformation is in accordance with the visual perception of the luminance (30% red, 59% green and 11% blue).<br>\**The value can be given as a real number between 0 and 1 or as an integer between 0 and 100.*
|.**stroke** ( value `Text` \| `Boolean` \| `Real` \| `Object` {; applyTo } ) → `cs.svg` | To define the painting of the outline of a shape (`stroke` attribute) or the `stroke-linecap` attribute.
|.**font** ( attributes : `Object` {; applyTo } ) → `cs.svg` | Sets the font attributes
|.**size** ( { width : `Real`; height : `Real` {; unit : `Text` }} ) → `cs.svg` | Sets the dimensions
|.**position** ( x : `Real` {; y : `Real` }{; unit : `Text` } ) → `cs.svg` | Sets the position. For `text`/`textArea`, can trigger automatic canvas width/viewBox extension when needed.
|.**moveHorizontally** ( x : `Real` {; applyTo } ) → `cs.svg` | Moves horizontally
|.**moveVertically** ( y : `Real` {; applyTo } ) → `cs.svg` | Moves vertically
|.**radius** ( radius : `Integer` {; applyTo} ) → `cs.svg` | Fix the radius of a circle or a rounded rectangle
|.**plot** ( points : `Text` \| `Collection` {; applyTo} ) → `cs.svg` | Populate the "points" property of a polyline, polygon or the "data" proprety of a path
|.**show** ( { applyTo } ) → `cs.svg` | Make visible
|.**hide** ( { applyTo } ) → `cs.svg` | Make invisible
|.**setValue** ( value : `Text` {; applyTo }{; CDATA : `Boolean` } ) → `cs.svg` | Sets the element value
|.**setText** ( text : `Text` {; applyTo } )| To set the text value of a `text` or a `textArea`
|.**getContainerText** ( { applyTo } ) → `Text` | Returns the textual content of a `text`, `tspan` or `textArea` element; line breaks are returned as CR (\r)
|.**getTextWidth** ( string : `Text` {; fontAttributes : `Object` } ) → `Integer` | Returns the rendered width (in pixels) of the given text using `textArea` rendering (optional `fontAttributes` applied)
|.**getTextHeight** ( string : `Text` {; fontAttributes : `Object` } ) → `Integer` | Attempts to return the rendered height of the given text (work in progress; may be approximate). Use with care.
|.**attachTo** ( parent : `Text` ) → `cs.svg` | Adds item to parent item
|.**addElement** ( name : `Text` {; attributes : `Object` \| `Collection` } {; attachTo } ) → `cs.svg` | Creates an element of any `name` (with optional attributes) in the current container — an escape hatch for elements without a dedicated function.
|.**addTo** ( target : `Text` {; applyTo } ) → `cs.svg` | Attaches the element to the `target` container and resets the cursor to the root.
|.**clone** ( source : `Text` {; attachTo} ) → `cs.svg` |To create a copy of a svg object
|.**addClass** ( class : `Text` {; applyTo} ) → `cs.svg` | Add a value to the node class
|.**removeClass** ( class : `Text` {; applyTo} ) → `cs.svg` | Remove a value to the node class
|.**isOfClass** ( class : `Text` {; applyTo } ) → `isOfclass` : Boolean | Tests if the node belongs to a class
|.**layer** ( name : `Text` ) → `cs.svg` | Creates one or more group at the root of the SVG structure
|.**push**(name:`Text`) →`cs.svg` | Keeps the dom reference into the store associated with the given name
|.**fetch**(name:`Text`) →`Text` | Retrieve a stored dom reference associated with the given name
|.**with**(name:`Text`) →`Boolean` | Defines an element for the next operations
|.**point**(x:`Real`;y:`Real`) →`Point` | Helper to create a point collection `[x, y]` (values rounded to 5 decimals)
|.**polarToCartesian**(point:`Point`;r:`Real`;degree:`Integer`) →`Point` | Transforms polar coordinates (offset) into cartesian coordinates updating the given point
|.**TextToPicture**(text:`Text`{;fontAttributes:`Object`}) →`Picture` | Returns a picture of the given text.
|.**preview**({keepStructure:`Boolean`}) | Display the SVG image & tree into the SVG Viewer if the component `4D SVG` is available. If not, generates the picture, copies it to the pasteboard and opens the clipboard.
|.**goUp**({level:`Integer`}) →`cs.svg` | Move up one (default)  or x level(s) in the XML tree.

### Notes

- 4D multi-style text parsing is available for both `.text()` and `.textArea()` when the input contains `<span ...>` fragments.
- `color:` declarations in inline style are normalized to SVG `fill:`.
- `.autoExtendCanvas` avoids clipping by extending root `width` and `viewBox` when text exceeds canvas width.

## 🔸 cs.svg.new()
The class constructor `cs.svg.new()` can be called without parameters to create a default svg structure with these attributes:
>`"viewport-fill"="none"`    
>`"fill"="none"`    
>`"stroke"="black"`    
>`"font-family"="'lucida grande','segoe UI',sans-serif"`    
>`"font-size"=12`    
>`"text-rendering"="geometricPrecision"`    
>`"shape-rendering"="crispEdges"`    
>`"preserveAspectRatio"="none"`

The class constructor also accepts an optional parameter, so you can create a svg structure by passing a 4D.File, a Blob variable or a Text variable.
>`cs.svg.new(4D.file)` Loads & parses the file content    
>`cs.svg.new(Blob)` Parses the blob variable content     
>`cs.svg.new(Text)` Parses the text variable content


## <a name="linearGradient">.linearGradient()</a>

.**linearGradient** ( id ) : Object<br>
.**linearGradient** ( id; startColor ) : Object<br>
.**linearGradient** ( id; startColor; stopColor ) : Object<br>
.**linearGradient** ( id; startColor; stopColor; options ) : Object<br>

|Parameter|Type||Description|
|---|---|---|---|
| id | Text | → | Name of gradient |
| startColor | Text | → | Start color |
| stopColor | Text | → | Stop color |
| options | Object | → | Gradient options |
| result | This | ← | This class instance |

### Description

This function defines a new linear gradient in the SVG container.

A gradient consists in a continuous progressive color transition from one color to another along a vector. Once specified, gradients are called on a given graphic element, while indicating whether this element must be filled or edged with the gradient called.

The `id` parameter specifies the name of the gradient. If an element with the same name exists, it will be replaced. This is the name that will be used to call the gradient each time a that a color expression is expected by using the syntax "url(#id)".

The `startColor` (default "white") and `endColor` (default "black") parameters specify the colors used to begin and end the gradient.

The options parameter allow to define some optional values:

|Parameter|Type|Description|
|---|---|---|
`rotation` | Integer | sets the position and direction of the gradient vector (see example)
`spreadMethod` | Text | defines the filling to be used when the gradient begins or ends within the bounds of the parent.\*
`x1`, `y1`, `x2`, `x2` | Integer | defines the gradient vector. This vector provides the starting and ending points used by the rendering engine. You can pass percentages expressed as ratios (0...1) in these parameters.
`startColorOffset` | Real | defines the percentage value of the start color\*\*.
`stopColorOffset` | Real | defines the percentage value of the stop color\*\*.

\* You can pass in `spreadMethod` one of the following strings in this parameter:  
  
	* "pad" (default) : use the terminal colors of the gradient to fill the remainder of the area.    
	* "reflect": reflect the gradient pattern start-to-end, end-to-start, start-to-end, etc. continuously until the object is filled.    
	* "repeat": repeat the gradient pattern start-to-end, start-to-end, start-to-end, etc. continuously until the object is filled.

\*\* You can pass either a real value < 1, or a value between 0 and 100 to set the percentage, i.e. "0.1" and/or "10" are both interpreted as 10%. Passing a negative value is interpreted as 0% for the startColorOffset parameter and as 100% for the endColorOffset parameter. If you pass a value > 100, it is interpreted as 100%.


#### Example

Draw 6 solid squares where each uses a linear gradient paint server while varying the rotation and direction of the gradient vector:

```4D
var $svg:=cs.svg.new()

$svg.linearGradient("demoGradient_1"; "red"; "yellow")
$svg.rect(90; 90).position(10; 10).gradient("demoGradient_1")
$svg.textArea("rotation = 0\rrotation = 180").position(10; 100).width(90).alignment(Align center)

$svg.linearGradient("demoGradient_2"; "red"; "yellow"; {rotation: -180})
$svg.rect(90; 90).position(110; 10).gradient("demoGradient_2")
$svg.textArea("rotation = -180").position(110; 100).width(100).alignment(Align center)

$svg.linearGradient("demoGradient_3"; "red"; "yellow"; {rotation: 45})
$svg.rect(90; 90).position(10; 140).gradient("demoGradient_3")
$svg.textArea("rotation = 45").position(10; 230).width(90).alignment(Align center)

$svg.linearGradient("demoGradient_4"; "red"; "yellow"; {rotation: -45})
$svg.rect(90; 90).position(110; 140).gradient("demoGradient_4")
$svg.textArea("rotation = -45").position(110; 230).width(90).alignment(Align center)

$svg.linearGradient("demoGradient_5"; "red"; "yellow"; {rotation: 90})
$svg.rect(90; 90).position(10; 270).gradient("demoGradient_5")
$svg.textArea("rotation = 90").position(10; 360).width(90).alignment(Align center)

$svg.linearGradient("demoGradient_6"; "red"; "yellow"; {rotation: -90})
$svg.rect(90; 90).position(110; 270).gradient("demoGradient_6")
$svg.textArea("rotation = -90").position(110; 360).width(90).alignment(Align center)

$svg.linearGradient("demoGradient_7"; "red"; "yellow"; {rotation: -180; spreadMethod: "reflect"})
$svg.rect(90; 90).position(10; 400).gradient("demoGradient_7")
$svg.textArea("rotation = -180").position(10; 490).width(100).alignment(Align center)

$svg.linearGradient("demoGradient_8"; "red"; "yellow"; {rotation: -180; spreadMethod: "reflect"; startOffset: 20; stopOffset: 80})
$svg.rect(90; 90).position(110; 400).gradient("demoGradient_8")
$svg.textArea("rotation = -180\roffset=20/80").position(110; 490).width(100).alignment(Align center)

$svg.preview()
```

See additional examples in <a href="svg_examples.md"> `svg_examples`</a>.