summaryrefslogtreecommitdiffstats
path: root/scilab/modules/graphics/help/en_US/figure_operations/figure_properties.xml
blob: 225cc004393a1576ec392d6aefd6e72c15238835 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Djalel Abdemouche
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="figure_properties">
    <refnamediv>
        <refname>figure properties</refname>
        <refpurpose>description of the graphics
            figure entity properties
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The figure entity is the top level of the graphics entities hierarchy.
            This entity contain a number of properties designed to control many
            aspects of displaying Scilab graphics objects. These properties fall into
            two categories. Properties that contain information about figure itself
            and others related to set default values for the children creation.
        </para>
        <variablelist>
            <varlistentry>
                <term>Figure properties: </term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>children: </term>
                            <listitem>
                                <para>This handles represent the vector of the figure's children .
                                    Note that all figure children are of type <literal>"Axes"</literal>.
                                    Also keep in mind that, when creating a figure entity (using
                                    <link linkend="scf">scf</link> command), an <literal>Axes</literal> entity is
                                    simultaneously built too.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_style: </term>
                            <listitem>
                                <para>The value of this field defines the figure style.
                                    Since Scilab 5.0, old graphic mode has been disable.
                                    This property will be removed in Scilab 5.4 family.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_position: </term>
                            <listitem>
                                <para>This field contains the position in pixel of the graphic
                                    window on the screen. This is a vector <literal>[x,y]</literal>
                                    defining the position of the upper-left corner of the window.
                                    The position <literal>[0,0]</literal> is the upper-left corner of the
                                    screen.
                                </para>
                                <para>The initial position of graphic windows is taken from the default figure entity (see
                                    <link linkend="gdf">gdf</link>). The only exception is when default figure <literal>figure_position</literal>
                                    value is <literal>[-1,-1]</literal>. In this case, the initial position of graphic windows is automatically set
                                    by the windowing system.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_size: </term>
                            <listitem>
                                <para>This property controls the size in pixel of the screen's
                                    graphics window. The size is the vector
                                    <literal>[width,height]</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>axes_size: </term>
                            <listitem>
                                <para>Used to Specifies the size in pixel of the virtual graphics
                                    window. The size is the vector <literal>[width,height] </literal>. The
                                    virtual graphic window should be bigger than the part really
                                    visible on the screen. This property could not be modified if the figure is docked
                                    with other elements.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>auto_resize: </term>
                            <listitem>
                                <para>This property determines if graphics window is resized. If the
                                    value is <literal>"on"</literal> then the <literal>axes_size</literal>
                                    property is equaled to the <literal>figure_size</literal> and the axes
                                    children are zoomed accordingly. If the value is
                                    <literal>"off"</literal> that indicate that <literal>axes_size</literal>
                                    cannot be resized when <literal>figure_size</literal> is changed.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>viewport: </term>
                            <listitem>
                                <para>Position of the visible part of graphics in the
                                    panner.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_name: </term>
                            <listitem>
                                <para>This field contains the name of the figure. This name is a
                                    character string displayed at the top of the graphics_window. The
                                    name can contain a single substring <literal>%d</literal> which will be
                                    replaced by the <literal>figure_id</literal>. No other instance of the
                                    <literal>%</literal> character is allowed inside the name.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_id: </term>
                            <listitem>
                                <para>This field contains the identifier of the figure. This is an
                                    integer number which is set at figure creation and cannot be
                                    changed after.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info_message: </term>
                            <listitem>
                                <para>This character string set the text displayed in the info bar of the
                                    graphic window.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>color_map: </term>
                            <listitem>
                                <para>Property which defines the colormap used by this figure. The
                                    colormap is a <literal>m</literal> by <literal>3</literal> matrix.
                                    <literal>m</literal> is the number of colors. Color number i is given as
                                    a 3-uple <literal>R</literal>, <literal>G</literal>, <literal>B</literal>
                                    corresponding respectively to red, green and blue intensity
                                    between 0 and 1.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>pixel_drawing_mode: </term>
                            <listitem>
                                <para>This field specifies the bitwise operation used for pixel rendering.
                                    The default mode is <literal>copy</literal>.
                                    For more details see the <link linkend="pixel_drawing_mode">pixel drawing mode reference page</link>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>anti_aliasing: </term>
                            <listitem>
                                <para>This property controls the anti-aliasing level used to improve graphic quality.
                                    If the property is set to "off", anti-aliasing is disable. To enable anti-aliasing
                                    the property must set to either "2x", "4x", "8x" or "16x". In this case, it stands for the anti-aliasing level.
                                    For example, "16x" is a higher quality level than "2x".
                                    Specifying a higher anti-aliasing level improves image quality but also decreases graphic performances.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>immediate_drawing: </term>
                            <listitem>
                                <para>This property controls the figure display. Its value can be
                                    <literal>"on"</literal> (default mode) or <literal>"off"</literal>. It is used
                                    to delay a huge succession of graphics commands (implying several
                                    drawings or redrawings). Note that, when using
                                    <literal>drawlater</literal> or <literal>drawnow</literal> commands, it
                                    affects the property value of the current figure (which is
                                    respectively turned to <literal>'off'</literal> or
                                    <literal>'on'</literal>).
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>background: </term>
                            <listitem>
                                <para>This property controls the figure window background color. It
                                    takes as value an index relative to the current colormap.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>event_handler</term>
                            <listitem>
                                <para>A character string. The name of the Scilab function which is intended
                                    to handle the events. Note that setting an empty string will disable
                                    the event handler. For more information about event handler functions see the
                                    <link linkend="eventhandlerfunctions">event handler functions</link> help.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>event_handler_enable</term>
                            <listitem>
                                <para>Enable or disable the event handler. Its value must be either
                                    "on" or "off".
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>user_data: </term>
                            <listitem>
                                <para>This field can be use to store any scilab variable in the
                                    figure data structure, and to retrieve it.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tag: </term>
                            <listitem>
                                <para>This field can be use to store a character string generally used to identify the control. It allows to give it a "name". Mainly used in conjunction with findobj().</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>resizefcn: </term>
                            <listitem>
                                <para>This field can be used to store the name of a Scilab function or a Scilab expression as a character string. This character string will be evaluated whenever the user resizes the figure and when the figure is created. </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>closerequestfcn: </term>
                            <listitem>
                                <para>This field can be used to store the name of a Scilab function or a Scilab expression as a character string. This character string will be evaluated whenever the user tries to close the figure using the top-right cross.</para>
                                <para>When this property is set, the "figure closed" event (-1000) will no more be trapped by the event handler function.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>resize: </term>
                            <listitem>
                                <para>
                                    This property locks the figure size. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal> (the figure can not be resized by mouse events).
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>menubar_visible: </term>
                            <listitem>
                                <para>
                                    This property controls the figure menubar visibility. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>toolbar_visible: </term>
                            <listitem>
                                <para>
                                    This property controls the figure toolbar visibility. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>infobar_visible: </term>
                            <listitem>
                                <para>
                                    This property controls the figure status bar visibility. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>visible: </term>
                            <listitem>
                                <para>
                                    When the figure <literal>"dockable"</literal> property is <literal>"off"</literal>, setting the <literal>"Visible"</literal> property affects the whole figure including its window decorations.
                                </para>
                                <para>
                                    When the figure <literal>"dockable"</literal> property is <literal>"on"</literal> and the figure is docked with an other one inside the same parent window, this field concerns only the figure children (See dedicated part below). If the figure is not docked with an other one, then the <literal>"Visible"</literal> property behaves as if the figure <literal>"dockable"</literal> property was set to <literal>"off"</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>layout: </term>
                            <listitem>
                                <para>
                                    This property sets the layout used to dispose the figure children. See <link linkend="layout">layout</link> page for more information about available layouts.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>layout_options: </term>
                            <listitem>
                                <para>
                                    This property sets the options of the layout used to dispose the figure children. See <link linkend="layout">layout</link> page for more information about available options.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>icon: </term>
                            <listitem>
                                <para>This field can be used to customize the icon of a Scilab figure.</para>
                                <para>
                                    Its value is a character string containing the (absolute or relative to Scilab <link linkend="pwd">current working directory.</link> path of the image file containing the icon.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>default_axes: </term>
                            <listitem>
                                <para>
                                    This property enables to manage axes creation in figures. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
                                </para>
                                <para>
                                    If its value is <literal>"on"</literal>, an axes will be created at figure creation and each time the latest axes of the figure is deleted, a new one will be created. If its value is <literal>"off"</literal>, no axes will be initialized at figure creation but an axes can be added in the figure using <link linkend="newaxes">newaxes</link> function.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
        <variablelist>
            <varlistentry>
                <term>Children's default values: </term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>visible: </term>
                            <para>{"on"} | "off"</para>
                            <listitem>
                                <para>This field sets if the contents of the figure (axes and uicontrols) has to be
                                    redrawn. Its value should be <literal>"on"</literal> or <literal>"off"</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>rotation_style: </term>
                            <para>{"unary"} | "multiple"</para>
                            <listitem>
                                <para>This field is related to the "3D Rot" button. It takes
                                    <literal>unary</literal> as value (default) in the aim to rotate only
                                    selected 3D plot. In the other case its value can be
                                    <literal>multiple</literal> : all 3D plots are rotated.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
        <variablelist>
            <varlistentry>
                <term>Creation related properties: </term>
                <para>
                    Some properties must be set at creation time using the <link linkend="figure">figure</link> function and will be then read-only.
                </para>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>dockable</term>
                            <listitem>
                                <para>
                                    This property determines if created window can be docked inside Scilab environment. If its value is <literal>"on"</literal> then the window will have a bar enabling the user to dock/undock it. Else the window will look like a standard OS window. This value can only be set at creation.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>menubar</term>
                            <listitem>
                                <para>{"figure"} | "none"</para>
                                <para>
                                    This property determines the type of the menubar of the figure. If its value is <literal>"none"</literal> then the window will not have any menubar until a menu is added using <link linkend="uimenu">uimenu function</link>. Else the window will be created with default figure menus. This value can only be set at creation.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>toolbar</term>
                            <listitem>
                                <para>{"figure"} | "none"</para>
                                <para>
                                    This property determines the type of the toolbar of the figure. If its value is <literal>"none"</literal> then the window will not have any menubar. Else the window will be created with a default figure toolbar. This value can only be set at creation.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Note on default values: </term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term/>
                            <listitem>
                                <para>All these listed properties and fields inherit from default
                                    values stored in a figure model. These default values can be seen
                                    and changed. To do so, use the <literal>get("default_figure")</literal>
                                    command : it returns a graphic handle on the figure model. Note
                                    that no graphic window is created by this command. The next
                                    created figures will inherit from this model (see example 2
                                    below).
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example">
            <![CDATA[
lines(0) // disables vertical paging

//Example 1
f=get("current_figure") //get the handle of the current figure :
                        //if none exists, create a figure and return the corresponding handle
f.figure_position
f.figure_size=[200,200]
f.background=2
f.children  // man can see that an Axes entity already exists
delete(f);
f=gcf(); // macro shortcut <=> f=get("current_figure")
f.immediate_drawing = "off";
plot2d() // nothing happens on the screen...
f.immediate_drawing = "on";

//Example 2 : default_figure settings
df=get("default_figure") // get the default values (shortcut is gdf() )
// Let's change the defaults...
df.color_map=hotcolormap(128)
df.background= 110 // set background toa kind of yellow (Note that we
                   // are using a color index inside the color_map previously redefined)
scf(122); // creates new figure number 122 with the new default
plot2d()
scf(214);
t=-%pi:0.3:%pi;
plot3d(t,t,sin(t)'*cos(t),35,45,'X@Y@Z',[15,2,4]);
 ]]>
        </programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="lines">lines</link>
            </member>
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="scf">scf</link>
            </member>
            <member>
                <link linkend="gcf">gcf</link>
            </member>
            <member>
                <link linkend="gdf">gdf</link>
            </member>
            <member>
                <link linkend="gca">gca</link>
            </member>
            <member>
                <link linkend="gda">gda</link>
            </member>
            <member>
                <link linkend="axes_properties">axes_properties</link>
            </member>
            <member>
                <link linkend="hotcolormap">hotcolormap</link>
            </member>
            <member>
                <link linkend="eventhandlerfunctions">event handler functions</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>"visible" property meaning changed (uicontrols managed and the whole figure can be made invisible in some cases.</listitem>
                        <listitem>"icon" property added to allow figure icon change.</listitem>
                        <listitem>"menubar_visible" property added.</listitem>
                        <listitem>"toolbar_visible" property added.</listitem>
                        <listitem>"infobar_visible" property added.</listitem>
                        <listitem>"resize" property added.</listitem>
                        <listitem>"dockable" property added.</listitem>
                        <listitem>"menubar" property added.</listitem>
                        <listitem>"toolbar" property added.</listitem>
                        <listitem>"default_axes" property added.</listitem>
                        <listitem>"layout" property added.</listitem>
                        <listitem>"layout_options" property added.</listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>New resizefcn &amp; closerequestfcn properties introduced.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>