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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <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="polyline_properties">
  17     <refnamediv>
  18         <refname>polyline properties</refname>
  19         <refpurpose>description of the Polyline
  20             entity properties
  21         </refpurpose>
  22     </refnamediv>
  23     <refsection>
  24         <title>Description</title>
  25         <para>The Polyline entity is a leaf of the graphics entities hierarchy. This
  26             entity defines the parameters for polylines.
  27         </para>
  28         <variablelist>
  29             <varlistentry>
  30                 <term>parent: </term>
  31                 <listitem>
  32                     <para>This field contains the handle of the parent. The parent of the
  33                         polyline entity should be of the type <literal>"Axes"</literal> or
  34                         <literal>"Compound"</literal>.
  35                     </para>
  36                 </listitem>
  37             </varlistentry>
  38             <varlistentry>
  39                 <term>children: </term>
  40                 <listitem>
  41                     <para>
  42                         This property contains a vector with the <literal>children</literal> of
  43                         the handle. However, polyline handles currently do not have any
  44                         <literal>children</literal>.
  45                     </para>
  46                 </listitem>
  47             </varlistentry>
  48             <varlistentry>
  49                 <term>visible: </term>
  50                 <listitem>
  51                     <para>
  52                         This field contains the <literal>visible</literal> property value for
  53                         the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .
  54                         By default, the polyline is visible, the value's property is
  55                         <literal>"on" </literal>. If <literal>"off"</literal> the polyline is not drawn on
  56                         the screen.
  57                     </para>
  58                 </listitem>
  59             </varlistentry>
  60             <varlistentry>
  61                 <term>data: </term>
  62                 <listitem>
  63                     <para>This field contains the values for the x and y coordinates.
  64                         Component Z is to be added in the case of three-dimensional axes. It
  65                         is a two (three) column matrix <literal>[x,y,[z]]</literal> of points.
  66                     </para>
  67                 </listitem>
  68             </varlistentry>
  69             <varlistentry>
  70                 <term>closed: </term>
  71                 <listitem>
  72                     <para>This field determines whether the polyline is closed or not: its
  73                         value can be <literal>"on"</literal> or <literal>"off"</literal> (no default
  74                         value, it depends on the primitive used to create the polyline).
  75                     </para>
  76                 </listitem>
  77             </varlistentry>
  78             <varlistentry>
  79                 <term>line_mode: </term>
  80                 <listitem>
  81                     <para>
  82                         This field contains the default <literal>line_mode</literal> property
  83                         value for the polyline. Its value should be <literal>"on" </literal>(line
  84                         drawn) or <literal>"off"</literal> (no line drawn).
  85                     </para>
  86                 </listitem>
  87             </varlistentry>
  88             <varlistentry>
  89                 <term>fill_mode: </term>
  90                 <listitem>
  91                     <para>
  92                         If the <literal>polyline_style</literal> field is different of 5, fill
  93                         the background of the curve with color defined by the
  94                         <literal>background</literal> property.
  95                     </para>
  96                 </listitem>
  97             </varlistentry>
  98             <varlistentry>
  99                 <term>line_style: </term>
 100                 <listitem>
 101                     <para>
 102                         This field contains the default <literal>line_style</literal>
 103                         property value for Segs, Arcs, Rectangle and Polyline objects.
 104                         <literal>line_style</literal> selects the type of line to be used to
 105                         draw lines . Its value should be an integer in [1 10]. 1
 106                         stand for solid, the other values stand for a selection of dashes
 107                         (dash, dash dot, longdash dot, bigdash dot, bigdash longdash, dot, double dot, longblank dot, bigblank dot).
 108                         See example below.
 109                     </para>
 110                 </listitem>
 111             </varlistentry>
 112             <varlistentry>
 113                 <term>thickness: </term>
 114                 <listitem>
 115                     <para>This property is a positive real specifying the line width
 116                         in pixels. The displayed width is actually determined by rounding the supplied width
 117                         to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
 118                         value is considered.
 119                     </para>
 120                 </listitem>
 121             </varlistentry>
 122             <varlistentry>
 123                 <term>arrow_size_factor: </term>
 124                 <listitem>
 125                     <para>This integer allows to set the size of arrows drawn on the
 126                         polyline. The actual size of arrows is the product of the
 127                         <literal>thickness</literal> and the size factor.
 128                     </para>
 129                 </listitem>
 130             </varlistentry>
 131             <varlistentry>
 132                 <term>polyline_style: </term>
 133                 <listitem>
 134                     <para>This property sets several polyline drawing mode:</para>
 135                     <itemizedlist>
 136                         <listitem>
 137                             <para>If the value is 0 or 1 lines are drawn between two
 138                                 consecutives points.
 139                             </para>
 140                         </listitem>
 141                         <listitem>
 142                             <para>If the value is 2 the polyline produces a staircase plot. Two
 143                                 consecutives points are linked by a horizontal line followed by a
 144                                 vertical line.
 145                             </para>
 146                         </listitem>
 147                         <listitem>
 148                             <para>If the value is 3 the polyline produces a bar plot. For each
 149                                 given point (x,y) a vertical line is drawn from (x,y) to
 150                                 (x,0).
 151                             </para>
 152                         </listitem>
 153                         <listitem>
 154                             <para>If the value is 4 arrows are drawn between two consecutives
 155                                 points.
 156                             </para>
 157                         </listitem>
 158                         <listitem>
 159                             <para>If the value is 5 the polyline is filled (patch).</para>
 160                         </listitem>
 161                         <listitem>
 162                             <para>If the value is 6 the polyline is a Matlab-like bar object.
 163                                 The properties <literal>bar_shift</literal> and <literal>bar_width</literal>
 164                                 command its appearance.
 165                             </para>
 166                         </listitem>
 167                     </itemizedlist>
 168                     <para>
 169                         <inlinemediaobject>
 170                             <imageobject>
 171                                 <imagedata fileref="../../images/polyline_style.svg"/>
 172                             </imageobject>
 173                         </inlinemediaobject>
 174                     </para>
 175                 </listitem>
 176             </varlistentry>
 177             <varlistentry>
 178                 <term>foreground: </term>
 179                 <listitem>
 180                     <para>
 181                         This field contains the default <literal>foreground</literal> property
 182                         used to draw the polyline. Its value should be a color index (relative
 183                         to the current colormap).
 184                     </para>
 185                 </listitem>
 186             </varlistentry>
 187             <varlistentry>
 188                 <term>background: </term>
 189                 <listitem>
 190                     <para>This field contains the color used to fill the background of the
 191                         polyline. Its value should be a color index (relative to the current
 192                         colormap).
 193                     </para>
 194                 </listitem>
 195             </varlistentry>
 196             <varlistentry>
 197                 <term>interp_color_vector: </term>
 198                 <listitem>
 199                     <para>This field contains the vector of color indices used to fill in
 200                         the polyline when the <literal>interp_color_mode</literal> property is set
 201                         to <literal>"on"</literal>. It defines the intervals of colormap indices
 202                         used to fill each segment. For instance, the first segment will be
 203                         filled by every colors whose index is between the first two elements
 204                         of the vector. It is only applicable if the polyline is defined by 3 or
 205                         4 points. Therefore, the size of the vector must match this
 206                         dimension.
 207                     </para>
 208                 </listitem>
 209             </varlistentry>
 210             <varlistentry>
 211                 <term>interp_color_mode: </term>
 212                 <listitem>
 213                     <para>This field determines if we are using the interpolated shading
 214                         mode to fill the polyline : its value can be <literal>"on"</literal> or
 215                         <literal>"off"</literal>. Note that an <literal>interp_color_vector</literal> must
 216                         be defined before switching to "on" value (see above).
 217                     </para>
 218                 </listitem>
 219             </varlistentry>
 220             <varlistentry>
 221                 <term>mark_mode: </term>
 222                 <listitem>
 223                     <para>
 224                         This field contains the default <literal>mark_mode</literal> property
 225                         value for the polyline. Its value should be <literal>"on"</literal> (marks
 226                         drawn) or <literal>"off"</literal> (no marks drawn).
 227                     </para>
 228                 </listitem>
 229             </varlistentry>
 230             <varlistentry>
 231                 <term>mark_style: </term>
 232                 <listitem>
 233                     <para>
 234                         The <literal>mark_style</literal> property value is used to select the
 235                         type of mark to use when <literal>mark_mode</literal> property is
 236                         <literal>"on"</literal>. The value should be an integer in [0 14] which
 237                         stands for: dot, plus, cross, star, filled diamond, diamond, triangle
 238                         up, triangle down, diamond plus, circle, asterisk, square, triangle
 239                         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.
 240                     </para>
 241                     <para>
 242                         <inlinemediaobject>
 243                             <imageobject>
 244                                 <imagedata fileref="../../images/marks.svg"/>
 245                             </imageobject>
 246                         </inlinemediaobject>
 247                     </para>
 248                 </listitem>
 249             </varlistentry>
 250             <varlistentry>
 251                 <term>mark_size_unit: </term>
 252                 <listitem>
 253                     <para>
 254                         This field contains the default <literal>mark_size_unit</literal>
 255                         property value. If <literal>mark_size_unit</literal> is set to
 256                         <literal>"point"</literal>, then the <literal>mark_size</literal> value is
 257                         directly given in points. When <literal>mark_size_unit</literal> is set to
 258                         <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed relative
 259                         to the font size array: therefore, its value should be an integer in
 260                         [0 5] which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
 261                         <link linkend="plot2d">plot2d</link> and pure scilab functions use
 262                         <literal>tabulated</literal> mode as default ; when using <link linkend="plot">plot</link>
 263                         function, the <literal>point</literal> mode is automatically enabled.
 264                     </para>
 265                 </listitem>
 266             </varlistentry>
 267             <varlistentry>
 268                 <term>mark_size: </term>
 269                 <listitem>
 270                     <para>
 271                         The <literal>mark_size</literal> property is used to select the type of
 272                         size of the marks when <literal>mark_mode</literal> property is
 273                         <literal>"on"</literal>. Its value should be an integer between 0 and 5
 274                         with stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
 275                     </para>
 276                 </listitem>
 277             </varlistentry>
 278             <varlistentry>
 279                 <term>mark_foreground: </term>
 280                 <listitem>
 281                     <para>
 282                         This field contains the <literal>mark_foreground</literal> property
 283                         value which is the marks' edge color. Its value should be a color
 284                         index (relative to the current color_map) or 0 for transparent edge.
 285                     </para>
 286                 </listitem>
 287             </varlistentry>
 288             <varlistentry>
 289                 <term>mark_background: </term>
 290                 <listitem>
 291                     <para>
 292                         This field contains the <literal>mark_background</literal> property
 293                         value which is the marks' face color. Its value should be a color
 294                         index (relative to the current color_map) or 0 for transparent face.
 295                     </para>
 296                 </listitem>
 297             </varlistentry>
 298             <varlistentry>
 299                 <term>mark_offset: </term>
 300                 <listitem>
 301                     <para>
 302                         This field contains the <literal>mark_offset</literal> property
 303                         value which is the offset to use to draw the first mark. Its value should be an integer
 304                         greater or equal to 0 (default value is 0).
 305                     </para>
 306                 </listitem>
 307             </varlistentry>
 308             <varlistentry>
 309                 <term>mark_stride: </term>
 310                 <listitem>
 311                     <para>
 312                         This field contains the <literal>mark_stride</literal> property
 313                         value which is the stride to use to draw the marks (i.e. stride-1 points are skipped
 314                         between two consecutive marks). Its value should be integer greater or equal to 1 (default value is 1).
 315                     </para>
 316                 </listitem>
 317             </varlistentry>
 318             <varlistentry>
 319                 <term>x_shift: </term>
 320                 <listitem>
 321                     <para>This field contains the offset computed by a call to the
 322                         <link linkend="bar">bar</link> function (or re-computed by a call to
 323                         <link linkend="barhomogenize">barhomogenize</link>) and is used to perform a nice vertical bar
 324                         representation. Note that this offset is also taken into account for
 325                         all the other <literal>polyline_style</literal>. The unit is expressed in
 326                         user coordinates.
 327                     </para>
 328                 </listitem>
 329             </varlistentry>
 330             <varlistentry>
 331                 <term>y_shift: </term>
 332                 <listitem>
 333                     <para>This field contains the offset computed by a call to the
 334                         <link linkend="bar">bar</link> function (or re-computed by a call to
 335                         <link linkend="barhomogenize">barhomogenize</link>) and is used to perform a nice horizontal
 336                         bar representation. Note that this offset is also taken into account
 337                         for all the other <literal>polyline_style</literal>. The unit is expressed
 338                         in user coordinates.
 339                     </para>
 340                 </listitem>
 341             </varlistentry>
 342             <varlistentry>
 343                 <term>z_shift: </term>
 344                 <listitem>
 345                     <para>This field contains the offset the user may specify. Note that
 346                         this offset is taken into account for all the
 347                         <literal>polyline_style</literal>. The unit is expressed in user
 348                         coordinates.
 349                     </para>
 350                 </listitem>
 351             </varlistentry>
 352             <varlistentry>
 353                 <term>bar_width: </term>
 354                 <listitem>
 355                     <para>This field determines the width of the selected polyline when its
 356                         <literal>polyline_style</literal> is set to bar mode (case 6) : the unit is
 357                         expressed in user coordinates.
 358                     </para>
 359                 </listitem>
 360             </varlistentry>
 361             <varlistentry>
 362                 <term>clip_state: </term>
 363                 <listitem>
 364                     <para>
 365                         This field contains the <literal>clip_state</literal> property value for
 366                         the polyline. It should be :
 367                     </para>
 368                     <itemizedlist>
 369                         <listitem>
 370                             <para>
 371                                 <literal>"off"</literal> this means that the polyline is not
 372                                 clipped.
 373                             </para>
 374                         </listitem>
 375                         <listitem>
 376                             <para>
 377                                 <literal>"clipgrf"</literal> this means that the polyline is clipped
 378                                 outside the Axes box.
 379                             </para>
 380                         </listitem>
 381                         <listitem>
 382                             <para>
 383                                 <literal>"on"</literal> this means that the polyline is clipped
 384                                 outside the rectangle given by property clip_box.
 385                             </para>
 386                         </listitem>
 387                     </itemizedlist>
 388                 </listitem>
 389             </varlistentry>
 390             <varlistentry>
 391                 <term>clip_box: </term>
 392                 <listitem>
 393                     <para>
 394                         This field is to determinate the <literal>clip_box</literal> property.
 395                         By Default its value should be an empty matrix if clip_state is "off".
 396                         Other cases the vector <literal>[x,y,w,h]</literal> (upper-left point width
 397                         height) defines the portions of the polyline to display, however
 398                         <literal>clip_state</literal> property value will be changed.
 399                     </para>
 400                 </listitem>
 401             </varlistentry>
 402             <varlistentry>
 403                 <term>user_data: </term>
 404                 <listitem>
 405                     <para>This field can be use to store any scilab variable in the polyline
 406                         data structure, and to retrieve it.
 407                     </para>
 408                 </listitem>
 409             </varlistentry>
 410             <varlistentry>
 411                 <term>datatips: </term>
 412                 <listitem>
 413                     <para>
 414                         This property contains a vector of the <literal>datatips</literal> handles related to the polyline.
 415                         However, polyline handles currently do not have any <literal>children</literal>.
 416                     </para>
 417                 </listitem>
 418             </varlistentry>
 419             <varlistentry>
 420                 <term>display_function: </term>
 421                 <listitem>
 422                     <para>
 423                         A character string that contains a function name. This function syntax must be <literal>str=fun(datatipHandle)</literal> where <literal>datatipHandle</literal> is the handle of the datatip to be displayed. This function must return a string or a vector of strings in str.
 424                     </para>
 425                     <para>
 426                         This function can be overloaded by setting the similar property on a datatip itself.
 427                     </para>
 428                 </listitem>
 429             </varlistentry>
 430             <varlistentry>
 431                 <term>display_function_data: </term>
 432                 <listitem>
 433                     <para>
 434                         Any Scilab data needed by the <literal>display_function</literal> function.
 435                     </para>
 436                 </listitem>
 437             </varlistentry>
 438         </variablelist>
 439     </refsection>
 440     <refsection>
 441         <title>Examples</title>
 442         <programlisting role="example"><![CDATA[
 443 a=get("current_axes")//get the handle of the newly created axes
 444 a.data_bounds=[-2,-2;2,2];
 445
 446 xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
 447 p=get("hdl"); //get handle on current entity (here the polyline entity)
 448 p.foreground=2;
 449 p.thickness=3;
 450 p.mark_style=9;
 451 d=p.data;d(1,:)=[0 0];p.data=d;
 452 a.rotation_angles=[0 45];
 453  ]]></programlisting>
 454         <scilab:image>
 455             a=get("current_axes")
 456             a.data_bounds=[-2,-2;2,2];
 457             xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
 458             p=get("hdl");
 459             p.foreground=2;
 460             p.thickness=3;
 461             p.mark_style=9;
 462             d=p.data;d(1,:)=[0 0];p.data=d;
 463             a.rotation_angles=[0 45];
 464         </scilab:image>
 465         <programlisting role="example"><![CDATA[
 466 xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
 467 p=get("hdl"); //get handle on current entity (here the polyline entity)
 468 p.data=[(-2:0.1:2)' sin((-2:0.1:2)*%pi)']
 469 p.mark_mode="off";
 470 p.polyline_style=3;
 471 p.line_style=4;
 472  ]]></programlisting>
 473         <scilab:image>
 474             xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
 475             p=get("hdl");
 476             p.data=[(-2:0.1:2)' sin((-2:0.1:2)*%pi)']
 477             p.mark_mode="off";
 478             p.polyline_style=3;
 479             p.line_style=4;
 480         </scilab:image>
 481         <programlisting role="example"><![CDATA[
 482 // Example for line_style property
 483 clf();
 484 f=gcf();
 485 for i=1:10
 486     plot2d(1:10, i*ones([1:10]), 2);
 487     // Change line_style:
 488     f.children.children(1).children.line_style = i;
 489     f.children.children(1).children.thickness = 2;
 490 end
 491 f.children.axes_visible = ["off","on","off"];
 492 f.children.y_label.text = "line_style value";
 493 f.children.y_label.font_size = 3;
 494  ]]></programlisting>
 495         <scilab:image>
 496             clf();
 497             f=gcf();
 498             for i=1:10
 499             plot2d(1:10, i*ones([1:10]), 2);
 500             f.children.children(1).children.line_style = i;
 501             f.children.children(1).children.thickness = 2;
 502             end
 503             f.children.axes_visible = ["off","on","off"];
 504             f.children.y_label.text = "line_style value";
 505             f.children.y_label.font_size = 3;
 506         </scilab:image>
 507     </refsection>
 508     <refsection role="see also">
 509         <title>See also</title>
 510         <simplelist type="inline">
 511             <member>
 512                 <link linkend="set">set</link>
 513             </member>
 514             <member>
 515                 <link linkend="get">get</link>
 516             </member>
 517             <member>
 518                 <link linkend="delete">delete</link>
 519             </member>
 520             <member>
 521                 <link linkend="xpoly">xpoly</link>
 522             </member>
 523             <member>
 524                 <link linkend="xfpoly">xfpoly</link>
 525             </member>
 526             <member>
 527                 <link linkend="xpolys">xpolys</link>
 528             </member>
 529             <member>
 530                 <link linkend="xfpolys">xfpolys</link>
 531             </member>
 532             <member>
 533                 <link linkend="graphics_entities">graphics_entities</link>
 534             </member>
 535         </simplelist>
 536     </refsection>
 537     <refsection>
 538         <title>History</title>
 539         <revhistory>
 540             <revision>
 541                 <revnumber>5.4.0</revnumber>
 542                 <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>
 543             </revision>
 544         </revhistory>
 545     </refsection>
 546 </refentry>