<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>

  <TITLE>figure_properties</TITLE>

  <TYPE>Scilab Data type</TYPE>

  <DATE>2002</DATE>

  <SHORT_DESCRIPTION name="figure_properties">description of the graphics
  figure entity properties</SHORT_DESCRIPTION>

  <DESCRIPTION>
    <P>The figure entity is the top level of the graphics entities hierarchy.
    This entity contain a number of properties designed to control many
    aspects of displaying Scilab graphics objects. These properties fall into
    two categories. Properties that contain information about figure itself
    and others related to set default values for the children creation.</P>

    <DESCRIPTION_INDENT>
      <DESCRIPTION_ITEM label="Figure properties: ">
        <DESCRIPTION_INDENT>
          <DESCRIPTION_ITEM label="children: ">
            <SP>This handles represent the vector of the figure's children .
            Note that all figure children are of type <VERB>"Axes"</VERB>.
            Also keep in mind that, when creating a figure entity (using
            <VERB>scf</VERB> command), an <VERB>Axes</VERB> entity is
            simultaneously built too.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="figure_style: ">
            <SP>The value of this field defines the figure style, it should be
            <VERB>"old"</VERB> or <VERB>"new"</VERB>. The <VERB>"new"</VERB>
            value sets the entity based style. The <VERB>"old"</VERB> value
            represents the old Scilab graphic mode. In this case
            <VERB>figure_style</VERB> is the only defined property.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="figure_position: ">
            <SP>This field contains the position in pixel of the graphic
            window on the screen. The size is the vector <VERB>[x,y]</VERB>.
            The point <VERB>[0,0]</VERB> if the upper-left corner of the
            screen.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="figure_size: ">
            <SP>This property controls the size in pixel of the screen's
            graphics window. The size is the vector
            <VERB>[width,height]</VERB>.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="axes_size: ">
            <SP>Used to Specifies the size in pixel of the virtual graphics
            window. The size is the vector <VERB>[width,height] </VERB>. The
            virtual graphic window should be bigger than the part really
            visible on the screen.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="auto_resize: ">
            <SP>This property determines if graphics window is resized. If the
            value is <VERB>"on"</VERB> then the <VERB>axes_size</VERB>
            property is equaled to the <VERB>figure_size</VERB> and the axes
            children are zoomed accordingly. If the value is
            <VERB>"off"</VERB> that indicate that <VERB>axes_size</VERB>
            cannot be resized when <VERB>figure_size</VERB> is changed.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="figure_name: ">
            <SP>This field contains the name of the figure. This name is a
            character string displayed at the top of the graphics_window. The
            name can contain a single substring <VERB>%d</VERB> which will be
            replaced by the <VERB>figure_id</VERB>. No other instance of the
            <VERB>%</VERB> character is allowed inside the name.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="figure_id: ">
            <SP>This field contains the identifier of the figure. This is an
            integer number which is set at figure creation and cannot be
            changed after.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="color_map: ">
            <SP>Property which defines the colormap used by this figure. The
            colormap is a <VERB>m</VERB> by <VERB>3</VERB> matrix.
            <VERB>m</VERB> is the number of colors. Color number i is given as
            a 3-uple <VERB>R</VERB>, <VERB>G</VERB>, <VERB>B</VERB>
            corresponding respectively to red, green and blue intensity
            between 0 and 1.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="pixmap: ">
            <SP>This property controls the pixmap status of a Graphic Window.
            If this property value is <VERB>"off"</VERB> the graphics are
            directly displayed on the screen. If it is <VERB>"on"</VERB> the
            graphics are done on a pixmap and are sent to the graphics window
            with the command <VERB>show_pixmap()</VERB>.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="pixel_drawing_mode: ">
            <SP>This field defines the bitwise operation used to draw the
            pixel on the screen. The default mode is <VERB>copy</VERB> what is
            to say the pixel is drawn as required. More generally the bitwise
            operation is performed between the color of the source pixel and
            the color of the pixel already present on the screen. Operations
            are : <VERB>"clear"</VERB>, <VERB>"and"</VERB>,
            <VERB>"andReverse"</VERB> , <VERB>"copy"</VERB>,
            <VERB>"andInverted"</VERB> , <VERB>"noop"</VERB> ,
            <VERB>"xor"</VERB> , <VERB>"or"</VERB> , <VERB>"nor"</VERB> ,
            <VERB>"equiv"</VERB> , <VERB>"invert"</VERB> ,
            <VERB>"orReverse"</VERB> , <VERB>"copyInverted"</VERB> ,
            <VERB>"orInverted"</VERB> , <VERB>"nand"</VERB> ,
            <VERB>"set"</VERB> ,</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="immediate_drawing: ">
            <SP>This property controls the figure display. Its value can be
            <VERB>"on"</VERB> (default mode) or <VERB>"off"</VERB>. It is used
            to delay a huge succession of graphics commands (implying several
            drawings or redrawings). Note that, when using
            <VERB>drawlater</VERB> or <VERB>drawnow</VERB> commands, it
            affects the property value of the current figure (which is
            respectively turned to <VERB>'off'</VERB> or
            <VERB>'on'</VERB>).</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="background: ">
            <SP>This property controls the figure window background color. It
            takes as value an index relative to the current colormap.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="user_data: ">
            <SP>This field can be use to store any scilab variable in the
            figure data structure, and to retreive it.</SP>
          </DESCRIPTION_ITEM>
        </DESCRIPTION_INDENT>
      </DESCRIPTION_ITEM>
    </DESCRIPTION_INDENT>

    <DESCRIPTION_INDENT>
      <DESCRIPTION_ITEM label="Children's default values: ">
        <DESCRIPTION_INDENT>
          <DESCRIPTION_ITEM label="visible: ">
            <SP>This field ules if the contents of the figure as to be
            redrawn. Its value should be <VERB>"on"</VERB> or
            <VERB>"off"</VERB>.</SP>
          </DESCRIPTION_ITEM>

          <DESCRIPTION_ITEM label="rotation_style: ">
            <SP>This field is related to the "3D Rot" button. It takes
            <VERB>unary</VERB> as value (default) in the aim to rotate only
            selected 3D plot. In the other case its value can be
            <VERB>multiple</VERB> : all 3D plots are rotated.</SP>
          </DESCRIPTION_ITEM>
        </DESCRIPTION_INDENT>
      </DESCRIPTION_ITEM>

      <DESCRIPTION_ITEM label="Note on default values :">
        <DESCRIPTION_INDENT>
          <DESCRIPTION_ITEM label="">
            <SP>All these listed properties and fields inherit from default
            values stored in a figure model. These default values can be seen
            and changed. To do so, use the <VERB>get("default_figure")</VERB>
            command : it returns a graphic handle on the figure model. Note
            that no graphic window is created by this command. The next
            created figures will inherit from this model (see example 2
            below).</SP>
          </DESCRIPTION_ITEM>
        </DESCRIPTION_INDENT>
      </DESCRIPTION_ITEM>
    </DESCRIPTION_INDENT>
  </DESCRIPTION>

  <EXAMPLE><![CDATA[
   lines(0) // disables vertical paging 
  //Example 1
   set("figure_style","new") //create a figure and set the figure as the current selected one
   f=get("current_figure") //get the handle of the current figure : 
                                           //if none exists, create a figure and return the corresponding handle
   f.figure_position
   f.figure_size=[200,200]
   f.background=2
   f.children  // man can see that an Axes entity already exists
   delete(f);
   f=gcf(); // macro shortcut <=> f=get("current_figure")
   f.pixmap = "on" // set pixmap status to on
   plot2d() // nothing happens on the screen...
   show_pixmap() // ...display the pixmap on screen
   //Example 2 : default_figure settings
   df=get("default_figure") // get the default values (shortcut is gdf() )
   // Let's change the defaults...
   df.color_map=hotcolormap(128)
   df.background= 110 // set background toa kind of yellow (Note that we are using a color index inside the color_map previously redefined)
   scf(122); // creates new figure number 122 with the new default
   plot2d()
   scf(214);
   t=-%pi:0.3:%pi;
   plot3d(t,t,sin(t)'*cos(t),35,45,'X@Y@Z',[15,2,4]);
     ]]></EXAMPLE>

  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>lines</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>set</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>get</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>scf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>gcf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>gdf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>gca</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>gda</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>axes_properties</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>show_pixmap</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>clear_pixmap</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM></SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>hotcolormap</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>

  <AUTHOR>Djalel ABDEMOUCHE</AUTHOR>
</MAN>