* Bug 6070 fixed [doc]: Documenting How to make multiscaled plots
[scilab.git] / scilab / modules / graphics / help / en_US / axis / drawaxis.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) ENPC - Jean-Philippe Chancelier
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="drawaxis">
17     <refnamediv>
18         <refname>drawaxis</refname>
19         <refpurpose>draw an axis</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             drawaxis([options]); // options: x,y,dir,sub_int,fontsize,format_n,seg,textcolor,ticscolor,tics
25             e = drawaxis([options]);
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>dir=string</term>
33                 <listitem>
34                     <para>
35                         used to specify the tics direction. <literal>string</literal> can be chosen among   'u','r','d','l' and 'l' is the default value. the values 'u','r','d','l' stands respectively for up, right, down, left
36                     </para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>tics=string</term>
41                 <listitem>
42                     <para>
43                         A flag which describes how the tics are given.   <literal>string</literal> can be chosen among 'v','r', and 'i', and, 'v' is the default value
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>x,y</term>
49                 <listitem>
50                     <para>two vectors which give tics positions.</para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>val= string matrix</term>
55                 <listitem>
56                     <para>A string matrix, which, when given, gives the string to be drawn along the axis at tics positions.</para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>fontsize=int</term>
61                 <listitem>
62                     <para>
63                         specifies the fontsize to use for displaying values along the axis. Default value is <literal>-1</literal> which stands for current fontsize
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>format_n=string</term>
69                 <listitem>
70                     <para>
71                         format to use for displaying numbers along the axis, where <literal>string</literal> gives the format according to the C language
72                         printf function format syntax (for example <literal>string="%.3f"</literal>).
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>seg= 1 or 0</term>
78                 <listitem>
79                     <para>A flag which controls the display of the base segment of the axis (default value is 1).</para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>sub_int=integer</term>
84                 <listitem>
85                     <para>an integer which gives the number of sub-intervals to draw  between large tics.</para>
86                 </listitem>
87             </varlistentry>
88             <varlistentry>
89                 <term>textcolor=integer</term>
90                 <listitem>
91                     <para>
92                         specify the color to use for displaying values along the axis. Default value is <literal>-1</literal> which stands for current color.
93                     </para>
94                 </listitem>
95             </varlistentry>
96             <varlistentry>
97                 <term>ticscolor=integer</term>
98                 <listitem>
99                     <para>
100                         specify the color to use for tics drawing. Default value is <literal>-1</literal> which stands for current color.
101                     </para>
102                 </listitem>
103             </varlistentry>
104             <varlistentry>
105                 <term>e</term>
106                 <listitem>
107                     <para>
108                         handle, the handle of the created axis.
109                     </para>
110                 </listitem>
111             </varlistentry>
112         </variablelist>
113     </refsection>
114     <refsection>
115         <title>Description</title>
116         <para>
117             <literal>drawaxis</literal> is used to draw an axis in vertical or horizontal
118             direction. This function returns the handle of the created axis.
119             The direction of the axis is given by dir
120             <literal>dir = 'u'</literal> or <literal>'d'</literal> gives a horizontal axis
121             with tics going up (<literal>'u'</literal>) or down (<literal>'d'</literal>).
122             <literal>dir = 'r'</literal> or <literal>'l'</literal> give a vertical axis
123             with tics going right (<literal>'r'</literal>) or left (<literal>'l'</literal>).
124         </para>
125         <para>
126             <literal>x</literal> and <literal>y</literal> give the axis tics positions.
127             If the axis is horizontal then <literal>y</literal>
128             must be a scalar or can be omitted and <literal>x</literal>
129             is a Scilab vector. The meaning of <literal>x</literal>
130             is controlled by <literal>tics</literal>.
131         </para>
132         <para>
133             If <literal>tics='v'</literal> then <literal>x</literal> gives the tics positions along the x-axis.
134         </para>
135         <para>
136             If <literal>tics='r'</literal> then <literal>x</literal> must be of size 3. <literal>x=[xmin,xmax,n]</literal> and
137             <literal>n</literal> gives the number of intervals.
138         </para>
139         <para>
140             If <literal>tics='i'</literal> then <literal>x</literal> must be of size 4, <literal>x=[k1,k2,a,n]</literal>.
141             then <literal>xmin=k1*10^a</literal>, <literal>xmax=k2*10^a</literal> and <literal>n</literal> gives the number of intervals
142         </para>
143         <para>
144             If <literal>y</literal> is omitted then the axis will be positioned at
145             the top of the frame if <literal>dir='u'</literal> or at the bottom if  <literal>dir='d'</literal>
146         </para>
147         <para>
148             By default, numbers are drawn along the axis. They are drawn using
149             a default format which can be changed with <literal>format_n</literal>.
150             It is also possible to display given strings and not numbers,
151             this is done if <literal>val</literal> is provided. The size of <literal>val</literal> must
152             match the number of tics.
153         </para>
154     </refsection>
155     <refsection>
156         <title>Examples</title>
157         <programlisting role="example"><![CDATA[
158 plot2d(1:10,1:10,1,"020")
159 // horizontal axis
160 e = drawaxis(x=2:7,y=4,dir='u',tics='v')
161 // horizontal axis on top of the frame
162 drawaxis(x=2:7,dir='u',tics='v')
163 // horizontal axis at the bottom of the frame
164 e = drawaxis(x=2:7,dir='d',tics='v')
165
166 // horizontal axis given by a range
167 drawaxis(x=[2,7,3],y=4,dir='d',tics='r')
168
169 // vertical axis
170 e = drawaxis(x=4,y=2:7,dir='r',tics='v')
171 e = drawaxis(x=2,y=[2,7,3],dir='l',tics='r')
172 e = drawaxis(y=2:7,dir='r',tics='v')
173 e = drawaxis(y=2:7,dir='l',tics='v')
174
175 // horizontal axis with strings displayed at tics positions
176 drawaxis(x=2:7,y=8,dir='u',tics='v',val='A'+string(1:6));
177 // vertical axis with strings displayed at tics positions
178 drawaxis(x=8,y=2:7,dir='r',tics='v',val='B'+string(1:6));
179
180 // horizontal axis given with a 'i' range.
181 e = drawaxis(x=[2,5,0,3],y=9,dir='u',tics='i');
182 e = drawaxis(x=9,y=[2,5,0,3],dir='r',tics='i',sub_int=5);
183
184 // horizontal axis again
185 drawaxis(x=2:7,y=4,dir='u',tics='v',fontsize=10,textcolor=9,ticscolor=7,seg=0,sub_int=20)
186  ]]></programlisting>
187         <scilab:image>
188             plot2d(1:10,1:10,1,"020")
189             drawaxis(x=2:7,y=4,dir='u',tics='v')
190             drawaxis(x=2:7,dir='u',tics='v')
191             drawaxis(x=2:7,dir='d',tics='v')
192
193             drawaxis(x=[2,7,3],y=4,dir='d',tics='r')
194
195             drawaxis(x=4,y=2:7,dir='r',tics='v')
196             drawaxis(x=2,y=[2,7,3],dir='l',tics='r')
197             drawaxis(y=2:7,dir='r',tics='v')
198             drawaxis(y=2:7,dir='l',tics='v')
199
200             drawaxis(x=2:7,y=8,dir='u',tics='v',val='A'+string(1:6));
201             drawaxis(x=8,y=2:7,dir='r',tics='v',val='B'+string(1:6));
202
203             drawaxis(x=[2,5,0,3],y=9,dir='u',tics='i');
204             drawaxis(x=9,y=[2,5,0,3],dir='r',tics='i',sub_int=5);
205
206             drawaxis(x=2:7,y=4,dir='u',tics='v',fontsize=10,textcolor=9,ticscolor=7,seg=0,sub_int=20)
207         </scilab:image>
208     </refsection>
209     <refsection role="see also">
210         <title>See also</title>
211         <simplelist type="inline">
212             <member>
213                 <link linkend="plot_multiscaled">Multiscaled plots</link>
214             </member>
215             <member>
216                 <link linkend="axis_properties">axis_properties</link>
217             </member>
218         </simplelist>
219     </refsection>
220 </refentry>