a5c8593e2e63d1c2befc1bddca0f820517354ab4
[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>box: </term>
302                             <listitem>
303                                 <para>This property specifies whether to enclose the axes in a box.
304                                     Its value can be either <literal>"off"</literal>,
305                                     <literal>"hidden_axes"</literal>, <literal>"back_half"</literal> or
306                                     <literal>"on".</literal> If the property is <literal>"off"</literal>, the box
307                                     is not draw. If the property is <literal>"hidden_axes"</literal>, only
308                                     the back frame is drawn. If the property is
309                                     <literal>"back_half"</literal>, the X, Y and Z axis are also drawn. If
310                                     the property is <literal>"on"</literal> the whole box is drawn.
311                                 </para>
312                             </listitem>
313                         </varlistentry>
314                         <varlistentry>
315                             <term>filled: </term>
316                             <listitem>
317                                 <para>This property specifies whether the axes background should be drawn or not.
318                                     Its value can be either <literal>"off"</literal> or
319                                     <literal>"on".</literal> If the property is <literal>"off"</literal>, the background
320                                     is not drawn, the axes box is transparent. If the property is <literal>"on"</literal> the
321                                     background is drawn using the color specified by the <literal>background</literal> property.
322                                 </para>
323                             </listitem>
324                         </varlistentry>
325                         <varlistentry>
326                             <term>sub_ticks: </term>
327                             <listitem>
328                                 <para>This field sets the number of tics to draw between two main
329                                     tics. The field value is the vector <literal>[nx,ny]</literal> where
330                                     <literal>nx</literal> is the number of sub tics for the x-axis and
331                                     <literal>ny</literal> respecting to the y-axis.
332                                 </para>
333                             </listitem>
334                         </varlistentry>
335                         <varlistentry>
336                             <term>font_style: </term>
337                             <listitem>
338                                 <para>Specifies the font used for displaying tics labels. This is a positive integer referecing one of the loaded fonts.
339                                     Its value must be between 0, referecing the first font,
340                                     and the number of loaded fonts minus one, referencing the last font.
341                                     For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
342                                 </para>
343                             </listitem>
344                         </varlistentry>
345                         <varlistentry>
346                             <term>font_size: </term>
347                             <listitem>
348                                 <para>
349                                     It is a scalar specifying the character size of tics labels.
350                                     If <literal>fractional_font</literal> property is <literal>"off"</literal>
351                                     only the integer part of the value is used.
352                                     For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
353                                 </para>
354                             </listitem>
355                         </varlistentry>
356                         <varlistentry>
357                             <term>font_color: </term>
358                             <listitem>
359                                 <para>This property determines the color of the tics labels.</para>
360                             </listitem>
361                         </varlistentry>
362                         <varlistentry>
363                             <term>fractional_font: </term>
364                             <listitem>
365                                 <para>
366                                     This property specify whether ticks labels are displayed using fractional font sizes.
367                                     Its value must be either <literal>"on"</literal> or <literal>"off"</literal>.
368                                     If <literal>"on"</literal> the floating point value of <literal>font_size</literal>
369                                     is used for display and the font is anti-aliased. If <literal>"off"</literal> only the integer part is used
370                                     and the font is not smoothed.
371                                 </para>
372                             </listitem>
373                         </varlistentry>
374                         <varlistentry>
375                             <term>isoview: </term>
376                             <listitem>
377                                 <para>This property is used to have isometric scales on the x, y and
378                                     z axes (for exemple to make the display of the curve sin(x) versus
379                                     cos(x) be a circle not an ellipse). Its value should be
380                                     <literal>"on"</literal> or <literal>"off"</literal>. If the value is
381                                     <literal>"on"</literal>, the axes <literal>data_bounds</literal> automatically
382                                     change according to the corresponding figure
383                                     <literal>figure_size</literal> property values.
384                                 </para>
385                             </listitem>
386                         </varlistentry>
387                         <varlistentry>
388                             <term>cube_scaling:</term>
389                             <listitem>
390                                 <para>
391                                     This property is used in <literal>3d mode</literal> to have a
392                                     rescaling of the x, y and z axes. Indeed, it allows the
393                                     <literal>data</literal> to fit into a 1x1x1 cube ; the goal is to better
394                                     display 3d graphics in case axes scales are very different from
395                                     one to another. Its value should be <literal>"on" </literal> or
396                                     <literal>"off"</literal> (which is the default value). In most cases, it
397                                     helps generating Matlab-like 3d view.
398                                 </para>
399                             </listitem>
400                         </varlistentry>
401                         <varlistentry>
402                             <term>view: </term>
403                             <listitem>
404                                 <para>This field is related to the graphics universe. It takes
405                                     <literal>"3d"</literal> as value corresponding to the three-dimensional
406                                     views. In the other case its value can be <literal>"2d"</literal> for
407                                     initial 2d plotting (default value). This flag also depends on the
408                                     plots the user enters : a <literal>plot3d </literal>command, for
409                                     example, will switch the <literal>view</literal> flag from
410                                     <literal>"2d"</literal> to <literal>"3d"</literal>.
411                                 </para>
412                             </listitem>
413                         </varlistentry>
414                         <varlistentry>
415                             <term>rotation_angles: </term>
416                             <listitem>
417                                 <para>
418                                     This field is the vector <literal>[alpha,theta]</literal>. These two
419                                     values give the spherical coordinates of the observation points
420                                     (in degree).
421                                 </para>
422                             </listitem>
423                         </varlistentry>
424                         <varlistentry>
425                             <term>log_flags: </term>
426                             <listitem>
427                                 <para> 3 character string that sets the scale (linear or logarithmic) along the axes.
428                                     Each character speficfies the scale for respectivgly the X, Y and Z axes.
429                                     They should take a value between <literal>'n'</literal> for linear scale or
430                                     <literal>'l'</literal> for logarithmic scale.
431                                 </para>
432                             </listitem>
433                         </varlistentry>
434                         <varlistentry>
435                             <term>tight_limits: </term>
436                             <listitem>
437                                 <para>
438                                     If this property value is <literal>"on"</literal> axes adapt to fit exactly with the minima and
439                                     maxima values of the data bounds. If this field value is <literal>"off"</literal>, axes may
440                                     enlarge boundaries such as to produce pretty tics labels.
441                                 </para>
442                             </listitem>
443                         </varlistentry>
444                         <varlistentry>
445                             <term>data_bounds: </term>
446                             <listitem>
447                                 <para>This field contains the boundary values for the x, y and z
448                                     coordinates. It is either the matrix or the vector
449                                     <literal>[xmin,ymin; xmax,ymax]</literal>,
450                                     <literal>[xmin,ymin,zmin; xmax,ymax,zmax]</literal>,
451                                     <literal>[xmin,xmax,ymin,ymax]</literal>,
452                                     <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>,
453                                     <literal>[xmin;xmax;ymin;ymax]</literal> or
454                                     <literal>[xmin;xmax;ymin;ymax;zmin;zmax]</literal>. Note that, to stricly have the
455                                     specified data bounds, <literal>tight_limits</literal> must be set to
456                                     <literal>"on"</literal> value (see above).
457                                     To manually set data_bounds set <literal>auto_scale="off"</literal>
458                                 </para>
459                             </listitem>
460                         </varlistentry>
461                         <varlistentry>
462                             <term>zoom_box: </term>
463                             <listitem>
464                                 <para>This field contains the current zoom box if any coordinates
465                                     are given. It is an empty matrix (no zoom) or the vector
466                                     <literal>[xmin,ymin,xmax,ymax,zmin,zmax]</literal> (defines a smaller axes box).
467                                 </para>
468                             </listitem>
469                         </varlistentry>
470                         <varlistentry>
471                             <term>margins: </term>
472                             <listitem>
473                                 <para>A vector
474                                     <literal>[margin_left,margin_right,margin_top,margin_bottom]</literal>
475                                     specifying the margins portion for this axes. This vector is
476                                     composed of numbers between [0 1] with default: [0.125 0.125 0.125
477                                     0.125]. These numbers are ratios relative to associated values of the
478                                     <literal>axes_bounds</literal> property, which are <literal>width</literal> for
479                                     <literal>margin_left</literal> and <literal>margin_right</literal>, and
480                                     <literal>height</literal> for <literal>margin_top</literal> and
481                                     <literal>margin_bottom</literal>.
482                                 </para>
483                             </listitem>
484                         </varlistentry>
485                         <varlistentry>
486                             <term>auto_margins: </term>
487                             <listitem>
488                                 <para>A property to allow the automatic computation of the margins accordint to their contents.
489                                     If value is <literal>"on"</literal>, then the automatic computation is activated.
490                                 </para>
491                             </listitem>
492                         </varlistentry>
493                         <varlistentry>
494                             <term>axes_bounds: </term>
495                             <listitem>
496                                 <para>
497                                     A vector <literal>[x_left,y_up,width,height]</literal> specifying
498                                     the portion of figure used by this axes. Where
499                                     <literal>x_left</literal>, <literal>y_up</literal>, <literal>width</literal> and
500                                     <literal>height</literal> are numbers in [0 1] give respectively the
501                                     position of the upper-left corner and the dimension of the axes
502                                     (these numbers are ratio relative to the corresponding figure
503                                     <literal>figure_size</literal> property values).
504                                 </para>
505                             </listitem>
506                         </varlistentry>
507                         <varlistentry>
508                             <term>hidden_axis_color: </term>
509                             <listitem>
510                                 <para>This property defined the color of the hidden axis. It takes
511                                     an index relative to the current colormap.
512                                 </para>
513                             </listitem>
514                         </varlistentry>
515                         <varlistentry>
516                             <term>user_data: </term>
517                             <listitem>
518                                 <para>This field can be use to store any scilab variable in the axes
519                                     data structure, and to retreive it.
520                                 </para>
521                             </listitem>
522                         </varlistentry>
523                     </variablelist>
524                 </listitem>
525             </varlistentry>
526             <varlistentry>
527                 <term>Properties for high level functions</term>
528                 <listitem>
529                     <para>
530                         The <literal>plot</literal>, <literal>plot2dx</literal>, <literal>grayplot</literal>
531                         and <literal>matplot</literal> functions use the following properties to
532                         decide how to merge consecutive plots if this is not stated by the
533                         <literal>frameflag</literal> calling argument. The result of the merge is
534                         decided through these two following properties:
535                     </para>
536                     <variablelist>
537                         <varlistentry>
538                             <term>auto_clear: </term>
539                             <listitem>
540                                 <para>
541                                     If this property value is equal to <literal>"on"</literal>, a call
542                                     to a high level graphic will re-ininitialize the current axes and
543                                     erase all its children before preforming the drawing (log_flags will be reset).
544                                     If the value is <literal>"off"</literal> the drawings will be added to current axes
545                                     according to <literal>"auto_scale"</literal> property.
546                                 </para>
547                             </listitem>
548                         </varlistentry>
549                         <varlistentry>
550                             <term>auto_scale: </term>
551                             <listitem>
552                                 <para>A property to update the axes data boundary. If value is
553                                     <literal>"on"</literal>, a new plot will adapt the current axes
554                                     properties to fit with previous and current plots. If its value is
555                                     <literal>"off"</literal> the new plot will be drawn in the current axes
556                                     data boundary.
557                                 </para>
558                             </listitem>
559                         </varlistentry>
560                     </variablelist>
561                 </listitem>
562             </varlistentry>
563             <varlistentry>
564                 <term>Children's default values: </term>
565                 <listitem>
566                     <variablelist>
567                         <varlistentry>
568                             <term>hiddencolor: </term>
569                             <listitem>
570                                 <para>This property controls the hidden parts' color. It takes as
571                                     value an index relative to the current colormap. In another case,
572                                     if it is a negative value, the hidden parts take the same colors
573                                     as the surface
574                                 </para>
575                             </listitem>
576                         </varlistentry>
577                         <varlistentry>
578                             <term>line_mode: </term>
579                             <listitem>
580                                 <para>
581                                     This field contains the default <literal>line_mode</literal>
582                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
583                                     Polyline objects. Its value should be <literal>"on" </literal>(default)
584                                     or <literal>"off"</literal>.
585                                 </para>
586                             </listitem>
587                         </varlistentry>
588                         <varlistentry>
589                             <term>line_style: </term>
590                             <listitem>
591                                 <para>
592                                     This field contains the default <literal>line_style</literal>
593                                     property value for Segs, Arcs, Rectangle and Polyline objects.
594                                     <literal>line_style</literal> selects the type of line to be used to
595                                     draw lines . Its value should be an integer in [1 10]. 1
596                                     stand for solid, the other values stand for a selection of dashes
597                                     (dash, dash dot, longdash dot, bigdash dot, bigdash longdash, dot, double dot, longblank dot, bigblank dot).
598                                 </para>
599                             </listitem>
600                         </varlistentry>
601                         <varlistentry>
602                             <term>thickness: </term>
603                             <listitem>
604                                 <para>
605                                     This field contains the default <literal>thickness</literal>
606                                     property value for all objects using line drawing. It is a positive real specifying the line width
607                                     in pixels. The displayed width is actually determined by rounding the supplied width
608                                     to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
609                                     value is considered.
610                                 </para>
611                             </listitem>
612                         </varlistentry>
613                         <varlistentry>
614                             <term>mark_mode: </term>
615                             <listitem>
616                                 <para>
617                                     This field contains the default <literal>mark_mode</literal>
618                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
619                                     Polyline objects. Its value should be <literal>"on" </literal> or
620                                     <literal>"off"</literal> (default).
621                                 </para>
622                             </listitem>
623                         </varlistentry>
624                         <varlistentry>
625                             <term>mark_style: </term>
626                             <listitem>
627                                 <para>
628                                     This field contains the default <literal>mark_style</literal>
629                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
630                                     Polyline objects. <literal>mark_style</literal> selects the type of mark
631                                     to be displayed. Its value should be an integer in [0 9] which
632                                     stands for: dot, plus, cross, star, filled diamond, diamond,
633                                     triangle up, triangle down, trefle and circle.
634                                 </para>
635                             </listitem>
636                         </varlistentry>
637                         <varlistentry>
638                             <term>mark_size_unit: </term>
639                             <listitem>
640                                 <para>
641                                     This field contains the default <literal>mark_size_unit</literal>
642                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
643                                     Polyline objects. If <literal>mark_size_unit</literal> is set to
644                                     <literal>"point"</literal>, then the <literal>mark_size</literal> value is
645                                     directly given in points. When <literal>mark_size_unit</literal> is set
646                                     to <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed
647                                     relative to the font size array: therefore, its value should be an
648                                     integer in [0 5] whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and
649                                     24pt. Note that <link linkend="plot2d">plot2d</link> and pure scilab functions use
650                                     <literal>tabulated</literal> mode as default ; when using
651                                     <link linkend="plot">plot</link> function, the <literal>point</literal> mode is
652                                     automatically enabled.
653                                 </para>
654                             </listitem>
655                         </varlistentry>
656                         <varlistentry>
657                             <term>mark_size: </term>
658                             <listitem>
659                                 <para>
660                                     This field contains the default <literal>mark_size</literal>
661                                     property value for Segs Rectangle Legend Axis Plot3d Fac3d and
662                                     Polyline objects. <literal>mark_size</literal> selects the font size of
663                                     mark to be displayed. Its value should be an integer in [0 5]
664                                     whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt (see
665                                     <link linkend="getmark">getmark</link>).
666                                 </para>
667                                 <para>
668                                     <warning>In the special case where mark_style and mark_size are 0, a dot of one pixel is drawn.</warning>
669                                 </para>
670                             </listitem>
671                         </varlistentry>
672                         <varlistentry>
673                             <term>mark_foreground: </term>
674                             <listitem>
675                                 <para>
676                                     This field contains the default <literal>mark_foreground</literal>
677                                     property value for all objects created under this axes. Polyline,
678                                     rectangle, legend, surface, segment and axis objects are using
679                                     this property to specify a foreground (edge) color for their
680                                     marks. Its value should be a color index (relative to the current
681                                     color_map) or 0 for transparant edge. Note that the default value is <literal>-1</literal>
682                                     (default black) and, even if you change the
683                                     <literal>color_map</literal>, this <literal>-1</literal> value will always
684                                     point onto the default black color.
685                                 </para>
686                             </listitem>
687                         </varlistentry>
688                         <varlistentry>
689                             <term>mark_background: </term>
690                             <listitem>
691                                 <para>This property controls the default
692                                     <literal>mark_background</literal> property value for all objects
693                                     created under this axes. Polyline, rectangle, legend, surface,
694                                     segment and axis objects are using this property to specify a
695                                     background (face) color for their marks. It takes as value an
696                                     index relative to the current colormap or 0 for transparant face. Note that the default value
697                                     is <literal>-2</literal> (default white) and, even if you change the
698                                     <literal>color_map</literal>, this <literal>-2</literal> value will always
699                                     point onto the default white color.
700                                 </para>
701                             </listitem>
702                         </varlistentry>
703                         <varlistentry>
704                             <term>foreground: </term>
705                             <listitem>
706                                 <para>
707                                     This field contains the default <literal>foreground</literal>
708                                     property value for axes and all objects created under this axes.
709                                     Its value should be a color index (relative to the current
710                                     color_map). Note that the default value is <literal>-1</literal>
711                                     (default black) and, even if you change the
712                                     <literal>color_map</literal>, this <literal>-1</literal> value will always
713                                     point onto the default black color.
714                                 </para>
715                             </listitem>
716                         </varlistentry>
717                         <varlistentry>
718                             <term>background: </term>
719                             <listitem>
720                                 <para>
721                                     This property controls the default <literal>background</literal>
722                                     property value for axes and all objects created under this axes.
723                                     It takes as value an index relative to the current colormap.Note
724                                     that the default value is <literal>-2</literal> (default white) and,
725                                     even if you change the <literal>color_map</literal>, this
726                                     <literal>-2</literal> value will always point onto the default white
727                                     color.
728                                 </para>
729                             </listitem>
730                         </varlistentry>
731                         <varlistentry>
732                             <term>arc_drawing_mode: </term>
733                             <listitem>
734                                 <para>
735                                     This property controls the default <literal>arc_drawing_mode</literal>
736                                     property value for all created Arc objects under this Axes object.
737                                     Its value should be either <literal>"nurbs"</literal> or <literal>"lines"</literal>.
738                                 </para>
739                             </listitem>
740                         </varlistentry>
741                         <varlistentry>
742                             <term>clip_state: </term>
743                             <listitem>
744                                 <para>
745                                     This field contains the default <literal>clip_state</literal>
746                                     property value for all objects. Its value should be :
747                                 </para>
748                                 <itemizedlist>
749                                     <listitem>
750                                         <para>
751                                             <literal>"off"</literal> this means that all objects created
752                                             after that are not clipped (default value).
753                                         </para>
754                                     </listitem>
755                                     <listitem>
756                                         <para>
757                                             <literal>"clipgrf"</literal> this means that all objects created
758                                             after that are clipped outside the Axes boundaries.
759                                         </para>
760                                     </listitem>
761                                     <listitem>
762                                         <para>
763                                             <literal>"on"</literal> this means that all objects created
764                                             after that are clipped outside the rectangle given by property
765                                             clip_box.
766                                         </para>
767                                     </listitem>
768                                 </itemizedlist>
769                             </listitem>
770                         </varlistentry>
771                         <varlistentry>
772                             <term>clip_box: </term>
773                             <listitem>
774                                 <para>
775                                     This field contains the default <literal>clip_box</literal> property
776                                     value for all objects. Its value should be an empty matrix if
777                                     clip_state is <literal>"off"</literal>. Other case the clipping is given
778                                     by the vector <literal>[x,y,w,h]</literal> (upper-left point width
779                                     height).
780                                 </para>
781                             </listitem>
782                         </varlistentry>
783                         <varlistentry>
784                             <term>Note on default values :</term>
785                             <listitem>
786                                 <variablelist>
787                                     <varlistentry>
788                                         <term/>
789                                         <listitem>
790                                             <para>All these listed properties and fields inherit from
791                                                 default values stored in an axes model. These default values
792                                                 can be seen and changed. To do so, use the
793                                                 <literal>get("default_axes")</literal> command : it returns a
794                                                 graphic handle on the axes model. Note that no graphic window
795                                                 is created by this command. The next created axes will inherit
796                                                 from this model (see "Example on axes model" below).
797                                             </para>
798                                         </listitem>
799                                     </varlistentry>
800                                 </variablelist>
801                             </listitem>
802                         </varlistentry>
803                     </variablelist>
804                 </listitem>
805             </varlistentry>
806         </variablelist>
807     </refsection>
808     <refsection>
809         <title>Examples</title>
810         <programlisting role="example"><![CDATA[
811 lines(0) // disables vertical paging
812 a=get("current_axes")//get the handle of the newly created axes
813 a.axes_visible="on"; // makes the axes visible
814 a.font_size=3; //set the tics label font size
815 a.x_location="top"; //set the x axis position
816 a.data_bounds=[-100,-2,-1;100,2,1]; //set the boundary values for the x, y and z coordinates.
817 a.sub_tics=[5,0];
818 a.labels_font_color=5;
819 a.grid=[2,2];
820 a.box="off";
821
822 // Example with 3D axes
823 clf(); //clear the graphics window
824 x=0.1:0.1:2*%pi;plot2d(x-.3,sin(x)*7+.2);
825 a=gca(); // get the handle of the current axes
826 a.grid=[1 -1 -1]; //make x-grid
827 a.rotation_angles=[70 250]; //turn the axes with giving angles
828 a.grid=[1 6 -1]; //make y-grid
829 a.view="2d"; //return te the 2d view
830 a.box="back_half";
831 a.labels_font_color=5;
832 a.children.children.thickness=4;
833 a.children.children.polyline_style=3;
834 a.view="3d"; //return te the 3d view
835 a.children.children.thickness=1;
836 a.children.children.foreground=2;
837 a.grid=[1 6 3]; //make z-grid
838 a.parent.background=4;
839 a.background=7;
840 plot2d(cos(x)+1,3*sin(x)-3);
841 plot2d(cos(x)+7,3*sin(x)+3);
842 a.children(2).children.polyline_style=2;
843 a.children(1).children.polyline_style=4;
844 a.children(1).children.foreground=5;
845 a.children(2).children.foreground=14;
846 a.parent.figure_size= [1200,800];
847 a.box="on";
848 a.labels_font_size=4;
849 a.parent.background=8;
850 a.parent.figure_size= [400,200];
851 a.rotation_angles=[0 260];
852 delete(a.children(2));
853 delete(); // delete current object
854
855 a = gca();
856 a.labels_font_size=1;
857 a.auto_clear= "on";
858 x=0:0.1:2.5*%pi;plot2d(10*cos(x),sin(x));
859
860 a.data_bounds(:,1) = [1;15] ; // set positive bounds for X axe
861 a.log_flags = "lnn" ; // set X axes to logarithmic scale
862 a.log_flags = "nnn" ; // switch back to linear scale
863
864 a=gca();
865 a.rotation_angles=[45 45];
866 a.data_bounds=[-20,-3,-2;20 3 ,2];
867 xrect([-4 0.5 8 1]);
868 a.auto_clear = "off" ;
869 a.isoview="on"; // isoview mode
870 xrect([-2 0.25 4 0.5]);
871 a.children(1).fill_mode="on";
872 a.axes_visible="off";
873 a.children(1).data=[-2 0.25 -1 4 0.5];
874 a.children(2).data=[-4 0.5 1 8 1];
875 x=2*%pi*(0:7)/8;
876 xv=[.2*sin(x);.9*sin(x)];yv=[.2*cos(x);.9*cos(x)];
877 xsegs(10*xv,yv,1:8)
878 s=a.children(1);
879 s.arrow_size=1;
880 s.segs_color=5;
881 a.data_bounds //the boundary values for the x,y and z coordinates
882 a.view="2d";
883 a.data_bounds=[-10,-1; 10,1]; // set the boundary values for the two-dimensional views
884
885 // Example on axes model
886 da=gda() // get the handle on axes model to view and edit the fields
887 // title by default
888 da.title.text="My Default@Title"
889 da.title.foreground = 12;
890 da.title.font_size = 4;
891 // x labels default
892 da.x_label.text="x";
893 da.x_label.text="x"; // Latex or MathML can be used here also
894 da.x_label.font_style = 8;
895 da.x_label.font_size = 2;
896 da.x_label.foreground = 5;
897 da.x_location = "middle";
898 // y labels default
899 da.y_label.text="y";
900 da.y_label.font_style = 3;
901 da.y_label.font_size = 5;
902 da.y_label.foreground = 3;
903 da.y_location = "right";
904 da.thickness = 2;
905 da.foreground = 7;
906 // the plot
907 x=(0:0.1:2*%pi)';
908 plot2d(x,[sin(x),sin(2*x),sin(3*x)],style=[1,2,3],rect=[0,-2,2*%pi,2]);
909 sda() // back to default axes model
910
911
912 // Example with LaTeX / MathML ticks:
913 plot2d();
914 a=gca();
915
916 mathml="<mrow><mfrac><mrow><mi>d</mi>  <mi>y</mi></mrow><mrow>  <mi>d</mi>  <mi>x</mi></mrow></mfrac> <mo>=</mo>..
917 <mfrac><mn>1</mn><msup> <mi>y</mi>  <mn>2</mn></msup> </mfrac> </mrow>";
918 // Only LaTeX expression
919 a.x_ticks = tlist(["ticks", "locations", "labels"], (0:6)', [mathml;"1";"$\sin(x)$";"3";"$\cos(a) - test$";"5";"6"]);
920
921 // Mixed expression: MathML and LaTex
922 a.y_ticks = tlist(["ticks", "locations", "labels"], (-2:0.5:2)', ["0";"1";"2";"3";"$\cos(a)$";"5";"6";mathml;"8"]);
923
924  ]]></programlisting>
925     </refsection>
926     <refsection role="see also">
927         <title>See Also</title>
928         <simplelist type="inline">
929             <member>
930                 <link linkend="axis_properties">axis_properties</link>
931             </member>
932             <member>
933                 <link linkend="lines">lines</link>
934             </member>
935             <member>
936                 <link linkend="set">set</link>
937             </member>
938             <member>
939                 <link linkend="get">get</link>
940             </member>
941             <member>
942                 <link linkend="gca">gca</link>
943             </member>
944             <member>
945                 <link linkend="gda">gda</link>
946             </member>
947             <member>
948                 <link linkend="gcf">gcf</link>
949             </member>
950             <member>
951                 <link linkend="sda">sda</link>
952             </member>
953             <member>
954                 <link linkend="sdf">sdf</link>
955             </member>
956             <member>
957                 <link linkend="scf">scf</link>
958             </member>
959             <member>
960                 <link linkend="graphics_entities">graphics_entities</link>
961             </member>
962         </simplelist>
963     </refsection>
964     <refsection>
965         <title>History</title>
966         <revhistory>
967             <revision>
968                 <revnumber>5.4.0</revnumber>
969                 <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>
970             </revision>
971             <revision>
972                 <revnumber>5.5.0</revnumber>
973                 <revremark>line_style values 9 and 10 can be used to have respectively longblank dot and bigblank dot styles.</revremark>
974                 <revremark>auto_margins property added to allow automatic computation of the margins.</revremark>
975             </revision>
976         </revhistory>
977     </refsection>
978 </refentry>