1 <?xml version="1.0" encoding="UTF-8"?>
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) INRIA - Djalel Abdemouche
6 * Copyright (C) 2012 - 2016 - Scilab Enterprises
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.
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">
18 <refname>polyline properties</refname>
19 <refpurpose>description of the Polyline
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.
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>.
39 <term>children: </term>
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>.
49 <term>visible: </term>
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
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.
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).
79 <term>line_mode: </term>
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).
89 <term>fill_mode: </term>
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.
99 <term>line_style: </term>
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).
113 <term>thickness: </term>
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>
123 <term>arrow_size_factor: </term>
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.
132 <term>polyline_style: </term>
134 <para>This property sets several polyline drawing mode:</para>
137 <para>If the value is 0 or 1 lines are drawn between two
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
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
154 <para>If the value is 4 arrows are drawn between two consecutives
159 <para>If the value is 5 the polyline is filled (patch).</para>
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.
171 <imagedata fileref="../../images/polyline_style.svg"/>
178 <term>foreground: </term>
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).
188 <term>background: </term>
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
197 <term>interp_color_vector: </term>
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
211 <term>interp_color_mode: </term>
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).
221 <term>mark_mode: </term>
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).
231 <term>mark_style: </term>
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.
244 <imagedata fileref="../../images/marks.svg"/>
251 <term>mark_size_unit: </term>
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.
268 <term>mark_size: </term>
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.
279 <term>mark_foreground: </term>
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.
289 <term>mark_background: </term>
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.
299 <term>mark_offset: </term>
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).
309 <term>mark_stride: </term>
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).
319 <term>x_shift: </term>
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
331 <term>y_shift: </term>
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
343 <term>z_shift: </term>
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
353 <term>bar_width: </term>
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.
362 <term>clip_state: </term>
365 This field contains the <literal>clip_state</literal> property value for
366 the polyline. It should be :
371 <literal>"off"</literal> this means that the polyline is not
377 <literal>"clipgrf"</literal> this means that the polyline is clipped
378 outside the Axes box.
383 <literal>"on"</literal> this means that the polyline is clipped
384 outside the rectangle given by property clip_box.
391 <term>clip_box: </term>
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.
403 <term>user_data: </term>
405 <para>This field can be use to store any scilab variable in the polyline
406 data structure, and to retrieve it.
411 <term>datatips: </term>
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>.
420 <term>display_function: </term>
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.
426 This function can be overloaded by setting the similar property on a datatip itself.
431 <term>display_function_data: </term>
434 Any Scilab data needed by the <literal>display_function</literal> function.
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];
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)
451 d=p.data;d(1,:)=[0 0];p.data=d;
452 a.rotation_angles=[0 45];
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)
462 d=p.data;d(1,:)=[0 0];p.data=d;
463 a.rotation_angles=[0 45];
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)']
474 xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
476 p.data=[(-2:0.1:2)' sin((-2:0.1:2)*%pi)']
481 <programlisting role="example"><![CDATA[
482 // Example for line_style property
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;
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;
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;
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;
508 <refsection role="see also">
509 <title>See also</title>
510 <simplelist type="inline">
512 <link linkend="set">set</link>
515 <link linkend="get">get</link>
518 <link linkend="delete">delete</link>
521 <link linkend="xpoly">xpoly</link>
524 <link linkend="xfpoly">xfpoly</link>
527 <link linkend="xpolys">xpolys</link>
530 <link linkend="xfpolys">xfpolys</link>
533 <link linkend="graphics_entities">graphics_entities</link>
538 <title>History</title>
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>