scilab/modules/graphics/help/en_US/polygon/polyline_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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" version="5.0-subset Scilab" xml:lang="en" xml:id="polyline_properties">
  14     <refnamediv>
  15         <refname>polyline_properties</refname>
  16         <refpurpose>description of the Polyline
  17             entity properties
  18         </refpurpose>
  19     </refnamediv>
  20     <refsection>
  21         <title>Description</title>
  22         <para>The Polyline entity is a leaf of the graphics entities hierarchy. This
  23             entity defines the parameters for polylines.
  24         </para>
  25         <variablelist>
  26             <varlistentry>
  27                 <term>parent: </term>
  28                 <listitem>
  29                     <para>This field contains the handle of the parent. The parent of the
  30                         polyline entity should be of the type <literal>"Axes"</literal> or
  31                         <literal>"Compound"</literal>.
  32                     </para>
  33                 </listitem>
  34             </varlistentry>
  35             <varlistentry>
  36                 <term>children: </term>
  37                 <listitem>
  38                     <para>
  39                         This property contains a vector with the <literal>children</literal> of
  40                         the handle. However, polyline handles currently do not have any
  41                         <literal>children</literal>.
  42                     </para>
  43                 </listitem>
  44             </varlistentry>
  45             <varlistentry>
  46                 <term>visible: </term>
  47                 <listitem>
  48                     <para>
  49                         This field contains the <literal>visible</literal> property value for
  50                         the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .
  51                         By default, the polyline is visible, the value's property is
  52                         <literal>"on" </literal>. If <literal>"off"</literal> the polyline is not drawn on
  53                         the screen.
  54                     </para>
  55                 </listitem>
  56             </varlistentry>
  57             <varlistentry>
  58                 <term>data: </term>
  59                 <listitem>
  60                     <para>This field contains the values for the x and y coordinates.
  61                         Component Z is to be added in the case of three-dimensional axes. It
  62                         is a two (three) column matrix <literal>[x,y,[z]]</literal> of points.
  63                     </para>
  64                 </listitem>
  65             </varlistentry>
  66             <varlistentry>
  67                 <term>closed: </term>
  68                 <listitem>
  69                     <para>This field determines wether the polyline is closed or not: its
  70                         value can be <literal>"on"</literal> or <literal>"off"</literal> (no default
  71                         value, it depends on the primitive used to create the polyline).
  72                     </para>
  73                 </listitem>
  74             </varlistentry>
  75             <varlistentry>
  76                 <term>line_mode: </term>
  77                 <listitem>
  78                     <para>
  79                         This field contains the default <literal>line_mode</literal> property
  80                         value for the polyline. Its value should be <literal>"on" </literal>(line
  81                         drawn) or <literal>"off"</literal> (no line drawn).
  82                     </para>
  83                 </listitem>
  84             </varlistentry>
  85             <varlistentry>
  86                 <term>fill_mode: </term>
  87                 <listitem>
  88                     <para>
  89                         If the <literal>polyline_style</literal> field is different of 5, fill
  90                         the background of the curve with color defined by the
  91                         <literal>background</literal> property.
  92                     </para>
  93                 </listitem>
  94             </varlistentry>
  95             <varlistentry>
  96                 <term>line_style: </term>
  97                 <listitem>
  98                     <para>
  99                         The <literal>line_style</literal> property value should be an integer in
 100                         [1 8]. 1 stands for solid, the other value stands for a selection of
 101                         dashes (see <link linkend="axes_properties">getlinestyle</link>).
 102                     </para>
 103                 </listitem>
 104             </varlistentry>
 105             <varlistentry>
 106                 <term>thickness: </term>
 107                 <listitem>
 108                     <para>This property is a positive real specifying the line width
 109                         in pixels. The displayed width is actually determined by rounding the supplied width
 110                         to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
 111                         value is considered.
 112                     </para>
 113                 </listitem>
 114             </varlistentry>
 115             <varlistentry>
 116                 <term>arrow_size_factor: </term>
 117                 <listitem>
 118                     <para>This integer allows to set the size of arrows drawn on the
 119                         polyline. The actual size of arrows is the product of the
 120                         <literal>thickness</literal> and the size factor.
 121                     </para>
 122                 </listitem>
 123             </varlistentry>
 124             <varlistentry>
 125                 <term>polyline_style: </term>
 126                 <listitem>
 127                     <para>This property sets several polyline drawing mode:</para>
 128                     <itemizedlist>
 129                         <listitem>
 130                             <para>If the value is 0 or 1 lines are drawn between two
 131                                 consecutives points.
 132                             </para>
 133                         </listitem>
 134                         <listitem>
 135                             <para>If the value is 2 the polyline produces a staircase plot. Two
 136                                 consecutives points are linked by a horizontal line followed by a
 137                                 vertical line.
 138                             </para>
 139                         </listitem>
 140                         <listitem>
 141                             <para>If the value is 3 the polyline produces a bar plot. For each
 142                                 given point (x,y) a vertical line is drawn from (x,y) to
 143                                 (x,0).
 144                             </para>
 145                         </listitem>
 146                         <listitem>
 147                             <para>If the value is 4 arrows are drawn between two consecutives
 148                                 points.
 149                             </para>
 150                         </listitem>
 151                         <listitem>
 152                             <para>If the value is 5 the polyline is filled (patch).</para>
 153                         </listitem>
 154                         <listitem>
 155                             <para>If the value is 6 the polyline is a Matlab-like bar object.
 156                                 The properties <literal>bar_shift</literal> and <literal>bar_width</literal>
 157                                 command its appearance.
 158                             </para>
 159                         </listitem>
 160                     </itemizedlist>
 161                     <para>
 162                         <inlinemediaobject>
 163                             <imageobject>
 164                                 <imagedata fileref="../../images/polyline_style.svg"/>
 165                             </imageobject>
 166                         </inlinemediaobject>
 167                     </para>
 168                 </listitem>
 169             </varlistentry>
 170             <varlistentry>
 171                 <term>foreground: </term>
 172                 <listitem>
 173                     <para>
 174                         This field contains the default <literal>foreground</literal> property
 175                         used to draw the polyline. Its value should be a color index (relative
 176                         to the current colormap).
 177                     </para>
 178                 </listitem>
 179             </varlistentry>
 180             <varlistentry>
 181                 <term>background: </term>
 182                 <listitem>
 183                     <para>This field contains the color used to fill the background of the
 184                         polyline. Its value should be a color index (relative to the current
 185                         colormap).
 186                     </para>
 187                 </listitem>
 188             </varlistentry>
 189             <varlistentry>
 190                 <term>interp_color_vector: </term>
 191                 <listitem>
 192                     <para>This field contains the vector of color indices used to fill in
 193                         the polyline when the <literal>interp_color_mode</literal> property is set
 194                         to <literal>"on"</literal>. It defines the intervals of colormap indices
 195                         used to fill each segment. For instance, the first segment will be
 196                         filled by every colors whose index is between the first two elements
 197                         of the vector. It is only applicable if the polyline is defined by 3 or
 198                         4 points. Therefore, the size of the vector must match this
 199                         dimension.
 200                     </para>
 201                 </listitem>
 202             </varlistentry>
 203             <varlistentry>
 204                 <term>interp_color_mode: </term>
 205                 <listitem>
 206                     <para>This field determines if we are using the interpolated shading
 207                         mode to fill the polyline : its value can be <literal>"on"</literal> or
 208                         <literal>"off"</literal>. Note that an <literal>interp_color_vector</literal> must
 209                         be defined before switching to "on" value (see above).
 210                     </para>
 211                 </listitem>
 212             </varlistentry>
 213             <varlistentry>
 214                 <term>mark_mode: </term>
 215                 <listitem>
 216                     <para>
 217                         This field contains the default <literal>mark_mode</literal> property
 218                         value for the polyline. Its value should be <literal>"on"</literal> (marks
 219                         drawn) or <literal>"off"</literal> (no marks drawn).
 220                     </para>
 221                 </listitem>
 222             </varlistentry>
 223             <varlistentry>
 224                 <term>mark_style: </term>
 225                 <listitem>
 226                     <para>
 227                         The <literal>mark_style</literal> property value is used to select the
 228                         type of mark to use when <literal>mark_mode</literal> property is
 229                         <literal>"on"</literal>. The value should be an integer in [0 14] which
 230                         stands for: dot, plus, cross, star, filled diamond, diamond, triangle
 231                         up, triangle down, diamond plus, circle, asterisk, square, triangle
 232                         right, triangle left and pentagram. The figure below shows the aspects of the marks depending on the <literal>mark_style</literal> and the <literal>mark_foreground</literal> and <literal>mark_background</literal> properties.
 233                     </para>
 234                     <para>
 235                         <inlinemediaobject>
 236                             <imageobject>
 237                                 <imagedata fileref="../../images/marks.svg"/>
 238                             </imageobject>
 239                         </inlinemediaobject>
 240                     </para>
 241                 </listitem>
 242             </varlistentry>
 243             <varlistentry>
 244                 <term>mark_size_unit: </term>
 245                 <listitem>
 246                     <para>
 247                         This field contains the default <literal>mark_size_unit</literal>
 248                         property value. If <literal>mark_size_unit</literal> is set to
 249                         <literal>"point"</literal>, then the <literal>mark_size</literal> value is
 250                         directly given in points. When <literal>mark_size_unit</literal> is set to
 251                         <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed relative
 252                         to the font size array: therefore, its value should be an integer in
 253                         [0 5] which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
 254                         <link linkend="plot2d">plot2d</link> and pure scilab functions use
 255                         <literal>tabulated</literal> mode as default ; when using <link linkend="plot">plot</link>
 256                         function, the <literal>point</literal> mode is automatically enabled.
 257                     </para>
 258                 </listitem>
 259             </varlistentry>
 260             <varlistentry>
 261                 <term>mark_size: </term>
 262                 <listitem>
 263                     <para>
 264                         The <literal>mark_size</literal> property is used to select the type of
 265                         size of the marks when <literal>mark_mode</literal> property is
 266                         <literal>"on"</literal>. Its value should be an integer between 0 and 5
 267                         whith stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
 268                     </para>
 269                 </listitem>
 270             </varlistentry>
 271             <varlistentry>
 272                 <term>mark_foreground: </term>
 273                 <listitem>
 274                     <para>
 275                         This field contains the <literal>mark_foreground</literal> property
 276                         value which is the marks' edge color. Its value should be a color
 277                         index (relative to the current color_map) or 0 for transparant edge.
 278                     </para>
 279                 </listitem>
 280             </varlistentry>
 281             <varlistentry>
 282                 <term>mark_background: </term>
 283                 <listitem>
 284                     <para>
 285                         This field contains the <literal>mark_background</literal> property
 286                         value which is the marks' face color. Its value should be a color
 287                         index (relative to the current color_map) or 0 for transparant face.
 288                     </para>
 289                 </listitem>
 290             </varlistentry>
 291             <varlistentry>
 292                 <term>x_shift: </term>
 293                 <listitem>
 294                     <para>This field contains the offset computed by a call to the
 295                         <link linkend="bar">bar</link> function (or re-computed by a call to
 296                         <link linkend="barhomogenize">barhomogenize</link>) and is used to perform a nice vertical bar
 297                         representation. Note that this offset is also taken into account for
 298                         all the other <literal>polyline_style</literal>. The unit is expressed in
 299                         user coordinates.
 300                     </para>
 301                 </listitem>
 302             </varlistentry>
 303             <varlistentry>
 304                 <term>y_shift: </term>
 305                 <listitem>
 306                     <para>This field contains the offset computed by a call to the
 307                         <link linkend="bar">bar</link> function (or re-computed by a call to
 308                         <link linkend="barhomogenize">barhomogenize</link>) and is used to perform a nice horizontal
 309                         bar representation. Note that this offset is also taken into account
 310                         for all the other <literal>polyline_style</literal>. The unit is expressed
 311                         in user coordinates.
 312                     </para>
 313                 </listitem>
 314             </varlistentry>
 315             <varlistentry>
 316                 <term>z_shift: </term>
 317                 <listitem>
 318                     <para>This field contains the offset the user may specify. Note that
 319                         this offset is taken into account for all the
 320                         <literal>polyline_style</literal>. The unit is expressed in user
 321                         coordinates.
 322                     </para>
 323                 </listitem>
 324             </varlistentry>
 325             <varlistentry>
 326                 <term>bar_width: </term>
 327                 <listitem>
 328                     <para>This field determines the width of the selected polyline when its
 329                         <literal>polyline_style</literal> is set to bar mode (case 6) : the unit is
 330                         expressed in user coordinates.
 331                     </para>
 332                 </listitem>
 333             </varlistentry>
 334             <varlistentry>
 335                 <term>clip_state: </term>
 336                 <listitem>
 337                     <para>
 338                         This field contains the <literal>clip_state</literal> property value for
 339                         the polyline. It should be :
 340                     </para>
 341                     <itemizedlist>
 342                         <listitem>
 343                             <para>
 344                                 <literal>"off"</literal> this means that the polyline is not
 345                                 clipped.
 346                             </para>
 347                         </listitem>
 348                         <listitem>
 349                             <para>
 350                                 <literal>"clipgrf"</literal> this means that the polyline is clipped
 351                                 outside the Axes box.
 352                             </para>
 353                         </listitem>
 354                         <listitem>
 355                             <para>
 356                                 <literal>"on"</literal> this means that the polyline is clipped
 357                                 outside the rectangle given by property clip_box.
 358                             </para>
 359                         </listitem>
 360                     </itemizedlist>
 361                 </listitem>
 362             </varlistentry>
 363             <varlistentry>
 364                 <term>clip_box: </term>
 365                 <listitem>
 366                     <para>
 367                         This field is to determinate the <literal>clip_box</literal> property.
 368                         By Default its value should be an empty matrix if clip_state is "off".
 369                         Other cases the vector <literal>[x,y,w,h]</literal> (upper-left point width
 370                         height) defines the portions of the polyline to display, however
 371                         <literal>clip_state</literal> property value will be changed.
 372                     </para>
 373                 </listitem>
 374             </varlistentry>
 375             <varlistentry>
 376                 <term>user_data: </term>
 377                 <listitem>
 378                     <para>This field can be use to store any scilab variable in the polyline
 379                         data structure, and to retrieve it.
 380                     </para>
 381                 </listitem>
 382             </varlistentry>
 383         </variablelist>
 384     </refsection>
 385     <refsection>
 386         <title>Sample</title>
 387         <scilab:image>
 388             a=get("current_axes")
 389             a.data_bounds=[-2,-2;2,2];
 390
 391             xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
 392             p=get("hdl");
 393             p.foreground=2;
 394             p.thickness=3;
 395             p.mark_style=9;
 396             d=p.data;d(1,:)=[0 0];p.data=d;
 397             a.rotation_angles=[0 45];
 398         </scilab:image>
 399     </refsection>
 400     <refsection>
 401         <title>Examples</title>
 402         <programlisting role="example"><![CDATA[
 403 a=get("current_axes")//get the handle of the newly created axes
 404 a.data_bounds=[-2,-2;2,2];
 405
 406 xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
 407 p=get("hdl"); //get handle on current entity (here the polyline entity)
 408 p.foreground=2;
 409 p.thickness=3;
 410 p.mark_style=9;
 411 d=p.data;d(1,:)=[0 0];p.data=d;
 412 a.rotation_angles=[0 45];
 413
 414 p.data=[(-2:0.1:2)' sin((-2:0.1:2)*%pi)']
 415 p.mark_mode="off";
 416 p.polyline_style=3;
 417 p.line_style=4;
 418  ]]></programlisting>
 419     </refsection>
 420     <refsection role="see also">
 421         <title>See Also</title>
 422         <simplelist type="inline">
 423             <member>
 424                 <link linkend="set">set</link>
 425             </member>
 426             <member>
 427                 <link linkend="get">get</link>
 428             </member>
 429             <member>
 430                 <link linkend="delete">delete</link>
 431             </member>
 432             <member>
 433                 <link linkend="xpoly">xpoly</link>
 434             </member>
 435             <member>
 436                 <link linkend="xfpoly">xfpoly</link>
 437             </member>
 438             <member>
 439                 <link linkend="xpolys">xpolys</link>
 440             </member>
 441             <member>
 442                 <link linkend="xfpolys">xfpolys</link>
 443             </member>
 444             <member>
 445                 <link linkend="graphics_entities">graphics_entities</link>
 446             </member>
 447         </simplelist>
 448     </refsection>
 449     <refsection>
 450         <title>History</title>
 451         <revhistory>
 452             <revision>
 453                 <revnumber>5.4.0</revnumber>
 454                 <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>
 455             </revision>
 456         </revhistory>
 457     </refsection>
 458 </refentry>