<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Farid Belahcene
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="barh" xml:lang="pt">
    <refnamediv>
        <refname>barh</refname>
        <refpurpose>Exibição horizontal de um histograma de barras</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>barh(y)
            barh(x,y)
            barh([h],x,y [,width [,color [,style]]])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                    <para>manipulador de eixos, (padrão: h=gca() ). </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>escalar real, vetor de tamanho N ou uma matriz NxM. </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>escalar real ou um vetor de tamanho N, (padrão: se y é um
                        vetor, então x é um vetor e o comprimento de x é igual ao
                        comprimento de y. Se y é uma matriz, então x é um vetor e o
                        comprimento de x é igual ao número de linhas de y)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>width</term>
                <listitem>
                    <para>(opcional), escalar real, define a largura (uma porcentagem do
                        espaço disponível) para a barra (padrão: 0.8, i.e. 80%).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>color</term>
                <listitem>
                    <para>(opcional), um string (padrão: 'blue'), especificando a cor
                        interior da barra barra.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style:</term>
                <listitem>
                    <para>string, 'grouped' ou 'stacked' (padrão: 'grouped').</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            <literal>barh(y,...) :</literal> se y é um vetor então a função bar
            desenha uma poligonal que tem <literal>polyline_style</literal> tipo 6. Se
            y for um vetor, desenha o vetor y versus o vetor 1:size(y,'*'). Se y for
            uma matriz N*M, bar desenha M poligonais (tipo 6), cada poligonal
            corresponde a uma coluna de y versus o vetor x=1:size(y,1)
        </para>
        <para>
            <literal>barh(x,y,...) :</literal> se y for um vetor então a função
            desenha uma poligonal que tem <literal>polyline_style</literal> tipo 6,
            onde comprimento de x = comprimento de y. Se y é uma matriz NxM então a
            função desenha M poligonais que possuem tipo 6. Cada poligonal corresponde
            a uma coluna de y versus o vetor x.
        </para>
        <para>
            <literal>barh(h,...) :</literal> define os eixos correntes onde o
            desenho é realizado.
        </para>
        <para>
            <literal>barh(...,width,...) :</literal> define a largura da(s)
            barra(s) em porcentagem (geralmente: 0&lt;width&lt;1).
        </para>
        <para>
            <literal>barh(...,style,...) :</literal> define como as barras serão
            desenhadas. Se y é uma matriz NxM (então temos M poligonais de tipo 6)
            então há dois modos de se desenhar as M barras. A opção style= 'grouped'
            permite centrar as M poligonais versus cada componente de x, e a opção
            style = 'stacked' permite empilhá-las.
        </para>
        <para>
            <literal>barh(...,color,...) : </literal>define a cor da barra.
            Funções de barra utilizam o mesmo mapa de cores que na função
            <literal>plot</literal>.
        </para>
        <para>Se há várias chamadas a barh, a função
            <literal>barhomogenize</literal> permite homogeneizar a largura e estilo
            de todas as barras (i.e poligonais do tipo 6) inclusas nos eixos
            correntes.
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
// primeiro exemplo: desenhando uma barra (i.e uma poligonal com polyline_style =6),style='grouped', width=0.5, color='yellow', x=1:length(y)
scf(0);
y=[1 -3 5];
barh(y,0.5,'yellow');

// segundo exemplo: desenhando três barras (i.e três poligonais com polyline_style =6),style='grouped'
scf(1);
x=[1 2 5]; y=[1  -5 6;3 -2 7;4  -3 8];
barh(x,y);

// terceiro exemplo: style='stacked'.
scf(2);
x=[1 2 5]; y=[1 4 7;2 5 8;3 6  9];
barh(x,y,'stacked');

// quarto exemplo: width=0.2;color='green'; style='grouped'
scf(3);
x=[1 2 5]; y=[1 4 7;2 5 8;3 6 9];
barh(x,y,0.2,'green');
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="bar">bar</link>
            </member>
            <member>
                <link linkend="barhomogenize">barhomogenize</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="polyline_properties">polyline_properties</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
