<chapter label="11" id="custom-shapes-chapter">
<title>Module Custom Shape</title>
  <sect1 id="custom-shapes-intro">
    <title>Introduction au module custom-shapes</title>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <para>
        <emphasis>Une</emphasis> 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.
      </para>
      <para>
        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.
      </para>
      <para>
        Dia prend soin du reste pour vous (changement de taille, de
        position, connexion de lignes, chargement, enregistrement, etc).
      </para>
    </sect1>
    <sect1 id='custom-shapes-shapes'>
      <title>Forme</title>

    <para>
        Un fichier de forme typique peut ressembler à ceci :
    <literallayout>
    <literal>
  &lt;?xml version="1.0"?&gt;

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

    &lt;aspectratio type="fixed"/&gt;

    &lt;textbox x1="4" y1="-3" x2="12" y2="3" /&gt;

    &lt;svg:svg&gt;
      &lt;svg:line x1="0" y1="0" x2="3" y2="0" /&gt;
      &lt;svg:line x1="3" y1="-3" x2="3" y2="3" /&gt;
      &lt;svg:line x1="3" y1="-2" x2="6" y2="-4" /&gt;
      &lt;svg:line x1="3" y1="2" x2="6" y2="4" /&gt;

      &lt;svg:polyline points="5,4 6,4 5.6154,3.0769" /&gt;
    &lt;/svg:svg&gt;

  &lt;/shape&gt;
    </literal>
    </literallayout>
    </para>
    <para>
        Seuls les éléments &og;<literal>name</literal>&fg; et 
        &og;<literal>svg</literal>&fg; sont requis dans le
        fichier shape. Le reste est optionnel.
    </para>
    <para>
        L'élément <literal>name</literal> donne le nom de l'objet. 
        Le nom est l'identifiant
        unique de cette forme, utilisé pour le chargement et l'enregistrement.
    </para>
    <para>
        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.
    </para>
    <para>
        L'élément &og;<literal>icon</literal>&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.
    </para>
    <para>
        La section &og;<literal>connections</literal>&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.
    </para>
    <para>
        L'élément &og;<literal>aspectratio</literal>&fg; 
        vous permet de spécifier
        quelles proportions
        de la forme peuvent être modifiées. Les trois possibilités
        sont :
    <itemizedlist>
    <listitem>
    <simpara>
    <literal>&lt;aspectratio type="free"/&gt;</literal>
    : tout ratio de proportions autorisé (le defaut)
    </simpara>
    </listitem>
    <listitem>
    <simpara>
    <literal>&lt;aspectratio type="fixed"/&gt;</literal>
    : la proportion est fixe.
    </simpara>
    </listitem>
    <listitem>
    <simpara>
    <literal>&lt;aspectratio type="range" min="n" max="m"/&gt;</literal>
    : Donne une plage de valeurs.
    </simpara>
    </listitem>
    </itemizedlist>
        La dernière option vous permet de spécifier une plage des valeurs
        de déformation, ce qui peut être utile dans certains cas.
    </para>
    <para>
        L'élément <literal>textbox</literal> vous permet 
        d'associer du texte[1] à la forme.
        La syntaxe est :
    <literallayout>
    <literal>
   &lt;textbox x1="left" y1="top" x2="right" y2="bottom"/&gt;
    </literal>
    </literallayout>
        (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.
    </para>
    <para>
	À 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:
	<simplelist>
	<member><literal><![CDATA[ <default-width>1cm</default-width> ]]></literal></member>
	<member><literal><![CDATA[ <default-height>1cm</default-height>  ]]></literal></member>
	</simplelist>
    </para>
    <para>
        L'élément <literal>svg</literal> 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 :
        <ulink type="http"
               url="http://www.w3.org/Graphics/SVG">http://www.w3.org/Graphics/SVG</ulink>
     </para>
     <para>
        La section suivante détaille quelles parties de la spécification
        SVG peuvent être utilisées dans un fichier shape.
     </para>
   </sect1>
   <sect1 id="custom-chapes-shape-desc">
   <title>Description de forme</title>
     <para>
        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.
     </para>
     <sect2 id="custom-shapes-shape-style-attribute">
     <title>Attribut style</title>
     <para>
        Chaque élément du dessin SVG prend en compte l'attribut
        &og;<literal>style</literal>&fg;.  L'attribut doit être de la forme :
     <literallayout>
    <literal>
  &lt;svg:toto style="name1: value1; name2: value2; ... name42: value42"/&gt;
    </literal>
     </literallayout>
     </para>
     <para>
        Actuellement, seuls les styles suivants sont interprétés :
     <itemizedlist>
       <listitem>
         <para>
          <literal>stroke-width</literal> : La largeur de ligne, 
                    relative à la largeur spécifiée
                    par l'utilisateur dans le tag svg.
         </para>
       </listitem>
       <listitem>
         <para>
          <literal>stroke-linecap</literal> : Le style des bouts de ligne.
                      Un parmi
                      <literal>butt</literal>, 
                      <literal>round</literal>,
                      <literal>square</literal>,
                      <literal>projecting</literal> (un synonyme de 
                      <literal>square</literal>),
                      ou <literal>default</literal>.
         </para>
       </listitem>
       <listitem>
         <para>
            <literal>stroke-linejoin</literal> : Le style des jointures.
                      Un parmi 
                      <literal>miter</literal>,
                      <literal>round</literal>,
                      <literal>bevel</literal>
                      ou <literal>default</literal>.
         </para>
       </listitem>
       <listitem>
         <para>
            <literal>stroke-pattern</literal> : Le motif de points.
                    Un parmi, 
                    <literal>dashed</literal>,
                    <literal>dash-dot</literal>,
                    <literal>dash-dot-dot</literal>,
                    <literal>dotted</literal>
                    ou <literal>default</literal>.
         </para>
       </listitem>
       <listitem>
         <para>
            <literal>stroke-dashlength</literal> : 
            La longueur des traits dans le motif précédent, en
                      relation avec la valeur spécifiée par
                      l'utilisateur 
                      (<literal>default</literal> est un synonyme pour 1.0).
         </para>
       </listitem>
       <listitem>
         <para>
            <literal>stroke</literal> : La couleur de ligne. 
                Vous pouvez utiliser un des noms
                 symboliques
                 <literal>foreground</literal>,
                 <literal>fg</literal>,
                 <literal>default</literal>,
                 <literal>background</literal>,
                 <literal>bg</literal>,
                 <literal>inverse</literal>,
                 <literal>text</literal> ou
                 <literal>none</literal>, ou utiliser une couleur
                 hexadécimale de forme <literal>#rrggbb</literal>.
         </para>
       </listitem>
       <listitem>
         <para>
            <literal>fill</literal>  : La couleur de remplissage. 
                Mêmes valeurs que pour
                 <literal>stroke</literal>, excepté que la signification 
                 de <literal>default</literal> et
                 <literal>inverse</literal> sont échangées.
                 Par défaut, les éléments ne
                 sont pas remplis, aussi, pour obtenir le remplissage
                 par défaut, utilisez "<literal>fill: default</literal>"
         </para>
       </listitem>
       </itemizedlist>
       <tip>
        <simpara>
            Pour dessiner un rectangle avec une ligne de largeur minimale
            (hairline), cette astuce devrait fontionner :
	</simpara>
            <literallayout>
            <literal>
  &lt;svg:rect style="stroke-width: 0" x="..." y="..." width="..." height="..."/&gt;
            </literal>
            </literallayout>
        </tip>
        </para>
        <para>
            Les ordonnées x et y grandissent comme dans Dia.
        </para>
      </sect2>
     <sect2 id="custom-shapes-shape-elements">
     <title>Éléments svg reconnus</title>
       <para> 
        Les éléments de dessin reconnus sont :
       </para>
         <itemizedlist>
           <listitem>
            <simpara>
               <literal>
        &lt;svg:g&gt;
               </literal>
            </simpara>
             <para>
        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).
             </para>
           </listitem>
           <listitem>
            <simpara>
               <literal>
        &lt;svg:line x1="..." y1="..." x2="..." y2="..."/&gt;
               </literal>
            </simpara>
             <para>
        Cet élément est une ligne.
             </para>
           </listitem>
           <listitem>
            <simpara>
                 <literal>
        &lt;svg:polyline points="...."/&gt;
                 </literal>
            </simpara>
              <para>
        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 
        "<literal>x1,y1 x2,y2 x3,y3 ...</literal>".
              </para>
           </listitem>
           <listitem>
            <simpara>
                <literal>
        &lt;svg:polygon points="...."/&gt;
                </literal>
            </simpara>
              <para>
        Ceci est un polygone. L'argument &og;points&fg; est du même format
        que celui de l'élément &og;polyline&fg;.
              </para>
           </listitem>
           <listitem>
            <simpara>
                 <literal>
        &lt;svg:rect x1="..." y1="..." width="..." height="..."/&gt;
                 </literal>
            </simpara>
              <para>
        Ceci est un rectangle. Le coin supérieur gauche est (x1,y1), et
        le coin inférieur droit est (x1+width,y1+height).
              </para>
           </listitem>
           <listitem>
            <simpara>
                 <literal>
        &lt;svg:image x1="..." y1="..." width="..." height="..." xlink:href="..." /&gt;
                 </literal>
            </simpara>
              <para>
        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
        "<literal>file:///home/user/image.png</literal>", ou relatif sans le préfixe
        <literal>file://</literal> comme dans "<literal>image.png</literal>".
        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<!-- <xref linkend="repertoire"/> -->.
        <!-- pour les unices, on parle bien de répertoire (directory) et non de
        dossier (folder), le dernier étant une fantaisie née de la mauvaise
        interprétation de l'interface graphique par les utilisateurs (la bonne
        interprétation étant un index de Rolodex(tm)). D'ailleurs, la commande
        Windows pour lister leur « dossier » est toujours "dir", et celle pour
        changer de répertoire est toujours "cd". Allez savoir pourquoi... -->
              </para>
        <note>
        <simpara>
    pour les unices, on parle bien de répertoire (directory) et non de
    dossier (folder). Par exemple les commande &og;<literal>cd</literal>&fg;
    (change directory),
    et, sous Windows, &og;<literal>dir</literal>&fg;.
        </simpara>
        </note>
           </listitem>
           <listitem>
            <simpara>
                 <literal>
        &lt;svg:circle cx="..." cy="..." r="..."/&gt;
                 </literal>
            </simpara>
              <para>
        Ceci est un cercle de centre (cx,cy) et de rayon r.
              </para>
           </listitem>
           <listitem>
            <simpara>
                 <literal>
        &lt;svg:ellipse cx="..." cy="..." rx="..." ry="..."/&gt;
                 </literal>
            </simpara>
              <para>
        Ceci est une ellipse de centre (cx, cy), de rayon rx dans la
        direction x, et de rayon ry dans la direction y.
              </para>
           </listitem>
           <listitem>
            <simpara>
                 <literal>
        &lt;svg:path d="...."/&gt;
                 </literal>
            </simpara>
              <para>
        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.
              </para>
              <para>
        Les commandes prises en charge sont :
                 <itemizedlist>
                    <listitem>
                       <para>
            <literal>M x,y</literal> :  Bouge le curseur
                       </para>
                    </listitem>
                    <listitem>
                       <para>
            <literal>L x,y</literal> : Dessine une ligne jusqu'à (x,y)
                       </para>
                    </listitem>
                    <listitem>
                       <para>
            <literal>H x</literal> : Dessine une ligne horizontale jusqu'à x
                       </para>
                    </listitem>
                    <listitem>
                       <para>
            <literal>V y</literal> : Dessine une ligne verticale jusqu'à y
                       </para>
                    </listitem>
                    <listitem>
                       <para>
            <literal>C x1,y1 x2,y2, x3,y3</literal> : Dessine une courbe de bézier jusqu'à (x3,y3)
                          avec (x1,y1) et (x2,y2) comme points de
                          contrôle.
                       </para>
                    </listitem>
                    <listitem>
                       <para>
            <literal>S x1,y1 x2,y2</literal> : 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.
                       </para>
                    </listitem>
                    <listitem>
                       <para>
            <literal>Z</literal> : Ferme le chemin.
                       </para>
                    </listitem>
                 </itemizedlist>
        
            Si le chemin est fermé avec <literal>z</literal> ou <literal>Z</literal>, il peut être rempli.
            Autrement, il est juste dessiné.
              </para>
            </listitem>
            <listitem>
            <simpara>
                <literal>
            &lt;svg:text x="..." y="..." style="..."&gt;...&lt;/svg:text&gt;
                </literal>
            </simpara>
              <para>
            Un texte dans la forme. Le texte doit se situer entre les balises.
              </para>
              <para>
            Les paramètres sont :
                <itemizedlist>
                  <listitem>
                    <para>
            <literal>x,y</literal> : La position du texte
                    </para>
                  </listitem>
                  <listitem>
                    <para>
            <literal>style</literal> : Les options de formatage de texte
                    </para>
                    <para>
            Les options de style sont les suivantes :
                       <itemizedlist>
                          <listitem>
                             <para>
                <literal>font-size</literal> : Taille de la fonte en &og;pt&fg; (point)
                <!-- du temps de grand-papa, on fondait des caractères
                en plomb. La police, elle, désigne l'ensemble des formes
                des caractères (Times, Helvetica...), pas leurs fontes -->
                            </para>
                          </listitem>
                       </itemizedlist>
                    </para>
                  </listitem>
                 </itemizedlist>
              </para>
            </listitem>
    </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id='custom-shapes-sheets'>
    <title>Description de feuille (sheet)</title>
      <para>
        Vous pouvez disposer plusieurs formes dans une feuille : les
        formes que vous créez ou toute forme &og;appartenant&fg; à
        d'autres feuilles.
      </para>
      <para>
        Une &og;feuille&fg; simple pourrait ressembler à ceci :
      <literallayout>  
            <literal>
&lt;?xml version="1.0" encoding="utf-8"?&gt; 
&lt;sheet xmlns="http://www.lysator.liu.se/~alla/dia/dia-sheet-ns"&gt;
  &lt;name&gt;Circuit with identifiers&lt;/name&gt;
  &lt;name xml:lang="es"&gt;Circuito con identificadores&lt;/name&gt;
  &lt;name xml:lang="fr"&gt;Circuit avec identifiants&lt;/name&gt;
  &lt;description&gt;Components for circuit diagrams&lt;/description&gt;
  &lt;description xml:lang="es"&gt;Componentes para diagramas de circuitos&lt;/description&gt;
  &lt;description xml:lang="fr"&gt;Composants pour les diagrammes de circuits&lt;/description&gt;
  &lt;contents&gt;
    &lt;object name="Circuit with identifiers - NPN Transistor"&gt;
     &lt;description&gt;A bipolar npn transistor&lt;/description&gt;
     &lt;description xml:lang="es"&gt;Un transistor bipolar npn identificable&lt;/description&gt;
     &lt;description xml:lang="fr"&gt;Un transistor bipolaire npn identifiable&lt;/description&gt;
    &lt;/object&gt;
    &lt;object name="UML - Objet"&gt;
     &lt;description&gt;An UML object&lt;/description&gt;
     &lt;description xml:lang="es"&gt;Un objeto UML&lt;/description&gt;
     &lt;description xml:lang="fr"&gt;Un objet UML&lt;/description&gt;
    &lt;/object&gt;
   &lt;/contents&gt;
&lt;/sheet&gt;
            </literal>
    </literallayout>
    </para>
  </sect1>
  <sect1 id='custom-shapes-managing'>
    <title>De comment Dia vous aide à gérer les feuilles et les
    formes</title>
    <para>
        Vous pouvez utiliser Dia avec ses éléments existants pour dessiner une
        forme. Pour l'exporter dans un fichier shape, en utilisant
        <menuchoice><guimenu>Fichier</guimenu><guimenuitem>Exporter</guimenuitem></menuchoice>
        avec comme option d'exportation
        <menuchoice><guimenu>Déterminer le type de
        fichier</guimenu><guimenuitem>Fichier de forme Dia
        (*.shape)</guimenuitem></menuchoice>
    </para>
    <para>
        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.
    </para>
    <para>    
        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.
    </para>
    <para>
        Choisissez <menuchoice><guimenu>Fichier(du menu
        principal)</guimenu><guimenuitem>Feuilles et
        objets</guimenuitem></menuchoice> pour créer de nouvelles
        feuilles, et ajouter, enlever, éditer partiellement les formes,
        et copier ou passer les formes d'une feuille à l'autre.
    </para>
  </sect1>
  <sect1 id="custom-shapes-code">
  <title>Notes de conception</title>
    <para>
        Le code &og;custom shape&fg; est conçu pour qu'une feuille
        d'objets puisse être contenue dans un seul 
        répertoire<!-- <xref linkend="repertoire"/> -->. 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
    </para>
    <para>
        Si vous avez des suggestions à-propos de ce code, dites-le moi
        (ndt: en anglais...).
    </para>
    <para>
        James Henstridge <email>james@daa.com.au</email>,
        avec des modifications apportées par
        Dolores Alia de Saravia <email>loli@unsa.edu.ar</email>     
    </para>
  </sect1>
  <!--
  <glossary>
  <title>Glossaire</title>
    <glossentry>
    <glossterm>répertoire :</glossterm>
    <glossdef>
    <para id="repertoire">
    pour les unices, on parle bien de répertoire (directory) et non de
    dossier (folder). Par exemple les commande &og;<literal>cd</literal>&fg;
    (change directory),
    et, sous Windows, &og;<literal>dir</literal>&fg;.
    </para>
    </glossdef>
    </glossentry>
  </glossary>
  -->
</chapter>
