La estructura XML utilizada para describir los esquemas en QElectroTech 0.3

El diagrama de arriba se pueden obtener con el siguiente código XML: ver el código XML de este esquema.

En la parte superior de la estructura XML, se encuentra el elemento raíz “project”, que representa un proyecto QElectroTech (fichiers *.qet). El elemento XML “project” acepte:

• el atributo “version” quién debe contener la versión de QElectroTech que registra el fichero. Esto servirá para facilitar la compatibilidad con versiones anteriores más tarde sobre el cambio de formato.
• el atributo title : título del proyecto

El elemento XML “projet” contiene :

• 0 a 1 elemento XML “newdiagrams”, encapsulando las propiedades por defecto que se utilizarán cuando se añade un nuevo esquema con el proyecto;
• 0 a n elementos XML “diagram”, cada uno representa un esquema;
• 0 a 1 elemento XML “collection”, representa una colección de elementos agrupados

Este elemento XML Esta destinado a encapsular todas las propiedades que pueden aplicarse a un esquema y que debe ser aplicada en la adición de un nuevo esquema al proyecto. Esto implica tres elementos XML:

• “border”, que acepta los atributos relativos a dimensiones del esquema y a graficos del esquema,con la excepción del atributo “height” ;
• “inset”, que acepta los atributos relativos al cartucho, excepto que el atributo de fecha podrá adoptar los siguientes valores:
  • una fecha al formato aaMMdd (ejemplo : 20090314) para especificar una fecha precisa;
  • “now” para utilizar la fecha de adición del esquema;
  • “null” ou “” para que no muestre la fecha;
• “conductors”, que acepta los atributos relativos a conductores.

Bajo el proyecto, se encuentra un esquema en forma de elemento XML “diagram”. Este acepta distintos atributos.

Los atributos siguientes sirven para llenar el cartucho del esquema:

• title : título indicado en el cartucho
• author : autor indicado en el cartucho
• date : fecha al formato AAAAMMDD, indicada en el cartucho
• filename : nombre de fichero indicado en el cartucho. Este valor es estrictamente independiente del fichero que contiene el XML.
• folio : Valor libre indicado en el cartucho. A partir de la versión 0.2, los valores siguientes se interpretan:
  • %id : Número del esquema en el proyecto
  • %total : Número total de esquemas en el proyecto

A partir de la versión 0.11, QElectroTech expresa las dimensiones de sus esquemas en líneas y columnas, y en lugar de columnas y altura de columnas. Un esquema debe pues enarbolar los siguientes atributos:

• cols : número de columnas
• colsize : anchura de las columnas, en píxeles
• rows : número de líneas
• rowsize : altura de las líneas, en píxeles
• height : atributo conservado para la retro-compatibilidad; es igual a rows × rowsize (filas × tamaño de fila)

A partir de la versión 0.11, es posible de indicar o no los encabezados de filas y columnas, gracias a los siguientes atributos:

• displayrows : “true” para indicar los encabezamientos de las líneas, “false” para ocultar
• displaycols : “true” para indicar los encabezamientos de las columnas, “false” para ocultar

A tener en cuenta que el espacio ocupado por los encabezamientos no se suprime. Sólo su registro no se efectúa.

El elemento XML “diagrama” contiene cuatro elementos: las propiedades de los conductores por defecto, los elementos, los conductores y los campos de texto.

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, ou dashed, pour un trait en 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. 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="f" ></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>