scilab/modules/graphics/help/en_US/text/text_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) INRIA - Jean-Baptiste silvy
   6  *
   7  * This file must be used under the terms of the CeCILL.
   8  * This source file is licensed as described in the file COPYING, which
   9  * you should have received as part of this distribution.  The terms
  10  * are also available at
  11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
  12  *
  13  -->
  14 <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="text_properties">
  15     <refnamediv>
  16         <refname>text properties</refname>
  17         <refpurpose>description of the Text entity
  18             properties
  19         </refpurpose>
  20     </refnamediv>
  21     <refsection>
  22         <title>Description</title>
  23         <para>The Text entity is a leaf of the graphics entities hierarchy. This
  24             entity defines the parameters for string drawing
  25         </para>
  26         <variablelist>
  27             <varlistentry>
  28                 <term>parent: </term>
  29                 <listitem>
  30                     <para>This property contains the handle of the parent. The parent of the
  31                         text entity should be of the type <literal>"Axes"</literal> or
  32                         <literal>"Compound"</literal>.
  33                     </para>
  34                 </listitem>
  35             </varlistentry>
  36             <varlistentry>
  37                 <term>children: </term>
  38                 <listitem>
  39                     <para>
  40                         This property contains a vector with the <literal>children</literal> of
  41                         the handle. However, text handles currently do not have any
  42                         <literal>children</literal>.
  43                     </para>
  44                 </listitem>
  45             </varlistentry>
  46             <varlistentry>
  47                 <term>visible: </term>
  48                 <listitem>
  49                     <para>
  50                         This field contains the <literal>visible</literal> property value for
  51                         the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .By
  52                         default, the text is visible, the value's property is
  53                         <literal>"on"</literal>. If <literal>"off"</literal> the text is not displayed on
  54                         the screen.
  55                     </para>
  56                 </listitem>
  57             </varlistentry>
  58             <varlistentry>
  59                 <term>text: </term>
  60                 <listitem>
  61                     <para>the matrix containing the strings of the object. The rows of the
  62                         matrix are displayed horizontally and the columns vertically.
  63                     </para>
  64                     <para>
  65                         Starting from Scilab 5.2, it is possible to write <link linkend="math_rendering_features_in_graphic">LaTeX or MathML expression</link>.
  66                     </para>
  67                 </listitem>
  68             </varlistentry>
  69             <varlistentry>
  70                 <term>alignment: </term>
  71                 <listitem>
  72                     <para>Specify how the strings are aligned in their columns. The value
  73                         must be <emphasis role="bold">'left'</emphasis>,<emphasis role="bold"> 'center' </emphasis>or <emphasis role="bold">'right'</emphasis>.
  74                     </para>
  75                 </listitem>
  76             </varlistentry>
  77             <varlistentry>
  78                 <term>data: </term>
  79                 <listitem>
  80                     <para>
  81                         This field is the vector <literal>[x,y,[z]]</literal> of the origin of
  82                         the text in the data units of the axes.
  83                     </para>
  84                 </listitem>
  85             </varlistentry>
  86             <varlistentry>
  87                 <term>box: </term>
  88                 <listitem>
  89                     <para>
  90                         This field takes the values <literal>"on"</literal> or
  91                         <literal>"off"</literal>. If <literal>"on"</literal> a box is draw around the text
  92                         with a line on its edge and a background.
  93                     </para>
  94                 </listitem>
  95             </varlistentry>
  96             <varlistentry>
  97                 <term>line_mode: </term>
  98                 <listitem>
  99                     <para>This boolean property allows to draw or not a line around the box
 100                         when the <literal>box</literal> property is <literal>"on"</literal>. If
 101                         <literal>line_mode</literal> is <literal>"off"</literal>, the line of the box is
 102                         not drawn.
 103                     </para>
 104                 </listitem>
 105             </varlistentry>
 106             <varlistentry>
 107                 <term>fill_mode: </term>
 108                 <listitem>
 109                     <para>This boolean property allows to draw or not the background of the
 110                         box when the <literal>box</literal> property is <literal>"on"</literal>. If
 111                         <literal>fill_mode</literal> is <literal>"off"</literal>, the background of the
 112                         box is not transparent.
 113                     </para>
 114                 </listitem>
 115             </varlistentry>
 116             <varlistentry>
 117                 <term>text_box: </term>
 118                 <listitem>
 119                     <para>A two dimensional vector specifying the size of a rectangle in user coordinates.
 120                         The rectangle is used when the text_box_mode property is set to
 121                         <emphasis role="bold">'centered'</emphasis> or <emphasis role="bold">'filled'</emphasis>.
 122                     </para>
 123                 </listitem>
 124             </varlistentry>
 125             <varlistentry>
 126                 <term>text_box_mode: </term>
 127                 <listitem>
 128                     <para>
 129                         May have three different value : <emphasis role="bold">'off'</emphasis>,
 130                         <emphasis role="bold">'centered'</emphasis> or <emphasis role="bold">'filled'</emphasis>. If <emphasis role="bold">'off'</emphasis>, the
 131                         strings are displayed using the given font and the data field
 132                         specifies the position of the lower-left point of the text. If
 133                         <emphasis role="bold">'centered'</emphasis>, the text is displayed in the middle of the
 134                         rectangle whose size is given by text_box. If <emphasis role="bold">'filled'</emphasis> the
 135                         font size of the strings will be expanded to fill the rectangle.
 136                     </para>
 137                     <para>
 138                         When using <emphasis role="bold">'off'</emphasis> or <emphasis role="bold">'centered'</emphasis> modes,
 139                         text size remains constant upon zooming. They are the best modes to create annotations
 140                         in a graph. On the contrary, when using the <emphasis role="bold">'filled'</emphasis> mode, the text size follow
 141                         the graphic scale. It is then possible to zoom upon text objects.
 142                     </para>
 143                 </listitem>
 144             </varlistentry>
 145             <varlistentry>
 146                 <term>auto_dimensionning: </term>
 147                 <listitem>
 148                   <para>
 149                     auto_dimensionning set to "off" is equivalent to text_box_mode set to "filled". If text_box_mode is "off" or "centered" then it implies that auto_dimensionning is "on".
 150                   </para>
 151                 </listitem>
 152             </varlistentry>
 153             <varlistentry>
 154                 <term>font_foreground: </term>
 155                 <listitem>
 156                     <para>This field contains the color used to display the characters of
 157                         the text. Its value should be a color index (relative to the current
 158                         colormap).
 159                     </para>
 160                 </listitem>
 161             </varlistentry>
 162             <varlistentry>
 163                 <term>foreground: </term>
 164                 <listitem>
 165                     <para>This field contains the color used to display the line on the edge
 166                         of the box. Its value should be a color index (relative to the current
 167                         colormap).
 168                     </para>
 169                 </listitem>
 170             </varlistentry>
 171             <varlistentry>
 172                 <term>background: </term>
 173                 <listitem>
 174                     <para>This field contains the color used to fill the box around of the
 175                         text. Its value should be a color index (relative to the current
 176                         colormap).
 177                     </para>
 178                 </listitem>
 179             </varlistentry>
 180             <varlistentry>
 181                 <term>font_size: </term>
 182                 <listitem>
 183                     <para>It is a scalar specifying the displayed characters size.
 184                         If <literal>fractional_font</literal> property is <literal>"off"</literal>
 185                         only the integer part of the value is used.
 186                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
 187                     </para>
 188                 </listitem>
 189             </varlistentry>
 190             <varlistentry>
 191                 <term>font_style: </term>
 192                 <listitem>
 193                     <para>Specifies the font used to display the character strings.
 194                         This is a positive integer referecing one of the loaded fonts.
 195                         Its value must be between 0, referecing the first font,
 196                         and the number of loaded fonts minus one, referencing the last font.
 197                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
 198                     </para>
 199                 </listitem>
 200             </varlistentry>
 201             <varlistentry>
 202                 <term>fractional_font: </term>
 203                 <listitem>
 204                     <para>
 205                         This property specify whether text is displayed using fractional font sizes.
 206                         Its value must be either <literal>"on"</literal> or <literal>"off"</literal>.
 207                         If <literal>"on"</literal> the floating point value of <literal>font_size</literal>
 208                         is used for display and the font is anti-aliased. If <literal>"off"</literal> only the integer part is used
 209                         and the font is not smoothed.
 210                     </para>
 211                 </listitem>
 212             </varlistentry>
 213             <varlistentry>
 214                 <term>font_angle: </term>
 215                 <listitem>
 216                     <para>This property determines the orientation of the text string.
 217                         Specify value of rotation in degrees.
 218                     </para>
 219                 </listitem>
 220             </varlistentry>
 221             <varlistentry>
 222                 <term>clip_state: </term>
 223                 <listitem>
 224                     <para>
 225                         This field contains the <literal>clip_state</literal> property value for
 226                         the text. Its value should be :
 227                     </para>
 228                     <itemizedlist>
 229                         <listitem>
 230                             <para>
 231                                 <literal>"off"</literal> this means that the text is not
 232                                 clipped.
 233                             </para>
 234                         </listitem>
 235                         <listitem>
 236                             <para>
 237                                 <literal>"clipgrf"</literal> this means that the text is clipped
 238                                 outside the Axes box.
 239                             </para>
 240                         </listitem>
 241                         <listitem>
 242                             <para>
 243                                 <literal>"on"</literal> this means that the text is clipped outside
 244                                 the rectangle given by the property <literal>clip_box</literal>.
 245                             </para>
 246                         </listitem>
 247                     </itemizedlist>
 248                 </listitem>
 249             </varlistentry>
 250             <varlistentry>
 251                 <term>clip_box: </term>
 252                 <listitem>
 253                     <para>
 254                         This field contains the <literal>clip_box</literal> property. Its value
 255                         should be an empty matrix if clip_state is "off" or the vector
 256                         <literal>[x,y,w,h</literal>] (upper-left point width height).
 257                     </para>
 258                 </listitem>
 259             </varlistentry>
 260             <varlistentry>
 261                 <term>user_data: </term>
 262                 <listitem>
 263                     <para>This field can be use to store any scilab variable in the text
 264                         data structure, and to retreive it.
 265                     </para>
 266                 </listitem>
 267             </varlistentry>
 268         </variablelist>
 269     </refsection>
 270     <refsection>
 271         <title>Examples</title>
 272         <programlisting role="example"><![CDATA[
 273 a=get("current_axes");
 274 a.data_bounds=[0,0;1,1];
 275 a.axes_visible = 'on' ;
 276
 277 xstring(0.5,0.5,"Scilab is not esilaB",0,0)
 278
 279 t=get("hdl")   //get the handle of the newly created object
 280
 281 t.font_foreground=6; // change font properties
 282 t.font_size=5;
 283 t.font_style=5;
 284
 285
 286 t.text=["SCILAB","is";"not","esilaB"] ; // change the text
 287 t.font_angle=90 ; // turn the strings
 288 t.text_box = [0,0] ;
 289 t.text_box_mode = 'centered' ; // the text is now centered on [0.5,0.5].
 290 t.alignment = 'center' ;
 291 t.box = 'on' ; // draw a box around the text
 292
 293 // Only valid from Scilab 5.2
 294 mathml="<mrow>      <mfrac>        <mrow>          <mi>d</mi>          <mi>y</mi>        </mrow>        <mrow>          <mi>d</mi>          <mi>x</mi>        </mrow>      </mfrac>      <mo>=</mo>      <mfrac>        <mn>1</mn>        <msup>          <mi>y</mi>          <mn>2</mn>        </msup>      </mfrac>    </mrow>";
 295 t.text=["SCILAB","can write LaTeX :","$\frac{abc}{xyz}$";"or","MathML :",mathml] ;
 296
 297
 298  ]]></programlisting>
 299         <scilab:image>
 300             a=get("current_axes");
 301             a.data_bounds=[0,0;1,1];
 302             a.axes_visible = 'on' ;
 303
 304             xstring(0,0,"Scilab is not esilaB",0,0)
 305
 306             t=get("hdl")
 307
 308             t.font_foreground=6;
 309             t.font_size=5;
 310             t.font_style=5;
 311         </scilab:image>
 312     </refsection>
 313     <refsection role="see also">
 314         <title>See Also</title>
 315         <simplelist type="inline">
 316             <member>
 317                 <link linkend="set">set</link>
 318             </member>
 319             <member>
 320                 <link linkend="get">get</link>
 321             </member>
 322             <member>
 323                 <link linkend="delete">delete</link>
 324             </member>
 325             <member>
 326                 <link linkend="xtitle">xtitle</link>
 327             </member>
 328             <member>
 329                 <link linkend="graphics_entities">graphics_entities</link>
 330             </member>
 331         </simplelist>
 332     </refsection>
 333 </refentry>