scilab/modules/graphics/help/en_US/axis/axis_properties.xml

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