# Module Custom Shape

## Introduction au module custom-shapes

Le module custom shape vous permet de créer de nouvelles formes pour Dia sans avoir à écrire de code C. À la place, il suffit d'écrire un fichier XML décrivant la forme. Les non programmeurs peuvent ainsi créer de nouvelles formes pour Dia.

La forme elle-même est décrite en utilisant un sous-ensemble de la spécification SVG. Les éléments line, polyline, polygon, rect, circle, ellipse, path et g sont supportés. Notez que l'élément path prend seulement en charge les commandes M,m,L,l,H,h,V,v,C,c,S,s,Z et z. Les transformations et unités CSS ne sont pas prises en charge (seules les unités &og;user&fg; le sont), et seul un jeu limité d'attributs CSS est pris en charge.

Des points de connexion peuvent être associés à la forme. Ils sont spécifiés dans le même système de coordonnées que la description SVG de la forme.

Une boîte de texte peut être associée à la forme. La boîte de texte est également spécifiée dans le même repère de coordonnées que la forme.

Pour choisir la taille et la position de la boîte de texte, vous pouvez penser à un rectangle contenant la boîte de texte, et un autre contenant tous les autres éléments SVG (appelons-le le rectangle Image) : lorsque vous obtenez la forme sur le canevas, et y écrivez du texte, tout le texte doit entrer dans la boîte de texte. Si nécessaire, la boîte de texte s'agrandira, et, dans les mêmes proportions, le rectangle Image s'agrandira également.

Dia prend soin du reste pour vous (changement de taille, de position, connexion de lignes, chargement, enregistrement, etc).

## Forme

Un fichier de forme typique peut ressembler à ceci :

      <?xml version="1.0"?>

      <shape xmlns="http://www.daa.com.au/~james/dia-shape-ns"
             xmlns:svg="http://www.w3.org/2000/svg">
        <name>Circuit with identifiers - NPN Transistor</name>
        <icon>npn.xpm</icon>
        <connections>
          <point x="0" y="0"/>
          <point x="6" y="-4"/>
          <point x="6" y="4"/>
        </connections>

        <aspectratio type="fixed"/>

        <textbox x1="4" y1="-3" x2="12" y2="3" />

        <svg:svg>
          <svg:line x1="0" y1="0" x2="3" y2="0" />
          <svg:line x1="3" y1="-3" x2="3" y2="3" />
          <svg:line x1="3" y1="-2" x2="6" y2="-4" />
          <svg:line x1="3" y1="2" x2="6" y2="4" />

          <svg:polyline points="5,4 6,4 5.6154,3.0769" />
        </svg:svg>

      </shape>

Seuls les éléments &og;`name`&fg; et &og;`svg`&fg; sont requis dans le fichier shape. Le reste est optionnel.

L'élément `name` donne le nom de l'objet. Le nom est l'identifiant unique de cette forme, utilisé pour le chargement et l'enregistrement.

Comme dans cet exemple, vous pouvez utiliser des &og;noms composés&fg;. Beaucoup de formes ont pour première partie de leur nom le nom de la feuille (sheet) dans laquelle elles apparaissent, mais c'est optionnel.

L'élément &og;`icon`&fg; spécifie un fichier xpm ou png utilisé comme icône dans la &toolbox; Dia. Le nom de fichier peut être relatif au fichier de forme (le chemin peut...). Si cet élément n'est pas précisé, une icône par défault sera utilisée pour les formes personnalisées.

La section &og;`connections`&fg; spécifie un jeu de points de connexion pour la forme. Le repère de coordonnées pour ces points est le même que le repère utilisé dans la description svg de la forme.

L'élément &og;`aspectratio`&fg; vous permet de spécifier quelles proportions de la forme peuvent être modifiées. Les trois possibilités sont :

- `<aspectratio type="free"/>` : tout ratio de proportions autorisé (le defaut)

- `<aspectratio type="fixed"/>` : la proportion est fixe.

- `<aspectratio type="range" min="n" max="m"/>` : Donne une plage de valeurs.

La dernière option vous permet de spécifier une plage des valeurs de déformation, ce qui peut être utile dans certains cas.

L'élément `textbox` vous permet d'associer du texte[1] à la forme. La syntaxe est :

       <textbox x1="left" y1="top" x2="right" y2="bottom"/>

(seulement une textbox par forme) où les attributs donnent les limites de la boîte de texte dans le même repère que la description SVG de la forme.

À leur création, les formes ont une taille par défaut. Si leur dimension ne correspond pas à vos besoins, vous pouvez remplacer celles-ci par l'une ou les deux directives:

- `<default-width>1cm</default-width>`
- `<default-height>1cm</default-height>`

L'élément `svg` décrit la forme. les attributs width et height sont ignorés, et donnés seulement pour compatibilité avec la spécification SVG. voir les pages du W3C à-propos du format à l'adresse : http://www.w3.org/Graphics/SVG

La section suivante détaille quelles parties de la spécification SVG peuvent être utilisées dans un fichier shape.

## Description de forme

Le format SVG (Scalable Vector Graphics) est utilisé pour décrire la forme. C'est pourquoi un espace de noms séparé est utilisé pour cette partie du fichier.

### Attribut style

Chaque élément du dessin SVG prend en compte l'attribut &og;`style`&fg;. L'attribut doit être de la forme :

      <svg:toto style="name1: value1; name2: value2; ... name42: value42"/>

Actuellement, seuls les styles suivants sont interprétés :

- `stroke-width` : La largeur de ligne, relative à la largeur spécifiée par l'utilisateur dans le tag svg.

- `stroke-linecap` : Le style des bouts de ligne. Un parmi `butt`, `round`, `square`, `projecting` (un synonyme de `square`), ou `default`.

- `stroke-linejoin` : Le style des jointures. Un parmi `miter`, `round`, `bevel` ou `default`.

- `stroke-pattern` : Le motif de points. Un parmi, `dashed`, `dash-dot`, `dash-dot-dot`, `dotted` ou `default`.

- `stroke-dashlength` : La longueur des traits dans le motif précédent, en relation avec la valeur spécifiée par l'utilisateur (`default` est un synonyme pour 1.0).

- `stroke` : La couleur de ligne. Vous pouvez utiliser un des noms symboliques `foreground`, `fg`, `default`, `background`, `bg`, `inverse`, `text` ou `none`, ou utiliser une couleur hexadécimale de forme `#rrggbb`.

- `fill` : La couleur de remplissage. Mêmes valeurs que pour `stroke`, excepté que la signification de `default` et `inverse` sont échangées. Par défaut, les éléments ne sont pas remplis, aussi, pour obtenir le remplissage par défaut, utilisez "`fill: default`"

Pour dessiner un rectangle avec une ligne de largeur minimale (hairline), cette astuce devrait fontionner :

      <svg:rect style="stroke-width: 0" x="..." y="..." width="..." height="..."/>

Les ordonnées x et y grandissent comme dans Dia.

### Éléments svg reconnus

Les éléments de dessin reconnus sont :

- `<svg:g>`

  Ceci est l'élément groupe. Vous pouvez y placer d'autres éléments. Le contenu de l'attribut style de l'élément g est propagé aux éléments contenus (à moins qu'ils ne les modifient).

- `<svg:line x1="..." y1="..." x2="..." y2="..."/>`

  Cet élément est une ligne.

- `<svg:polyline points="...."/>`

  Ceci est une ligne brisée (une collection de segments de droite connectés). L'attribut &og;points&fg; contient les coordonnées des extrémités des segments. Les coordonnées sont séparées par un blanc ou des virgules. Le format suggéré est "`x1,y1 x2,y2 x3,y3 ...`".

- `<svg:polygon points="...."/>`

  Ceci est un polygone. L'argument &og;points&fg; est du même format que celui de l'élément &og;polyline&fg;.

- `<svg:rect x1="..." y1="..." width="..." height="..."/>`

  Ceci est un rectangle. Le coin supérieur gauche est (x1,y1), et le coin inférieur droit est (x1+width,y1+height).

- `<svg:image x1="..." y1="..." width="..." height="..." xlink:href="..." />`

  Ceci est une image externe. Le supérieur gauche est (x1,y1), et le coin inférieur droit est (x1+width,y1+height). Deux formes de lien sont pris en charge : un chemin absolu de la forme "`file:///home/user/image.png`", ou relatif sans le préfixe `file://` comme dans "`image.png`". La dernière forme est préférable car indépendante de l'installation. Le nom de fichier est relatif à l'emplacement du fichier de forme (xxx.shape). Dans l'exemple ci-dessus les fichiers PNG et shape doivent être dans le même répertoire.

  pour les unices, on parle bien de répertoire (directory) et non de dossier (folder). Par exemple les commande &og;`cd`&fg; (change directory), et, sous Windows, &og;`dir`&fg;.

- `<svg:circle cx="..." cy="..." r="..."/>`

  Ceci est un cercle de centre (cx,cy) et de rayon r.

- `<svg:ellipse cx="..." cy="..." rx="..." ry="..."/>`

  Ceci est une ellipse de centre (cx, cy), de rayon rx dans la direction x, et de rayon ry dans la direction y.

- `<svg:path d="...."/>`

  Ceci est l'élément de dessin le plus complexe. Il décrit un chemin fait de segments de droite et de courbes de bézier. Actuellement, il ne prend en charge ni l'arc elliptique ni les courbes de bézier quadratiques. La chaîne &og;d &fg; est faite de commandes de la forme "x arg1 arg2 ..." où &og;x&fg; est le code de caractère identifiant la commande, et où les arguments sont des nombres séparés par un blanc ou des virgules. Chaque commande a une variante absolue et relative. Les commandes relatives sont données par une lettre minuscule. Elles utilisent le point d'extrémité de la commande précédente comme point d'origine.

  Les commandes prises en charge sont :

  - `M x,y` : Bouge le curseur

  - `L x,y` : Dessine une ligne jusqu'à (x,y)

  - `H x` : Dessine une ligne horizontale jusqu'à x

  - `V y` : Dessine une ligne verticale jusqu'à y

  - `C x1,y1 x2,y2, x3,y3` : Dessine une courbe de bézier jusqu'à (x3,y3) avec (x1,y1) et (x2,y2) comme points de contrôle.

  - `S x1,y1 x2,y2` : Même chose qu'au-dessus, mais dessine un bézier lisse : le premier point de contrôle est déduit du bézier précédent.

  - `Z` : Ferme le chemin.

  Si le chemin est fermé avec `z` ou `Z`, il peut être rempli. Autrement, il est juste dessiné.

- `<svg:text x="..." y="..." style="...">...</svg:text>`

  Un texte dans la forme. Le texte doit se situer entre les balises.

  Les paramètres sont :

  - `x,y` : La position du texte

  - `style` : Les options de formatage de texte

    Les options de style sont les suivantes :

    - `font-size` : Taille de la fonte en &og;pt&fg; (point)

## Description de feuille (sheet)

Vous pouvez disposer plusieurs formes dans une feuille : les formes que vous créez ou toute forme &og;appartenant&fg; à d'autres feuilles.

Une &og;feuille&fg; simple pourrait ressembler à ceci :

    <?xml version="1.0" encoding="utf-8"?>
    <sheet xmlns="http://www.lysator.liu.se/~alla/dia/dia-sheet-ns">
      <name>Circuit with identifiers</name>
      <name xml:lang="es">Circuito con identificadores</name>
      <name xml:lang="fr">Circuit avec identifiants</name>
      <description>Components for circuit diagrams</description>
      <description xml:lang="es">Componentes para diagramas de circuitos</description>
      <description xml:lang="fr">Composants pour les diagrammes de circuits</description>
      <contents>
        <object name="Circuit with identifiers - NPN Transistor">
         <description>A bipolar npn transistor</description>
         <description xml:lang="es">Un transistor bipolar npn identificable</description>
         <description xml:lang="fr">Un transistor bipolaire npn identifiable</description>
        </object>
        <object name="UML - Objet">
         <description>An UML object</description>
         <description xml:lang="es">Un objeto UML</description>
         <description xml:lang="fr">Un objet UML</description>
        </object>
       </contents>
    </sheet>

## De comment Dia vous aide à gérer les feuilles et les formes

Vous pouvez utiliser Dia avec ses éléments existants pour dessiner une forme. Pour l'exporter dans un fichier shape, en utilisant Fichier Exporter avec comme option d'exportation Déterminer le type de fichier Fichier de forme Dia (*.shape)

Mais jusqu'ici, ces &og;shapes&fg; n'ont pas de boîte de texte (Elles peuvent avoir des éléments svg:text mais pas de boîte de texte). Si vous en avez besoin, vous pouvez éditer le fichier.

Avec le fichier shape, vient également un fichier png (après avoir accepté la taille proposée) qui peut être utilisé comme l'icône pour la forme.

Choisissez Fichier(du menu principal)Feuilles et objets pour créer de nouvelles feuilles, et ajouter, enlever, éditer partiellement les formes, et copier ou passer les formes d'une feuille à l'autre.

## Notes de conception

Le code &og;custom shape&fg; est conçu pour qu'une feuille d'objets puisse être contenue dans un seul répertoire. Installer des formes peut être aussi simple que de décompresser un fichier .tar.gz dans ~/.dia/shapes ou $(prefix)/share/dia/shapes, avec la description de feuille (.sheet) allant dans ~/.dia/sheets

Si vous avez des suggestions à-propos de ce code, dites-le moi (ndt: en anglais...).

James Henstridge james@daa.com.au, avec des modifications apportées par Dolores Alia de Saravia loli@unsa.edu.ar