scilab/modules/graphics/help/en_US/annotation/legend_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-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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="legend_properties" xml:lang="en">
  14     <refnamediv>
  15         <refname>Legend entity properties</refname>
  16         <refpurpose>description of the Legend entity properties.</refpurpose>
  17     </refnamediv>
  18     <refsection>
  19         <title>Description</title>
  20         <para>The Legend entity is a leaf of the graphics entities
  21             hierarchy. This entity defines the parameters for legends drawn
  22             below <literal>plot2dx</literal> graphs or created by the <link linkend="captions">captions</link> function. For selected line
  23             plotted, the legend shows a sample of the line type, marker
  24             symbol, and color.
  25         </para>
  26         <variablelist>
  27             <varlistentry>
  28                 <term>parent:</term>
  29                 <listitem>
  30                     <para>This property contains the handle of the parent. The
  31                         parent of the legend entity should be of the type
  32                         <literal>"Compound"</literal>. This Compound entity contains
  33                         also the remainder of the graph's entities.
  34                     </para>
  35                 </listitem>
  36             </varlistentry>
  37             <varlistentry>
  38                 <term>children:</term>
  39                 <listitem>
  40                     <para>This property contains a vector with the
  41                         <literal>children</literal> of the handle. However,
  42                         <literal>legend</literal> handles currently do not have any
  43                         <literal>children</literal>.
  44                     </para>
  45                 </listitem>
  46             </varlistentry>
  47             <varlistentry>
  48                 <term>visible:</term>
  49                 <listitem>
  50                     <para>
  51                         This field contains the <literal>visible</literal> property
  52                         value for the entity . It should be <literal>"on" </literal> or
  53                         <literal>"off"</literal> . If <literal>"on"</literal> the legend is
  54                         drawn , If <literal>"off"</literal> the legend is not displayed on
  55                         the screen.
  56                     </para>
  57                 </listitem>
  58             </varlistentry>
  59             <varlistentry>
  60                 <term>text:</term>
  61                 <listitem>
  62                     <para>This field is the character string vector which contains the
  63                         legends for each annotated objects.
  64                     </para>
  65                     <para>
  66                         Starting from Scilab 5.2, it is possible to write <link linkend="math_rendering_features_in_graphic">LaTeX or MathML expression</link>.
  67                     </para>
  68                 </listitem>
  69             </varlistentry>
  70             <varlistentry>
  71                 <term>font_size:</term>
  72                 <listitem>
  73                     <para>It is a scalar specifying the displayed characters size.
  74                         If <literal>fractional_font</literal> property is <literal>"off"</literal>
  75                         only the integer part of the value is used.
  76                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
  77                     </para>
  78                 </listitem>
  79             </varlistentry>
  80             <varlistentry>
  81                 <term>font_style:</term>
  82                 <listitem>
  83                     <para>Specifies the font used to display the legend labels.
  84                         This is a positive integer referecing one of the loaded fonts.
  85                         Its value must be between 0, referecing the first font,
  86                         and the number of loaded fonts minus one, referencing the last font.
  87                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
  88                     </para>
  89                 </listitem>
  90             </varlistentry>
  91             <varlistentry>
  92                 <term>font_color</term>
  93                 <listitem>
  94                     <para>A color index, this property determines the color of the
  95                         text.
  96                     </para>
  97                 </listitem>
  98             </varlistentry>
  99             <varlistentry>
 100                 <term>fractional_font:</term>
 101                 <listitem>
 102                     <para>This property specify whether text is displayed using
 103                         fractional font sizes. Its value must be either
 104                         <literal>"on"</literal> or <literal>"off"</literal>. If
 105                         <literal>"on"</literal> the floating point value of
 106                         <literal>font_size</literal> is used for display and the
 107                         font is anti-aliased. If <literal>"off"</literal> only the
 108                         integer part is used and the font is not smoothed.
 109                     </para>
 110                 </listitem>
 111             </varlistentry>
 112             <varlistentry>
 113                 <term>links:</term>
 114                 <listitem>
 115                     <para>A row array of handles. They refer to the associated
 116                         polylines.
 117                     </para>
 118                 </listitem>
 119             </varlistentry>
 120             <varlistentry>
 121                 <term>legend_location</term>
 122                 <listitem>
 123                     <para>A character string, specifies the location of the
 124                         Legend.
 125                     </para>
 126                     <itemizedlist>
 127                         <listitem>
 128                             <para>
 129                                 <literal>"in_upper_right" </literal>: captions are drawn
 130                                 in the upper right corner of the axes box.
 131                             </para>
 132                         </listitem>
 133                         <listitem>
 134                             <para>
 135                                 <literal>"in_upper_left"</literal>: captions are drawn in
 136                                 the upper left corner of the axes box.
 137                             </para>
 138                         </listitem>
 139                         <listitem>
 140                             <para>
 141                                 <literal>"in_lower_right"</literal>: captions are drawn in
 142                                 the lower right corner of the axes box.
 143                             </para>
 144                         </listitem>
 145                         <listitem>
 146                             <para>
 147                                 <literal>"in_lower_left"</literal>: captions are drawn in
 148                                 the lower left corner of the axes box.
 149                             </para>
 150                         </listitem>
 151                         <listitem>
 152                             <para>
 153                                 <literal>"out_upper_right"</literal>: captions are drawn
 154                                 at the right of the upper right corner of the axes box.
 155                             </para>
 156                         </listitem>
 157                         <listitem>
 158                             <para>
 159                                 <literal>"out_upper_left"</literal>: captions are drawn at
 160                                 the left of the upper left corner of the axes box.
 161                             </para>
 162                         </listitem>
 163                         <listitem>
 164                             <para>
 165                                 <literal>"out_lower_right"</literal>: captions are drawn
 166                                 at the right of the lower right corner of the axes box.
 167                             </para>
 168                         </listitem>
 169                         <listitem>
 170                             <para>
 171                                 <literal>"out_lower_left"</literal>: captions are drawn at
 172                                 the left of the lower left corner of the axes box.
 173                             </para>
 174                         </listitem>
 175                         <listitem>
 176                             <para>
 177                                 <literal>"upper_caption"</literal>: captions are drawn
 178                                 above the upper left corner of the axes box.
 179                             </para>
 180                         </listitem>
 181                         <listitem>
 182                             <para>
 183                                 <literal>"lower_caption"</literal>: captions are drawn
 184                                 below the lower left corner of the axes box. This option
 185                                 correspond to the <literal>leg</literal> argument of <link linkend="plot2d">plot2d</link>
 186                             </para>
 187                         </listitem>
 188                         <listitem>
 189                             <para>
 190                                 <literal>"by_coordinates"</literal>: the upper left
 191                                 corner of the captions box is given by the "position"
 192                                 field of the associated data structure. The
 193                                 <literal>x</literal> and <literal>y</literal>
 194                                 positions are given as fractions of the
 195                                 <literal>axes_bounds</literal>.
 196                             </para>
 197                         </listitem>
 198                     </itemizedlist>
 199                 </listitem>
 200             </varlistentry>
 201             <varlistentry>
 202                 <term>position</term>
 203                 <listitem>
 204                     <para>The coordinates of the upper left corner of the
 205                         legend. The <literal>x</literal> and <literal>y</literal>
 206                         positions are given as fractions of the
 207                         <literal>axes_bounds</literal> sizes. This field may be set
 208                         if <literal>legend_location=="by_coordinates"</literal> or
 209                         get for the other legend_location settings.
 210                     </para>
 211                     <para>
 212                         The following instructions can be used to transform these
 213                         coordinates (<literal>position</literal>) to user
 214                         coordinates ((<literal>x_user</literal>,
 215                         <literal>y_user</literal>) or conversely.
 216                     </para>
 217                     <programlisting role="user coordinates"><![CDATA[
 218 as=get(gcf(),"axes_size");//size of the canvas in pixels
 219 bnds=get(gca(),"axes_bounds");//bounds of the current axes rectangle in figure size ratio.
 220 //from legend coordinates to user coordinates
 221 [x_user,y_user]=xchange(position(1)*as(1)*bnds(3)+as(1)*bnds(1),...
 222                position(2)*as(2)*bnds(4)+as(2)*bnds(2),"i2f")
 223 //from   user coordinates to legend coordinates
 224 [x1,y1]=xchange(x_user,y_user,'f2i')
 225 position=[(x1-as(1)*bnds(1))/(as(1)*bnds(3)),...
 226           (y1-as(2)*bnds(2))/(as(2)*bnds(4))];
 227
 228  ]]></programlisting>
 229                 </listitem>
 230             </varlistentry>
 231             <varlistentry>
 232                 <term>line_mode</term>
 233                 <listitem>
 234                     <para>This field specifies if a rectangle is drawn around the legeng
 235                         or not. It should be <literal>"on"</literal> or
 236                         <literal>"off"</literal>. If <literal>"on"</literal> the rectangle
 237                         is drawn using the following properties.
 238                     </para>
 239                 </listitem>
 240             </varlistentry>
 241             <varlistentry>
 242                 <term>thickness</term>
 243                 <listitem>
 244                     <para>This property is a positive real specifying the surrounding rectangle shape width
 245                         in pixels. The displayed width is actually determined by rounding the supplied width
 246                         to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
 247                         value is considered.
 248                     </para>
 249                 </listitem>
 250             </varlistentry>
 251             <varlistentry>
 252                 <term>foreground</term>
 253                 <listitem>
 254                     <para>This field gives the color index of the line used to draw the
 255                         rectangle shape.
 256                     </para>
 257                 </listitem>
 258             </varlistentry>
 259             <varlistentry>
 260                 <term>fill_mode</term>
 261                 <listitem>
 262                     <para>This field specifies if the legeng background is painted or
 263                         not. It should be <literal>"on"</literal> or
 264                         <literal>"off"</literal>. If <literal>"on"</literal> the background
 265                         is painted using the color index set in the
 266                         <literal>background</literal> field.
 267                     </para>
 268                 </listitem>
 269             </varlistentry>
 270             <varlistentry>
 271                 <term>background</term>
 272                 <listitem>
 273                     <para>This field gives the color index of the line used to paint the
 274                         rectangle area.
 275                     </para>
 276                 </listitem>
 277             </varlistentry>
 278             <varlistentry>
 279                 <term>clip_state:</term>
 280                 <listitem>
 281                     <para>
 282                         This field contains the default <literal>clip_state</literal>
 283                         property value for all objects. Its value should be :
 284                     </para>
 285                     <itemizedlist>
 286                         <listitem>
 287                             <para>
 288                                 <literal>"off"</literal> this means that all objects
 289                                 created after that are not clipped (default value).
 290                             </para>
 291                         </listitem>
 292                         <listitem>
 293                             <para>
 294                                 <literal>"clipgrf"</literal> this means that all objects
 295                                 created after that are clipped outside the Axes
 296                                 boundaries.
 297                             </para>
 298                         </listitem>
 299                         <listitem>
 300                             <para>
 301                                 <literal>"on"</literal> this means that all objects
 302                                 created after that are clipped outside the rectangle given by
 303                                 property clip_box.
 304                             </para>
 305                         </listitem>
 306                     </itemizedlist>
 307                 </listitem>
 308             </varlistentry>
 309             <varlistentry>
 310                 <term>clip_box:</term>
 311                 <listitem>
 312                     <para>
 313                         This field contains the default <literal>clip_box</literal>
 314                         property value for all objects. Its value should be an empty matrix
 315                         if clip_state is <literal>"off"</literal>. Other case the clipping
 316                         is given by the vector <literal>[x,y,w,h]</literal> (upper-left
 317                         point width height).
 318                     </para>
 319                 </listitem>
 320             </varlistentry>
 321             <varlistentry>
 322                 <term>user_data:</term>
 323                 <listitem>
 324                     <para>This field can be use to store any scilab variable in the text
 325                         data structure, and to retreive it.
 326                     </para>
 327                 </listitem>
 328             </varlistentry>
 329         </variablelist>
 330     </refsection>
 331     <refsection>
 332         <title>Examples</title>
 333         <programlisting role="example"><![CDATA[
 334 // x initialisation
 335 x=[0:0.1:2*%pi]';
 336 plot2d(x,[sin(x) sin(2*x) sin(3*x)],..
 337   [1,2,3],leg="L1@L2@L3")
 338 a=get("current_axes");
 339 l=a.children(2);
 340 l.links
 341 l.text=["sin(x)";"sin(2*x)";"sin(3*x)"];
 342 l.visible="off"; // invisible
 343 l.font_size = 2;
 344 l.font_style = 5;
 345 l.visible='on';
 346 // Starting from Scilab 5.2, Latex:
 347 l.text=["$\sin(x)$";"$\sin(2*x)$";"$\sin(3*x)$"];
 348  ]]></programlisting>
 349     </refsection>
 350     <refsection role="see also">
 351         <title>See Also</title>
 352         <simplelist type="inline">
 353             <member>
 354                 <link linkend="plot2d">plot2d</link>
 355             </member>
 356             <member>
 357                 <link linkend="graphics_entities">graphics_entities</link>
 358             </member>
 359         </simplelist>
 360     </refsection>
 361 </refentry>