* Bug #13690 fixed - tight_limits property can now manage X, Y and Z axis separately.
[scilab.git] / scilab / modules / graphics / help / en_US / axes_operations / axes_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  * Copyright (C) 2009 - DIGITEO - Pierre Lando
6  * Copyright (C) 2013 - Samuel GOUGEON : revision for x|y|z_ticks and "See also" sections
7  *
8  * This file must be used under the terms of the CeCILL.
9  * This source file is licensed as described in the file COPYING, which
10  * you should have received as part of this distribution.  The terms
11  * are also available at
12  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
13  *
14  -->
15 <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="axes_properties">
16     <refnamediv>
17         <refname>axes properties</refname>
18         <refpurpose>
19             description of the axes entity
20             properties
21         </refpurpose>
22     </refnamediv>
23     <refsection>
24         <title>Description</title>
25         <para>
26             The Axes entity is the second level of the graphics entities hierarchy.
27             This entity defines the parameters allowing the change of coordinates and
28             the axes drawing as well as the parameters' default values for the
29             children creation.
30         </para>
31         <variablelist>
32             <varlistentry>
33                 <term>Axes properties</term>
34                 <listitem>
35                     <variablelist>
36                         <varlistentry>
37                             <term>parent: </term>
38                             <listitem>
39                                 <para>This field contains the handle of the parent figure.</para>
40                             </listitem>
41                         </varlistentry>
42                         <varlistentry>
43                             <term>children: </term>
44                             <listitem>
45                                 <para>
46                                     FA vector containing the handles of all graphics objects
47                                     children of the axes These graphics objects are of type
48                                     <literal>"Compound"</literal>, <literal>"Rectangle"</literal>,
49                                     <literal>"Polyline"</literal>, <literal>"Segs"</literal>, <literal>"Arc"</literal>,
50                                     <literal>"Grayplot"</literal>,.. (see <link linkend="Compound_properties">Compound_properties</link>,
51                                     <link linkend="rectangle_properties">rectangle_properties</link>, <link linkend="champ_properties">champ_properties</link>,
52                                     <link linkend="axis_properties">axis_properties</link>, <link linkend="polyline_properties">polyline_properties</link>,
53                                     <link linkend="segs_properties">segs_properties</link>, <link linkend="grayplot_properties">grayplot_properties</link>,
54                                     <link linkend="surface_properties">surface_properties</link>,
55                                     <link linkend="fec_properties">fec_properties</link>, <link linkend="text_properties">text_properties</link>,
56                                     <link linkend="legend_properties">legend_properties</link>)
57                                 </para>
58                             </listitem>
59                         </varlistentry>
60                         <varlistentry>
61                             <term>visible: </term>
62                             <listitem>
63                                 <para>
64                                     This field contains the <literal>visible</literal> property value
65                                     for axes . Its value should be <literal>"on" </literal> or
66                                     <literal>"off"</literal> . By default, axes is visible <literal>"on"</literal>
67                                     in case all "visible" chidren are displayed on the screen, If
68                                     <literal>"off"</literal> the axes and all its chidren are not
69                                     drawn.
70                                 </para>
71                             </listitem>
72                         </varlistentry>
73                         <varlistentry>
74                             <term>axes_visible: </term>
75                             <listitem>
76                                 <para>
77                                     A <literal>1x3</literal> string vector. This property specifies
78                                     whether each axis is drawn or not. Its value should be
79                                     <literal>"on"</literal> or <literal>"off"</literal> for a global setting.To
80                                     act on a single axis, the syntax is <literal>axes_visible(N)</literal>
81                                     where <literal>N</literal> is <literal>1,2</literal> or <literal>3</literal>
82                                     corresponding to the <literal> x,y</literal> or <literal>z</literal> axis. The
83                                     scaling data and if required the grids are drawn if the value is
84                                     <literal>"on"</literal>. Note that when creating a simple axes entity
85                                     using the <literal>gca()</literal> (shorcut for
86                                     <literal>get"current_axes")</literal>) or <literal>gcf()</literal> (shortcut
87                                     for <literal>get(current_figure)</literal>) commands, the axes
88                                     visiblibilty is set to <literal>"off"</literal>.
89                                 </para>
90                             </listitem>
91                         </varlistentry>
92                         <varlistentry>
93                             <term>axes_reverse: </term>
94                             <listitem>
95                                 <para>
96                                     A <literal>1x3</literal> string vector corresponding to the three
97                                     axes (X,Y,Z). For each axes, the property specifies the direction
98                                     of the incresing values. If <literal>"off"</literal>, the default
99                                     direction is used. If <literal>"on"</literal>, the direction is reverse.
100                                     It is also possible to use only one string, <literal>"on"</literal> or
101                                     <literal>"off"</literal>, to set simultaneously the three data.
102                                 </para>
103                             </listitem>
104                         </varlistentry>
105                         <varlistentry>
106                             <term>grid: </term>
107                             <listitem>
108                                 <para>
109                                     The field value is a vector
110                                     <literal>[x-grid,y-grid,z-grid]</literal> where <literal>x-grid</literal>
111                                     controls a grid drawning for the x-axis and <literal>
112                                         y-grid,
113                                         z-grid
114                                     </literal>
115                                     respecting to the y-axis, z-axis. The default values
116                                     is <literal>-1</literal> grids are not drawn, else the grids are drawn
117                                     using the color given indexed by the grid value.
118                                 </para>
119                             </listitem>
120                         </varlistentry>
121                         <varlistentry>
122                             <term>grid_position: </term>
123                             <listitem>
124                                 <para>
125                                     This character string specifies the grid position compared with other graphic entities.
126                                     Its value can be either <literal>"foreground"</literal>
127                                     to draw the grid ahead other graphic entities or <literal>"background"</literal> to draw the grid behind.
128                                 </para>
129                             </listitem>
130                         </varlistentry>
131                         <varlistentry>
132                             <term>x_location: </term>
133                             <listitem>
134                                 <para>
135                                     Specify the location of the x-axis. The possible values
136                                     are:
137                                 </para>
138                                 <itemizedlist>
139                                     <listitem>
140                                         <para>
141                                             <literal>"bottom"</literal>. In this case the x axis is drawn at
142                                             the bottom of the axes rectangle.
143                                         </para>
144                                     </listitem>
145                                     <listitem>
146                                         <para>
147                                             <literal>"top"</literal>. In this case the x axis is drawn at
148                                             the top of the axes rectangle.
149                                         </para>
150                                     </listitem>
151                                     <listitem>
152                                         <para>
153                                             <literal>"middle"</literal>. In this case the x axis is drawn
154                                             at the centered position.
155                                         </para>
156                                     </listitem>
157                                     <listitem>
158                                         <para>
159                                             <literal>"origin"</literal>. In this case the x axis is drawn
160                                             at the origin.
161                                         </para>
162                                     </listitem>
163                                 </itemizedlist>
164                             </listitem>
165                         </varlistentry>
166                         <varlistentry>
167                             <term>y_location: </term>
168                             <listitem>
169                                 <para>
170                                     Specify the location of the y-axis. The possible values
171                                     are:
172                                 </para>
173                                 <itemizedlist>
174                                     <listitem>
175                                         <para>
176                                             <literal>"left"</literal>. In this case the y axis is drawn at
177                                             the left of the axes rectangle.
178                                         </para>
179                                     </listitem>
180                                     <listitem>
181                                         <para>
182                                             <literal>"right"</literal>. In this case the y axis is drawn at
183                                             the right of the axes rectangle.
184                                         </para>
185                                     </listitem>
186                                     <listitem>
187                                         <para>
188                                             <literal>"middle"</literal>. In this case the y axis is drawn
189                                             at the centered position.
190                                         </para>
191                                     </listitem>
192                                     <listitem>
193                                         <para>
194                                             <literal>"origin"</literal>. In this case the y axis is drawn
195                                             at the origin.
196                                         </para>
197                                     </listitem>
198                                 </itemizedlist>
199                             </listitem>
200                         </varlistentry>
201                         <varlistentry>
202                             <term>title: </term>
203                             <listitem>
204                                 <para>
205                                     An object attached to the Axes entity and returning a graphic
206                                     handle on a Label structure (see <link linkend="label_properties">label_properties</link>).
207                                     This field defines a title with options on this label.
208                                 </para>
209                             </listitem>
210                         </varlistentry>
211                         <varlistentry>
212                             <term>x_label: </term>
213                             <listitem>
214                                 <para>
215                                     An object attached to the Axes entity and returning a graphic
216                                     handle on a Label structure (see <link linkend="label_properties">label_properties</link>).
217                                     This field defines a label on x axis with options on this
218                                     label.
219                                 </para>
220                             </listitem>
221                         </varlistentry>
222                         <varlistentry>
223                             <term>y_label: </term>
224                             <listitem>
225                                 <para>
226                                     An object attached to the Axes entity and returning a graphic
227                                     handle on a Label structure (see <link linkend="label_properties">label_properties</link>).
228                                     This field defines a label on y axis with options on this
229                                     label.
230                                 </para>
231                             </listitem>
232                         </varlistentry>
233                         <varlistentry>
234                             <term>z_label: </term>
235                             <listitem>
236                                 <para>
237                                     An object attached to the Axes entity and returning a graphic
238                                     handle on a Label structure (see <link linkend="label_properties">label_properties</link>).
239                                     This field defines a label on z axis with options on this
240                                     label.
241                                 </para>
242                             </listitem>
243                         </varlistentry>
244                         <varlistentry>
245                             <term>auto_ticks: </term>
246                             <listitem>
247                                 <para>
248                                     A <literal>1x3</literal> string vector giving the auto_ticks status
249                                     for each axis. This property specifies whether each axis is
250                                     graduated using a computational algorithm or not (graduations are
251                                     set by the user). Its value should be <literal>"on"</literal> or
252                                     <literal>"off"</literal> for a global setting.To act on a single axis,
253                                     the syntax is <literal>auto_ticks(N)</literal> where <literal>N</literal> is
254                                     <literal>1,2</literal> or <literal>3</literal> corresponding to the
255                                     <literal>x,y</literal> or <literal>z</literal> axis. Note that editing ticks
256                                     (text and/or locations) via <literal>x_ticks, y_ticks</literal> or
257                                     <literal>z_ticks</literal> automatically set <literal>auto_ticks</literal> to
258                                     <literal>"off"</literal> for the corresponding axes.
259                                 </para>
260                             </listitem>
261                         </varlistentry>
262                         <varlistentry>
263                             <term>x_ticks, y_ticks, z_ticks: </term>
264                             <listitem>
265                                 <para>
266                                     Each of these properties is a tlist of type "ticks" with 2 fields named "locations" and "labels":
267                                     <literal>tlist(["ticks", "locations", "labels"], Locations, Labels)</literal> where
268                                     <variablelist>
269                                         <varlistentry>
270                                             <term>Locations</term>
271                                             <listitem>
272                                                 is a real vector containing the locations of graduations along and according to the data scale of the given x or y or z axis.
273                                                 When the number of ticks does not need to be changed, their locations can be set or changed through
274                                                 the syntax (e.g. along x) <literal>Haxes.x_ticks.locations = Locations</literal> where <literal>Haxes = gca();</literal>
275                                                 and <literal>Locations</literal> is the complete vector of updated ticks positions. To change just the ith location, just use:
276                                                 <literal>Haxes.x_ticks.locations(i) = newLoc</literal>
277                                             </listitem>
278                                         </varlistentry>
279                                         <varlistentry>
280                                             <term>Labels</term>
281                                             <listitem>
282                                                 is a text vector containing the labels to be displayed in front of each related graduation. As for Locations of ticks, Labels can be addressed with (e.g. along y) <literal>Haxes.y_ticks.labels = Labels</literal> or <literal>Haxes.y_ticks.labels(j) = newLabelJ</literal>
283                                             </listitem>
284                                         </varlistentry>
285                                     </variablelist>
286                                     <warning>
287                                         <para>
288                                             For an axis, <literal>Locations</literal> and <literal>Labels</literal> vectors must have the same number of components.
289                                         </para>
290                                         <para>
291                                             When the number of ticks must be changed, their positions AND labels must be changed at once, in order to avoid any mismatch: The syntax (e.g. along x) <literal>Haxes.x_ticks = tlist(["ticks" "locations", "labels"], newLocations, newLabels)</literal> must then be used.
292                                         </para>
293                                     </warning>
294                                 </para>
295                             </listitem>
296                         </varlistentry>
297                         <varlistentry>
298                             <term>x_ticks.locations, y_ticks.locations, z_ticks.locations: </term>
299                             <listitem>
300                                 <para>
301                                     Each of these properties is a real vector containing the locations of graduations on the related x or y or z axis. <varname>x_ticks.locations</varname> must have the same number of components as <varname>x_ticks.labels</varname>. See <varname>x_ticks</varname> hereabove for more details.
302                                 </para>
303                             </listitem>
304                         </varlistentry>
305                         <varlistentry>
306                             <term>x_ticks.labels, y_ticks.labels, z_ticks.labels: </term>
307                             <listitem>
308                                 <para>
309                                     Each of these properties is a text vector containing the labels to be displayed in front of ticks on the related x or y or z axis. <varname>x_ticks.labels</varname> must have the same number of components as <varname>x_ticks.locations</varname>. See <varname>x_ticks</varname> hereabove for more details.
310                                 </para>
311                             </listitem>
312                         </varlistentry>
313                         <varlistentry>
314                             <term>ticks_format: </term>
315                             <listitem>
316                                 <para>
317                                     This property specifies the format to use for each axes.
318                                     It is a row vector with at most 3 columns containing strings format (as specified for <link linkend="mprintf">mprintf</link>). Each ticks position will be used to format the string used as label.
319                                 </para>
320                                 <para>
321                                     So, for example ticks_format="%.2e" will print ticks positions in using scientific notation with two decimals.
322                                 </para>
323                             </listitem>
324                         </varlistentry>
325                         <varlistentry>
326                             <term>ticks_st: </term>
327                             <listitem>
328                                 <para>
329                                     This property specifies scale-translate factors to apply to each ticks position before to use it in the formatted string used as label. So if the factors are <literal>[x_s y_s z_s ; x_t y_t z_t]</literal> and if a x_tick is positionned at X, the value used to format the label will be <literal>x_s*(X-x_t)</literal>. It could be particulary useful when the axes bounds are too closed.
330                                     <para>
331                                         It is a matrix with 2 rows and at most 3 columns.
332                                     </para>
333                                 </para>
334                                 <para>
335                                     So, for example <literal>base=B</literal>, labels could be printed with <literal>ticks_format=string(base)+"%+.2e"</literal> and <literal>ticks_st=[1 base]</literal>
336                                 </para>
337                             </listitem>
338                         </varlistentry>
339                         <varlistentry>
340                             <term>box: </term>
341                             <listitem>
342                                 <para>
343                                     This property specifies whether to enclose the axes in a box.
344                                     Its value can be either <literal>"off"</literal>,
345                                     <literal>"hidden_axes"</literal>, <literal>"back_half"</literal> or
346                                     <literal>"on".</literal> If the property is <literal>"off"</literal>, the box
347                                     is not draw. If the property is <literal>"hidden_axes"</literal>, only
348                                     the back frame is drawn. If the property is
349                                     <literal>"back_half"</literal>, the X, Y and Z axis are also drawn. If
350                                     the property is <literal>"on"</literal> the whole box is drawn.
351                                 </para>
352                             </listitem>
353                         </varlistentry>
354                         <varlistentry>
355                             <term>filled: </term>
356                             <listitem>
357                                 <para>
358                                     This property specifies whether the axes background should be drawn or not.
359                                     Its value can be either <literal>"off"</literal> or
360                                     <literal>"on".</literal> If the property is <literal>"off"</literal>, the background
361                                     is not drawn, the axes box is transparent. If the property is <literal>"on"</literal> the
362                                     background is drawn using the color specified by the <literal>background</literal> property.
363                                 </para>
364                             </listitem>
365                         </varlistentry>
366                         <varlistentry>
367                             <term>sub_ticks: </term>
368                             <listitem>
369                                 <para>
370                                     This field sets the number of tics to draw between two main
371                                     tics. The field value is the vector <literal>[nx,ny]</literal> where
372                                     <literal>nx</literal> is the number of sub tics for the x-axis and
373                                     <literal>ny</literal> respecting to the y-axis.
374                                 </para>
375                             </listitem>
376                         </varlistentry>
377                         <varlistentry>
378                             <term>font_style: </term>
379                             <listitem>
380                                 <para>
381                                     Specifies the font used for displaying tics labels. This is a positive integer referecing one of the loaded fonts.
382                                     Its value must be between 0, referecing the first font,
383                                     and the number of loaded fonts minus one, referencing the last font.
384                                     For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
385                                 </para>
386                             </listitem>
387                         </varlistentry>
388                         <varlistentry>
389                             <term>font_size: </term>
390                             <listitem>
391                                 <para>
392                                     It is a scalar specifying the character size of tics labels.
393                                     If <literal>fractional_font</literal> property is <literal>"off"</literal>
394                                     only the integer part of the value is used.
395                                     For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
396                                 </para>
397                             </listitem>
398                         </varlistentry>
399                         <varlistentry>
400                             <term>font_color: </term>
401                             <listitem>
402                                 <para>This property determines the color of the tics labels.</para>
403                             </listitem>
404                         </varlistentry>
405                         <varlistentry>
406                             <term>fractional_font: </term>
407                             <listitem>
408                                 <para>
409                                     This property specify whether ticks labels are displayed using fractional font sizes.
410                                     Its value must be either <literal>"on"</literal> or <literal>"off"</literal>.
411                                     If <literal>"on"</literal> the floating point value of <literal>font_size</literal>
412                                     is used for display and the font is anti-aliased. If <literal>"off"</literal> only the integer part is used
413                                     and the font is not smoothed.
414                                 </para>
415                             </listitem>
416                         </varlistentry>
417                         <varlistentry>
418                             <term>isoview: </term>
419                             <listitem>
420                                 <para>
421                                     This property is used to have isometric scales on the x, y and
422                                     z axes (for exemple to make the display of the curve sin(x) versus
423                                     cos(x) be a circle not an ellipse). Its value should be
424                                     <literal>"on"</literal> or <literal>"off"</literal>. If the value is
425                                     <literal>"on"</literal>, the axes <literal>data_bounds</literal> automatically
426                                     change according to the corresponding figure
427                                     <literal>figure_size</literal> property values.
428                                 </para>
429                             </listitem>
430                         </varlistentry>
431                         <varlistentry>
432                             <term>cube_scaling:</term>
433                             <listitem>
434                                 <para>
435                                     This property is used in <literal>3d mode</literal> to have a
436                                     rescaling of the x, y and z axes. Indeed, it allows the
437                                     <literal>data</literal> to fit into a 1x1x1 cube ; the goal is to better
438                                     display 3d graphics in case axes scales are very different from
439                                     one to another. Its value should be <literal>"on" </literal> or
440                                     <literal>"off"</literal> (which is the default value). In most cases, it
441                                     helps generating Matlab-like 3d view.
442                                 </para>
443                             </listitem>
444                         </varlistentry>
445                         <varlistentry>
446                             <term>view: </term>
447                             <listitem>
448                                 <para>
449                                     This field is related to the graphics universe. It takes
450                                     <literal>"3d"</literal> as value corresponding to the three-dimensional
451                                     views. In the other case its value can be <literal>"2d"</literal> for
452                                     initial 2d plotting (default value). This flag also depends on the
453                                     plots the user enters : a <literal>plot3d </literal>command, for
454                                     example, will switch the <literal>view</literal> flag from
455                                     <literal>"2d"</literal> to <literal>"3d"</literal>.
456                                 </para>
457                             </listitem>
458                         </varlistentry>
459                         <varlistentry>
460                             <term>rotation_angles: </term>
461                             <listitem>
462                                 <para>
463                                     This field is the vector <literal>[alpha,theta]</literal>. These two
464                                     values give the spherical coordinates of the observation points
465                                     (in degree).
466                                 </para>
467                             </listitem>
468                         </varlistentry>
469                         <varlistentry>
470                             <term>log_flags: </term>
471                             <listitem>
472                                 <para>
473                                     3 character string that sets the scale (linear or logarithmic) along the axes.
474                                     Each character speficfies the scale for respectively the X, Y and Z axes.
475                                     They should take a value between <literal>'n'</literal> for linear scale or
476                                     <literal>'l'</literal> for logarithmic scale.
477                                 </para>
478                             </listitem>
479                         </varlistentry>
480                         <varlistentry>
481                             <term>tight_limits: </term>
482                             <listitem>
483                                 <para>
484                                     A <literal>1x3</literal> string vector giving the tight_limits status
485                                     for each axis. This property specifies whether each axis fits exactly with the minima and
486                                     maxima values of the data bounds. If an item is <literal>"off"</literal>, the corresponding axis may
487                                     enlarge boundaries such as to produce pretty tics labels. For a global setting (all axes at once), you have to set its value
488                                     to <literal>"on"</literal> or <literal>"off"</literal> (single string). To act on a single axis,
489                                     the syntax is <literal>tight_limits(N)</literal> where <literal>N</literal> is
490                                     <literal>1,2</literal> or <literal>3</literal> corresponding to the
491                                     <literal>x,y</literal> or <literal>z</literal> axis.
492                                 </para>
493                             </listitem>
494                         </varlistentry>
495                         <varlistentry>
496                             <term>data_bounds: </term>
497                             <listitem>
498                                 <para>
499                                     This field contains the boundary values for the x, y and z
500                                     coordinates. It is either the matrix or the vector
501                                     <literal>[xmin,ymin; xmax,ymax]</literal>,
502                                     <literal>[xmin,ymin,zmin; xmax,ymax,zmax]</literal>,
503                                     <literal>[xmin,xmax,ymin,ymax]</literal>,
504                                     <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>,
505                                     <literal>[xmin;xmax;ymin;ymax]</literal> or
506                                     <literal>[xmin;xmax;ymin;ymax;zmin;zmax]</literal>. Note that, to stricly have the
507                                     specified data bounds, <literal>tight_limits</literal> must be set to
508                                     <literal>"on"</literal> value (see above).
509                                     To manually set data_bounds set <literal>auto_scale="off"</literal>
510                                 </para>
511                             </listitem>
512                         </varlistentry>
513                         <varlistentry>
514                             <term>zoom_box: </term>
515                             <listitem>
516                                 <para>
517                                     This field contains the current zoom box if any coordinates
518                                     are given. It is an empty matrix (no zoom) or the vector
519                                     <literal>[xmin,ymin,xmax,ymax,zmin,zmax]</literal> (defines a smaller axes box).
520                                 </para>
521                             </listitem>
522                         </varlistentry>
523                         <varlistentry>
524                             <term>margins: </term>
525                             <listitem>
526                                 <para>
527                                     A vector
528                                     <literal>[margin_left,margin_right,margin_top,margin_bottom]</literal>
529                                     specifying the margins portion for this axes. This vector is
530                                     composed of numbers between [0 1] with default: [0.125 0.125 0.125
531                                     0.125]. These numbers are ratios relative to associated values of the
532                                     <literal>axes_bounds</literal> property, which are <literal>width</literal> for
533                                     <literal>margin_left</literal> and <literal>margin_right</literal>, and
534                                     <literal>height</literal> for <literal>margin_top</literal> and
535                                     <literal>margin_bottom</literal>.
536                                 </para>
537                             </listitem>
538                         </varlistentry>
539                         <varlistentry>
540                             <term>auto_margins: </term>
541                             <listitem>
542                                 <para>
543                                     A property to allow the automatic computation of the margins accordint to their contents.
544                                     If value is <literal>"on"</literal>, then the automatic computation is activated.
545                                 </para>
546                             </listitem>
547                         </varlistentry>
548                         <varlistentry>
549                             <term>axes_bounds: </term>
550                             <listitem>
551                                 <para>
552                                     A vector <literal>[x_left,y_up,width,height]</literal> specifying
553                                     the portion of figure used by this axes. Where
554                                     <literal>x_left</literal>, <literal>y_up</literal>, <literal>width</literal> and
555                                     <literal>height</literal> are numbers in [0 1] give respectively the
556                                     position of the upper-left corner and the dimension of the axes
557                                     (these numbers are ratio relative to the corresponding figure
558                                     <literal>figure_size</literal> property values).
559                                 </para>
560                             </listitem>
561                         </varlistentry>
562                         <varlistentry>
563                             <term>hidden_axis_color: </term>
564                             <listitem>
565                                 <para>
566                                     This property defined the color of the hidden axis. It takes
567                                     an index relative to the current colormap.
568                                 </para>
569                             </listitem>
570                         </varlistentry>
571                         <varlistentry>
572                             <term>user_data: </term>
573                             <listitem>
574                                 <para>
575                                     This field can be use to store any scilab variable in the axes
576                                     data structure, and to retreive it.
577                                 </para>
578                             </listitem>
579                         </varlistentry>
580                     </variablelist>
581                 </listitem>
582             </varlistentry>
583             <varlistentry>
584                 <term>Properties for high level functions</term>
585                 <listitem>
586                     <para>
587                         The <literal>plot</literal>, <literal>plot2dx</literal>, <literal>grayplot</literal>
588                         and <literal>matplot</literal> functions use the following properties to
589                         decide how to merge consecutive plots if this is not stated by the
590                         <literal>frameflag</literal> calling argument. The result of the merge is
591                         decided through these two following properties:
592                     </para>
593                     <variablelist>
594                         <varlistentry>
595                             <term>auto_clear: </term>
596                             <listitem>
597                                 <para>
598                                     If this property value is equal to <literal>"on"</literal>, a call
599                                     to a high level graphic will re-ininitialize the current axes and
600                                     erase all its children before preforming the drawing (log_flags will be reset).
601                                     If the value is <literal>"off"</literal> the drawings will be added to current axes
602                                     according to <literal>"auto_scale"</literal> property.
603                                 </para>
604                             </listitem>
605                         </varlistentry>
606                         <varlistentry>
607                             <term>auto_scale: </term>
608                             <listitem>
609                                 <para>
610                                     A property to update the axes data boundary. If value is
611                                     <literal>"on"</literal>, a new plot will adapt the current axes
612                                     properties to fit with previous and current plots. If its value is
613                                     <literal>"off"</literal> the new plot will be drawn in the current axes
614                                     data boundary.
615                                 </para>
616                             </listitem>
617                         </varlistentry>
618                     </variablelist>
619                 </listitem>
620             </varlistentry>
621             <varlistentry>
622                 <term>Children's default values: </term>
623                 <listitem>
624                     <variablelist>
625                         <varlistentry>
626                             <term>hiddencolor: </term>
627                             <listitem>
628                                 <para>
629                                     This property controls the hidden parts' color. It takes as
630                                     value an index relative to the current colormap. In another case,
631                                     if it is a negative value, the hidden parts take the same colors
632                                     as the surface
633                                 </para>
634                             </listitem>
635                         </varlistentry>
636                         <varlistentry>
637                             <term>line_mode: </term>
638                             <listitem>
639                                 <para>
640                                     This field contains the default <literal>line_mode</literal>
641                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
642                                     Polyline objects. Its value should be <literal>"on" </literal>(default)
643                                     or <literal>"off"</literal>.
644                                 </para>
645                             </listitem>
646                         </varlistentry>
647                         <varlistentry>
648                             <term>line_style: </term>
649                             <listitem>
650                                 <para>
651                                     This field contains the default <literal>line_style</literal>
652                                     property value for Segs, Arcs, Rectangle and Polyline objects.
653                                     <literal>line_style</literal> selects the type of line to be used to
654                                     draw lines . Its value should be an integer in [1 10]. 1
655                                     stand for solid, the other values stand for a selection of dashes
656                                     (dash, dash dot, longdash dot, bigdash dot, bigdash longdash, dot, double dot, longblank dot, bigblank dot).
657                                 </para>
658                             </listitem>
659                         </varlistentry>
660                         <varlistentry>
661                             <term>thickness: </term>
662                             <listitem>
663                                 <para>
664                                     This field contains the default <literal>thickness</literal>
665                                     property value for all objects using line drawing. It is a positive real specifying the line width
666                                     in pixels. The displayed width is actually determined by rounding the supplied width
667                                     to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
668                                     value is considered.
669                                 </para>
670                             </listitem>
671                         </varlistentry>
672                         <varlistentry>
673                             <term>mark_mode: </term>
674                             <listitem>
675                                 <para>
676                                     This field contains the default <literal>mark_mode</literal>
677                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
678                                     Polyline objects. Its value should be <literal>"on" </literal> or
679                                     <literal>"off"</literal> (default).
680                                 </para>
681                             </listitem>
682                         </varlistentry>
683                         <varlistentry>
684                             <term>mark_style: </term>
685                             <listitem>
686                                 <para>
687                                     This field contains the default <literal>mark_style</literal>
688                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
689                                     Polyline objects. <literal>mark_style</literal> selects the type of mark
690                                     to be displayed. Its value should be an integer in [0 9] which
691                                     stands for: dot, plus, cross, star, filled diamond, diamond,
692                                     triangle up, triangle down, trefle and circle.
693                                 </para>
694                             </listitem>
695                         </varlistentry>
696                         <varlistentry>
697                             <term>mark_size_unit: </term>
698                             <listitem>
699                                 <para>
700                                     This field contains the default <literal>mark_size_unit</literal>
701                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
702                                     Polyline objects. If <literal>mark_size_unit</literal> is set to
703                                     <literal>"point"</literal>, then the <literal>mark_size</literal> value is
704                                     directly given in points. When <literal>mark_size_unit</literal> is set
705                                     to <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed
706                                     relative to the font size array: therefore, its value should be an
707                                     integer in [0 5] whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and
708                                     24pt. Note that <link linkend="plot2d">plot2d</link> and pure scilab functions use
709                                     <literal>tabulated</literal> mode as default ; when using
710                                     <link linkend="plot">plot</link> function, the <literal>point</literal> mode is
711                                     automatically enabled.
712                                 </para>
713                             </listitem>
714                         </varlistentry>
715                         <varlistentry>
716                             <term>mark_size: </term>
717                             <listitem>
718                                 <para>
719                                     This field contains the default <literal>mark_size</literal>
720                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
721                                     Polyline objects. <literal>mark_size</literal> selects the font size of
722                                     mark to be displayed. Its value should be an integer in [0 5]
723                                     whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
724                                 </para>
725                                 <para>
726                                     <warning>In the special case where mark_style and mark_size are 0, a dot of one pixel is drawn.</warning>
727                                 </para>
728                             </listitem>
729                         </varlistentry>
730                         <varlistentry>
731                             <term>mark_foreground: </term>
732                             <listitem>
733                                 <para>
734                                     This field contains the default <literal>mark_foreground</literal>
735                                     property value for all objects created under this axes. Polyline,
736                                     rectangle, legend, surface, segment and axis objects are using
737                                     this property to specify a foreground (edge) color for their
738                                     marks. Its value should be a color index (relative to the current
739                                     color_map) or 0 for transparant edge. Note that the default value is <literal>-1</literal>
740                                     (default black) and, even if you change the
741                                     <literal>color_map</literal>, this <literal>-1</literal> value will always
742                                     point onto the default black color.
743                                 </para>
744                             </listitem>
745                         </varlistentry>
746                         <varlistentry>
747                             <term>mark_background: </term>
748                             <listitem>
749                                 <para>
750                                     This property controls the default
751                                     <literal>mark_background</literal> property value for all objects
752                                     created under this axes. Polyline, rectangle, legend, surface,
753                                     segment and axis objects are using this property to specify a
754                                     background (face) color for their marks. It takes as value an
755                                     index relative to the current colormap or 0 for transparant face. Note that the default value
756                                     is <literal>-2</literal> (default white) and, even if you change the
757                                     <literal>color_map</literal>, this <literal>-2</literal> value will always
758                                     point onto the default white color.
759                                 </para>
760                             </listitem>
761                         </varlistentry>
762                         <varlistentry>
763                             <term>foreground: </term>
764                             <listitem>
765                                 <para>
766                                     This field contains the default <literal>foreground</literal>
767                                     property value for axes and all objects created under this axes.
768                                     Its value should be a color index (relative to the current
769                                     color_map). Note that the default value is <literal>-1</literal>
770                                     (default black) and, even if you change the
771                                     <literal>color_map</literal>, this <literal>-1</literal> value will always
772                                     point onto the default black color.
773                                 </para>
774                             </listitem>
775                         </varlistentry>
776                         <varlistentry>
777                             <term>background: </term>
778                             <listitem>
779                                 <para>
780                                     This property controls the default <literal>background</literal>
781                                     property value for axes and all objects created under this axes.
782                                     It takes as value an index relative to the current colormap.Note
783                                     that the default value is <literal>-2</literal> (default white) and,
784                                     even if you change the <literal>color_map</literal>, this
785                                     <literal>-2</literal> value will always point onto the default white
786                                     color.
787                                 </para>
788                             </listitem>
789                         </varlistentry>
790                         <varlistentry>
791                             <term>arc_drawing_mode: </term>
792                             <listitem>
793                                 <para>
794                                     This property controls the default <literal>arc_drawing_mode</literal>
795                                     property value for all created Arc objects under this Axes object.
796                                     Its value should be either <literal>"nurbs"</literal> or <literal>"lines"</literal>.
797                                 </para>
798                             </listitem>
799                         </varlistentry>
800                         <varlistentry>
801                             <term>clip_state: </term>
802                             <listitem>
803                                 <para>
804                                     This field contains the default <literal>clip_state</literal>
805                                     property value for all objects. Its value should be :
806                                 </para>
807                                 <itemizedlist>
808                                     <listitem>
809                                         <para>
810                                             <literal>"off"</literal> this means that all objects created
811                                             after that are not clipped (default value).
812                                         </para>
813                                     </listitem>
814                                     <listitem>
815                                         <para>
816                                             <literal>"clipgrf"</literal> this means that all objects created
817                                             after that are clipped outside the Axes boundaries.
818                                         </para>
819                                     </listitem>
820                                     <listitem>
821                                         <para>
822                                             <literal>"on"</literal> this means that all objects created
823                                             after that are clipped outside the rectangle given by property
824                                             clip_box.
825                                         </para>
826                                     </listitem>
827                                 </itemizedlist>
828                             </listitem>
829                         </varlistentry>
830                         <varlistentry>
831                             <term>clip_box: </term>
832                             <listitem>
833                                 <para>
834                                     This field contains the default <literal>clip_box</literal> property
835                                     value for all objects. Its value should be an empty matrix if
836                                     clip_state is <literal>"off"</literal>. Other case the clipping is given
837                                     by the vector <literal>[x,y,w,h]</literal> (upper-left point width
838                                     height).
839                                 </para>
840                             </listitem>
841                         </varlistentry>
842                         <varlistentry>
843                             <term>Note on default values :</term>
844                             <listitem>
845                                 <variablelist>
846                                     <varlistentry>
847                                         <term/>
848                                         <listitem>
849                                             <para>
850                                                 All these listed properties and fields inherit from
851                                                 default values stored in an axes model. These default values
852                                                 can be seen and changed. To do so, use the
853                                                 <literal>get("default_axes")</literal> command : it returns a
854                                                 graphic handle on the axes model. Note that no graphic window
855                                                 is created by this command. The next created axes will inherit
856                                                 from this model (see "Example on axes model" below).
857                                             </para>
858                                         </listitem>
859                                     </varlistentry>
860                                 </variablelist>
861                             </listitem>
862                         </varlistentry>
863                     </variablelist>
864                 </listitem>
865             </varlistentry>
866         </variablelist>
867     </refsection>
868     <refsection>
869         <title>Examples</title>
870         <programlisting role="example">
871             <![CDATA[
872 lines(0) // disables vertical paging
873 a=get("current_axes")//get the handle of the newly created axes
874 a.axes_visible="on"; // makes the axes visible
875 a.font_size=3; //set the tics label font size
876 a.x_location="top"; //set the x axis position
877 a.data_bounds=[-100,-2,-1;100,2,1]; //set the boundary values for the x, y and z coordinates.
878 a.sub_tics=[5,0];
879 a.labels_font_color=5;
880 a.grid=[2,2];
881 a.box="off";
882
883 // Example with 3D axes
884 clf(); //clear the graphics window
885 x=0.1:0.1:2*%pi;plot2d(x-.3,sin(x)*7+.2);
886 a=gca(); // get the handle of the current axes
887 a.grid=[1 -1 -1]; //make x-grid
888 a.rotation_angles=[70 250]; //turn the axes with giving angles
889 a.grid=[1 6 -1]; //make y-grid
890 a.view="2d"; //return te the 2d view
891 a.box="back_half";
892 a.labels_font_color=5;
893 a.children.children.thickness=4;
894 a.children.children.polyline_style=3;
895 a.view="3d"; //return te the 3d view
896 a.children.children.thickness=1;
897 a.children.children.foreground=2;
898 a.grid=[1 6 3]; //make z-grid
899 a.parent.background=4;
900 a.background=7;
901 plot2d(cos(x)+1,3*sin(x)-3);
902 plot2d(cos(x)+7,3*sin(x)+3);
903 a.children(2).children.polyline_style=2;
904 a.children(1).children.polyline_style=4;
905 a.children(1).children.foreground=5;
906 a.children(2).children.foreground=14;
907 a.parent.figure_size= [1200,800];
908 a.box="on";
909 a.labels_font_size=4;
910 a.parent.background=8;
911 a.parent.figure_size= [400,200];
912 a.rotation_angles=[0 260];
913 delete(a.children(2));
914 delete(); // delete current object
915
916 a = gca();
917 a.labels_font_size=1;
918 a.auto_clear= "on";
919 x=0:0.1:2.5*%pi;plot2d(10*cos(x),sin(x));
920
921 a.data_bounds(:,1) = [1;15] ; // set positive bounds for X axe
922 a.log_flags = "lnn" ; // set X axes to logarithmic scale
923 a.log_flags = "nnn" ; // switch back to linear scale
924
925 a=gca();
926 a.rotation_angles=[45 45];
927 a.data_bounds=[-20,-3,-2;20 3 ,2];
928 xrect([-4 0.5 8 1]);
929 a.auto_clear = "off" ;
930 a.isoview="on"; // isoview mode
931 xrect([-2 0.25 4 0.5]);
932 a.children(1).fill_mode="on";
933 a.axes_visible="off";
934 a.children(1).data=[-2 0.25 -1 4 0.5];
935 a.children(2).data=[-4 0.5 1 8 1];
936 x=2*%pi*(0:7)/8;
937 xv=[.2*sin(x);.9*sin(x)];yv=[.2*cos(x);.9*cos(x)];
938 xsegs(10*xv,yv,1:8)
939 s=a.children(1);
940 s.arrow_size=1;
941 s.segs_color=5;
942 a.data_bounds //the boundary values for the x,y and z coordinates
943 a.view="2d";
944 a.data_bounds=[-10,-1; 10,1]; // set the boundary values for the two-dimensional views
945
946 // Example on axes model
947 da=gda() // get the handle on axes model to view and edit the fields
948 // title by default
949 da.title.text="My Default@Title"
950 da.title.foreground = 12;
951 da.title.font_size = 4;
952 // x labels default
953 da.x_label.text="x";
954 da.x_label.text="x"; // Latex or MathML can be used here also
955 da.x_label.font_style = 8;
956 da.x_label.font_size = 2;
957 da.x_label.foreground = 5;
958 da.x_location = "middle";
959 // y labels default
960 da.y_label.text="y";
961 da.y_label.font_style = 3;
962 da.y_label.font_size = 5;
963 da.y_label.foreground = 3;
964 da.y_location = "right";
965 da.thickness = 2;
966 da.foreground = 7;
967 // the plot
968 x=(0:0.1:2*%pi)';
969 plot2d(x,[sin(x),sin(2*x),sin(3*x)],style=[1,2,3],rect=[0,-2,2*%pi,2]);
970 sda() // back to default axes model
971
972
973 // Example with LaTeX / MathML ticks:
974 plot2d();
975 a=gca();
976
977 mathml="<mrow><mfrac><mrow><mi>d</mi>  <mi>y</mi></mrow><mrow>  <mi>d</mi>  <mi>x</mi></mrow></mfrac> <mo>=</mo>..
978 <mfrac><mn>1</mn><msup> <mi>y</mi>  <mn>2</mn></msup> </mfrac> </mrow>";
979 // Only LaTeX expression
980 a.x_ticks = tlist(["ticks", "locations", "labels"], (0:6)', [mathml;"1";"$\sin(x)$";"3";"$\cos(a) - test$";"5";"6"]);
981
982 // Mixed expression: MathML and LaTex
983 a.y_ticks = tlist(["ticks", "locations", "labels"], (-2:0.5:2)', ["0";"1";"2";"3";"$\cos(a)$";"5";"6";mathml;"8"]);
984
985  ]]>
986         </programlisting>
987         <para/>
988         <programlisting role="example">
989             <![CDATA[
990 m=[66.425514; 66.425513];
991 plot([69;70], m);
992 a=gca();
993 a.ticks_format=["" sprintf("%.2f", m(2))+"%+.1e"];
994 a.ticks_st=[1 1;0 m(2)];
995  ]]>
996         </programlisting>
997     </refsection>
998     <refsection role="see also">
999         <title>See Also</title>
1000         <simplelist type="inline">
1001             <member>
1002                 <link linkend="axis_properties">axis_properties</link>
1003             </member>
1004             <member>
1005                 <link linkend="lines">lines</link>
1006             </member>
1007             <member>
1008                 <link linkend="set">set</link>
1009             </member>
1010             <member>
1011                 <link linkend="get">get</link>
1012             </member>
1013             <member>
1014                 <link linkend="gca">gca</link>
1015             </member>
1016             <member>
1017                 <link linkend="gda">gda</link>
1018             </member>
1019             <member>
1020                 <link linkend="gcf">gcf</link>
1021             </member>
1022             <member>
1023                 <link linkend="sda">sda</link>
1024             </member>
1025             <member>
1026                 <link linkend="sdf">sdf</link>
1027             </member>
1028             <member>
1029                 <link linkend="scf">scf</link>
1030             </member>
1031             <member>
1032                 <link linkend="graphics_entities">graphics_entities</link>
1033             </member>
1034         </simplelist>
1035     </refsection>
1036     <refsection>
1037         <title>History</title>
1038         <revhistory>
1039             <revision>
1040                 <revnumber>5.4.0</revnumber>
1041                 <revremark>line_style value 0 is obsolete, use 1 instead (both are equivalent for SOLID). Using value 0 will produce an error in Scilab 5.4.1.</revremark>
1042             </revision>
1043             <revision>
1044                 <revnumber>5.5.0</revnumber>
1045                 <revremark>
1046                     <itemizedlist>
1047                         <listitem>line_style values 9 and 10 can be used to have respectively longblank dot and bigblank dot styles.</listitem>
1048                         <listitem>auto_margins property added to allow automatic computation of the margins.</listitem>
1049                         <listitem>ticks_format and ticks_st properties added to improve ticks labels display.</listitem>
1050                     </itemizedlist>
1051                 </revremark>
1052             </revision>
1053             <revision>
1054                 <revnumber>5.5.2</revnumber>
1055                 <revremark>tight_limits property can now manage X, Y and Z axis separately.</revremark>
1056             </revision>
1057         </revhistory>
1058     </refsection>
1059 </refentry>