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