* Bug 16148: xmlSetValues() <= setPreferencesValue()
[scilab.git] / scilab / modules / preferences / help / en_US / setPreferencesValue.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) 2014 - Scilab Enterprises - Calixte DENIZET
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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="setPreferencesValue" xml:lang="en">
17     <refnamediv>
18         <refname>setPreferencesValue</refname>
19         <refpurpose>Set preferences value <emphasis role="bold">(obsolete)</emphasis></refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             setPreferencesValue(xpath, key_value [, doc])
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>xpath</term>
32                 <listitem>
33                     <para>a string, represents the XPath request to get the node in the preferences file.</para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>key_value</term>
38                 <listitem>
39                     <para>a 2xN matrix of strings, the key-values to set.</para>
40                 </listitem>
41             </varlistentry>
42         </variablelist>
43         <variablelist>
44             <varlistentry>
45                 <term>doc</term>
46                 <listitem>
47                     <para>a mlist typed XMLDoc, the XML document associated to the preference file.
48                     </para>
49                 </listitem>
50             </varlistentry>
51         </variablelist>
52     </refsection>
53     <refsection>
54         <title>Description</title>
55         <warning>
56             <literal>setPreferencesValue()</literal> is obsolete and will be removed in Scilab 6.1.x.
57             Please use <code>xmlSetValues()</code> instead.
58         </warning>
59         <para>
60             Set the values of the attributes in preferences file (<literal>SCIHOME+'/XConfiguration.xml'</literal>).
61         </para>
62         <warning>
63             Modifying incorrectly some preferences can alter Scilab's behaviour.
64         </warning>
65         <para>
66             When doc is specified, the values are searched in this document. It is useful when several requests need to be done to avoid to parse again and again the same configuration file.
67         </para>
68         <para>
69             All valid XPath requests are possible. For example to write the XPath request to set proxy settings:
70         </para>
71         <simplelist type="inline">
72             <member>
73                 <para>
74                     Open the file <literal>SCIHOME+'/XConfiguration.xml'</literal> and gets the nodes names to access to the expected node:
75                 </para>
76                 <programlisting role="xml"><![CDATA[
77 <?xml version="1.0" encoding="utf-8" standalone="no"?>
78 <interface height="600" path="1/" version="0.17" width="800">
79     <general title="_(General)">
80     ...
81     </general>
82     <web title="_(Web)">
83         <body>
84             <web command-browser="" command-mailer="" default-browser="true" default-mailer="true"/>
85             <proxy enabled="false" host="" password="" port="" user=""/>
86             <previous-proxy enabled="false" host="" password="" port="" user=""/>
87         </body>
88     </web>
89     ...
90 </interface>
91           ]]></programlisting>
92                 <para>
93                     The path will be <literal>"/interface/web/body/proxy"</literal> (or to simplify <literal>"//web/body/proxy"</literal>).
94                 </para>
95             </member>
96         </simplelist>
97     </refsection>
98     <refsection>
99         <title>Examples</title>
100         <programlisting role="example"><![CDATA[
101 // Get the current values
102 prev = xmlGetValues("//web/body/proxy", ["enabled", "host", "port"]);
103 setPreferencesValue("//web/body/proxy", ["enabled", "host", "port"; "true", "my.proxy.org", "1234"]);
104
105 // Ok that's work
106 xmlGetValues("//web/body/proxy", ["enabled", "host", "port"])
107
108 // We restore the previous values
109 setPreferencesValue("//web/body/proxy", ["enabled", "host", "port" ; prev]);
110 xmlGetValues("//web/body/proxy", ["enabled", "host", "port"])
111  ]]></programlisting>
112     </refsection>
113     <refsection role="see also">
114         <title>See also</title>
115         <simplelist type="inline">
116             <member>
117                 <link linkend="xmlGetValues">xmlGetValues</link>
118             </member>
119         </simplelist>
120     </refsection>
121     <refsection role="history">
122         <title>History</title>
123         <revhistory>
124             <revision>
125                 <revnumber>6.1.0</revnumber>
126                 <revdescription>
127                     setPreferencesValue() declared obsolete, replaced with xmlSetValues().
128                 </revdescription>
129             </revision>
130         </revhistory>
131     </refsection>
132 </refentry>