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