More samples in the graphic help pages Note that they are automatically generated...
[scilab.git] / scilab / modules / graphics / help / en_US / bar_histogram / barh.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Farid Belahcene
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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" version="5.0-subset Scilab" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="barh">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>barh</refname>
19     <refpurpose>horizontal display of bar histogram</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>barh(y)
24       barh(x,y)
25       barh([h],x,y [,width [,color [,style]]])
26     </synopsis>
27   </refsynopsisdiv>
28   <refsection>
29     <title>Arguments</title>
30     <variablelist>
31       <varlistentry>
32         <term>h</term>
33         <listitem>
34           <para>an axes handle, (default: h=gca() ).</para>
35         </listitem>
36       </varlistentry>
37       <varlistentry>
38         <term>y</term>
39         <listitem>
40           <para>a real scalar, vector of size N, or a matrice N*M.</para>
41         </listitem>
42       </varlistentry>
43       <varlistentry>
44         <term>x</term>
45         <listitem>
46           <para>a real scalar or a vector of size N, (default: if y is a
47             vector then x is a vector and x length equals to y length. If y is a
48             matrix then x is a vector and x length equals to the lines number of
49             y.
50           </para>
51         </listitem>
52       </varlistentry>
53       <varlistentry>
54         <term>width</term>
55         <listitem>
56           <para>(optional), a real scalar, defines the width (a percentage of
57             the available room) for the bar (default: 0.8, i.e=80%).
58           </para>
59         </listitem>
60       </varlistentry>
61       <varlistentry>
62         <term>color</term>
63         <listitem>
64           <para>(optional), a string (default: 'blue'), specifying the inside
65             color bar.
66           </para>
67         </listitem>
68       </varlistentry>
69       <varlistentry>
70         <term>style:</term>
71         <listitem>
72           <para>a string, 'grouped' or 'stacked' (default: 'grouped').</para>
73         </listitem>
74       </varlistentry>
75     </variablelist>
76   </refsection>
77   <refsection>
78     <title>Description</title>
79     <para>
80       <literal>barh(y,...) :</literal> if y is a vector then bar function draws a
81       polyline which has the <literal>polyline_style</literal> type 6. If y is a
82       vector, bar draws vector y versus vector x=1:size(y,'*') . If y is a
83       matrix N*M, bar draws M polylines (type 6), each polyline corresponds to a
84       column of y versus vector x=1:size(y,1).
85     </para>
86     <para>
87       <literal>barh(x,y,...) :</literal> if y is a vector then bar function draws a
88       polyline which has the <literal>polyline_style</literal> type 6, where x length
89       = y length. If y is a matrix NxM then bar function draws M polylines which
90       have the type 6. Each polyline corresponds to a column of y versus vector
91       x.
92     </para>
93     <para>
94       <literal>barh(h,...) :</literal> defines the current axes where the drawing
95       is performed.
96     </para>
97     <para>
98       <literal>barh(...,width,...) :</literal> defines the width of the bar(s) in
99       percentage (generally: 0&lt;width&lt;1).
100     </para>
101     <para>
102       <literal>barh(...,style,...) :</literal> defines how the bar is drawn. If y
103       is a matrix N*M (so M polylines of type 6) then there are two ways to draw
104       the M bars. the style option = 'grouped' allows to center the M polylines
105       versus each components of x, and the style option = 'stacked' allows to
106       stack them.
107     </para>
108     <para>
109       <literal>barh(...,color,...) : </literal>defines the bar color. Bar functions
110       uses the same colormap than in the <literal>plot</literal> function.
111     </para>
112     <para>
113       If there are several bar calls, the <literal>barhomogenize</literal> function
114       allows to homegenize the width and style of all bars (i.e polylines of
115       type 6) included in the current working axes.
116     </para>
117   </refsection>
118   
119   <refsection>
120     <title>Sample</title>
121     <scilab:image>
122       x=[1 2 5];
123       y=[1  -5 6;3 -2 7;4  -3 8];
124       barh(x,y);
125     </scilab:image>
126   </refsection>
127   
128   <refsection>
129     <title>Examples</title>
130     <programlisting role="example"><![CDATA[ 
131 // 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)
132 scf(0);
133 y=[1 -3 5];
134 barh(y,0.5,'yellow');
135  ]]></programlisting>
136     
137     <programlisting role="example"><![CDATA[ 
138 // Second example: draw 3 bars (i.e 3 polylines with polyline_style type =6),default style='grouped'
139 scf(1);
140 x=[1 2 5];
141 y=[1  -5 6;3 -2 7;4  -3 8];
142 barh(x,y);
143  ]]></programlisting>
144     
145     <programlisting role="example"><![CDATA[ 
146 // Third example : style='stacked'.
147 scf(2);
148 x=[1 2 5];
149 y=[1 4 7;2 5 8;3 6  9];
150 barh(x,y,'stacked');
151  ]]></programlisting>
152     
153     <programlisting role="example"><![CDATA[ 
154 // Fourth example: width=0.2;color='green'; default style='grouped'
155 scf(3);
156 x=[1 2 5];
157 y=[1 4 7;2 5 8;3 6 9];
158 barh(x,y,0.2,'green');
159  ]]></programlisting>
160   </refsection>
161   <refsection role="see also">
162     <title>See Also</title>
163     <simplelist type="inline">
164       <member>
165         <link linkend="bar">bar</link>
166       </member>
167       <member>
168         <link linkend="barhomogenize">barhomogenize</link>
169       </member>
170       <member>
171         <link linkend="plot">plot</link>
172       </member>
173       <member>
174         <link linkend="polyline_properties">polyline_properties</link>
175       </member>
176     </simplelist>
177   </refsection>
178 </refentry>