La structure XML utilisée pour décrire les schémas dans QElectroTech 0.3

Le schéma ci-dessus peut être obtenu avec le code XML suivant : voir le code XML de ce schéma.

Tout en haut de l'arborescence XML, on trouve l'élément racine “project”, qui représente un projet QElectroTech (fichiers *.qet). L'élément XML “project” accepte :

• l'attribut “version” qui doit contenir la version de QElectroTech ayant enregistré le fichier. Cela servira à faciliter la rétro-compatibilité ultérieurement en cas de changement de format.
• l'attribut title : titre du projet

L'élément XML “projet” contient :

• 0 à 1 élément XML “newdiagrams”, encapsulant les propriétés par défaut qui devront être utilisées lors de l'ajout d'un nouveau schéma au projet ;
• 0 à n éléments XML “diagram”, chacun représentant un schéma ;
• 0 à 1 élément XML “collection”, représentant une collection d'éléments embarquée.

Cet élément XML est destiné à encapsuler toutes les propriétés qui peuvent s'appliquer à un schéma et qui doivent être appliquées lors de l'ajout d'un nouveau schéma au projet. Cela implique trois éléments XML :

• “border”, qui accepte les attributs relatifs aux dimensions du schéma et au rendu du schéma, à l'exception de l'attribut “height” ;
• “inset”, qui accepte les attributs relatifs au cartouche, à ceci près que l'attribut date peut prendre les valeurs suivantes :
  • une date au format yyyMMdd (exemple : 20090314) pour spécifier une date précise ;
  • “now” pour utiliser la date d'ajout du schéma ;
  • “null” ou “” pour ne pas afficher de date ;
• “conductors”, qui accepte les attributs relatifs aux conducteurs.

Sous le projet, on retrouve un schéma sous la forme de l'élément XML “diagram”. Celui-ci accepte différents attributs.

Les attributs suivants servent à remplir le cartouche du schéma :

• title : titre affiché dans le cartouche
• author : auteur affiché dans le cartouche
• date : date au format AAAAMMJJ, affichée dans le cartouche
• filename : nom de fichier affiché dans le cartouche. Cette valeur est strictement indépendante du fichier contenant le XML.
• folio : Valeur libre affichée dans le cartouche. À partir de la version 0.2, les valeurs suivantes sont interprétées :
  • %id : Numéro du schéma dans le projet
  • %total : Nombre total de schémas dans le projet

À partir de la version 0.11, QElectroTech exprime les dimensions de ses schémas en lignes et colonnes, et non plus en colonnes et hauteur de colonnes. Un schéma doit donc arborer les attributs suivants :

• cols : nombre de colonnes
• colsize : largeur des colonnes, en pixels
• rows : nombre de lignes
• rowsize : hauteur des lignes, en pixels
• height : attribut conservé pour la rétro-compatibilité ; est égal à rows × rowsize

À partir de la version 0.11, il est possible d'afficher ou non les en-têtes des lignes et colonnes, grâce aux attributs suivants :

• displayrows : “true” pour afficher les en-têtes des lignes, “false” pour les masquer
• displaycols : “true” pour afficher les en-têtes des colonnes, “false” pour les masquer

À noter que l'espace occupé par les en-têtes n'est pas supprimé. Seul leur rendu n'est pas effectué.

L'élément XML “diagram” accueille ensuite quatre autres éléments : les propriétés des conducteurs par défaut, les éléments, les conducteurs et les champs de texte.

L'élément XML “defaultconductor” permet de spécifier le type de conducteurs par défaut pour ce schéma. En effet, lorsqu'on travaille sur un schéma, on n'utilise généralement qu'un seul type de conducteur, avec des propriétés bien définies. Il est alors fastidieux de respécifier pour chaque nouveau conducteur qu'il doit être de tel type, avec telles propriétés, etc. À noter que ceci n'influence absolument pas le rendu du schéma, il s'agit seulement d'une indication pour faciliter les manipulations dans l'éditeur WYSIWYG de QElectroTech.

Les conducteurs peuvent être de trois types : simples (“simple”), unifilaires (“single”) ou multifilaires (“multi”). Un conducteur multifilaire possède un champ de texte permettant de le numéroter. Un conducteur unifilaire ne possède pas de champ de texte mais arbore des symboles permettant de déterminer les fils qu'il représente. Un conducteur simple n'a ni symbole ni champ de texte.

L'élément XML “defaultconductor” accepte l'attribut “type” pour définir le type de conducteur. Si type vaut “simple”, les autres attributs seront ignorés. Si type vaut “multi”, le champ de texte contiendra la valeur de l'attribut “num”. Si type vaut “single”, le conducteur arborera :

• le symbole neutre si l'attribut “neutral” vaut “true”
• le symbole terre si l'attribut “ground” vaut “true”
• 0 à 3 symbole(s) phase selon la valeur de l'attribut “phase” : 0, 1, 2 ou 3

À cela s'ajoutent :

• l'attribut “color”, qui prend pour valeur un code hexadécimal représentant une couleur Rouge-Vert-Bleu précédé d'un dièse ; exemple : color=“#5fffac”
• l'attribut “style” - son utilisation 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. Un seul style est pour le moment supporté : line-style, qui peut prendre les valeurs normal pour un trait plein, dashed pour un trait en pointillés ou dashdotted pour un trait de type pointillés - points - pointillés.

L'attribut XML “elements” regroupe la liste des éléments électriques qui apparaissent sur le schéma. Chaque élément XML “element” (ça y est, on va commencer à s'embrouiller) accepte les attributs suivants :

• x : abscisse de la position de l'élément
• y : ordonnée de la position de l'élément
• type : il s'agit de l'adresse virtuelle de la définition de l'élément à placer sur le schéma
• orientation : 0 (Nord), 1 (Est), 2 (Sud), 3 (Ouest)

Concernant le positionnement de l'élément, il s'agit de la position du “hotspot” (point de saisie) de l'élément, et non de son coin supérieur gauche ou de son barycentre. Cette position est donnée dans un repère orthonormal dont l'origine est situé en haut à droite de la fenêtre d'édition (pour information, le coin supérieur gauche du schéma est situé à 5px,5px), dont le vecteur x se dirige vers la droite et dont le vecteur y se dirige vers le bas.

Les adresses virtuelles commencent par :

• common:// pour désigner un élément de la collection commune
• custom:// pour désigner un élément de la collection de l'utilisateur.
• embed:// pour désigner un élément embarqué dans le projet. Cette fonctionnalité est supportée à partir de la version 0.2.

À l'intérieur de chaque élément XML “element”, on peut trouver :

• des bornes (éléments XML “terminal”) encapsulées dans un élément XML “terminals”
• des champs de texte (éléments XML “input”) encapsulés dans un élément XML “inputs”

Comme dans la définition d'un élément, une borne est définie par l'attribut XML “terminal” et exige les attributs “x”, “y” et “orientation” dans les coordonnées de l'élément. Ces attributs sont utilisés pour repérer la borne correspondante dans l'élément. L'attribut id permet de retrouver cette borne parmi toutes celles apparaissant sur le schéma. Il s'agit d'un entier positif. Il est impossible de relier un conducteur à une borne sans id. De même, il est impossible d'ajouter une borne à un élément sans éditer cet élément.

Comme les bornes, les champs de texte (éléments XML “input”) exigent les attributs “x” et “y” dans les coordonnées de l'élément afin de repérer le champ de texte correspondant dans l'élément. Il n'est pas non plus possible d'ajouter un champ de texte non prévu dans la définition de l'élément. Le champ de texte ainsi repéré se verra attribué la valeur de l'attribut “text”.

À partir de la version 0.3, il est possible de spécifier l'orientation des champs de texte des éléments. Par défaut, l'orientation spécifiée dans la définition de l'élément est utilisée. Elle peut toutefois être surchargée par l'attribut “userrotation” (spécifique à chaque champ de texte). Sa valeur est un nombre décimal qui doit être compris entre -360.0° et 360.0°. 0° correspond à la position de la petite aiguille d'une montre lorsqu'il est 3 heures. Une valeur négative représente un angle dans le sens contraire des aiguilles d'une montre tandis qu'une valeur positive représente un angle dans le sens des aiguilles d'une montre.

À partir de la version 0.3, il est également possible de spécifier la position des champs de texte des éléments. Par défaut, la position spécifiée dans la définition de l'élément est utilisée. Elle peut toutefois être surchargée par les attributs “userx” et “usery” (spécifiques à chaque champ de texte). Leur valeur correspondent à l'abscisse et à l'ordonnée du champ de texte relativement à l'élément : le repère utilisé pour positionner les champs de texte a pour origine le point d'accroche (hotspot) de l'élément (cf La structure XML utilisée pour décrire les éléments dans QElectroTech 0.3)

Le positionnement et la rotation s'effectuent par rapport au milieu du côté gauche du champ de texte.

Encapsulés dans l'élément XML “conductors”, les conducteurs sont représentés par des éléments XML “conductor” (si !). Ils acceptent les mêmes attributs que l'élément XML “default conductor” pour définir leur type et leurs options. À cela s'ajoutent les attributs “terminal1” et “terminal2” qui doivent avoir pour valeur les ids des bornes que le conducteur relie.

Un conducteur est optionnellement composé de segments ( = éléments XML “segment”, si, si !) décrivant sa trajectoire. Si aucun segment n'est présent ou que la trajectoire décrite est incohérente, le logiciel repasse sur le trajet par défaut pour relier les deux bornes.

Un segment possède un attribut “orientation” qui peut prendre les valeurs “horizontal” ou “vertical” pour définir le sens du segment. Il possède également un attribut length définissant sa longueur. Les segments sont lus dans l'ordre et représentent la trajectoire de la borne 1 vers la borne 2.

À partir de la version 0.3, il est possible de spécifier l'orientation des champs de texte des conducteurs via l'attribut “rotation”. Par défaut, le champ de texte est horizontal. La valeur de l'attribut “rotation” est un nombre décimal qui doit être compris entre -360.0° et 360.0°. 0° correspond à la position de la petite aiguille d'une montre lorsqu'il est 3 heures. Une valeur négative représente un angle dans le sens contraire des aiguilles d'une montre tandis qu'une valeur positive représente un angle dans le sens des aiguilles d'une montre. La rotation s'effectue par rapport au coin supérieur gauche du champ de texte.

Encapsulés dans l'élément XML “inputs” situé sous l'élément XML “diagram”, les champs de texte sont représentés par des éléments XML (suspens…) “input” (vous avez eu peur hein ?). Contrairement aux “inputs” des éléments ou au “num” des conducteurs multifilaires, ils ne sont pas liés à un conducteur ou un élément et peuvent être positionnés librement sur le schéma.

L'élément XML “input” accepte les attributs suivants :

• x : abscisse du coin supérieur gauche du champ de texte
• y : ordonnée du coin supérieur gauche du champ de texte
• text : contenu du champ de texte - utilisez 
 pour faire un retour à la ligne.
• rotation : à partir de la version 0.3, il est possible de spécifier l'orientation des champs de texte. Par défaut, le texte est horizontal. La valeur de cet attribut est un nombre décimal qui doit être compris entre -360.0° et 360.0°. 0° correspond à la position de la petite aiguille d'une montre lorsqu'il est 3 heures. Une valeur négative représente un angle dans le sens contraire des aiguilles d'une montre tandis qu'une valeur positive représente un angle dans le sens des aiguilles d'une montre.

Le positionnement et la rotation s'effectuent par rapport au coin supérieur gauche du champ de texte.

L'élément XML “collection” permet d'embarquer des éléments et catégories comme s'il s'agissait d'une collection d'éléments sur disque dur. Il n'accepte pas d'attribut particulier. Il peut contenir des éléments XML “category” et “element”.

L'élément XML “category” accepte un attribut name, utilisé pour désigner le nom de cette catégorie dans un chemin ; ainsi, embed://test désigne la catégorie “test” embarquée dans le projet courant. Une catégorie doit contenir une liste de noms humains, représentée par un élément XML “names”, contenant lui-même 1 à n noms, représentés par des éléments XML “name”. Celui-ci accepte l'attribut lang, avec pour valeur deux lettres représentant un langage humain (exemples : en pour english, fr pour français, es pour espagnol, etc.). Cet élément XML doit contenir le nom de l'élément électrique dans la langue correspondant à l'attribut lang.

Une catégorie peut également contenir :

• 0 à n éléments XML “category”
• 0 à n éléments XML “element”

L'élément XML “element” obéit aux règles décrites dans La structure XML utilisée pour décrire les éléments dans QElectroTech 0.3. À ces règles s'ajoute la présence d'un attribut name, utilisé pour désigner le nom de cet élément électrique dans un chemin ; ainsi, embed://test/nouvel_element.elmt désigne l'élément “nouvel_element.elmt”, situé dans la catégorie “test” de la collection embarquée du projet courant.

Exemple de collection embarquée :

    <collection>
        <category name="test" >
            <names>
                <name lang="en" >English test</name>
                <name lang="fr" >Test</name>
            </names>
            <element name="nouvel_element.elmt" >
                <definition width="30" version="0.2" hotspot_x="15" hotspot_y="35" height="70" type="element" orientation="dyyy" >
                    <names>
                        <name lang="en" >Quadrilateral</name>
                        <name lang="fr" >Quadrilatère</name>
                    </names>
                    <description>
                        <polygon antialias="true" style="line-style:normal;line-weight:normal;filling:none;color:black" x1="-7.25" y1="-1.5" x2="1.25" y2="-20.25" x3="10.5" y3="-0.5" x4="-1.5" y4="22" />
                    </description>
                </definition>
            </element>
        </category>
    </collection>