a5f4f8be67e1ba0eb0a85e3cff4e84acda3dedda
[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 respectivgly 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                                     If this property value is <literal>"on"</literal> axes adapt to fit exactly with the minima and
485                                     maxima values of the data bounds. If this field value is <literal>"off"</literal>, axes may
486                                     enlarge boundaries such as to produce pretty tics labels.
487                                 </para>
488                             </listitem>
489                         </varlistentry>
490                         <varlistentry>
491                             <term>data_bounds: </term>
492                             <listitem>
493                                 <para>
494                                     This field contains the boundary values for the x, y and z
495                                     coordinates. It is either the matrix or the vector
496                                     <literal>[xmin,ymin; xmax,ymax]</literal>,
497                                     <literal>[xmin,ymin,zmin; xmax,ymax,zmax]</literal>,
498                                     <literal>[xmin,xmax,ymin,ymax]</literal>,
499                                     <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>,
500                                     <literal>[xmin;xmax;ymin;ymax]</literal> or
501                                     <literal>[xmin;xmax;ymin;ymax;zmin;zmax]</literal>. Note that, to stricly have the
502                                     specified data bounds, <literal>tight_limits</literal> must be set to
503                                     <literal>"on"</literal> value (see above).
504                                     To manually set data_bounds set <literal>auto_scale="off"</literal>
505                                 </para>
506                             </listitem>
507                         </varlistentry>
508                         <varlistentry>
509                             <term>zoom_box: </term>
510                             <listitem>
511                                 <para>
512                                     This field contains the current zoom box if any coordinates
513                                     are given. It is an empty matrix (no zoom) or the vector
514                                     <literal>[xmin,ymin,xmax,ymax,zmin,zmax]</literal> (defines a smaller axes box).
515                                 </para>
516                             </listitem>
517                         </varlistentry>
518                         <varlistentry>
519                             <term>margins: </term>
520                             <listitem>
521                                 <para>
522                                     A vector
523                                     <literal>[margin_left,margin_right,margin_top,margin_bottom]</literal>
524                                     specifying the margins portion for this axes. This vector is
525                                     composed of numbers between [0 1] with default: [0.125 0.125 0.125
526                                     0.125]. These numbers are ratios relative to associated values of the
527                                     <literal>axes_bounds</literal> property, which are <literal>width</literal> for
528                                     <literal>margin_left</literal> and <literal>margin_right</literal>, and
529                                     <literal>height</literal> for <literal>margin_top</literal> and
530                                     <literal>margin_bottom</literal>.
531                                 </para>
532                             </listitem>
533                         </varlistentry>
534                         <varlistentry>
535                             <term>auto_margins: </term>
536                             <listitem>
537                                 <para>
538                                     A property to allow the automatic computation of the margins accordint to their contents.
539                                     If value is <literal>"on"</literal>, then the automatic computation is activated.
540                                 </para>
541                             </listitem>
542                         </varlistentry>
543                         <varlistentry>
544                             <term>axes_bounds: </term>
545                             <listitem>
546                                 <para>
547                                     A vector <literal>[x_left,y_up,width,height]</literal> specifying
548                                     the portion of figure used by this axes. Where
549                                     <literal>x_left</literal>, <literal>y_up</literal>, <literal>width</literal> and
550                                     <literal>height</literal> are numbers in [0 1] give respectively the
551                                     position of the upper-left corner and the dimension of the axes
552                                     (these numbers are ratio relative to the corresponding figure
553                                     <literal>figure_size</literal> property values).
554                                 </para>
555                             </listitem>
556                         </varlistentry>
557                         <varlistentry>
558                             <term>hidden_axis_color: </term>
559                             <listitem>
560                                 <para>
561                                     This property defined the color of the hidden axis. It takes
562                                     an index relative to the current colormap.
563                                 </para>
564                             </listitem>
565                         </varlistentry>
566                         <varlistentry>
567                             <term>user_data: </term>
568                             <listitem>
569                                 <para>
570                                     This field can be use to store any scilab variable in the axes
571                                     data structure, and to retreive it.
572                                 </para>
573                             </listitem>
574                         </varlistentry>
575                     </variablelist>
576                 </listitem>
577             </varlistentry>
578             <varlistentry>
579                 <term>Properties for high level functions</term>
580                 <listitem>
581                     <para>
582                         The <literal>plot</literal>, <literal>plot2dx</literal>, <literal>grayplot</literal>
583                         and <literal>matplot</literal> functions use the following properties to
584                         decide how to merge consecutive plots if this is not stated by the
585                         <literal>frameflag</literal> calling argument. The result of the merge is
586                         decided through these two following properties:
587                     </para>
588                     <variablelist>
589                         <varlistentry>
590                             <term>auto_clear: </term>
591                             <listitem>
592                                 <para>
593                                     If this property value is equal to <literal>"on"</literal>, a call
594                                     to a high level graphic will re-ininitialize the current axes and
595                                     erase all its children before preforming the drawing (log_flags will be reset).
596                                     If the value is <literal>"off"</literal> the drawings will be added to current axes
597                                     according to <literal>"auto_scale"</literal> property.
598                                 </para>
599                             </listitem>
600                         </varlistentry>
601                         <varlistentry>
602                             <term>auto_scale: </term>
603                             <listitem>
604                                 <para>
605                                     A property to update the axes data boundary. If value is
606                                     <literal>"on"</literal>, a new plot will adapt the current axes
607                                     properties to fit with previous and current plots. If its value is
608                                     <literal>"off"</literal> the new plot will be drawn in the current axes
609                                     data boundary.
610                                 </para>
611                             </listitem>
612                         </varlistentry>
613                     </variablelist>
614                 </listitem>
615             </varlistentry>
616             <varlistentry>
617                 <term>Children's default values: </term>
618                 <listitem>
619                     <variablelist>
620                         <varlistentry>
621                             <term>hiddencolor: </term>
622                             <listitem>
623                                 <para>
624                                     This property controls the hidden parts' color. It takes as
625                                     value an index relative to the current colormap. In another case,
626                                     if it is a negative value, the hidden parts take the same colors
627                                     as the surface
628                                 </para>
629                             </listitem>
630                         </varlistentry>
631                         <varlistentry>
632                             <term>line_mode: </term>
633                             <listitem>
634                                 <para>
635                                     This field contains the default <literal>line_mode</literal>
636                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
637                                     Polyline objects. Its value should be <literal>"on" </literal>(default)
638                                     or <literal>"off"</literal>.
639                                 </para>
640                             </listitem>
641                         </varlistentry>
642                         <varlistentry>
643                             <term>line_style: </term>
644                             <listitem>
645                                 <para>
646                                     This field contains the default <literal>line_style</literal>
647                                     property value for Segs, Arcs, Rectangle and Polyline objects.
648                                     <literal>line_style</literal> selects the type of line to be used to
649                                     draw lines . Its value should be an integer in [1 10]. 1
650                                     stand for solid, the other values stand for a selection of dashes
651                                     (dash, dash dot, longdash dot, bigdash dot, bigdash longdash, dot, double dot, longblank dot, bigblank dot).
652                                 </para>
653                             </listitem>
654                         </varlistentry>
655                         <varlistentry>
656                             <term>thickness: </term>
657                             <listitem>
658                                 <para>
659                                     This field contains the default <literal>thickness</literal>
660                                     property value for all objects using line drawing. It is a positive real specifying the line width
661                                     in pixels. The displayed width is actually determined by rounding the supplied width
662                                     to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
663                                     value is considered.
664                                 </para>
665                             </listitem>
666                         </varlistentry>
667                         <varlistentry>
668                             <term>mark_mode: </term>
669                             <listitem>
670                                 <para>
671                                     This field contains the default <literal>mark_mode</literal>
672                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
673                                     Polyline objects. Its value should be <literal>"on" </literal> or
674                                     <literal>"off"</literal> (default).
675                                 </para>
676                             </listitem>
677                         </varlistentry>
678                         <varlistentry>
679                             <term>mark_style: </term>
680                             <listitem>
681                                 <para>
682                                     This field contains the default <literal>mark_style</literal>
683                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
684                                     Polyline objects. <literal>mark_style</literal> selects the type of mark
685                                     to be displayed. Its value should be an integer in [0 9] which
686                                     stands for: dot, plus, cross, star, filled diamond, diamond,
687                                     triangle up, triangle down, trefle and circle.
688                                 </para>
689                             </listitem>
690                         </varlistentry>
691                         <varlistentry>
692                             <term>mark_size_unit: </term>
693                             <listitem>
694                                 <para>
695                                     This field contains the default <literal>mark_size_unit</literal>
696                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
697                                     Polyline objects. If <literal>mark_size_unit</literal> is set to
698                                     <literal>"point"</literal>, then the <literal>mark_size</literal> value is
699                                     directly given in points. When <literal>mark_size_unit</literal> is set
700                                     to <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed
701                                     relative to the font size array: therefore, its value should be an
702                                     integer in [0 5] whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and
703                                     24pt. Note that <link linkend="plot2d">plot2d</link> and pure scilab functions use
704                                     <literal>tabulated</literal> mode as default ; when using
705                                     <link linkend="plot">plot</link> function, the <literal>point</literal> mode is
706                                     automatically enabled.
707                                 </para>
708                             </listitem>
709                         </varlistentry>
710                         <varlistentry>
711                             <term>mark_size: </term>
712                             <listitem>
713                                 <para>
714                                     This field contains the default <literal>mark_size</literal>
715                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
716                                     Polyline objects. <literal>mark_size</literal> selects the font size of
717                                     mark to be displayed. Its value should be an integer in [0 5]
718                                     whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
719                                 </para>
720                                 <para>
721                                     <warning>In the special case where mark_style and mark_size are 0, a dot of one pixel is drawn.</warning>
722                                 </para>
723                             </listitem>
724                         </varlistentry>
725                         <varlistentry>
726                             <term>mark_foreground: </term>
727                             <listitem>
728                                 <para>
729                                     This field contains the default <literal>mark_foreground</literal>
730                                     property value for all objects created under this axes. Polyline,
731                                     rectangle, legend, surface, segment and axis objects are using
732                                     this property to specify a foreground (edge) color for their
733                                     marks. Its value should be a color index (relative to the current
734                                     color_map) or 0 for transparant edge. Note that the default value is <literal>-1</literal>
735                                     (default black) and, even if you change the
736                                     <literal>color_map</literal>, this <literal>-1</literal> value will always
737                                     point onto the default black color.
738                                 </para>
739                             </listitem>
740                         </varlistentry>
741                         <varlistentry>
742                             <term>mark_background: </term>
743                             <listitem>
744                                 <para>
745                                     This property controls the default
746                                     <literal>mark_background</literal> property value for all objects
747                                     created under this axes. Polyline, rectangle, legend, surface,
748                                     segment and axis objects are using this property to specify a
749                                     background (face) color for their marks. It takes as value an
750                                     index relative to the current colormap or 0 for transparant face. Note that the default value
751                                     is <literal>-2</literal> (default white) and, even if you change the
752                                     <literal>color_map</literal>, this <literal>-2</literal> value will always
753                                     point onto the default white color.
754                                 </para>
755                             </listitem>
756                         </varlistentry>
757                         <varlistentry>
758                             <term>foreground: </term>
759                             <listitem>
760                                 <para>
761                                     This field contains the default <literal>foreground</literal>
762                                     property value for axes and all objects created under this axes.
763                                     Its value should be a color index (relative to the current
764                                     color_map). Note that the default value is <literal>-1</literal>
765                                     (default black) and, even if you change the
766                                     <literal>color_map</literal>, this <literal>-1</literal> value will always
767                                     point onto the default black color.
768                                 </para>
769                             </listitem>
770                         </varlistentry>
771                         <varlistentry>
772                             <term>background: </term>
773                             <listitem>
774                                 <para>
775                                     This property controls the default <literal>background</literal>
776                                     property value for axes and all objects created under this axes.
777                                     It takes as value an index relative to the current colormap.Note
778                                     that the default value is <literal>-2</literal> (default white) and,
779                                     even if you change the <literal>color_map</literal>, this
780                                     <literal>-2</literal> value will always point onto the default white
781                                     color.
782                                 </para>
783                             </listitem>
784                         </varlistentry>
785                         <varlistentry>
786                             <term>arc_drawing_mode: </term>
787                             <listitem>
788                                 <para>
789                                     This property controls the default <literal>arc_drawing_mode</literal>
790                                     property value for all created Arc objects under this Axes object.
791                                     Its value should be either <literal>"nurbs"</literal> or <literal>"lines"</literal>.
792                                 </para>
793                             </listitem>
794                         </varlistentry>
795                         <varlistentry>
796                             <term>clip_state: </term>
797                             <listitem>
798                                 <para>
799                                     This field contains the default <literal>clip_state</literal>
800                                     property value for all objects. Its value should be :
801                                 </para>
802                                 <itemizedlist>
803                                     <listitem>
804                                         <para>
805                                             <literal>"off"</literal> this means that all objects created
806                                             after that are not clipped (default value).
807                                         </para>
808                                     </listitem>
809                                     <listitem>
810                                         <para>
811                                             <literal>"clipgrf"</literal> this means that all objects created
812                                             after that are clipped outside the Axes boundaries.
813                                         </para>
814                                     </listitem>
815                                     <listitem>
816                                         <para>
817                                             <literal>"on"</literal> this means that all objects created
818                                             after that are clipped outside the rectangle given by property
819                                             clip_box.
820                                         </para>
821                                     </listitem>
822                                 </itemizedlist>
823                             </listitem>
824                         </varlistentry>
825                         <varlistentry>
826                             <term>clip_box: </term>
827                             <listitem>
828                                 <para>
829                                     This field contains the default <literal>clip_box</literal> property
830                                     value for all objects. Its value should be an empty matrix if
831                                     clip_state is <literal>"off"</literal>. Other case the clipping is given
832                                     by the vector <literal>[x,y,w,h]</literal> (upper-left point width
833                                     height).
834                                 </para>
835                             </listitem>
836                         </varlistentry>
837                         <varlistentry>
838                             <term>Note on default values :</term>
839                             <listitem>
840                                 <variablelist>
841                                     <varlistentry>
842                                         <term/>
843                                         <listitem>
844                                             <para>
845                                                 All these listed properties and fields inherit from
846                                                 default values stored in an axes model. These default values
847                                                 can be seen and changed. To do so, use the
848                                                 <literal>get("default_axes")</literal> command : it returns a
849                                                 graphic handle on the axes model. Note that no graphic window
850                                                 is created by this command. The next created axes will inherit
851                                                 from this model (see "Example on axes model" below).
852                                             </para>
853                                         </listitem>
854                                     </varlistentry>
855                                 </variablelist>
856                             </listitem>
857                         </varlistentry>
858                     </variablelist>
859                 </listitem>
860             </varlistentry>
861         </variablelist>
862     </refsection>
863     <refsection>
864         <title>Examples</title>
865         <programlisting role="example">
866             <![CDATA[
867 lines(0) // disables vertical paging
868 a=get("current_axes")//get the handle of the newly created axes
869 a.axes_visible="on"; // makes the axes visible
870 a.font_size=3; //set the tics label font size
871 a.x_location="top"; //set the x axis position
872 a.data_bounds=[-100,-2,-1;100,2,1]; //set the boundary values for the x, y and z coordinates.
873 a.sub_tics=[5,0];
874 a.labels_font_color=5;
875 a.grid=[2,2];
876 a.box="off";
877
878 // Example with 3D axes
879 clf(); //clear the graphics window
880 x=0.1:0.1:2*%pi;plot2d(x-.3,sin(x)*7+.2);
881 a=gca(); // get the handle of the current axes
882 a.grid=[1 -1 -1]; //make x-grid
883 a.rotation_angles=[70 250]; //turn the axes with giving angles
884 a.grid=[1 6 -1]; //make y-grid
885 a.view="2d"; //return te the 2d view
886 a.box="back_half";
887 a.labels_font_color=5;
888 a.children.children.thickness=4;
889 a.children.children.polyline_style=3;
890 a.view="3d"; //return te the 3d view
891 a.children.children.thickness=1;
892 a.children.children.foreground=2;
893 a.grid=[1 6 3]; //make z-grid
894 a.parent.background=4;
895 a.background=7;
896 plot2d(cos(x)+1,3*sin(x)-3);
897 plot2d(cos(x)+7,3*sin(x)+3);
898 a.children(2).children.polyline_style=2;
899 a.children(1).children.polyline_style=4;
900 a.children(1).children.foreground=5;
901 a.children(2).children.foreground=14;
902 a.parent.figure_size= [1200,800];
903 a.box="on";
904 a.labels_font_size=4;
905 a.parent.background=8;
906 a.parent.figure_size= [400,200];
907 a.rotation_angles=[0 260];
908 delete(a.children(2));
909 delete(); // delete current object
910
911 a = gca();
912 a.labels_font_size=1;
913 a.auto_clear= "on";
914 x=0:0.1:2.5*%pi;plot2d(10*cos(x),sin(x));
915
916 a.data_bounds(:,1) = [1;15] ; // set positive bounds for X axe
917 a.log_flags = "lnn" ; // set X axes to logarithmic scale
918 a.log_flags = "nnn" ; // switch back to linear scale
919
920 a=gca();
921 a.rotation_angles=[45 45];
922 a.data_bounds=[-20,-3,-2;20 3 ,2];
923 xrect([-4 0.5 8 1]);
924 a.auto_clear = "off" ;
925 a.isoview="on"; // isoview mode
926 xrect([-2 0.25 4 0.5]);
927 a.children(1).fill_mode="on";
928 a.axes_visible="off";
929 a.children(1).data=[-2 0.25 -1 4 0.5];
930 a.children(2).data=[-4 0.5 1 8 1];
931 x=2*%pi*(0:7)/8;
932 xv=[.2*sin(x);.9*sin(x)];yv=[.2*cos(x);.9*cos(x)];
933 xsegs(10*xv,yv,1:8)
934 s=a.children(1);
935 s.arrow_size=1;
936 s.segs_color=5;
937 a.data_bounds //the boundary values for the x,y and z coordinates
938 a.view="2d";
939 a.data_bounds=[-10,-1; 10,1]; // set the boundary values for the two-dimensional views
940
941 // Example on axes model
942 da=gda() // get the handle on axes model to view and edit the fields
943 // title by default
944 da.title.text="My Default@Title"
945 da.title.foreground = 12;
946 da.title.font_size = 4;
947 // x labels default
948 da.x_label.text="x";
949 da.x_label.text="x"; // Latex or MathML can be used here also
950 da.x_label.font_style = 8;
951 da.x_label.font_size = 2;
952 da.x_label.foreground = 5;
953 da.x_location = "middle";
954 // y labels default
955 da.y_label.text="y";
956 da.y_label.font_style = 3;
957 da.y_label.font_size = 5;
958 da.y_label.foreground = 3;
959 da.y_location = "right";
960 da.thickness = 2;
961 da.foreground = 7;
962 // the plot
963 x=(0:0.1:2*%pi)';
964 plot2d(x,[sin(x),sin(2*x),sin(3*x)],style=[1,2,3],rect=[0,-2,2*%pi,2]);
965 sda() // back to default axes model
966
967
968 // Example with LaTeX / MathML ticks:
969 plot2d();
970 a=gca();
971
972 mathml="<mrow><mfrac><mrow><mi>d</mi>  <mi>y</mi></mrow><mrow>  <mi>d</mi>  <mi>x</mi></mrow></mfrac> <mo>=</mo>..
973 <mfrac><mn>1</mn><msup> <mi>y</mi>  <mn>2</mn></msup> </mfrac> </mrow>";
974 // Only LaTeX expression
975 a.x_ticks = tlist(["ticks", "locations", "labels"], (0:6)', [mathml;"1";"$\sin(x)$";"3";"$\cos(a) - test$";"5";"6"]);
976
977 // Mixed expression: MathML and LaTex
978 a.y_ticks = tlist(["ticks", "locations", "labels"], (-2:0.5:2)', ["0";"1";"2";"3";"$\cos(a)$";"5";"6";mathml;"8"]);
979
980  ]]>
981         </programlisting>
982         <para/>
983         <programlisting role="example">
984             <![CDATA[
985 m=[66.425514; 66.425513];
986 plot([69;70], m);
987 a=gca();
988 a.ticks_format=["" sprintf("%.2f", m(2))+"%+.1e"];
989 a.ticks_st=[1 1;0 m(2)];
990  ]]>
991         </programlisting>
992     </refsection>
993     <refsection role="see also">
994         <title>See Also</title>
995         <simplelist type="inline">
996             <member>
997                 <link linkend="axis_properties">axis_properties</link>
998             </member>
999             <member>
1000                 <link linkend="lines">lines</link>
1001             </member>
1002             <member>
1003                 <link linkend="set">set</link>
1004             </member>
1005             <member>
1006                 <link linkend="get">get</link>
1007             </member>
1008             <member>
1009                 <link linkend="gca">gca</link>
1010             </member>
1011             <member>
1012                 <link linkend="gda">gda</link>
1013             </member>
1014             <member>
1015                 <link linkend="gcf">gcf</link>
1016             </member>
1017             <member>
1018                 <link linkend="sda">sda</link>
1019             </member>
1020             <member>
1021                 <link linkend="sdf">sdf</link>
1022             </member>
1023             <member>
1024                 <link linkend="scf">scf</link>
1025             </member>
1026             <member>
1027                 <link linkend="graphics_entities">graphics_entities</link>
1028             </member>
1029         </simplelist>
1030     </refsection>
1031     <refsection>
1032         <title>History</title>
1033         <revhistory>
1034             <revision>
1035                 <revnumber>5.4.0</revnumber>
1036                 <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>
1037             </revision>
1038             <revision>
1039                 <revnumber>5.5.0</revnumber>
1040                 <revremark>
1041                     <itemizedlist>
1042                         <listitem>line_style values 9 and 10 can be used to have respectively longblank dot and bigblank dot styles.</listitem>
1043                         <listitem>auto_margins property added to allow automatic computation of the margins.</listitem>
1044                         <listitem>ticks_format and ticks_st properties added to improve ticks labels display.</listitem>
1045                     </itemizedlist>
1046                 </revremark>
1047             </revision>
1048         </revhistory>
1049     </refsection>
1050 </refentry>