Différences

Ci-dessous, les différences entre deux révisions de la page.

Lien vers cette vue comparative

Les deux révisions précédentesRévision précédente
doc:xml_struct_elements_0.2 [11/04/2010 16:40] – Correction de l'exemple pour l'orientation de l'élément xavierdoc:xml_struct_elements_0.2 [20/11/2014 14:02] (Version actuelle) – modification externe 127.0.0.1
Ligne 1: Ligne 1:
 +====== La structure XML utilisée pour décrire les éléments dans QElectroTech 0.2 ======
  
 +...ou le guide du créateur d'éléments en XML. Cette page a pour but de décrire la structure XML utilisée pour stocker les définitions des éléments utilisés dans QElectroTech. Elle s'adresse aux développeurs de QET mais également aux non-développeurs qui voudraient se passer de l'éditeur d'élément.
 +
 +===== Exemple et structure générale d'une définition d'élément =====
 +<code xml>
 +<!DOCTYPE definition SYSTEM "definition_element.dtd">
 +  <definition type="element" width="45" height="65" hotspot_x="25" hotspot_y="45" orientation="dnnn">
 +    <names>
 +      <name lang="fr">Moteur asynchrone triphasé</name>
 +      <name lang="en">Three-phase induction motor</name>
 +    </names>
 +    <description>
 +      <!--U-->
 +      <polygon x1="-20" y1="-40" x2="-20" y2="-20" x3="-14" y3="-14" antialias="false" closed="false"/>
 +      <!--V-->
 +      <line x1="0" y1="-40" x2="0" y2="-20" antialias="false"/>
 +      <!--W-->
 +      <polygon x1="20" y1="-40" x2="20" y2="-20" x3="14" y3="-14" antialias="false" closed="false"/>
 +      <circle x="-20" y="-20" diameter="40" antialias="true" style="filling:white;"/>
 +      <!--Lettre M-->
 +      <text x="-13.5" y="12" size="24" text="M"/>
 +      <!--Bornes-->
 +      <terminal orientation="n" x="-20" y="-40"/>
 +      <terminal orientation="n" x="0"   y="-40"/>
 +      <terminal orientation="n" x="20"  y="-40"/>
 +    </description>
 +  </definition>
 +</code>
 +Ce code XML représente un "moteur asynchrone triphasé" : {{:doc:moteur_asynchrone_triphase.png|moteur asynchrone triphase}}
 +
 +Le doctype en première ligne n'est pas très important dans la mesure où une DTD n'est pas suffisante pour valider complètement une définition d'élément
 +
 +L'élément XML principal est donc le tag "definition". Pour le cas où nous aurions plusieurs types de définitions à l'avenir, on utilise l'attribut type pour spécifier qu'il s'agit d'une définition d'élément.
 +==== Dimensions de l'élément ====
 +
 +L'une des premières choses à préciser lors de la définition d'un élément est sa taille : largeur (width) et hauteur (height), en pixels. Ces deux dimensions doivent être des entiers multiples de 10. Si ce n'est pas le cas, QET les arrondira à la dizaine supérieure (exemple : 50 pour 42 pixels). Elles déterminent la taille et le rectangle délimitant de l'élément.
 +
 +{{ schema_xml_element1.png |Schema explicatif}}
 +
 +==== Point d'accroche (hotspot) de l'élément ====
 +
 +Le point d'accroche de l'élément désigne le point accroché au curseur de la souris lors d'un drag'n drop de l'élément. Il doit s'agir de coordonnées entières. "hotspot_x" est l'abscisse, "hotspot_y" est l'ordonnée. On considére que le coin supérieur gauche du rectangle délimitant l'élément est l'origine. Si les valeurs fournies dépassent du rectangle délimitant, elle seront limitées à la taille de l'élément. Le hotspot est également le centre de rotation utilisé lors du changement d'orientation de l'élément.
 +==== Orientation de l'élément ====
 +
 +Il faut ensuite définir quelles sont les orientations possibles de l'élément. L'orientation de l'élément est utilisée lors de la pose des conducteurs mais également pour empêcher l'utilisateur de tourner un élément dans une direction qui n'aurait pas de sens. L'attribut orientation est défini par une suite de 4 caractères, chaque caractère définissant le comportement pour une orientation.
 +
 +  * 1<sup>er</sup> caractère : Nord
 +  * 2<sup>nd</sup> caractère : Est
 +  * 3<sup>ème</sup> caractère : Sud
 +  * 4<sup>ème</sup> caractère : Ouest
 +
 +Chaque caractère peut avoir la valeur suivante :
 +
 +  * d pour "default" : indique que, par défaut, l'élément est considéré comme étant orienté dans cette direction. Il faut absolument indiquer une orientation par défaut.
 +  * y pour "yes" : l'utilisateur peut orienter l'élément dans cette direction.
 +  * n pour "no" : l'utilisateur ne peut pas orienter l'élément dans cette direction.
 +
 +Exemple : orientation="ydny" signifie que l'élément est dessiné orienté vers l'est et qu'il peut être tourné vers le nord et l'ouest mais pas vers le sud.
 +
 +==== Connexions internes ====
 +
 +Par défaut, il n'est pas possible de relier deux bornes d'un même élément. Ce comportement peut être changé avec l'attribut "ic" et la valeur true.
 +
 +==== Le reste de la définition ====
 +
 +Le reste de la définition est scindé en deux parties : la première est la définition du ou des noms de l'élément, avec l'élément XML "names". La seconde est la description du dessin et de la composition de l'élément, avec l'élément XML "description".
 +
 +===== Définir un ou plusieurs noms pour l'élément =====
 +
 +Un élément donné n'a qu'un nom par langue. Il est donc possible de définir autant de noms que de traductions possibles. Selon la langue du système (qui peut être différente des traductions disponibles pour QET), le nom adéquat est choisi et affiché. En interne, QET ne manipule que des noms de fichiers.
 +
 +L'élément XML "names" accepte des éléments XML enfants "name". Chaque "name" doit avoir un attribut "lang", contenant deux lettres représentant une langue. Il s'agit en fait des deux premières lettres de la "locale" du système. Exemple : pour spécifier le nom d'un élément sous un système configuré avec la langue / locale "fr_FR@euro", il faut indiquer lang="fr".
 +
 +Les éléments "name" sans attribut "lang" sont ignorés. Si la langue du système n'est pas trouvée dans les noms de l'élément, la langue anglaise (lang="en") est utilisée à la place.
 +
 +===== Dessiner et composer l'élément =====
 +
 +La définition du dessin de l'élément est assez proche du codage d'une image au format SVG. Les parties du dessin sont dessinées dans le même ordre que les éléments XML, c'est-à-dire qu'un élément recouvrira éventuellement ses prédécesseurs. Les éléments XML non valides sont ignorés.
 +==== Attributs de style ====
 +
 +Pour la plupart des éléments XML représentant une partie du dessin, il est possible de définir des attributs de style portant notamment sur le type de trait et le remplissage de ces parties de dessin.
 +
 +L'utilisation de l'attribut "style" correspond à celle qui est faite dans les standards HTML et XHTML : sa valeur est une suite de couples style / valeur séparés par des points-virgules. Exemple :
 +
 +<code xml>
 +<circle x="-20" y="-20" diameter="40" antialias="true" style="line-weight:none;filling:white;"/>
 +</code>
 +=== Style du trait ===
 +
 +Le style de trait se définit avec le style "line-style". Les valeurs possibles sont :
 +
 +  * dashed : trait pointillé
 +  * normal [par défaut] : trait plein
 +
 +=== Couleur du trait ===
 +
 +La couleur du trait se définit avec le style "color". Les valeurs possibles sont :
 +
 +  * white : trait blanc
 +  * black [par défaut] : trait noir
 +
 +Ce paramètre s'applique également au texte
 +
 +=== Epaisseur du trait ===
 +
 +L'épaisseur du trait se définit avec le style "line-weight". Les valeurs possibles sont :
 +
 +  * thin: trait fin, toujours affiché avec une épaisseur de 1 pixel
 +  * normal [par défaut] : trait normal
 +  * none : trait non visible
 +
 +=== Remplissage ===
 +
 +Le remplissage se définit avec le style "filling". Les valeurs possibles sont :
 +
 +  * white : remplissage en blanc
 +  * black : remplissage en noir
 +  * none [par défaut] : pas de remplissage
 +
 +=== L'attribut antialiasing ===
 +
 +En plus de l'attribut "style", il est possible d'utiliser l'attribut "antialiasing" ; cet attribut, accepte les valeurs "true" ou "false". L'antialiasing est désactivé par défaut. Cet attribut permet de spécifier si le rendu de cette partie du dessin (et non pas de l'élément entier) sera fait de manière anticrénelée ou non.
 +
 +{{ antialiasing.png |Antialiasing}}\\  Une DEL avec et sans antialiasing. À noter que l'antialiasing n'est pas toujours souhaitable.
 +
 +=== Repère ===
 +
 +Les coordonnées sont exprimées par rapport au repère ayant pour origine le point d'accrochage (hotspot) et non le coin supérieur gauche du rectangle délimitant l'élément. L'axe x est horizontal et se dirige vers la droite. L'axe y est verticale et se dirige vers le bas. L'unité est le pixel. Les valeurs réelles sont acceptées (exemple : x="2.5").
 +
 +Veillez à ne pas sortir du rectangle délimitant l'élément, sous peine de bugs graphiques.
 +==== Ligne ====
 +
 +L'élément line accepte les attributs suivants :
 +
 +  * x1 : abscisse de la première extrémité de la ligne
 +  * y1 : ordonnée de la première extrémité de la ligne
 +  * x2 : abscisse de la seconde extrémité de la ligne
 +  * y2 : ordonnée de la seconde extrémité de la ligne
 +  * end1 : type d'embout pour la première extrémité
 +  * length1 : longueur utilisée pour dessiner l'embout de la première extrémité. La valeur par défaut est "none".
 +  * end2 : type d'extrémité pour la seconde extrémité
 +  * length2 : longueur utilisée pour dessiner l'embout de la seconde extrémité. La valeur par défaut est "none".
 +
 +Les types d'embouts possibles sont :
 +^ Embout                valeur pour l'attribut\\ end1 (ou end2)   ^
 +| normal               | "none"                                     |
 +| Flèche simple        | "simple"                                   |
 +| Flèche triangulaire  | "triangle"                                 |
 +| cercle               | "circle"                                   |
 +| carré                | "diamond"                                  |
 +
 +{{:doc:endtypes.png|}}
 +==== Rectangle ====
 +
 +Un rectangle est défini par les coordonnées de son coin supérieur gauche et par ses dimensions (largeur et hauteur). L'élément rect accepte donc les attributs suivants :
 +
 +  * x : abscisse du coin supérieur gauche du rectangle
 +  * y : ordonnée du coin supérieur gauche du rectangle
 +  * width : largeur du rectangle
 +  * height : hauteur du rectangle
 +
 +==== Ellipse ====
 +
 +Une ellipse est définie par le rectangle dans lequel elle s'inscrit. L'élément ellipse accepte donc les attributs suivants :
 +
 +  * x : abscisse du coin supérieur gauche du rectangle
 +  * y : ordonnée du coin supérieur gauche du rectangle
 +  * width : largeur du rectangle
 +  * height : hauteur du rectangle
 +
 +==== Cercle ====
 +
 +L'élément circle est défini par les attributs suivants :
 +
 +  * x : abscisse du coin superieur gauche de la quadrature du cercle
 +  * y : ordonnee du coin superieur gauche de la quadrature du cercle
 +  * diameter : diametre du cercle
 +
 +{{ ellipse-circle-arc.png |Ellipse, cercle et arc}}
 +
 +==== Arc ====
 +
 +Un arc de cercle est défini comme étant une portion d'ellipse. L'élément arc partage donc des attributs avec l'ellipse :
 +
 +  * x : abscisse du coin supérieur gauche du rectangle
 +  * y : ordonnée du coin supérieur gauche du rectangle
 +  * width : largeur du rectangle
 +  * height : hauteur du rectangle
 +
 +À ces attributs s'en ajoutent deux autres :
 +
 +  * start : angle de depart : l'angle "0 degré" est à trois heures
 +  * angle : étendue (en degrés) de l'arc de cercle ; une valeur positive va dans le sens contraire des aiguilles d'une montre
 +
 +==== Polygone ====
 +
 +Le polygone est définie par une suite de points. L"élément polygon prend donc une série d'attributs de la forme suivante : x1, y1, x2, y2, x3, y3, x4, y4, etc... Par défaut, le polygone est fermé. On peut l'ouvrir en utilisant l'attribut facultatif closed à la valeur "false". Exemple :
 +<code xml>
 +<!-- Dessine un carré -->
 +<polygon x1="1" y1="1" x2="41" y2="1" x3="41" y3="41" x4="1" y4="41" />
 +<!-- Dessine 3 côtés du carré -->
 +<polygon x1="1" y1="1" x2="41" y2="1" x3="41" y3="41" x4="1" y4="41" closed="false" />
 +</code>
 +
 +==== Texte ====
 +
 +L'élément text accepte les attributs suivants :
 +
 +  * x : abscisse du début du texte
 +  * y : ordonnée du début du texte
 +  * text : texte à dessiner
 +  * size : taille à utiliser pour la police de caractère
 +
 +Le police utilisée est "Sans Serif"
 +
 +==== Borne ====
 +
 +Les bornes sont les points de connexions utilisées pour raccorder des éléments entre eux par l'intermédaire de conducteurs. Il sont toujours dessinés en dernier (donc au-dessus des autres parties du dessin), quel que soit leur emplacement dans le fichier XML.
 +
 +Ils prennent donc trois attributs :
 +
 +  * x : abscisse de la borne
 +  * y : ordonnée de la borne
 +  * orientation : orientation de la borne = Nord (n), Sud (s), Est (e) ou Ouest (w)
 +
 +==== Les champs de texte ====
 +
 +Les champs de texte sont des textes éditables par l'utilisateur ; les modifications apportées au texte sont enregistrés dans les schémas.
 +
 +Un champ de texte est un élément XML "input". Il accepte les mêmes attributs qu'un élément "text" à ceci près que l'attribut "text" représente la valeur par défaut du texte.
 +
 +Par défaut, le champ de texte se comporte de manière à rester horizontal malgré les rotations subies par son élément parent (on dit alors qu'il ne suit pas les rotations de son élément parent). Ce comportement peut être changé avec l'attribut "rotate" et la valeur true.
Imprimer/exporter