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