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

<!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>
Ce code XML représente un “moteur asynchrone triphasé” : 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 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.

  • 1er caractère : Nord
  • 2nd caractère : Est
  • 3ème caractère : Sud
  • 4ème 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 :

<circle x="-20" y="-20" diameter="40" antialias="true" style="line-weight:none;filling:white;"/>

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
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”

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, 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 :

<!-- 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" />

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
Langages
Traductions de cette page: