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