xset: help page only 'fpf' + equivalences
[scilab.git] / scilab / modules / graphics / help / en_US / xset.xml
index 2220f0b..55b1a14 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ENPC - Jean-Philippe Chancelier
+ * Copyright (C) 2017 - Samuel GOUGEON
  *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="xset">
+<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="xset">
     <refnamediv>
         <refname>xset</refname>
         <refpurpose>
@@ -24,7 +28,6 @@
         <title>Syntax</title>
         <synopsis>
             xset(choice_name, x1, x2, x3, x4, x5)
-            xset()
         </synopsis>
     </refsynopsisdiv>
     <refsection>
     </refsection>
     <refsection>
         <title>Description</title>
-        <para>
             <warning>
-                This function is obsolete.
+                This function is obsolete. Use the Scilab graphic objects representation instead:
+                See equivalences here-below.
             </warning>
-            Use the Scilab graphic objects representation instead (see the
-            <link linkend="set">set</link> and <link linkend="get">get</link>
-            functions as well as the <link linkend="graphics_entities">graphics
-                entities
-            </link>
-            help page).
-        </para>
-        <para>
-            <function>xset</function> is used to set default values of the
-            current window graphic context.
-        </para>
-        <para>
-            When called no argument, a choice menu is created showing the
-            current values and changes can be performed through toggle buttons.
-        </para>
-        <para>
-            Use <code>xset()</code> to display or set the current color, mark
-            and fonts used.
-        </para>
-        <para/>
         <variablelist>
             <varlistentry>
-                <term>xset("auto clear","on"|"off")</term>
-                <listitem>
-                    <para>
-                        Switch <literal>"on"</literal> or <literal>"off"</literal>
-                        the auto clear mode for graphics. When the auto clear
-                        mode is <literal>"on"</literal>, successive plots are
-                        not superposed, i.e. a <code>clf()</code> operation (the
-                        graphics window is cleared and the associated recorded
-                        graphics is erased) is performed before each high
-                        level graphics function. Default value is <literal>"off"</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("background",color)</term>
-                <listitem>
-                    <para>
-                        Set the background color of the current <literal>Axes</literal>
-                        object. The <literal>color</literal> argument is the
-                        colormap index of the color to use.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("clipping", x, y, w, h)</term>
-                <listitem>
-                    <para>
-                        Set the clipping zone (the zone of the graphics window
-                        where plots can be drawn) to the rectangle
-                        <literal>(x,y,w,h)</literal> (Upper-Left point, Width,
-                        Height). This function uses the current coordinates of
-                        the plot.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("color",value)</term>
-                <listitem>
-                    <para>
-                        Set the default color for filling, line or text drawing
-                        functions. <literal>value</literal> is an integer
-                        projected in the interval <literal>[0,whiteid]</literal>.
-                        0 is used for black filling and <literal>whiteid</literal> for white. The
-                        value of <literal>whiteid</literal> can be obtained with <code>xget("white")</code>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("colormap",cmap)</term>
-                <listitem>
-                    <para>
-                        Set the colormap as a <literal>m x 3</literal> matrix,
-                        where <literal>m</literal> is the number of colors.
-                        Color number <literal>i</literal> is given as a 3-uple
-                        <literal>cmap(i,1)</literal>, <literal>cmap(i,2)</literal>,
-                        <literal>cmap(i,3)</literal>  corresponding respectively
-                        to red, green and blue intensity between 0 and 1.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("dashes",i)</term>
-                <listitem>
-                    <para>
-                        In black and white mode (<code>xset("use color",0)</code>),
-                        set the dash style to style <literal>i</literal> (0 for
-                        solid line). In color mode (<code>xset("use color",1)</code>)
-                        this is used to set line, mark and text color.
-                        <warning>
-                            This keyword is obsolete, please use
-                            <literal>xset('color',i)</literal> or
-                            <literal>xset('line style',i)</literal> instead.
-                        </warning>
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("default")</term>
-                <listitem>
-                    <para>
-                        Reset the graphics context to default values.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("font", fontid, fontsize):</term>
-                <listitem>
-                    <para>
-                        Set the current font and its current size. Note that
-                        <literal>fontsize</literal> applies to all fonts not
-                        only <literal>fontid</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("font size", fontsize)</term>
-                <listitem>
-                    <para>Set the fonts size.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("foreground",color)</term>
-                <listitem>
-                    <para>
-                        Set the foreground color of the current <literal>Axes</literal>
-                        object. The <literal>color</literal> argument is the
-                        colormap index of the color to use.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
                 <term>xset("fpf", string)</term>
                 <listitem>
                     <para>
                     </para>
                 </listitem>
             </varlistentry>
-            <varlistentry>
-                <term>xset("hidden3d", colorid): </term>
-                <listitem>
-                    <para>
-                        Set the color number for backward facing faces in
-                        <function>plot3d</function>. <literal>colorid=0</literal>
-                        zero suppress the drawing of backward facing faces of 3d
-                        objects. This is technically called 'culling' and speeds
-                        up the rendering of closed surfaces.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("line mode", type)</term>
-                <listitem>
-                    <para>
-                        This function is used to set the line drawing mode.
-                        Absolute mode is set with <literal>type=1</literal> and
-                        relative mode with type=0.
-                        <warning>The mode type=0 has bugs.</warning>
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("line style", value)</term>
-                <listitem>
-                    <para>
-                        Set the current line style (1 for solid, &gt;1 for
-                        dashed lines).
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("mark", markid, marksize)</term>
-                <listitem>
-                    <para>
-                        Set the current mark and the current mark size. Use
-                        <code>xset()</code> to see the marks. Note that
-                        <literal>marksize</literal> applies to all marks not
-                        only <literal>markid</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("mark size", marksize)</term>
-                <listitem>
-                    <para>Set the mark size.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("pattern", value)</term>
-                <listitem>
-                    <para>
-                        Set the current pattern for filling functions. value is
-                        an integer projected in the interval
-                        <literal>[0,whiteid]</literal>. 0 is used for black
-                        filling and <literal>whiteid</literal> for white. The
-                        value of <literal>whiteid</literal> can be obtained
-                        with <code>xget("white")</code>.
-                        <literal>"pattern"</literal> is equivalent to
-                        <literal>"color"</literal>.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("thickness", value)</term>
-                <listitem>
-                    <para>
-                        Set the thickness of lines in pixel (0 and 1 have the
-                        same meaning: 1 pixel thick).
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("use color", flag)</term>
-                <listitem>
-                    <para>
-                        If <literal>flag=1</literal> then <code>xset("pattern", 1)</code> or
-                        <code>xset("dashes", 1)</code> will be used so as to
-                        change the default color for drawing or for filling
-                        patterns. If <literal>flag=0</literal> then we switch
-                        back to the gray and dashes mode.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("viewport", x, y)</term>
-                <listitem>
-                    <para>Set the position of the panner.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("wdim", width, height)</term>
-                <listitem>
-                    <para>
-                        Set the width and the height of the current graphics
-                        window. This option is not used by the postscript
-                        driver.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("wpdim", width, height)</term>
-                <listitem>
-                    <para>
-                        Sets the width and the height of the current physical
-                        graphic window (which can be different from the actual
-                        size in mode <literal>wresize</literal> 1). This option
-                        is not used by the postscript driver.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("window", window_number)</term>
-                <listitem>
-                    <para>
-                        Set the current window to the window <literal>window_number</literal>
-                        and creates the window if it does not exist.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("wpos", [x, y])</term>
-                <listitem>
-                    <para>
-                        Set the position of the upper left point of the graphics
-                        window.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xset("wresize",flag)</term>
-                <listitem>
-                    <para>
-                        If <literal>flag=1</literal> then the graphic is
-                        automatically resized to fill the graphics window.
-                    </para>
-                    <programlisting role=""><![CDATA[
-xdel();
-xset("wresize",1);
-plot2d();
-xset("wdim",1000,500)
- ]]></programlisting>
-                    <para>
-                        If flag=0 the scale of the graphic is left unchanged
-                        when the graphics window is resized. Top left panner or
-                        keyboard arrows may be used to scroll over the graphic.
-                    </para>
-                    <programlisting role=""><![CDATA[
-xdel();
-plot2d();
-xset("wresize",0);
-xset("wdim",1000,500)
- ]]></programlisting>
-                </listitem>
-            </varlistentry>
         </variablelist>
+        <refsect2>
+            <title>Replacements</title>
+            <para>
+            <literal>xset(..)</literal> returned nothing. Please take care appending a semi-colon
+            after replacement instructions in order to cancel the display of their output.
+            </para>
+        <screen><![CDATA[
+// SCILAB 3 & 4                 SCILAB N>4
+// ------------                 ----------
+xset("default")                 clf("reset")
+
+xset("wpos", [x y])             gcf().figure_position = [x y];
+xset("wpdim", w, h)             gcf().figure_size = [w h];
+xset("wdim", w, h)              gcf().figure_size = [w h];
+xset("wresize", 0|1)  HS        gcf().auto_resize = "off"|"on";
+xset("colormap", CM)            gcf().color_map = CM;
+xset("figure", i)               scf(i);
+xset("window", i)               scf(i);
+xset("viewport", xp,yp)         gcf().viewport = [xp yp];
+
+xset("auto clear","on"|"off")   gca().auto_clear = "on"|"off";
+xset("line mode", 0|1)          gca().line_mode = "off"|"on";
+xset("line style", n)           gca().line_style = n;
+xset("dashes", n)               gca().line_style = n;
+xset("thickness", n)            gca().thickness = n;
+xset("font size", s)            gca().font_size = s;
+xset("font", id, fsize)         set(gca(), "font_style", id, "font_size", fsize);
+xset("mark size", msize)        set(gca(), "mark_size_unit", "tabulated", "mark_size", msize);
+xset("mark", id, msize)         set(gca(), "mark_style", id, "mark_size_unit", "tabulated", "mark_size", msize);
+xset("color", icol)             gca().foreground = icol;
+xset("color", 0)                gca().foreground = -1;
+xset("pattern", icol)           gca().foreground = icol;
+xset("pattern", 0)              gca().foreground = -1;
+xset("foreground", icol)        gca().foreground = icol;
+xset("background", icol)        gca().background = icol;
+xset("hidden3d", icol)          gca().hiddencolor = icol;
+
+xset("clipping", rect)          set(gca(), "clip_box", rect, "clip_state", "on");
+xset("clipgrf")                 gca().clip_state = "clipgrf";
+xset("clipoff")                 gca().clip_state = "off";
+
+xset("alufunction",i)           gcf().pixel_drawing_mode = str(i);
+                                #i   str(i)
+                                --   ------
+                                0 => "clear"
+                                1 => "and"
+                                2 => "andReverse"
+                                3 => "copy"
+                                4 => "andInverted"
+                                5 => "noop"
+                                6 => "xor"
+                                7 => "or"
+                                8 => "nor"
+                                9 => "equiv"
+                                10 => "invert"
+                                11 => "orReverse"
+                                12 => "copyInverted"
+                                13 => "orInverted"
+                                14 => "nand"
+                                15 => "set"
+]]></screen>
+        </refsect2>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -361,16 +139,28 @@ xset("wdim",1000,500)
                 <link linkend="xget">xget</link>
             </member>
             <member>
-                <link linkend="getcolor">getcolor</link>
+                <link linkend="set">set</link>
             </member>
             <member>
-                <link linkend="ged">ged</link>
+                <link linkend="graphics_entities">graphics entities</link>
             </member>
             <member>
-                <link linkend="set">set</link>
+                <link linkend="gcf">gcf</link>
             </member>
             <member>
-                <link linkend="graphics_entities">graphics entities</link>
+                <link linkend="gdf">gdf</link>
+            </member>
+            <member>
+                <link linkend="gca">gca</link>
+            </member>
+            <member>
+                <link linkend="gda">gda</link>
+            </member>
+            <member>
+                <link linkend="ged">ged</link>
+            </member>
+            <member>
+                <link linkend="getcolor">getcolor</link>
             </member>
         </simplelist>
     </refsection>
@@ -378,9 +168,23 @@ xset("wdim",1000,500)
         <title>History</title>
         <revhistory>
             <revision>
+                <revnumber>5.0.1</revnumber>
+                <revremark>
+                    The <literal>.alufunction</literal> property is obsolete. It is no longer
+                    taken into account for graphical renderings. It is replaced with
+                    <literal>gcf().pixel_drawing_mode</literal>.
+                </revremark>
+            </revision>
+            <revision>
                 <revnumber>5.4.0</revnumber>
                 <revremark>
-                    The "alufunction" property is no more supported, this property was no more used for rendering since Scilab 5.0.1.
+                    The <literal>"alufunction"</literal> is no longer supported..
+                </revremark>
+            </revision>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revremark>
+                    The only <literal>xset("fpf", format)</literal> syntax is now supported.
                 </revremark>
             </revision>
         </revhistory>