JSYG-utils

Many features added to JSYG-wrapper

Installation

You probably don't need to install this module individually. It's a brick of JSYG framework. You may be insterested by JSYG.FullEditor, a full svg editor API. If you want to install it anyway :

npm install jsyg-utils

API

Table of Contents

• attrNS
  • Parameters
  • Examples
• removeAttrNS
  • Parameters
• href
  • Parameters
• walkTheDom
  • Parameters
• isChildOf
  • Parameters
• getCenter
  • Parameters
• setCenter
  • Parameters
• viewBox
  • Parameters
• getDefaultStyle
• style2attr
  • Parameters
• styleRemove
• styleSave
  • Parameters
• styleRestore
  • Parameters
• styleClone
  • Parameters
• getDim
  • Parameters
• setDim
  • Examples
• fit
  • Parameters
• getShift
  • Parameters
• transfOrigin
  • Parameters
• resetTransf
• scale
  • Parameters
• scaleX
  • Parameters
• scaleY
  • Parameters
• scaleNonUniform
  • Parameters
• translate
  • Parameters
• translateX
  • Parameters
• translateY
  • Parameters
• rotate
  • Parameters
• getMtx
  • Parameters
• setMtx
  • Parameters
• addMtx
  • Parameters
• mtx2attrs
  • Parameters
  • Examples
• getTransf
• isOver
  • Parameters
• getCursorPos
  • Parameters
• fill
  • Parameters
• stroke
  • Parameters
• dragEvents
  • Parameters
  • Examples
• svg2g
• toSVGString
  • Parameters
• toDataURL
  • Parameters
  • Examples
• url2data
  • Parameters
  • Examples
• toCanvas
  • Examples
• moveBackwards
• moveBack
• moveForwards
• moveFront
• distance
  • Parameters
• clip
  • Parameters
  • Examples
• walkTheDom
  • Parameters
• addStyle
  • Parameters
  • Examples
• getCursorPos
  • Parameters
• rand
  • Parameters
• bindPlugin
  • Parameters
• parseSVG
  • Parameters
• serializeSVG
  • Parameters
• defaultStyles
• getComputedStyle
  • Parameters
• elementDisplay
• defaultDisplay
  • Parameters
• isSVGImage
  • Parameters
• viewBox2mtx
  • Parameters

attrNS

récupère ou fixe la valeur d'un attribut (au sens xml) dans un espace de noms donné. Pour définir rapidement plusieurs attributs, on peut passer en paramêtre un objet dont les clés sont les noms des attributs et les valeurs les valeurs à affecter.

Parameters

• ns espace de nom.
• attr nom de l'attribut.
• val si définie, fixe la valeur de l'attribut.

Examples

:<ul>
<li><strong>jsynObjet.attrNS('http://www.w3.org/2000/svg','name')</strong> : renvoie l'attribut name de l'élément.</li>
<li><strong>jsynObjet.attr('name','toto')</strong> : définit l'attribut name de l'élément.</li> 
</ul>

removeAttrNS

Suppression d'un ou plusieurs attributs des éléments de la collection dans un espace de noms donné.

Parameters

• ns espace de nom.
• attr nom de l'attribut. Le nombre d'arguments n'est pas limité.

Returns JSYG

href

Récupère ou définit le lien de l'élément DOM. Cette méthode est utile pour harmoniser le html et le svg. Cette méthode permet de ce fait de définir l'attribut src des balises img.

Parameters

• val si défini, fixe la valeur du lien.

walkTheDom

exécute une fonction sur la collection et récursivement sur tous les descendants

Parameters

• fct le mot clé this fait référence au noeud courant. Si la fonction renvoie false, on sort de la boucle

Returns JSYG

isChildOf

Teste si le premier élément de la collection est enfant de l'élément passé en argument

Parameters

• arg argument JSYG

Returns Boolean

getCenter

• See: JSYG.prototype.getDim

récupère les coordonnées du centre de l'élément.

Parameters

• arg optionnel, 'screen','page' ou élément référent (voir JSYG.prototype.getDim pour les détails)

Returns Vect

setCenter

définit les coordonnées du centre de l'élément par rapport au parent positionné, avant transformation. On peut aussi passer en argument un objet contenant les propriétés x et y. Il est possible de ne passer qu'une valeur sur les deux (ou null) pour centrer horizontalement ou verticalement uniquement.

Parameters

• x abcisse
• y ordonnée

Returns JSYG

viewBox

récupère ou fixe les attributs de la viewBox d'un élément SVG (qui dispose de cet attribut, essentiellement les balise <svg>)

Parameters

• dim optionnel, objet, si défini fixe les attributs

Returns JSYG si dim est défini, objet avec propriétés x,y,width,height

getDefaultStyle

Renvoie les propriétés de style par défaut du 1er élément de la collection

Returns Object

style2attr

Ajoute tous les éléments de style possiblement définis en css comme attributs. Cela est utile en cas d'export SVG, afin d'avoir le style dans les balises et non dans un fichier à part.

Parameters

• recursive si true applique la méthode à tous les enfants.

Returns JSYG

styleRemove

Retire l'attribut de style "style" + tous les attributs svg concernant le style.

styleSave

Sauvegarde le style pour être rétabli plus tard par la méthode styleRestore

Parameters

• id identifiant de la sauvegarde du style (pour ne pas interférer avec d'autres styleSave)

Returns JSYG

styleRestore

Restaure le style préalablement sauvé par la méthode styleSave. Attention avec des éléments html et Google Chrome la méthode est asynchrone.

Parameters

• id identifiant de la sauvegarde du style (pour ne pas interférer avec d'autres styleSave)

Returns JSYG

styleClone

Applique aux éléments de la collection tous les éléments de style de l'élément passé en argument.

Parameters

• elmt argument JSYG

Returns JSYG

getDim

Récupération des dimensions de l'élément sous forme d'objet avec les propriétés x,y,width,height. Pour les éléments HTML, Les dimensions prennent en compte padding, border mais pas margin. Pour les éléments SVG (balises <svg> comprises), ce sont les dimensions sans tenir compte de l'épaisseur du tracé (stroke-width)

Parameters

• type

Returns Object objet avec les propriétés x,y,width,height

setDim

définit les dimensions de la collection par rapport au parent positionné, avant transformation. Pour les éléments HTML, Les dimensions prennent en compte padding, border mais pas margin. Pour les éléments SVG (balises <svg> comprises), ce sont les dimensions sans tenir compte de l'épaisseur du tracé (stroke-width). En argument, au choix :

Examples

<pre> new JSYG('#monElement').setDim({x:50,y:50,width:250,height:300});

//équivalent à :
new JSYG('#monElement').setDim("x",50).setDim("y",50).setDim("width",250).setDim("height",300);

//équivalent à :
new JSYG('#monElement').setDim(50,50,250,300);

Returns JSYG

fit

Adapte la taille des éléments au mieux sans déformation

Parameters

• dimContainer Object doit contenir les propriétés width et height. Si omis, prend les dimensions du premier parent positionné.

Returns JSYG

getShift

• See: JSYG.prototype.transfOrigin

Utile plutot en interne ou pour la création de plugins. récupère le décalage (pour les transformations) en pixels à partir d'arguments de types différents.

Parameters

• pivotX 'left','right','center', nombre ou pourcentage. Si non renseigné, l'origine par défaut de l'élément ("center")
• pivotY 'top','bottom','center', nombre ou pourcentage. Si non renseigné, l'origine par défaut de l'élément ("center")

Returns Vect

transfOrigin

récupère ou définit l'origine pour les transformations 2D (html et svg). On peut passer un seul argument avec l'origine en x et en y séparées par des espaces ou deux arguments séparés. Pour les valeurs possibles, voir le lien ci-dessous.

Parameters

• x chaîne, origine horizontale
• y chaîne, origine verticale

Returns JSYG si passé avec un ou des arguments, sinon renvoie une chaîne représentant l'origine en x et y.

resetTransf

Annule toutes les transformations 2D de la collection.

Returns JSYG

scale

Ajoute une transformation à la collection selon l'échelle spécifiée, ou récupère l'échelle en x du premier élément de la collection

Parameters

• scale si définie, transforme la collection

Returns JSYG si scale est définie, la valeur de l'échelle sinon

scaleX

Ajoute une transformation à la collection selon l'échelle en x spécifiée, ou récupère l'échelle en x du premier élément de la collection.

Parameters

• scale si définie, transforme la collection

Returns JSYG si scale est définie, la valeur de l'échelle en x sinon

scaleY

Ajoute une transformation à la collection selon l'échelle en y spécifiée, ou récupère l'échelle en y du premier élément de la collection.

Parameters

• scale si définie, transforme la collection

Returns JSYG si scale est définie, la valeur de l'échelle en y sinon

scaleNonUniform

Ajoute une transformation à la collection selon l'échelle non uniforme spécifiée, ou récupère l'échelle du premier élément de la collection.

Parameters

• scaleX
• scaleY

Returns JSYG si scaleX et scaleY sont définis, sinon objet avec les propriétés scaleX et scaleY

translate

Ajoute une transformation à la collection selon la translation spécifiée, ou récupère la translation du premier élément de la collection.

Parameters

• x
• y

Returns JSYG si x et y sont définis, sinon objet Vect

translateX

Ajoute une transformation à la collection selon la translation horizontale spécifiée, ou récupère la translation horizontale du premier élément de la collection.

Parameters

• x

Returns JSYG si x est défini, valeur de la translation horizontale sinon

translateY

Ajoute une transformation à la collection selon la translation verticale spécifiée, ou récupère la translation verticale du premier élément de la collection.

Parameters

• y

Returns JSYG si y est défini, valeur de la translation verticale sinon

rotate

Ajoute une transformation à la collection selon la rotation spécifiée, ou récupère la rotation du premier élément de la collection.

Parameters

• angle (degrés)

Returns JSYG si angle est défini, valeur de la rotation sinon

getMtx

• See: Matrix

Récupération de l'objet matrice du 1er élément de la collection, instance de Matrix. Pour les éléments HTML, seule la transformation de l'élément lui-même est supporté

Parameters

• arg (éléments svg seulement) null : transformation de l'élément lui-même 'ctm' : transformation de l'élément par rapport à son viewport (balise <svg>) 'screen' : transformation de l'élément par rapport à l'écran 'page' : transformation de l'élément par rapport ) la page (screen + scroll) objet DOM SVG : transformation de l'élément par rapport ) cet objet

Returns Matrix

setMtx

définit la matrice de transformation de l'élément

Parameters

• mtx instance de Matrix (ou SVGMatrix natif)

Returns JSYG

addMtx

Ajoute une transformation sous forme d'objet matrice (multiplication de la matrice avec la matrice courante)

Parameters

• mtx instance de Matrix (ou SVGMatrix natif)

Returns JSYG

mtx2attrs

répercute les transformations sur les attributs (autant que possible). Le type de transformations répercutable est variable selon les éléments. La rotation ne l'est pas sauf pour les chemins (path,line,polyline,polygone). Pour les conteneurs (<g>), aucune ne l'est. etc.

Parameters

• opt si indéfini, répercute la matrice de transformation propre à l'élément. Si défini, il est un objet contenant les propriétés possibles suivantes :

Examples

new JSYG('<rect>').attr({x:0,y:0,width:100,height:100}).translate(50,50).mtx2attrs().attr("x") === 50

Returns JSYG

getTransf

Renvoie les transformations du 1er élément de la collection

Returns any objet avec les propriétés "scaleX","scaleY","rotate","translateX","translateY"

isOver

Teste si le premier element de la collection est au dessus de l'élément passé en argument

Parameters

• node argument JSYG
• type 'full','partial','center' full : l'élément est entièrement au dessus de l'autre

Returns Boolean

getCursorPos

Renvoie la position du pointeur de la souris relativement à l'élément, sous forme d'objet vecteur Point

Parameters

• e objet Event

Returns Point

fill

Remplit la collection de la couleur spécifiée, ou récupère la couleur du premier élément. Cette méthode est plutot réservée aux tests, il est préférable de jouer sur les classes, pour laisser les styles à part.

Parameters

• color couleur html (ou objet JSYG.Color). Si non définie, renvoie la couleur du premier élément.

stroke

Borde la collection selon la valeur spécifiée. Cette méthode est plutot réservée aux tests, il est préférable de jouer sur les classes, pour laisser les styles à part. Elle permet de définir rapidement, comme en html (attribut css border) la bordure des éléments SVG.

Parameters

• val définition de la bordure ("1px solid black", "2px dashed gray", etc) ou objet JSYG.Color

dragEvents

Active/désactive les évènements drag:start, drag:drag et drag:end

Parameters

• method (undefined | String) sans argument, active les évènements, si "destroy" désactive les évènements

Examples

<pre>var jDiv = new JSYG('#maDiv');
jDiv.dragEvents().on("drag:start",function() { console.log("start dragging !"); });

svg2g

Transforme les éléments <svg> de la collection en conteneurs <g>. Cela peut être utile pour insérer un document svg dans un autre et éviter d'avoir des balises svg imbriquées.

Returns JSYG objet JSYG contenant la collection des éléments g.

toSVGString

Convertit le 1er élément de la collection en chaîne de caractères correspondant directement à un fichier SVG. L'élément lui-même n'est pas impacté.

Parameters

• standalone Boolean si true, copiera en temps qu'attribut les propriétés de style définies en css, et les images seront intégrées au document (plutôt que liées).
• imagesQuality optionnel, qualité de 0 à 100 pour les images. Utile uniquement si standalone est à true.

Returns Promise

toDataURL

Convertit la collection en images sous forme d'url. L'élément lui-même n'est pas impacté.

Parameters

• standalone Boolean si true, copiera en temps qu'attribut les propriétés de style définies en css, et les images seront intégrées au document (plutôt que liées).
• imagesQuality optionnel, qualité de 0 à 100 pour les images. Utile uniquement si standalone est à true.

Examples

<pre>new JSYG('#monSVG").toDataURL().then(function(src) {

    new JSYG("<img>").href(src).appendTo('body');
    
    //ou en javascript pur :
    var img = new Image();
    img.src = src;
    document.body.appendChild(img);

    //afficher le résultat dans une nouvelle fenêtre :
    window.open(src);
});

Returns Promise

url2data

Transforme les liens des images de la collection par le contenu de celles-ci. Utile pour exporter du svg en intégrant les images (sinon le svg reste dépendant des fichiers images).

Parameters

• recursive Boolean si true cherche dans les descendants de la collection
• format optionnel, "png", "jpeg" ("png" par défaut)
• quality optionnel, qualité de 0 à 100

Examples

<pre>//envoi du contenu svg cété serveur :
new JSYG("svg image").url2data().then(function() {
  fetch("sauve_image.php",{
  	method:"post",
  	body:"img="+new JSYG('svg').toSVGString()
  });
});

Returns Promise

toCanvas

Convertit le 1er élément de la collection en élément canvas. L'élément lui-même n'est pas impacté.

Examples

<pre>new JSYG('#monSVG").toCanvas().then(function(canvas) {
  new JSYG(canvas).appendTo("body");
});

Returns Promise

moveBackwards

Move back each element before his previous sibling

Returns JSYG

moveBack

Move back each element before his parent first child

Returns JSYG

moveForwards

Move each element after his next sibling

Returns JSYG

moveFront

Move each element after his parent last child

Returns JSYG

distance

Calcule la distance entre deux points

Parameters

• pt1 Point ou objet quelconque avec les propriétés x et y
• pt2 Point ou objet quelconque avec les propriétés x et y

Returns Number distance en pixels (non arrondi)

clip

Renvoie un nombre borné aux limites spécifiées

Parameters

• nb nombre
• min limite inférieure
• max limite supérieure

Examples

JSYG.clip(5,0,10) === 5;
JSYG.clip(50,0,10) === 10;
JSYG.clip(-50,0,10) === 0;

Returns Number

walkTheDom

Execute une fonction sur le noeud et récursivement sur tous les descendants (nodeType==1 uniquement)

Parameters

• fct le mot clé this fait référence au noeud courant. Si la fonction renvoie false, on sort de la boucle
• node noeud parent

addStyle

Ajoute une règle de style css

Parameters

• str chaîne css

Examples

JSYG.addStyle(".maClass { font-style:italic }");

getCursorPos

• See: Point

Renvoie la position du pointeur de la souris relativement à l'élément, sous forme d'objet point Point

Parameters

• evt objet Event
• ref argument JSYG (noeud DOM, chaîne css, etc)

Returns Point

rand

Renvoie un nombre entier aléatoire entre min et max, ou une valeur aléatoire d'un tableau

Parameters

• min valeur plancher, ou tableau de données
• max valeur plafond

Returns Number entier, ou valeur du tableau

bindPlugin

Permet d'attacher un plugin aux instances JSYG, qui fonctionne ensuite selon la philosophie jQuery.

Parameters

• Construct constructeur

Returns Function

parseSVG

Parse une chaîne svg en renvoit l'objet JSYG correspondant

Parameters

• svgString chaîne svg

Returns JSYG

serializeSVG

Sérialise le noeud sous forme de chaîne de caractère svg

Parameters

• node noeud a représenter
• _dim

Returns String Le résultat représente un fichier svg complet

defaultStyles

Style par défaut des éléments html

getComputedStyle

Donne la valeur calculée finale de toutes les propriétés CSS sur le premier élément de la collection.

Parameters

• node

Returns Object objet CSSStyleDeclaration

elementDisplay

Display par défaut des éléments

defaultDisplay

Renvoie le display par défaut de l'élément. Tir� de zepto.js. Peut mieux faire.

Parameters

• obj

isSVGImage

Permet de savoir s'il s'agit d'une balise <image> faisant référence à  du contenu svg, car auquel cas elle se comporte plus comme un conteneur (du moins avec firefox).

Parameters

• elmt

viewBox2mtx

Renvoit la matrice de transformation équivalente à la viewbox

Parameters

• svgElmt