More samples in the graphic help pages Note that they are automatically generated...
[scilab.git] / scilab / modules / graphics / help / en_US / bar_histogram / barhomogenize.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="barhomogenize">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>barhomogenize</refname>
19     <refpurpose>homogenize all the bars included in the current working axes</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>barhomogenize()
24       barhomogenize([h[,'style'[,'width']]])
25     </synopsis>
26   </refsynopsisdiv>
27   <refsection>
28     <title>Arguments</title>
29     <variablelist>
30       <varlistentry>
31         <term>h</term>
32         <listitem>
33           <para>an axes handle, (default: h=gca() ).</para>
34         </listitem>
35       </varlistentry>
36       <varlistentry>
37         <term>style</term>
38         <listitem>
39           <para>a string, 'grouped' or 'stacked' (default: 'grouped').</para>
40         </listitem>
41       </varlistentry>
42       <varlistentry>
43         <term>width</term>
44         <listitem>
45           <para>(optional), a real scalar, defines the width (a percentage of
46             the available room) for the bar (default: 0.8).
47           </para>
48         </listitem>
49       </varlistentry>
50     </variablelist>
51   </refsection>
52   <refsection>
53     <title>Description</title>
54     <para>
55       If there are several bar calls, the <literal>barhomogenize</literal> function
56       allows to homogenize the width and style of all bars (i.e which has the
57       <literal>polyline_style</literal> type 6) included in the current working axes.
58       These bars must have the same x data.
59     </para>
60     <para>
61       <literal>barhomogenize( ) :</literal> takes the default values, h=gca(),
62       width=0.8, style='grouped'. <literal/>
63     </para>
64     <para>
65       <literal>barhomogenize(h,...) :</literal> defines the current axes where the
66       drawing is performed.
67     </para>
68     <para>
69       <literal>barhomogenize(...,width,...) :</literal> defines the width of the
70       bar(s) in percentage (generally: 0&lt;width&lt;=1).
71     </para>
72     <para>
73       <literal>barhomogenize(...,style,...) :</literal> defines how the bars are
74       drawn. The 'grouped' option allows to center the M polylines versus each
75       components of x, and the 'stacked' option allows to stack them.
76     </para>
77   </refsection>
78   
79   <refsection>
80     <title>Sample</title>
81     <scilab:image>
82       subplot(2,3,1)
83       xtitle('ex1: creation of 1 yellow bar and 3 bars')
84       x=1:3;
85       y1=1:3;
86       y2=[4 3 5;6 7 8;9 10 11];
87       bar(x,y1,'yellow');bar(x,y2);
88       
89       subplot(2,3,2) 
90       xtitle('grouped homogenisation')
91       x=1:3;
92       y1=1:3;
93       y2=[4 3 5;6 7 8;9 10 11];
94       bar(x,y1,'yellow');bar(x,y2);
95       barhomogenize();
96       
97       subplot(2,3,3)
98       xtitle('stacked homogenisation')
99       x=1:3; y1=1:3; y2=[4 3 5;6 7 8;9 10 11];
100       bar(x,y1,'yellow');bar(x,y2);
101       barhomogenize('stacked',1);
102     </scilab:image>
103   </refsection>
104   
105   <refsection>
106     <title>Examples</title>
107     <programlisting role="example"><![CDATA[ 
108 // First example: creation of 1 yellow bar (i.e 1 polyline with polyline_style=6) and 3 bars (i.e 3 polylines with polyline_style=6) 
109 subplot(2,3,1)
110 xtitle('ex1: creation of 1 yellow bar and 3 bars')
111 x=1:3;
112 y1=1:3;
113 y2=[4 3 5;6 7 8;9 10 11];
114 bar(x,y1,'yellow');bar(x,y2);
115
116 // grouped homogenisation of these 4 bars
117 subplot(2,3,2) 
118 xtitle('grouped homogenisation')
119 x=1:3;
120 y1=1:3;
121 y2=[4 3 5;6 7 8;9 10 11];
122 bar(x,y1,'yellow');bar(x,y2);
123 barhomogenize();
124
125 // stacked homogenisation of the 4 bars
126 subplot(2,3,3)
127 xtitle('stacked homogenisation')
128 x=1:3; y1=1:3; y2=[4 3 5;6 7 8;9 10 11];
129 bar(x,y1,'yellow');bar(x,y2);
130 barhomogenize('stacked',1);
131
132 // Second example : creation of 1 red bar (i.e 1 polyline with polyline_style=6) and 2 polylines with type=1 (calling plot function)
133 subplot(2,3,4)
134 xtitle('ex2: creation of 1 bar and 2 polylines')
135 x=1:10;
136 y=sin(x)/2;
137 bar(x,y,'red')
138 x1=1:10;
139 y1=[sin(x);cos(x)]
140 plot(x1,y1)
141
142 // modify the polyline_style type of the second polyline from plot (this polyline becomes a bar)
143 subplot(2,3,5)
144 xtitle('transformation of the second polyline to bar')
145 x=1:10; 
146 y=sin(x)/2;
147 bar(x,y,'red')
148 x1=1:10;
149 y1=[sin(x);cos(x)]
150 plot(x1,y1)
151 e=gce();
152 e2=e.children(2);
153 e2.polyline_style=6;
154
155 // homogenisation of the first bar (from bar function) and second bar (from the modification). 
156 subplot(2,3,6)
157 xtitle('grouped homogenisation')
158 x=1:10; 
159 y=sin(x)/2;
160 bar(x,y,'red')
161 x1=1:10;
162 y1=[sin(x);cos(x)]
163 plot(x1,y1)
164 e=gce();
165 e2=e.children(2);
166 e2.polyline_style=6;
167 barhomogenize();
168 // change the style and the width
169 //barhomogenize('stacked',0.5);
170 //barhomogenize('stacked',1);
171  ]]></programlisting>
172   </refsection>
173   <refsection role="see also">
174     <title>See Also</title>
175     <simplelist type="inline">
176       <member>
177         <link linkend="bar">bar</link>
178       </member>
179       <member>
180         <link linkend="polyline_properties">polyline_properties</link>
181       </member>
182     </simplelist>
183   </refsection>
184 </refentry>