<?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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="barh">
    <refnamediv>
        <refname>barh</refname>
        <refpurpose>horizontal display of bar histogram</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>barh(y)
            barh(x,y)
            barh([h],x,y [,width [,color [,style]]])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                    <para>an axes handle, (default: h=gca() ).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>a real scalar, vector of size N, or a matrix N*M.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>a real scalar or a vector of size N, (default: if y is a
                        vector then x is a vector and x length equals to y length. If y is a
                        matrix then x is a vector and x length equals to the lines number of
                        y.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>width</term>
                <listitem>
                    <para>(optional), a real scalar, defines the width (a percentage of
                        the available room) for the bar (default: 0.8, i.e=80%).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>color</term>
                <listitem>
                    <para>(optional), a string (default: 'blue'), specifying the inside
                        color bar.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style:</term>
                <listitem>
                    <para>a string, 'grouped' or 'stacked' (default: 'grouped').</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>barh(y,...) :</literal> if y is a vector then bar function draws a
            polyline which has the <literal>polyline_style</literal> type 6. If y is a
            vector, bar draws vector y versus vector x=1:size(y,'*') . If y is a
            matrix N*M, bar draws M polylines (type 6), each polyline corresponds to a
            column of y versus vector x=1:size(y,1).
        </para>
        <para>
            <literal>barh(x,y,...) :</literal> if y is a vector then bar function draws a
            polyline which has the <literal>polyline_style</literal> type 6, where x length
            = y length. If y is a matrix NxM then bar function draws M polylines which
            have the type 6. Each polyline corresponds to a column of y versus vector
            x.
        </para>
        <para>
            <literal>barh(h,...) :</literal> defines the current axes where the drawing
            is performed.
        </para>
        <para>
            <literal>barh(...,width,...) :</literal> defines the width of the bar(s) in
            percentage (generally: 0&lt;width&lt;1).
        </para>
        <para>
            <literal>barh(...,style,...) :</literal> defines how the bar is drawn. If y
            is a matrix N*M (so M polylines of type 6) then there are two ways to draw
            the M bars. the style option = 'grouped' allows to center the M polylines
            versus each components of x, and the style option = 'stacked' allows to
            stack them.
        </para>
        <para>
            <literal>barh(...,color,...) : </literal>defines the bar color. Bar functions
            uses the same colormap than in the <literal>plot</literal> function.
        </para>
        <para>
            If there are several bar calls, the <literal>barhomogenize</literal> function
            allows to homogenize the width and style of all bars (i.e polylines of
            type 6) included in the current working axes.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// First example: draw a bar (i.e a polyline with polyline_style type =6),default style='grouped', width=0.5, color='yellow', default x=1:length(y)
scf(0);
y=[1 -3 5];
barh(y,0.5,'yellow');
 ]]></programlisting>
        <scilab:image>
            y=[1 -3 5];
            barh(y,0.5,'yellow');
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Second example: draw 3 bars (i.e 3 polylines with polyline_style type =6),default style='grouped'
scf(1);
x=[1 2 5];
y=[1  -5 6;3 -2 7;4  -3 8];
barh(x,y);
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1  -5 6;3 -2 7;4  -3 8];
            barh(x,y);
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Third example : style='stacked'.
scf(2);
x=[1 2 5];
y=[1 4 7;2 5 8;3 6  9];
barh(x,y,'stacked');
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1 4 7;2 5 8;3 6  9];
            barh(x,y,'stacked');
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Fourth example: width=0.2;color='green'; default 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>
        <scilab:image>
            x=[1 2 5];
            y=[1 4 7;2 5 8;3 6 9];
            barh(x,y,0.2,'green');
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</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>
