* Bugs 7724 13766 fixed [doc]: figure_properties/figure fixed/improved
[scilab.git] / scilab / modules / graphics / help / en_US / figure_operations / figure_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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
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"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="figure_properties">
20     <refnamediv>
21         <refname>figure properties</refname>
22         <refpurpose>description of the graphics
23             figure entity properties
24         </refpurpose>
25     </refnamediv>
26     <refsection>
27         <title>Description</title>
28         <para>The figure entity is the top level of the graphics entities hierarchy.
29             This entity contain a number of properties designed to control many
30             aspects of displaying Scilab graphics objects. These properties fall into
31             two categories. Properties that contain information about figure itself
32             and others related to set default values for the children creation.
33         </para>
34         <variablelist>
35             <varlistentry>
36                 <term>Figure properties: </term>
37                 <listitem>
38                     <variablelist>
39                         <varlistentry>
40                             <term>children: </term>
41                             <listitem>
42                                 <para>This handles represent the vector of the figure's children .
43                                     Note that all figure children are of type <literal>"Axes"</literal>.
44                                     Also keep in mind that, when creating a figure entity (using
45                                     <link linkend="scf">scf</link> command), an <literal>Axes</literal> entity is
46                                     simultaneously built too.
47                                 </para>
48                             </listitem>
49                         </varlistentry>
50                         <varlistentry>
51                             <term>figure_position: </term>
52                             <listitem>
53                                 <para>This field contains the position in pixel of the graphic
54                                     window on the screen. This is a vector <literal>[x,y]</literal>
55                                     defining the position of the upper-left corner of the window.
56                                     The position <literal>[0,0]</literal> is the upper-left corner of the
57                                     screen.
58                                 </para>
59                                 <para>The initial position of graphic windows is taken from the default figure entity (see
60                                     <link linkend="gdf">gdf</link>). The only exception is when default figure <literal>figure_position</literal>
61                                     value is <literal>[-1,-1]</literal>. In this case, the initial position of graphic windows is automatically set
62                                     by the windowing system.
63                                 </para>
64                             </listitem>
65                         </varlistentry>
66                         <varlistentry>
67                             <term>figure_size: </term>
68                             <listitem>
69                                 <para>
70                                     Vector <literal>[width, height]</literal>, providing the
71                                     external size of the graphic window, in screen pixels.
72                                 </para>
73                                 <para>
74                                 <warning>
75                                     When the figure is docked (to the Scilab desktop, etc),
76                                     .figure_size holds for the whole docked block and should not
77                                     be set.
78                                 </warning>
79                                 <warning>
80                                     The OS window manager defines some minimal sizes. If sizes
81                                     smaller than minimal ones are provided, the minimal ones are
82                                     actually set.
83                                     <para>
84                                         On Windows, minimal sizes can be retrieved with
85                                         <screen><![CDATA[
86 --> [getsystemmetrics("SM_CXMIN") getsystemmetrics("SM_CYMIN")]
87  ans  =
88    158.   45.
89 ]]></screen>
90                                     </para>
91                                 </warning>
92                                 <warning>
93                                     When a figure is created in .auto_resize="on" mode,
94                                     the .axes_size value is set as specified, and .figure_size
95                                     is set accordingly, not the reverse.
96                                 </warning>
97                                 </para>
98                             </listitem>
99                         </varlistentry>
100                         <varlistentry>
101                             <term>axes_size: </term>
102                             <listitem>
103                                 <para>
104                                     Vector <literal>[width, height]</literal> of sizes of the whole
105                                     graphical area in the window, in pixels.
106                                 </para>
107                                 <warning>
108                                     This property should not be modified if the figure is docked
109                                     to the Scilab desktop.
110                                 </warning>
111                             </listitem>
112                         </varlistentry>
113                         <varlistentry>
114                             <term>position: </term>
115                             <listitem>
116                                 <para>
117                                     <literal>.position = [x, y, graphics_width, graphics_height]</literal>
118                                     or <literal>.position = 'x|y|graphics_width|graphics_height'</literal>
119                                     (like '100|150|500|300')
120                                     is a pseudo-property allowing to set or querry both
121                                     <literal>.figure_position</literal> and <literal>.axes_size</literal>
122                                     properties in a once.
123                                 </para>
124                             </listitem>
125                         </varlistentry>
126                         <varlistentry>
127                             <term>auto_resize: </term>
128                             <listitem>
129                                 <para>
130                                     Auto-resizing of children axes when the figure is resized.
131                                 </para>
132                                 <para>
133                                     When the figure is resized by hand or by setting the
134                                     .figure_size property, and .auto_resize is
135                                     <table>
136                                         <tr>
137                                             <th>"on"</th>
138                                             <td>Then the .axes_size is updated and axes contents
139                                                 are zoomed accordingly, without displaying scroll
140                                                 bars.
141                                             </td>
142                                         </tr>
143                                         <tr>
144                                             <th>"off"</th>
145                                             <td>Then the .axes_size is kept unchanged. The display
146                                                 scale of children axes is unchanged. If the window
147                                                 gets smaller than axes sizes, some scroll bars are
148                                                 displayed.
149                                             </td>
150                                         </tr>
151                                     </table>
152                                 </para>
153                             </listitem>
154                         </varlistentry>
155                         <varlistentry>
156                             <term>viewport: </term>
157                             <listitem>
158                                 <para>
159                                     Position of the visible part of graphics in the panner.
160                                 </para>
161                             </listitem>
162                         </varlistentry>
163                         <varlistentry>
164                             <term>figure_name or name:</term>
165                             <listitem>
166                                 <para>This field contains the name of the figure. This name is a
167                                     character string displayed at the top of the graphics_window. The
168                                     name can contain a single substring <literal>%d</literal> which will be
169                                     replaced by the <literal>figure_id</literal>. No other instance of the
170                                     <literal>%</literal> character is allowed inside the name.
171                                 </para>
172                             </listitem>
173                         </varlistentry>
174                         <varlistentry>
175                             <term>figure_id: </term>
176                             <listitem>
177                                 <para>This field contains the identifier of the figure. This is an
178                                     integer number which is set at figure creation and cannot be
179                                     changed after.
180                                 </para>
181                             </listitem>
182                         </varlistentry>
183                         <varlistentry>
184                             <term>color_map: </term>
185                             <listitem>
186                                 <para>Property which defines the colormap used by this figure. The
187                                     colormap is a <literal>m</literal> by <literal>3</literal> matrix.
188                                     <literal>m</literal> is the number of colors. Color number i is given as
189                                     a 3-uple <literal>R</literal>, <literal>G</literal>, <literal>B</literal>
190                                     corresponding respectively to red, green and blue intensity
191                                     between 0 and 1.
192                                 </para>
193                             </listitem>
194                         </varlistentry>
195                         <varlistentry>
196                             <term>pixel_drawing_mode: </term>
197                             <listitem>
198                                 <para>This field specifies the bitwise operation used for pixel rendering.
199                                     The default mode is <literal>copy</literal>.
200                                     For more details see the <link linkend="pixel_drawing_mode">pixel drawing mode reference page</link>.
201                                 </para>
202                             </listitem>
203                         </varlistentry>
204                         <varlistentry>
205                             <term>anti_aliasing: </term>
206                             <listitem>
207                                 <para>
208                                   This property controls the anti-aliasing level used to improve
209                                   graphic quality.
210                                   If the property is set to "off", anti-aliasing is disable.
211                                   To enable anti-aliasing, the property must set to either
212                                   "2x", "4x", "8x" or "16x". In this case, it stands for the
213                                   anti-aliasing level.
214                                   For example, "16x" is a higher quality level than "2x".
215                                   Specifying a higher anti-aliasing level improves image quality
216                                   but also decreases graphic performances.
217                                   Please visit the <link linkend="anti_aliasing">dedicated page</link>
218                                   to see specific examples.
219                                 </para>
220                             </listitem>
221                         </varlistentry>
222                         <varlistentry>
223                             <term>immediate_drawing: </term>
224                             <listitem>
225                                 <para>This property controls the figure display. Its value can be
226                                     <literal>"on"</literal> (default mode) or <literal>"off"</literal>. It is used
227                                     to delay a huge succession of graphics commands (implying several
228                                     drawings or redrawings). Note that, when using
229                                     <literal>drawlater</literal> or <literal>drawnow</literal> commands, it
230                                     affects the property value of the current figure (which is
231                                     respectively turned to <literal>'off'</literal> or
232                                     <literal>'on'</literal>).
233                                 </para>
234                             </listitem>
235                         </varlistentry>
236                         <varlistentry>
237                             <term>background: </term>
238                             <listitem>
239                                 <para>This property controls the figure window background color. It
240                                     takes as value an index relative to the current colormap.
241                                 </para>
242                             </listitem>
243                         </varlistentry>
244                        <varlistentry>
245                             <term>BackgroundColor</term>
246                             <listitem>
247                                 <para>
248                                     This pseudo-property is a set-only one. It is the same as
249                                     <literal>background</literal>, but allows to specify the color
250                                     as a [r g b] vector of real values of Red Green and Blue
251                                     intensities in [0,1] like <literal>[0.1, 0.5, 0.3]</literal>,
252                                     or as a unique equivalent 'r|g|b' string like
253                                     <literal>'0.1|0.5|0.3'</literal>, using "|" as a separator.
254                                 </para>
255                             </listitem>
256                         </varlistentry>
257                         <varlistentry>
258                             <term>event_handler</term>
259                             <listitem>
260                                 <para>A character string. The name of the Scilab function which is intended
261                                     to handle the events. Note that setting an empty string will disable
262                                     the event handler. For more information about event handler functions see the
263                                     <link linkend="eventhandlerfunctions">event handler functions</link> help.
264                                 </para>
265                             </listitem>
266                         </varlistentry>
267                         <varlistentry>
268                             <term>event_handler_enable</term>
269                             <listitem>
270                                 <para>Enable or disable the event handler. Its value must be either
271                                     "on" or "off".
272                                 </para>
273                             </listitem>
274                         </varlistentry>
275                         <varlistentry>
276                             <term>user_data: </term>
277                             <listitem>
278                                 <para>This field can be use to store any scilab variable in the
279                                     figure data structure, and to retrieve it.
280                                 </para>
281                             </listitem>
282                         </varlistentry>
283                         <varlistentry>
284                             <term>tag: </term>
285                             <listitem>
286                                 <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>
287                             </listitem>
288                         </varlistentry>
289                         <varlistentry>
290                             <term>resizefcn: </term>
291                             <listitem>
292                                 <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>
293                             </listitem>
294                         </varlistentry>
295                         <varlistentry>
296                             <term>closerequestfcn: </term>
297                             <listitem>
298                                 <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>
299                                 <para>When this property is set, the "figure closed" event (-1000) will no more be trapped by the event handler function.</para>
300                             </listitem>
301                         </varlistentry>
302                         <varlistentry>
303                             <term>resize: </term>
304                             <listitem>
305                                 <para>
306                                     <literal>"on"</literal> (default value) allows the user to interactively resize the figure with the mouse.
307                                     <literal>"off"</literal> forbids to do it, but still allows using efficiently the <literal>.figure_size</literal> property.
308                                 </para>
309                             </listitem>
310                         </varlistentry>
311                         <varlistentry>
312                             <term>menubar_visible: </term>
313                             <listitem>
314                                 <para>
315                                     This property controls the figure menubar visibility. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
316                                 </para>
317                             </listitem>
318                         </varlistentry>
319                         <varlistentry>
320                             <term>toolbar_visible: </term>
321                             <listitem>
322                                 <para>
323                                     This property controls the figure toolbar visibility. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
324                                 </para>
325                             </listitem>
326                         </varlistentry>
327                         <varlistentry>
328                             <term>infobar_visible: </term>
329                             <listitem>
330                                 <para>
331                                     This property controls the figure status bar visibility. Its value can be <literal>"on"</literal> (default value) or <literal>"off"</literal>.
332                                 </para>
333                             </listitem>
334                         </varlistentry>
335                         <varlistentry>
336                             <term>info_message: </term>
337                             <listitem>
338                                 <para>
339                                     Single character string: text displayed in the info bar
340                                     of the graphic window.
341                                 </para>
342                                 <note>
343                                     A multi-line message is possible, using ascii(10) as lines
344                                     separator, as with "Line #1"+ascii(10)+"Line #2".
345                                     Styling the text is not possible (HTML styles not supported).
346                                 </note>
347                             </listitem>
348                         </varlistentry>
349                         <varlistentry>
350                             <term>visible: </term>
351                             <listitem>
352                                 <para>
353                                     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.
354                                 </para>
355                                 <para>
356                                     When the figure <literal>"dockable"</literal> property is <literal>"on"</literal> and the figure is docked with another one inside the same parent window, this field concerns only the figure children (See dedicated part below). If the figure is not docked with another one, then the <literal>"Visible"</literal> property behaves as if the figure <literal>"dockable"</literal> property was set to <literal>"off"</literal>.
357                                 </para>
358                             </listitem>
359                         </varlistentry>
360                         <varlistentry>
361                             <term>layout: </term>
362                             <listitem>
363                                 <para>
364                                     This property sets the layout used to dispose the figure children. See <link linkend="layout">layout</link> page for more information about available layouts.
365                                 </para>
366                             </listitem>
367                         </varlistentry>
368                         <varlistentry>
369                             <term>layout_options: </term>
370                             <listitem>
371                                 <para>
372                                     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.
373                                 </para>
374                             </listitem>
375                         </varlistentry>
376                         <varlistentry>
377                             <term>icon: </term>
378                             <listitem>
379                                 <para>This field can be used to customize the icon of a Scilab figure.</para>
380                                 <para>
381                                     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.
382                                 </para>
383                             </listitem>
384                         </varlistentry>
385                         <varlistentry>
386                             <term>default_axes: </term>
387                             <listitem>
388                                 <para>
389                                     <literal>"on"</literal> (default value) means that the figure has always
390                                     a default axes: it is automatically set at the figure creation,
391                                     or automatically reset when the last axes of the figure is
392                                     intentionally deleted.
393                                 </para>
394                                 <para>
395                                     <literal>"off"</literal> means that
396                                     <itemizedlist>
397                                         <listitem>
398                                             the newly created figure has no default axes.
399                                         </listitem>
400                                         <listitem>
401                                             for an existing figure, it is possible to actually delete
402                                             all its existing axes.
403                                         </listitem>
404                                     </itemizedlist>
405                                     In both cases,
406                                     <itemizedlist>
407                                         <listitem>
408                                             without any axes, the figure can't be the default
409                                             target of any plotting instruction. This feature
410                                             can be used to protect an interactive interface built in
411                                             a figure (like the demos and the ATOMS ones) from being the default
412                                             plotting target when there is no other proper opened
413                                             graphical figures.
414                                         </listitem>
415                                         <listitem>
416                                             It is still possible to force creating an axes using the
417                                             <link linkend="newaxes">newaxes</link> function.
418                                         </listitem>
419                                     </itemizedlist>
420                                 </para>
421                             </listitem>
422                         </varlistentry>
423                     </variablelist>
424                 </listitem>
425             </varlistentry>
426         </variablelist>
427         <variablelist>
428             <varlistentry>
429                 <term>Children's default values: </term>
430                 <listitem>
431                     <variablelist>
432                         <varlistentry>
433                             <term>visible: </term>
434                             <para>{"on"} | "off"</para>
435                             <listitem>
436                                 <para>This field sets if the contents of the figure (axes and uicontrols) has to be
437                                     redrawn. Its value should be <literal>"on"</literal> or <literal>"off"</literal>.
438                                 </para>
439                             </listitem>
440                         </varlistentry>
441                         <varlistentry>
442                             <term>rotation_style: </term>
443                             <para>{"unary"} | "multiple"</para>
444                             <listitem>
445                                 <para>This field is related to the "3D Rot" button. It takes
446                                     <literal>unary</literal> as value (default) in the aim to rotate only
447                                     selected 3D plot. In the other case its value can be
448                                     <literal>multiple</literal> : all 3D plots are rotated.
449                                 </para>
450                             </listitem>
451                         </varlistentry>
452                     </variablelist>
453                 </listitem>
454             </varlistentry>
455         </variablelist>
456         <variablelist>
457             <varlistentry>
458                 <term>Creation related properties: </term>
459                 <para>
460                     Some properties must be set at creation time using the <link linkend="figure">figure</link> function and will be then read-only.
461                 </para>
462                 <listitem>
463                     <variablelist>
464                         <varlistentry>
465                             <term>dockable</term>
466                             <listitem>
467                                 <para>
468                                     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.
469                                 </para>
470                             </listitem>
471                         </varlistentry>
472                         <varlistentry>
473                             <term>menubar</term>
474                             <listitem>
475                                 <para>{"figure"} | "none"</para>
476                                 <para>
477                                     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.
478                                 </para>
479                             </listitem>
480                         </varlistentry>
481                         <varlistentry>
482                             <term>toolbar</term>
483                             <listitem>
484                                 <para>{"figure"} | "none"</para>
485                                 <para>
486                                     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.
487                                 </para>
488                             </listitem>
489                         </varlistentry>
490                     </variablelist>
491                 </listitem>
492             </varlistentry>
493             <varlistentry>
494                 <term>Note on default values: </term>
495                 <listitem>
496                     <variablelist>
497                         <varlistentry>
498                             <term/>
499                             <listitem>
500                                 <para>All these listed properties and fields inherit from default
501                                     values stored in a figure model. These default values can be seen
502                                     and changed. To do so, use the <literal>get("default_figure")</literal>
503                                     command : it returns a graphic handle on the figure model. Note
504                                     that no graphic window is created by this command. The next
505                                     created figures will inherit from this model (see example 2
506                                     below).
507                                 </para>
508                             </listitem>
509                         </varlistentry>
510                     </variablelist>
511                 </listitem>
512             </varlistentry>
513         </variablelist>
514     </refsection>
515     <refsection>
516         <title>Examples</title>
517         <programlisting role="example">
518             <![CDATA[
519 lines(0) // disables vertical paging
520
521 //Example 1
522 f=get("current_figure") //get the handle of the current figure :
523                         //if none exists, create a figure and return the corresponding handle
524 f.figure_position
525 f.figure_size=[200,200]
526 f.background=2
527 f.children  // man can see that an Axes entity already exists
528 delete(f);
529 f=gcf(); // macro shortcut <=> f=get("current_figure")
530 f.immediate_drawing = "off";
531 plot2d() // nothing happens on the screen...
532 f.immediate_drawing = "on";
533
534 //Example 2 : default_figure settings
535 df=get("default_figure") // get the default values (shortcut is gdf() )
536 // Let's change the defaults...
537 df.color_map=hotcolormap(128)
538 df.background= 110 // set background toa kind of yellow (Note that we
539                    // are using a color index inside the color_map previously redefined)
540 scf(122); // creates new figure number 122 with the new default
541 plot2d()
542 scf(214);
543 t=-%pi:0.3:%pi;
544 plot3d(t,t,sin(t)'*cos(t),35,45,'X@Y@Z',[15,2,4]);
545  ]]>
546         </programlisting>
547     </refsection>
548     <refsection role="see also">
549         <title>See also</title>
550         <simplelist type="inline">
551             <member>
552                 <link linkend="eventhandlerfunctions">event handler functions</link>
553             </member>
554             <member>
555                 <link linkend="pixel_drawing_mode">pixel_drawing_mode</link>
556             </member>
557             <member>
558                 <link linkend="anti_aliasing">anti_aliasing</link>
559             </member>
560             <member>
561                 <link linkend="colormap">colormap</link>
562             </member>
563             <member>
564                 <link linkend="scf">scf</link>
565             </member>
566             <member>
567                 <link linkend="gcf">gcf</link>
568             </member>
569             <member>
570                 <link linkend="gdf">gdf</link>
571             </member>
572             <member>
573                 <link linkend="get">get</link>
574             </member>
575             <member>
576                 <link linkend="set">set</link>
577             </member>
578             <member>
579                 <link linkend="axes_properties">axes_properties</link>
580             </member>
581             <member>
582                 <link linkend="getsystemmetrics">getsystemmetrics</link>
583             </member>
584         </simplelist>
585     </refsection>
586     <refsection>
587         <title>History</title>
588         <revhistory>
589             <revision>
590                 <revnumber>5.4.0</revnumber>
591                 <revremark>New resizefcn &amp; closerequestfcn properties introduced.</revremark>
592             </revision>
593             <revision>
594                 <revnumber>5.5.0</revnumber>
595                 <revremark>
596                     <itemizedlist>
597                         <listitem>"visible" property meaning changed (uicontrols managed and the whole figure can be made invisible in some cases.</listitem>
598                         <listitem>"icon" property added to allow figure icon change.</listitem>
599                         <listitem>"menubar_visible" property added.</listitem>
600                         <listitem>"toolbar_visible" property added.</listitem>
601                         <listitem>"infobar_visible" property added.</listitem>
602                         <listitem>"resize" property added.</listitem>
603                         <listitem>"dockable" property added.</listitem>
604                         <listitem>"menubar" property added.</listitem>
605                         <listitem>"toolbar" property added.</listitem>
606                         <listitem>"default_axes" property added.</listitem>
607                         <listitem>"layout" property added.</listitem>
608                         <listitem>"layout_options" property added.</listitem>
609                     </itemizedlist>
610                 </revremark>
611             </revision>
612         </revhistory>
613     </refsection>
614 </refentry>