Update of the documentation
[scilab.git] / scilab / modules / external_objects_java / help / en_US / jimport.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 *
4 * JIMS ( http://forge.scilab.org/index.php/p/JIMS/ ) - This file is a part of JIMS
5 * Copyright (C) 2010 - 2011 - Calixte DENIZET <calixte@contrib.scilab.org>
6 *
7 * This file must be used under the terms of the CeCILL.
8 * This source file is licensed as described in the file COPYING, which
9 * you should have received as part of this distribution.  The terms
10 * are also available at
11 * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12 *
13 *
14 -->
15 <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" version="5.0-subset Scilab" xml:lang="en" xml:id="jimport">
16     <refnamediv>
17         <refname>jimport</refname>
18         <refpurpose>Import a Java class</refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>
23             jimport(className)
24             cl = jimport(className, isAClassReturned)
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Parameters</title>
29         <variablelist>
30             <varlistentry>
31                 <term>className</term>
32                 <listitem>
33                     <para>A string giving the class name</para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>isAClassReturned</term>
38                 <listitem>
39                     <para>A boolean to indicate if a class object must be returned</para>
40                 </listitem>
41             </varlistentry>
42         </variablelist>
43     </refsection>
44     <refsection>
45         <title>Description</title>
46         <para>
47             The class must be in the classpath (to add a package or a directory in the Java classpath, just use <link type="scilab" linkend="scilab.help/javaclasspath">javaclasspath</link>).
48         </para>
49         <para>
50             When <literal>jimport("java.lang.String")</literal>, a mlist named String is created on the Scilab stack. The created mlist has a type equals to _JClass and can be used to instantiate new objects in using something like <literal>str = String.new("A Scilab String");</literal>. It is possible to call the static methods (if exist) of the class
51         </para>
52         <programlisting role="example"><![CDATA[
53                jautoUnwrap(%f);
54                jimport java.lang.System;
55                jimport java.util.Date;
56                System.err.println("A message print in the Scilab console");
57                l = System.currentTimeMillis(); //Working with the object is necessary
58                d = Date.new(l)
59                jremove(l,d);
60                jautoUnwrap(%t);
61       ]]></programlisting>
62         <para>
63             To avoid confusion with already existing Scilab variables, the second argument isAClassReturned can be used
64         </para>
65         <programlisting role="example"><![CDATA[
66                  String = "Hello";
67                  foo = jimport("java.lang.String", %f);
68                  obj = foo.new("A string...")
69                  jremove(obj);
70         ]]></programlisting>
71         <para>
72             A class can be reloaded if it is allowed by the function <literal>jallowReloadClass</literal>.
73         </para>
74     </refsection>
75     <refsection>
76         <title>Examples</title>
77         <programlisting role="example"><![CDATA[
78                jimport javax.swing.JFrame;
79                jimport javax.swing.JLabel;
80
81                jframe = JFrame.new("Hello World !! Window");
82                jlabel = JLabel.new("A JLabel containing ""Hello Wolrd""");
83                cp = jframe.getContentPane();
84                cp.add(jlabel);
85                jframe.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
86                jframe.pack();
87                jframe.setVisible(%t);
88                jremove jlabel cp jframe;
89       ]]></programlisting>
90     </refsection>
91     <refsection role="see also">
92         <title>See Also</title>
93         <simplelist type="inline">
94             <member>
95                 <link type="scilab" linkend="scilab.help/javaclasspath">javaclasspath</link>
96             </member>
97             <member>
98                 <link linkend="jallowClassReloading">jallowClassReloading</link>
99             </member>
100             <member>
101                 <link linkend="jremove">jremove</link>
102             </member>
103         </simplelist>
104     </refsection>
105 </refentry>