scatter with extended polyline properties mark_size, mark_foreground, mark_background
[scilab.git] / scilab / modules / graphics / help / en_US / segs_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="segs_properties">
14     <refnamediv>
15         <refname>Segments properties</refname>
16         <refpurpose>
17             description of the Segments entity properties
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>
23             The <literal>Segs</literal> entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for a set of colored segments or colored arrows.
24         </para>
25         <variablelist>
26             <varlistentry>
27                 <term>parent: </term>
28                 <listitem>
29                     <para>
30                         This property contains the handle of the parent. The
31                         parent of the segment entity should be of the type
32                         <literal>"Axes"</literal> or <literal>"Compound"</literal>.
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>children: </term>
38                 <listitem>
39                     <para>
40                         This property contains a vector with the
41                         <literal>children</literal> of the handle. However,
42                         <literal>segs</literal> handles currently do not have
43                         any <literal>children</literal>.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>visible: </term>
49                 <listitem>
50                     <para>
51                         This field contains the <literal>visible</literal>
52                         property value for the entity. It should be
53                         <literal>"on" </literal> or <literal>"off"</literal>.
54                         By default, the segments are visible, the value's
55                         property is <literal>"on"</literal>. If
56                         <literal>"off"</literal> the segments are not drawn on
57                         the screen.
58                     </para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>data: </term>
63                 <listitem>
64                     <para>
65                         This field is two column matrix <literal>[x,y,
66                             [z]]
67                         </literal>
68                         which gives the coordinates of the
69                         segments boundary. If <literal>xv =
70                             matrix(x,2,-1)
71                         </literal>
72                         and <literal>yv =
73                             matrix(y,2,-1)
74                         </literal>
75                         then <literal>xv(:,k)</literal>
76                         and <literal>yv(:,k)</literal> are the boundary
77                         coordinates of the segment numbered
78                         <literal>k</literal>.
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>line_mode: </term>
84                 <listitem>
85                     <para>
86                         This field contains the default
87                         <literal>line_mode</literal> property value for the
88                         <literal>segs</literal>. Its value should be
89                         <literal>"on"</literal> (line drawn) or
90                         <literal>"off"</literal> (no line drawn).
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>line_style: </term>
96                 <listitem>
97                     <para>
98                         The <literal>line_style</literal> property value should
99                         be an integer in <literal>[1 8]</literal>.
100                         <literal>1</literal> stands for solid, the other value
101                         stands for a selection of dashes (dash, dash dot, longdash dot, bigdash dot, bigdash longdash, dot, double dot).
102                     </para>
103                 </listitem>
104             </varlistentry>
105             <varlistentry>
106                 <term>thickness: </term>
107                 <listitem>
108                     <para>
109                         This property is a positive real specifying the arrow
110                         width in pixels. The displayed width is actually
111                         determined by rounding the supplied width to the nearest
112                         integer. The only exception is vectorial export where
113                         the whole <literal>thickness</literal> value is
114                         considered.
115                     </para>
116                 </listitem>
117             </varlistentry>
118             <varlistentry>
119                 <term>arrow_size: </term>
120                 <listitem>
121                     <para>
122                         The factor that specify the size of arrowheads. With a
123                         negative value, the size is also dependent on the arrows
124                         length. To draw segment, the value must be set to 0.
125                     </para>
126                 </listitem>
127             </varlistentry>
128             <varlistentry>
129                 <term>segs_color: </term>
130                 <listitem>
131                     <para>
132                         This field contains the vector of colors to use to draw
133                         each segment. Each element is a color index relative to the current colormap.
134                     </para>
135                 </listitem>
136             </varlistentry>
137             <varlistentry>
138                 <term>mark_mode: </term>
139                 <listitem>
140                     <para>
141                         This field contains the default
142                         <literal>mark_mode</literal> property value for the
143                         polyline. Its value should be <literal>"on"</literal>
144                         (marks drawn) or <literal>"off"</literal> (no marks
145                         drawn).
146                     </para>
147                 </listitem>
148             </varlistentry>
149             <varlistentry>
150                 <term>mark_style: </term>
151                 <listitem>
152                     <para>
153                         The <literal>mark_style</literal> property value is used
154                         to select the type of mark to use when
155                         <literal>mark_mode</literal> property is
156                         <literal>"on"</literal>. The value should be an integer
157                         in <literal>[0 14]</literal> which stands for: dot,
158                         plus, cross, star, filled diamond, diamond, triangle up,
159                         triangle down, diamond plus, circle, asterisk, square,
160                         triangle right, triangle left and pentagram. The figure
161                         below shows the aspects of the marks depending on the
162                         <literal>mark_style</literal> and the
163                         <literal>mark_foreground</literal> and
164                         <literal>mark_background</literal> properties.
165                     </para>
166                     <para>
167                         <inlinemediaobject>
168                             <imageobject>
169                                 <imagedata fileref="../images/marks.svg"/>
170                             </imageobject>
171                         </inlinemediaobject>
172                     </para>
173                 </listitem>
174             </varlistentry>
175             <varlistentry>
176                 <term>mark_size_unit: </term>
177                 <listitem>
178                     <para>
179                         This field contains the default <literal>mark_size_unit</literal>
180                         property value. If <literal>mark_size_unit</literal> is
181                         set to <literal>"point"</literal>, then the
182                         <literal>mark_size</literal> value is directly given in
183                         points. When <literal>mark_size_unit</literal> is set to
184                         <literal>"tabulated"</literal>, <literal>mark_size</literal>
185                         is computed relative to the font size array: therefore,
186                         its value should be an integer in <literal>[0 5]</literal>
187                         which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
188                         <link linkend="plot2d">plot2d</link> and pure scilab functions use
189                         <literal>tabulated</literal> mode as default; when using
190                         <link linkend="plot">plot</link> function, the
191                         <literal>point</literal> mode is automatically enabled.
192                     </para>
193                 </listitem>
194             </varlistentry>
195             <varlistentry>
196                 <term>mark_size: </term>
197                 <listitem>
198                     <para>
199                         The <literal>mark_size</literal> property is used to
200                         select the type of size of the marks when
201                         <literal>mark_mode</literal> property is
202                         <literal>"on"</literal>. Its value should be an integer between 0 and 5
203                         which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
204                     </para>
205                 </listitem>
206             </varlistentry>
207             <varlistentry>
208                 <term>mark_foreground: </term>
209                 <listitem>
210                     <para>
211                         This field contains the <literal>mark_foreground</literal>
212                         property value which is the marks' edge color. Its value
213                         should be a color index (relative to the current
214                         <literal>color_map</literal>) or 0 for transparent edge.
215                     </para>
216                 </listitem>
217             </varlistentry>
218             <varlistentry>
219                 <term>mark_background: </term>
220                 <listitem>
221                     <para>
222                         This field contains the <literal>mark_background</literal>
223                         property value which is the marks' face color. Its value should be a color index (relative to the current <literal>color_map</literal>) or 0 for transparent face.
224                     </para>
225                 </listitem>
226             </varlistentry>
227             <varlistentry>
228                 <term>clip_state: </term>
229                 <listitem>
230                     <para>
231                         This field contains the <literal>clip_state</literal>
232                         property value for the segments. It should be :
233                     </para>
234                     <itemizedlist>
235                         <listitem>
236                             <para>
237                                 <literal>"off"</literal> this means that the
238                                 segments are not clipped.
239                             </para>
240                         </listitem>
241                         <listitem>
242                             <para>
243                                 <literal>"clipgrf"</literal> this means that the
244                                 segments are clipped outside the Axes box.
245                             </para>
246                         </listitem>
247                         <listitem>
248                             <para>
249                                 <literal>"on"</literal> this means that the
250                                 segments are clipped outside the rectangle given
251                                 by the property <literal>clip_box</literal>.
252                             </para>
253                         </listitem>
254                     </itemizedlist>
255                 </listitem>
256             </varlistentry>
257             <varlistentry>
258                 <term>clip_box: </term>
259                 <listitem>
260                     <para>
261                         This field contains the <literal>clip_box</literal>
262                         property. By default segments are not clipped,
263                         <literal>clip_state</literal> is <literal>"off"</literal>,
264                         so the value should be an empty matrix. Other cases the
265                         vector <literal>[x, y, w, h]</literal>
266                         (upper-left point, width, height) defines the portions
267                         of the segments to display, however
268                         <literal>clip_state</literal> property value will be
269                         changed.
270                     </para>
271                 </listitem>
272             </varlistentry>
273             <varlistentry>
274                 <term>user_data: </term>
275                 <listitem>
276                     <para>
277                         This field can be use to store any scilab variable in
278                         the <literal>segs</literal> data structure, and to retrieve it.
279                     </para>
280                 </listitem>
281             </varlistentry>
282         </variablelist>
283     </refsection>
284     <refsection>
285         <title>Examples</title>
286         <programlisting role="example"><![CDATA[ 
287 a=get("current_axes");//get the handle of the newly created axes
288 a.data_bounds=[-10,-10;10,10];
289 x=2*%pi*(0:7)/8;
290 xv=[2*sin(x);9*sin(x)];
291 yv=[2*cos(x);9*cos(x)];
292 xsegs(xv,yv,1:8)
293
294 s=a.children
295 s.arrow_size=1;
296 s.segs_color=15:22;
297 for j=1:2
298   for i=1:8
299     h=s.data(i*2,j);
300     s.data(i*2,j)=s.data(i*2-1,j);
301     s.data(i*2-1,j)=  h;
302   end
303 end
304
305 s.segs_color=5; //set all the colors to 5
306
307 s.clip_box=[-4,4,8,8];
308 a.thickness=4;
309 xrect(s.clip_box);
310  ]]></programlisting>
311     </refsection>
312     <refsection role="see also">
313         <title>See Also</title>
314         <simplelist type="inline">
315             <member>
316                 <link linkend="set">set</link>
317             </member>
318             <member>
319                 <link linkend="get">get</link>
320             </member>
321             <member>
322                 <link linkend="delete">delete</link>
323             </member>
324             <member>
325                 <link linkend="xsegs">xsegs</link>
326             </member>
327             <member>
328                 <link linkend="graphics_entities">graphics entities</link>
329             </member>
330         </simplelist>
331     </refsection>
332     <refsection>
333         <title>History</title>
334         <revhistory>
335             <revision>
336                 <revnumber>5.4.0</revnumber>
337                 <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>
338             </revision>
339         </revhistory>
340     </refsection>
341 </refentry>