bbe73f7b6bddc2fc77550c702af5374c977447e2
[scilab.git] / scilab / modules / graphics / help / en_US / axis / axis_properties.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 - Djalel Abdemouche
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.1-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" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="axis_properties">
14     <refnamediv>
15         <refname>axis properties</refname>
16         <refpurpose>description of the axis entity
17             properties
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>The Axis entity is a leaf of the graphics entities hierarchy. This
23             entity defines the parameters for axis scaling and appearance.
24         </para>
25         <variablelist>
26             <varlistentry>
27                 <term>Axis properties</term>
28                 <listitem>
29                     <variablelist>
30                         <varlistentry>
31                             <term>parent: </term>
32                             <listitem>
33                                 <para>This property contains the handle of the parent. The parent of
34                                     the axis entity should be of the type <literal>"Axes"</literal> or
35                                     <literal>"Compound"</literal>.
36                                 </para>
37                             </listitem>
38                         </varlistentry>
39                         <varlistentry>
40                             <term>visible: </term>
41                             <listitem>
42                                 <para>
43                                     This field contains the <literal>visible</literal> property value
44                                     for the entity . It should be <literal>"on" </literal> or
45                                     <literal>"off"</literal> . By default, the axis entity is visible, the
46                                     value's property is <literal>"on"</literal>. If <literal>"off"</literal>, the
47                                     axis is not drawn on the screen.
48                                 </para>
49                             </listitem>
50                         </varlistentry>
51                         <varlistentry>
52                             <term>tics_direction: </term>
53                             <listitem>
54                                 <para>Specify the direction of the tics drawn under the horizontal
55                                     axis and the vertical axis. The possible values of this property
56                                     are:
57                                 </para>
58                                 <itemizedlist>
59                                     <listitem>
60                                         <para>
61                                             <literal>"top"</literal>. In this case, tics are drawn at the top
62                                             of the horizontal axis.
63                                         </para>
64                                     </listitem>
65                                     <listitem>
66                                         <para>
67                                             <literal>"bottom"</literal>. In this case, tics are drawn at the
68                                             bottom of the horizantal axis.
69                                         </para>
70                                     </listitem>
71                                     <listitem>
72                                         <para>
73                                             <literal>"left"</literal>. In this case, tics are going left on
74                                             the vertical axis.
75                                         </para>
76                                     </listitem>
77                                     <listitem>
78                                         <para>
79                                             <literal>"right"</literal>. In this case, tics are going right on
80                                             the vertical axis.
81                                         </para>
82                                     </listitem>
83                                 </itemizedlist>
84                                 <para>
85                                     The defaults values are <literal>"top"</literal> for the horizontal
86                                     axis and <literal>"right"</literal> for vertical axis.
87                                 </para>
88                             </listitem>
89                         </varlistentry>
90                         <varlistentry>
91                             <term>xtics_coord: </term>
92                             <listitem>
93                                 <para>This field represents the x-coordinate of the axis. It is a row
94                                     vector containing values increasing from left to right which give
95                                     tics positions for a horizontal axis. Other case, the entity is a
96                                     vertical axis, this property contain a scale which defines the
97                                     x-origin of the axis.
98                                 </para>
99                             </listitem>
100                         </varlistentry>
101                         <varlistentry>
102                             <term>ytics_coord: </term>
103                             <listitem>
104                                 <para>This field represents the y-coordinate of the axis. It is a row
105                                     vector containing values increasing from bottom to top which give
106                                     tics positions for a vertical axis. Other case, the entity is a
107                                     horizontal axis, this property contain a scale which defines the
108                                     y-origin of the axis.
109                                 </para>
110                             </listitem>
111                         </varlistentry>
112                         <varlistentry>
113                             <term>tics_color: </term>
114                             <listitem>
115                                 <para>The value of this properties is index of the color used to
116                                     draw the axis'lines and tics.
117                                 </para>
118                             </listitem>
119                         </varlistentry>
120                         <varlistentry>
121                             <term>tics_segment: </term>
122                             <listitem>
123                                 <para>This field contains a flag which controls the display of the
124                                     base segment of the axis. The default is <literal>"on"</literal>, else
125                                     if to not display it, the property takes <literal>"off"</literal> as
126                                     value.
127                                 </para>
128                             </listitem>
129                         </varlistentry>
130                         <varlistentry>
131                             <term>tics_style: </term>
132                             <listitem>
133                                 <para>This property describes how the tics are given. It is a string
134                                     flag which can have these possible values:
135                                 </para>
136                                 <itemizedlist>
137                                     <listitem>
138                                         <para>
139                                             <literal>"v"</literal>. It's the default value, In this case,
140                                             tics positions are given by the row factor
141                                             <literal>xtics_coord</literal> for horizontal axis
142                                             (<literal>ytics_coord</literal> for the vertical one).
143                                         </para>
144                                     </listitem>
145                                     <listitem>
146                                         <para>
147                                             <literal>"r"</literal>. In this case, tics positions are given by
148                                             the vector <literal>[min,max,n] </literal> where n is the number of
149                                             intervals.
150                                         </para>
151                                     </listitem>
152                                     <listitem>
153                                         <para>
154                                             <literal>"i"</literal>. In this case the vector given tics
155                                             positions is of size 4, <literal>[k1,k2,a,n]</literal> then values
156                                             are increasing between <literal>k1*10^a</literal> and
157                                             <literal>k2*10^a</literal>, n is the number of intervals.
158                                         </para>
159                                     </listitem>
160                                 </itemizedlist>
161                             </listitem>
162                         </varlistentry>
163                         <varlistentry>
164                             <term>sub_tics: </term>
165                             <listitem>
166                                 <para>This field sets the number of tics to draw between two main
167                                     tics.
168                                 </para>
169                             </listitem>
170                         </varlistentry>
171                         <varlistentry>
172                             <term>tics_labels: </term>
173                             <listitem>
174                                 <para>This field is a string matrix, which contains the strings to
175                                     be drawn along the axis at tics positions.
176                                 </para>
177                             </listitem>
178                         </varlistentry>
179                         <varlistentry>
180                             <term>format_n: </term>
181                             <listitem>
182                                 <para>This property is a character string which specifies the floating-point display format of the tics labels numbers,
183                                     when relevant. It uses the format syntax of the C language printf function (for example <literal>"%.3f"</literal>).
184                                     If equal to <literal>""</literal>, a default display format is used.
185                                 </para>
186                             </listitem>
187                         </varlistentry>
188                         <varlistentry>
189                             <term>labels_font_color: </term>
190                             <listitem>
191                                 <para>This property determines the color of the tics labels.</para>
192                             </listitem>
193                         </varlistentry>
194                         <varlistentry>
195                             <term>labels_font_size: </term>
196                             <listitem>
197                                 <para>It is a scalar specifying the character size of tics labels.
198                                     If <literal>fractional_font</literal> property is <literal>"off"</literal>
199                                     only the integer part of the value is used.
200                                     For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
201                                 </para>
202                             </listitem>
203                         </varlistentry>
204                         <varlistentry>
205                             <term>fractional_font: </term>
206                             <listitem>
207                                 <para>
208                                     This property specifies whether ticks labels are displayed using fractional font sizes.
209                                     Its value must be either <literal>"on"</literal> or <literal>"off"</literal>.
210                                     If <literal>"on"</literal> the floating point value of <literal>font_size</literal>
211                                     is used for display and the font is anti-aliased. If <literal>"off"</literal> only the integer part is used
212                                     and the font is not smoothed.
213                                 </para>
214                             </listitem>
215                         </varlistentry>
216                         <varlistentry>
217                             <term>clip_state: </term>
218                             <listitem>
219                                 <para>
220                                     This field contains the <literal>clip_state</literal> property value
221                                     for the arc. Clip_state value should be :
222                                 </para>
223                                 <itemizedlist>
224                                     <listitem>
225                                         <para>
226                                             <literal>"off"</literal> this means that the axis is not
227                                             clipped
228                                         </para>
229                                     </listitem>
230                                     <listitem>
231                                         <para>
232                                             <literal>"clipgrf"</literal> this means that the axis is clipped
233                                             outside the Axes box.
234                                         </para>
235                                     </listitem>
236                                     <listitem>
237                                         <para>
238                                             <literal>"on"</literal> this means that the axis is clipped
239                                             outside the arc given by property clip_box.
240                                         </para>
241                                     </listitem>
242                                 </itemizedlist>
243                             </listitem>
244                         </varlistentry>
245                         <varlistentry>
246                             <term>clip_box: </term>
247                             <listitem>
248                                 <para>
249                                     This field is to determinate the <literal>clip_box</literal>
250                                     property. By Default its value should be an empty matrix if
251                                     clip_state is "off". Other cases the vector <literal>[x,y,w,h]</literal>
252                                     (upper-left point width height) defines the portions of the axis
253                                     to display, however <literal>clip_state</literal> property value will be
254                                     changed.
255                                 </para>
256                             </listitem>
257                         </varlistentry>
258                         <varlistentry>
259                             <term>user_data: </term>
260                             <listitem>
261                                 <para>This field can be used to store any scilab variable in the axis
262                                     data structure, and to retrieve it.
263                                 </para>
264                             </listitem>
265                         </varlistentry>
266                     </variablelist>
267                 </listitem>
268             </varlistentry>
269         </variablelist>
270     </refsection>
271     <refsection>
272         <title>Examples</title>
273         <programlisting role="example"><![CDATA[ 
274 a=get("current_axes");//get the handle of the newly created axes
275 a.data_bounds=[-1,-1;10,10];
276
277 drawaxis(x=2:7,y=4,dir='u');
278 a1=a.children(1)
279 a1.xtics_coord=[1 4 5  8 10];
280 a1.tics_color=2;
281 a1.labels_font_size=3;
282 a1.tics_direction="bottom";
283 a1.tics_labels= [" February" "May"  "june" "August"  "October"];
284   
285 drawaxis(x=1.2:1:10,y=5,dir='u',textcolor=13);
286 a2=get("hdl")
287 a2.sub_tics=0;
288 a2.tics_segment="off";
289 a2.ytics_coord=4;
290   
291 drawaxis(x=-1,y=0:1:7,dir='r',fontsize=10,textcolor=5,ticscolor=6,sub_int=10)
292 a3=get("hdl");
293 a3.tics_labels= 'B'  +string(0:7);
294 a3.tics_direction="left";
295  ]]></programlisting>
296     </refsection>
297     <refsection role="see also">
298         <title>See Also</title>
299         <simplelist type="inline">
300             <member>
301                 <link linkend="set">set</link>
302             </member>
303             <member>
304                 <link linkend="get">get</link>
305             </member>
306             <member>
307                 <link linkend="delete">delete</link>
308             </member>
309             <member>
310                 <link linkend="drawaxis">drawaxis</link>
311             </member>
312             <member>
313                 <link linkend="graphics_entities">graphics_entities</link>
314             </member>
315         </simplelist>
316     </refsection>
317 </refentry>