<?xml version="1.0" encoding="UTF-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
          xml:lang="fr" xml:id="bar">
    <refnamediv>
        <refname>bar</refname>
        <refpurpose>histogramme de barres</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            bar(y)
            bar(x, y)
            bar(x, y, width, colors, style)
            bar(x, y [,width] [,colors] [,style])
            bar(h, x, y ..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                    <para>un pointeur sur les axes, (par défaut: h=gca() ).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                       scalaire, vecteur de taille N, ou matrice (N_lignes * M_colonnes) de nombres
                       réels ou d'entiers encodés, avec
                      <itemizedlist>
                        <listitem>
                          N : nombre de groupes de barres. Chaque groupe est rassemblé à (proximité
                          de) la position x dédiée.
                        </listitem>
                        <listitem>
                          M : nombre de catégories = nombre de barres dans chaque groupe.
                        </listitem>
                      </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>scalaire, ou vecteur de taille N. Par défaut,
                      <itemizedlist>
                        <listitem>
                          Si <varname>y</varname> est un vecteur : <literal>x=1:length(y)</literal>
                        </listitem>
                        <listitem>
                          Si <varname>y</varname> est une matrice : <literal>x=1:size(y,"r")</literal>
                        </listitem>
                      </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>width</term>
                <listitem>
                    <para>
                      (optionnel), un scalaire, définit l'épaisseur des barres (un pourcentage
                      de l'epaisseur maximum autorisé pour une barre), par défaut: width=0.8,
                      i.e 80%.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>colors</term>
                <listitem>
                    <para>
                        (option) String unique (commune), ou vecteur de M strings : noms des
                        couleurs des M catégories (choisis dans la liste Scilab des noms prédéfinis),
                        ou codes hexadécimaux de celles-ci (du type "#RRGGBB"). Par défaut, la
                        série de couleurs utilisées par défaut par plot() est utilisée, commençant
                        par "blue".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style</term>
                <listitem>
                    <para>
                      (option) 'grouped' (par défaut), ou 'stacked'.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>bar(y,...) :</literal> si y est un vecteur, alors bar()
            dessine une polyline unique de type <literal>polyline_style=6</literal>, avec
            <literal>x=1:length(y)</literal>. Si y est une matrice de taille N*M, alors bar()
            dessine M polylines de (type 6), avec x=1:size(y,1) ; chaque polyline correspond alors
            à une colonne de y, et à une catégorie, avec sa propre couleur .
        </para>
        <para>
            <literal>bar(x,y,...) :</literal> comme <literal>bar(y,...) :</literal>, mais en
            indiquant explicitement les N positions x des groupes.
        </para>
        <para>
            <literal>bar(h,...) :</literal> definit les axes courants ou le dessin est
            réalisé.
        </para>
        <para>
            <literal>bar(...,width,...) :</literal> definit la largeur relative des barres :
            0&lt;width&lt;=1.
        </para>
        <para>
            <literal>bar(...,style,...) :</literal> dans le cas ou y est une matrice
            l'option style definit la façon dont les barres sont positionnées les unes
            par rapport aux autres. Si y est une matice N*M (donc M polylines de type
            6) alors il y a 2 façons de dessiner ces M barres. l'option style fixée à
            grouped' permet de centrer les M polylines par rapport aux abscisses (i.e
            par rapport à chaque composantes de x), et l'option style fixée à
            'stacked' permet de les empiler.
        </para>
        <para>
            <literal>bar(...,colors,...) : </literal> definit les couleurs des catégories de barres.
            Toutes les barres d'une même catégorie sont remplies avec la même couleur.
        </para>
        <para>S'il y a plusieurs appels à la fonction bar(), la fonction
            <literal>barhomogenize</literal> permet d'homogénéiser l'épaisseur et le style
            de toutes les barres (i.e les polylines de type 6) inclus dans les axes
            courrants.
        </para>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <programlisting role="example"><![CDATA[
// Premier exemple : dessine une barre, avec les paramètres width=0.5
// et colors='yellow' et par défaut x=1:length(y), style = 'grouped'.
scf(0);
y=[1 -3 5];
bar(y,0.5,'yellow');
 ]]></programlisting>

        <scilab:image>
            y=[1 -3 5];
            bar(y,0.5,'yellow');
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Deuxième exemple : par défaut style='grouped'
scf(1);
x=[1 2 5]; y=[1  -5 6;3 -2 7;4  -3 8];
bar(x,y);
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1  -5 6;3 -2 7;4  -3 8];
            bar(x,y);
        </scilab:image>

        <programlisting role="example"><![CDATA[
// Troisième exemple : dessine 3 bars (nombre de colonnes de y) style='stacked'.
scf(2);
x=[1 2 5]; y=[1 4 7;2 5 8;3 6  9];
bar(x,y,'stacked');
 ]]></programlisting>


        <scilab:image>
            x=[1 2 5];
            y=[1 4 7;2 5 8;3 6  9];
            bar(x,y,'stacked');
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Quatrième exemple; width=0.2;colors='green'; par défaut style='grouped'
scf(3);
x=[1 2 5]; y=[1 4 7;2 5 8;3 6 9];
bar(x,y,0.2,'green');
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1 4 7;2 5 8;3 6 9];
            bar(x,y,0.2,'green');
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="barh">barh</link>
            </member>
            <member>
                <link linkend="barhomogenize">barhomogenize</link>
            </member>
            <member>
                <link linkend="histplot">histplot</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="color_list">couleurs prédéfinies</link>
            </member>
            <member>
                <link linkend="polyline_properties">polyline_properties</link>
            </member>
            <member>
                <link linkend="bar3d">bar3d</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Historique</title>
        <revhistory>
            <revision>
                <revnumber>6.0.1</revnumber>
                <revdescription>
                    <itemizedlist>
                      <listitem>
                        Un vecteur de M couleurs peut désormais être fourni, une couleur pour
                        chaque catégorie.
                      </listitem>
                      <listitem>
                        Les couleurs utilisables ne sont plus restreintes à la liste des 10 couleurs
                        majeures utilisées par plot(). Toutes les couleurs nommées prédéfinies
                        dans Scilab sont utilisables.
                      </listitem>
                      <listitem>
                        Les couleurs peuvent désormais être indiquées également par leur code
                        hexadécimal "#RRGGBB".
                      </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
