Update help and CHANGES after https://codereview.scilab.org/#/c/13053/
[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  *
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="figure_properties">
14     <refnamediv>
15         <refname>figure properties</refname>
16         <refpurpose>description of the graphics
17             figure entity properties
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>The figure entity is the top level of the graphics entities hierarchy.
23             This entity contain a number of properties designed to control many
24             aspects of displaying Scilab graphics objects. These properties fall into
25             two categories. Properties that contain information about figure itself
26             and others related to set default values for the children creation.
27         </para>
28         <variablelist>
29             <varlistentry>
30                 <term>Figure properties: </term>
31                 <listitem>
32                     <variablelist>
33                         <varlistentry>
34                             <term>children: </term>
35                             <listitem>
36                                 <para>This handles represent the vector of the figure's children .
37                                     Note that all figure children are of type <literal>"Axes"</literal>.
38                                     Also keep in mind that, when creating a figure entity (using
39                                     <link linkend="scf">scf</link> command), an <literal>Axes</literal> entity is
40                                     simultaneously built too.
41                                 </para>
42                             </listitem>
43                         </varlistentry>
44                         <varlistentry>
45                             <term>figure_style: </term>
46                             <listitem>
47                                 <para>The value of this field defines the figure style.
48                                     Since Scilab 5.0, old graphic mode has been disable.
49                                     This property will be removed in Scilab 5.4 family.
50                                 </para>
51                             </listitem>
52                         </varlistentry>
53                         <varlistentry>
54                             <term>figure_position: </term>
55                             <listitem>
56                                 <para>This field contains the position in pixel of the graphic
57                                     window on the screen. This is a vector <literal>[x,y]</literal>
58                                     defining the position of the upper-left corner of the window.
59                                     The position <literal>[0,0]</literal> is the upper-left corner of the
60                                     screen.
61                                 </para>
62                                 <para>The initial position of graphic windows is taken from the default figure entity (see
63                                     <link linkend="gdf">gdf</link>). The only exception is when default figure <literal>figure_position</literal>
64                                     value is <literal>[-1,-1]</literal>. In this case, the initial position of graphic windows is automatically set
65                                     by the windowing system.
66                                 </para>
67                             </listitem>
68                         </varlistentry>
69                         <varlistentry>
70                             <term>figure_size: </term>
71                             <listitem>
72                                 <para>This property controls the size in pixel of the screen's
73                                     graphics window. The size is the vector
74                                     <literal>[width,height]</literal>.
75                                 </para>
76                             </listitem>
77                         </varlistentry>
78                         <varlistentry>
79                             <term>axes_size: </term>
80                             <listitem>
81                                 <para>Used to Specifies the size in pixel of the virtual graphics
82                                     window. The size is the vector <literal>[width,height] </literal>. The
83                                     virtual graphic window should be bigger than the part really
84                                     visible on the screen. This property could not be modified if the figure is docked
85                                     with other elements.
86                                 </para>
87                             </listitem>
88                         </varlistentry>
89                         <varlistentry>
90                             <term>auto_resize: </term>
91                             <listitem>
92                                 <para>This property determines if graphics window is resized. If the
93                                     value is <literal>"on"</literal> then the <literal>axes_size</literal>
94                                     property is equaled to the <literal>figure_size</literal> and the axes
95                                     children are zoomed accordingly. If the value is
96                                     <literal>"off"</literal> that indicate that <literal>axes_size</literal>
97                                     cannot be resized when <literal>figure_size</literal> is changed.
98                                 </para>
99                             </listitem>
100                         </varlistentry>
101                         <varlistentry>
102                             <term>viewport: </term>
103                             <listitem>
104                                 <para>Postion of the visible part of graphics in the
105                                     panner.
106                                 </para>
107                             </listitem>
108                         </varlistentry>
109                         <varlistentry>
110                             <term>figure_name: </term>
111                             <listitem>
112                                 <para>This field contains the name of the figure. This name is a
113                                     character string displayed at the top of the graphics_window. The
114                                     name can contain a single substring <literal>%d</literal> which will be
115                                     replaced by the <literal>figure_id</literal>. No other instance of the
116                                     <literal>%</literal> character is allowed inside the name.
117                                 </para>
118                             </listitem>
119                         </varlistentry>
120                         <varlistentry>
121                             <term>figure_id: </term>
122                             <listitem>
123                                 <para>This field contains the identifier of the figure. This is an
124                                     integer number which is set at figure creation and cannot be
125                                     changed after.
126                                 </para>
127                             </listitem>
128                         </varlistentry>
129                         <varlistentry>
130                             <term>info_message: </term>
131                             <listitem>
132                                 <para>This character string set the text displayed in the info bar of the
133                                     graphic window.
134                                 </para>
135                             </listitem>
136                         </varlistentry>
137                         <varlistentry>
138                             <term>color_map: </term>
139                             <listitem>
140                                 <para>Property which defines the colormap used by this figure. The
141                                     colormap is a <literal>m</literal> by <literal>3</literal> matrix.
142                                     <literal>m</literal> is the number of colors. Color number i is given as
143                                     a 3-uple <literal>R</literal>, <literal>G</literal>, <literal>B</literal>
144                                     corresponding respectively to red, green and blue intensity
145                                     between 0 and 1.
146                                 </para>
147                             </listitem>
148                         </varlistentry>
149                         <varlistentry>
150                             <term>pixmap: </term>
151                             <listitem>
152                                 <para>This property controls the pixmap status of a Graphic Window.
153                                     This property is obsolete.
154                                 </para>
155                             </listitem>
156                         </varlistentry>
157                         <varlistentry>
158                             <term>pixel_drawing_mode: </term>
159                             <listitem>
160                                 <para>This field specifies the bitwise operation used for pixel rendering.
161                                     The default mode is <literal>copy</literal>.
162                                     For more details see the <link linkend="pixel_drawing_mode">pixel drawing mode reference page</link>.
163                                 </para>
164                             </listitem>
165                         </varlistentry>
166                         <varlistentry>
167                             <term>anti_aliasing: </term>
168                             <listitem>
169                                 <para>This property controls the anti-aliasing level used to improve graphic quality.
170                                     If the property is set to "off", anti-aliasing is disable. To enable anti-aliasing
171                                     the property must set to either "2x", "4x", "8x" or "16x". In this case, it stands for the anti-aliasing level.
172                                     For example, "16x" is a higher quality level than "2x".
173                                     Specifying a higher anti-aliasing level improves image quality but also decreases graphic performances.
174                                 </para>
175                             </listitem>
176                         </varlistentry>
177                         <varlistentry>
178                             <term>immediate_drawing: </term>
179                             <listitem>
180                                 <para>This property controls the figure display. Its value can be
181                                     <literal>"on"</literal> (default mode) or <literal>"off"</literal>. It is used
182                                     to delay a huge succession of graphics commands (implying several
183                                     drawings or redrawings). Note that, when using
184                                     <literal>drawlater</literal> or <literal>drawnow</literal> commands, it
185                                     affects the property value of the current figure (which is
186                                     respectively turned to <literal>'off'</literal> or
187                                     <literal>'on'</literal>).
188                                 </para>
189                             </listitem>
190                         </varlistentry>
191                         <varlistentry>
192                             <term>background: </term>
193                             <listitem>
194                                 <para>This property controls the figure window background color. It
195                                     takes as value an index relative to the current colormap.
196                                 </para>
197                             </listitem>
198                         </varlistentry>
199                         <varlistentry>
200                             <term>event_handler</term>
201                             <listitem>
202                                 <para>A character string. The name of the Scilab function which is intended
203                                     to handle the events. Note that setting an empty string will disable
204                                     the event handler. For more information about event handler functions see the
205                                     <link linkend="eventhandlerfunctions">event handler functions</link> help.
206                                 </para>
207                             </listitem>
208                         </varlistentry>
209                         <varlistentry>
210                             <term>event_handler_enable</term>
211                             <listitem>
212                                 <para>Enable or disable the event handler. Its value must be either
213                                     "on" or "off".
214                                 </para>
215                             </listitem>
216                         </varlistentry>
217                         <varlistentry>
218                             <term>user_data: </term>
219                             <listitem>
220                                 <para>This field can be use to store any scilab variable in the
221                                     figure data structure, and to retreive it.
222                                 </para>
223                             </listitem>
224                         </varlistentry>
225                         <varlistentry>
226                             <term>tag: </term>
227                             <listitem>
228                                 <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 conjontion with findobj().</para>
229                             </listitem>
230                         </varlistentry>
231                         <varlistentry>
232                             <term>resizefcn: </term>
233                             <listitem>
234                                 <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>
235                             </listitem>
236                         </varlistentry>
237                         <varlistentry>
238                             <term>closerequestfcn: </term>
239                             <listitem>
240                                 <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>
241                                 <para>When this property is set, the "figure closed" event (-1000) will no more be trapped by the event handler function.</para>
242                             </listitem>
243                         </varlistentry>
244                     </variablelist>
245                 </listitem>
246             </varlistentry>
247         </variablelist>
248         <variablelist>
249             <varlistentry>
250                 <term>Children's default values: </term>
251                 <listitem>
252                     <variablelist>
253                         <varlistentry>
254                             <term>visible: </term>
255                             <listitem>
256                                 <para>This field sets if the contents of the figure (axes and uicontrols) has to be
257                                     redrawn. Its value should be <literal>"on"</literal> or
258                                     <literal>"off"</literal>.
259                                 </para>
260                             </listitem>
261                         </varlistentry>
262                         <varlistentry>
263                             <term>rotation_style: </term>
264                             <listitem>
265                                 <para>This field is related to the "3D Rot" button. It takes
266                                     <literal>unary</literal> as value (default) in the aim to rotate only
267                                     selected 3D plot. In the other case its value can be
268                                     <literal>multiple</literal> : all 3D plots are rotated.
269                                 </para>
270                             </listitem>
271                         </varlistentry>
272                     </variablelist>
273                 </listitem>
274             </varlistentry>
275             <varlistentry>
276                 <term>Note on default values :</term>
277                 <listitem>
278                     <variablelist>
279                         <varlistentry>
280                             <term/>
281                             <listitem>
282                                 <para>All these listed properties and fields inherit from default
283                                     values stored in a figure model. These default values can be seen
284                                     and changed. To do so, use the <literal>get("default_figure")</literal>
285                                     command : it returns a graphic handle on the figure model. Note
286                                     that no graphic window is created by this command. The next
287                                     created figures will inherit from this model (see example 2
288                                     below).
289                                 </para>
290                             </listitem>
291                         </varlistentry>
292                     </variablelist>
293                 </listitem>
294             </varlistentry>
295         </variablelist>
296     </refsection>
297     <refsection>
298         <title>Examples</title>
299         <programlisting role="example">
300             <![CDATA[
301 lines(0) // disables vertical paging
302
303 //Example 1
304 f=get("current_figure") //get the handle of the current figure :
305                         //if none exists, create a figure and return the corresponding handle
306 f.figure_position
307 f.figure_size=[200,200]
308 f.background=2
309 f.children  // man can see that an Axes entity already exists
310 delete(f);
311 f=gcf(); // macro shortcut <=> f=get("current_figure")
312 f.immediate_drawing = "off";
313 plot2d() // nothing happens on the screen...
314 f.immediate_drawing = "on";
315
316 //Example 2 : default_figure settings
317 df=get("default_figure") // get the default values (shortcut is gdf() )
318 // Let's change the defaults...
319 df.color_map=hotcolormap(128)
320 df.background= 110 // set background toa kind of yellow (Note that we
321                    // are using a color index inside the color_map previously redefined)
322 scf(122); // creates new figure number 122 with the new default
323 plot2d()
324 scf(214);
325 t=-%pi:0.3:%pi;
326 plot3d(t,t,sin(t)'*cos(t),35,45,'X@Y@Z',[15,2,4]);
327  ]]>
328         </programlisting>
329     </refsection>
330     <refsection role="see also">
331         <title>See Also</title>
332         <simplelist type="inline">
333             <member>
334                 <link linkend="lines">lines</link>
335             </member>
336             <member>
337                 <link linkend="set">set</link>
338             </member>
339             <member>
340                 <link linkend="get">get</link>
341             </member>
342             <member>
343                 <link linkend="scf">scf</link>
344             </member>
345             <member>
346                 <link linkend="gcf">gcf</link>
347             </member>
348             <member>
349                 <link linkend="gdf">gdf</link>
350             </member>
351             <member>
352                 <link linkend="gca">gca</link>
353             </member>
354             <member>
355                 <link linkend="gda">gda</link>
356             </member>
357             <member>
358                 <link linkend="axes_properties">axes_properties</link>
359             </member>
360             <member>
361                 <link linkend="clear_pixmap">clear_pixmap</link>
362             </member>
363             <member/>
364             <member>
365                 <link linkend="hotcolormap">hotcolormap</link>
366             </member>
367             <member>
368                 <link linkend="eventhandlerfunctions">event handler functions</link>
369             </member>
370         </simplelist>
371     </refsection>
372     <refsection>
373         <title>History</title>
374         <revhistory>
375             <revision>
376                 <revnumber>5.5.0</revnumber>
377                 <revremark>"visible" property also applies to uicontrols.</revremark>
378             </revision>
379             <revision>
380                 <revnumber>5.4.0</revnumber>
381                 <revremark>New resizefcn &amp; closerequestfcn properties introduced.</revremark>
382             </revision>
383         </revhistory>
384     </refsection>
385 </refentry>