Revision of help pages for some obsolete functions from module "graphics" (en_US).
[scilab.git] / scilab / modules / graphics / help / en_US / xset.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) ENPC - Jean-Philippe Chancelier
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-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="xset">
14     <refnamediv>
15         <refname>xset</refname>
16         <refpurpose>
17             set values of the graphics context. <emphasis role="bold">This function is obsolete.</emphasis>
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>
23             xset(choice_name, x1, x2, x3, x4, x5)
24             xset()
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>choice_name</term>
32                 <listitem>
33                     <para>string</para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>x1, ..., x5</term>
38                 <listitem>
39                     <para>
40                         depending on <literal>choice_name</literal>.
41                     </para>
42                 </listitem>
43             </varlistentry>
44         </variablelist>
45     </refsection>
46     <refsection>
47         <title>Description</title>
48         <para>
49             <warning>
50                 This function is obsolete.
51             </warning>
52             Use the Scilab graphic objects representation instead (see the
53             <link linkend="set">set</link> and <link linkend="get">get</link>
54             functions as well as the <link linkend="graphics_entities">graphics
55             entities</link> help page).
56         </para>
57         <para>
58             <function>xset</function> is used to set default values of the
59             current window graphic context.
60         </para>
61         <para>
62             When called no argument, a choice menu is created showing the
63             current values and changes can be performed through toggle buttons.
64         </para>
65         <para>
66             Use <code>xset()</code> to display or set the current color, mark
67             and fonts used.
68         </para>
69         <para/>
70         <variablelist>
71             <varlistentry>
72                 <term>xset("auto clear","on"|"off")</term>
73                 <listitem>
74                     <para>
75                         Switch <literal>"on"</literal> or <literal>"off"</literal>
76                         the auto clear mode for graphics. When the auto clear
77                         mode is <literal>"on"</literal>, successive plots are
78                         not superposed, i.e. a <code>clf()</code> operation (the
79                         graphics window is cleared and the associated recorded
80                         graphics is erased) is performed before each high
81                         level graphics function. Default value is <literal>"off"</literal>.
82                     </para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>xset("background",color)</term>
87                 <listitem>
88                     <para>
89                         Set the background color of the current <literal>Axes</literal>
90                         object. The <literal>color</literal> argument is the
91                         colormap index of the color to use.
92                     </para>
93                 </listitem>
94             </varlistentry>
95             <varlistentry>
96                 <term>xset("clipping", x, y, w, h)</term>
97                 <listitem>
98                     <para>
99                         Set the clipping zone (the zone of the graphics window
100                         where plots can be drawn) to the rectangle
101                         <literal>(x,y,w,h)</literal> (Upper-Left point, Width,
102                         Height). This function uses the current coordinates of
103                         the plot.
104                     </para>
105                 </listitem>
106             </varlistentry>
107             <varlistentry>
108                 <term>xset("color",value)</term>
109                 <listitem>
110                     <para>
111                         Set the default color for filling, line or text drawing
112                         functions. <literal>value</literal> is an integer
113                         projected in the interval <literal>[0,whiteid]</literal>.
114                         0 is used for black filling and <literal>whiteid</literal> for white. The
115                         value of <literal>whiteid</literal> can be obtained with <code>xget("white")</code>.
116                     </para>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>xset("colormap",cmap)</term>
121                 <listitem>
122                     <para>
123                         Set the colormap as a <literal>m x 3</literal> matrix,
124                         where <literal>m</literal> is the number of colors.
125                         Color number <literal>i</literal> is given as a 3-uple
126                         <literal>cmap(i,1)</literal>, <literal>cmap(i,2)</literal>,
127                         <literal>cmap(i,3)</literal>  corresponding respectively
128                         to red, green and blue intensity between 0 and 1.
129                     </para>
130                 </listitem>
131             </varlistentry>
132             <varlistentry>
133                 <term>xset("dashes",i)</term>
134                 <listitem>
135                     <para>
136                         In black and white mode (<code>xset("use color",0)</code>),
137                         set the dash style to style <literal>i</literal> (0 for
138                         solid line). In color mode (<code>xset("use color",1)</code>)
139                         this is used to set line, mark and text color.
140                         <warning>
141                             This keyword is obsolete, please use
142                             <literal>xset('color',i)</literal> or
143                             <literal>xset('line style',i)</literal> instead.
144                         </warning>
145                     </para>
146                 </listitem>
147             </varlistentry>
148             <varlistentry>
149                 <term>xset("default")</term>
150                 <listitem>
151                     <para>
152                         Reset the graphics context to default values.
153                     </para>
154                 </listitem>
155             </varlistentry>
156             <varlistentry>
157                 <term>xset("font", fontid, fontsize):</term>
158                 <listitem>
159                     <para>
160                          Set the current font and its current size. Note that
161                          <literal>fontsize</literal> applies to all fonts not
162                         only <literal>fontid</literal>.
163                     </para>
164                 </listitem>
165             </varlistentry>
166             <varlistentry>
167                 <term>xset("font size", fontsize)</term>
168                 <listitem>
169                     <para>Set the fonts size.</para>
170                 </listitem>
171             </varlistentry>
172             <varlistentry>
173                 <term>xset("foreground",color)</term>
174                 <listitem>
175                     <para>
176                         Set the foreground color of the current <literal>Axes</literal>
177                         object. The <literal>color</literal> argument is the
178                         colormap index of the color to use.
179                     </para>
180                 </listitem>
181             </varlistentry>
182             <varlistentry>
183                 <term>xset("fpf", string)</term>
184                 <listitem>
185                     <para>
186                         Set the floating point format for number display in
187                         contour functions. <literal>string</literal> is a string
188                         giving the format in C format syntax (for example
189                         <code>string="%.3f"</code>). Use
190                         <code>string=""</code> to switch back to default format.
191                     </para>
192                 </listitem>
193             </varlistentry>
194             <varlistentry>
195                 <term>xset("hidden3d", colorid): </term>
196                 <listitem>
197                     <para>
198                         Set the color number for backward facing faces in
199                         <function>plot3d</function>. <literal>colorid=0</literal>
200                         zero suppress the drawing of backward facing faces of 3d
201                         objects. This is technically called 'culling' and speeds
202                         up the rendering of closed surfaces.
203                     </para>
204                 </listitem>
205             </varlistentry>
206             <varlistentry>
207                 <term>xset("line mode", type)</term>
208                 <listitem>
209                     <para>
210                         This function is used to set the line drawing mode.
211                         Absolute mode is set with <literal>type=1</literal> and
212                         relative mode with type=0.
213                         <warning>The mode type=0 has bugs.</warning>
214                     </para>
215                 </listitem>
216             </varlistentry>
217             <varlistentry>
218                 <term>xset("line style", value)</term>
219                 <listitem>
220                     <para>
221                         Set the current line style (1 for solid, &gt;1 for
222                         dashed lines).
223                     </para>
224                 </listitem>
225             </varlistentry>
226             <varlistentry>
227                 <term>xset("mark", markid, marksize)</term>
228                 <listitem>
229                     <para>
230                         Set the current mark and the current mark size. Use
231                         <code>xset()</code> to see the marks. Note that
232                         <literal>marksize</literal> applies to all marks not
233                         only <literal>markid</literal>.
234                     </para>
235                 </listitem>
236             </varlistentry>
237             <varlistentry>
238                 <term>xset("mark size", marksize)</term>
239                 <listitem>
240                     <para>Set the mark size.</para>
241                 </listitem>
242             </varlistentry>
243             <varlistentry>
244                 <term>xset("pattern", value)</term>
245                 <listitem>
246                     <para>
247                         Set the current pattern for filling functions. value is
248                         an integer projected in the interval
249                         <literal>[0,whiteid]</literal>. 0 is used for black
250                         filling and <literal>whiteid</literal> for white. The
251                         value of <literal>whiteid</literal> can be obtained
252                         with <code>xget("white")</code>.
253                         <literal>"pattern"</literal> is equivalent to
254                         <literal>"color"</literal>.
255                     </para>
256                 </listitem>
257             </varlistentry>
258             <varlistentry>
259                 <term>xset("pixmap", flag)</term>
260                 <listitem>
261                     <para>
262                         If <literal>flag=0</literal> the graphics are directly
263                         displayed on the screen. If <literal>flag=1</literal>
264                         the graphics are done on a pixmap and are sent to the
265                         graphics window with the command
266                         <code>xset("wshow")</code>. The pixmap is cleared with
267                         the command <code>xset("wwpc")</code>. Note that the
268                         usual command <code>clf()</code> also clears the pixmap.
269                     </para>
270                 </listitem>
271             </varlistentry>
272             <varlistentry>
273                 <term>xset("thickness", value)</term>
274                 <listitem>
275                     <para>
276                         Set the thickness of lines in pixel (0 and 1 have the
277                         same meaning: 1 pixel thick).
278                     </para>
279                 </listitem>
280             </varlistentry>
281             <varlistentry>
282                 <term>xset("use color", flag)</term>
283                 <listitem>
284                     <para>
285                         If <literal>flag=1</literal> then <code>xset("pattern", 1)</code> or
286                         <code>xset("dashes", 1)</code> will be used so as to
287                         change the default color for drawing or for filling
288                         patterns. If <literal>flag=0</literal> then we switch
289                         back to the gray and dashes mode.
290                     </para>
291                 </listitem>
292             </varlistentry>
293             <varlistentry>
294                 <term>xset("viewport", x, y)</term>
295                 <listitem>
296                     <para>Set the position of the panner.</para>
297                 </listitem>
298             </varlistentry>
299             <varlistentry>
300                 <term>xset("wdim", width, height)</term>
301                 <listitem>
302                     <para>
303                         Set the width and the height of the current graphics
304                         window. This option is not used by the postscript
305                         driver.
306                     </para>
307                 </listitem>
308             </varlistentry>
309             <varlistentry>
310                 <term>xset("wpdim", width, height)</term>
311                 <listitem>
312                     <para>
313                         Sets the width and the height of the current physical
314                         graphic window (which can be different from the actual
315                         size in mode <literal>wresize</literal> 1). This option
316                         is not used by the postscript driver.
317                     </para>
318                 </listitem>
319             </varlistentry>
320             <varlistentry>
321                 <term>xset("window", window_number)</term>
322                 <listitem>
323                     <para>
324                         Set the current window to the window <literal>window_number</literal>
325                         and creates the window if it does not exist.
326                     </para>
327                 </listitem>
328             </varlistentry>
329             <varlistentry>
330                 <term>xset("wpos", x, y)</term>
331                 <listitem>
332                     <para>
333                         Set the position of the upper left point of the graphics
334                         window.
335                     </para>
336                 </listitem>
337             </varlistentry>
338             <varlistentry>
339                 <term>xset("wresize",flag)</term>
340                 <listitem>
341                     <para>
342                         If <literal>flag=1</literal> then the graphic is
343                         automatically resized to fill the graphics window.
344                     </para>
345                     <programlisting role=""><![CDATA[
346 xdel();
347 xset("wresize",1);
348 plot2d();
349 xset("wdim",1000,500)
350  ]]></programlisting>
351                     <para>
352                         If flag=0 the scale of the graphic is left unchanged
353                         when the graphics window is resized. Top left panner or
354                         keyboard arrows may be used to scroll over the graphic.
355                     </para>
356                     <programlisting role=""><![CDATA[
357 xdel();
358 plot2d();
359 xset("wresize",0);
360 xset("wdim",1000,500)
361  ]]></programlisting>
362                 </listitem>
363             </varlistentry>
364             <varlistentry>
365                 <term>xset("wshow")</term>
366                 <listitem>
367                     <para>
368                         See <literal>xset("pixmap", 1)</literal> above.
369                     </para>
370                 </listitem>
371             </varlistentry>
372             <varlistentry>
373                 <term>xset("wwpc")</term>
374                 <listitem>
375                     <para>
376                         See <literal>xset("pixmap", 1)</literal> above.
377                     </para>
378                 </listitem>
379             </varlistentry>
380         </variablelist>
381     </refsection>
382     <refsection role="see also">
383         <title>See Also</title>
384         <simplelist type="inline">
385             <member>
386                 <link linkend="xget">xget</link>
387             </member>
388             <member>
389                 <link linkend="getcolor">getcolor</link>
390             </member>
391             <member>
392                 <link linkend="getsymbol">getsymbol</link>
393             </member>
394             <member>
395                 <link linkend="ged">ged</link>
396             </member>
397             <member>
398                 <link linkend="set">set</link>
399             </member>
400             <member>
401                 <link linkend="graphics_entities">graphics entities</link>
402             </member>
403         </simplelist>
404     </refsection>
405     <refsection>
406         <title>History</title>
407         <revhistory>
408             <revision>
409                 <revnumber>5.4.0</revnumber>
410                 <revremark>
411                     The "alufunction" property is no more supported, this property was no more used for rendering since Scilab 5.0.1.
412                 </revremark>
413             </revision>
414         </revhistory>
415     </refsection>
416 </refentry>