1 |
iliev |
1144 |
<?xml version="1.0" encoding="UTF-8"?> |
2 |
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
3 |
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
4 |
|
|
<book> |
5 |
|
|
<title>JSampler Manual</title> |
6 |
|
|
|
7 |
|
|
<bookinfo> |
8 |
|
|
<author> |
9 |
|
|
<firstname>by Grigor</firstname> |
10 |
|
|
|
11 |
|
|
<surname>Iliev</surname> |
12 |
|
|
</author> |
13 |
|
|
|
14 |
|
|
<copyright> |
15 |
|
|
<year>2007</year> |
16 |
|
|
|
17 |
|
|
<holder>Grigor Iliev <grigor@grigoriliev.com></holder> |
18 |
|
|
</copyright> |
19 |
|
|
|
20 |
|
|
<legalnotice> |
21 |
|
|
<para>This document is released under the terms of the <ulink |
22 |
|
|
url="gfdl.html">GNU Free Documentation License</ulink>.</para> |
23 |
|
|
</legalnotice> |
24 |
|
|
|
25 |
iliev |
1285 |
<pubdate>Updated: Fri, 10 August 2007</pubdate> |
26 |
iliev |
1144 |
</bookinfo> |
27 |
|
|
|
28 |
|
|
<chapter> |
29 |
|
|
<title>Introduction</title> |
30 |
|
|
|
31 |
|
|
<section> |
32 |
|
|
<title>What is JSampler?</title> |
33 |
|
|
|
34 |
|
|
<para>JSampler is an opensource, platform-independent, GUI front-end for |
35 |
|
|
<ulink url="http://www.linuxsampler.org">LinuxSampler</ulink>, written |
36 |
|
|
entirely in <ulink url="http://java.sun.com">Java</ulink>. The main goal |
37 |
|
|
of the JSampler's design is to be extensible and more flexible regarding |
38 |
|
|
the integration of different GUI implementations. JSampler consists of |
39 |
|
|
two parts:</para> |
40 |
|
|
|
41 |
|
|
<para><itemizedlist> |
42 |
|
|
<listitem> |
43 |
|
|
<para>JSampler core - handles the LSCP command processing and |
44 |
|
|
event notifications, sent by LinuxSampler, and provides convenient |
45 |
|
|
data models and controllers to be used instead. The core also |
46 |
|
|
provides the necessary interfaces that should be implemented by |
47 |
|
|
all JSamler views.</para> |
48 |
|
|
</listitem> |
49 |
|
|
|
50 |
|
|
<listitem> |
51 |
|
|
<para>JSampler view - an extension to the JSampler core, which |
52 |
|
|
provides the user interface part of JSampler.</para> |
53 |
|
|
</listitem> |
54 |
|
|
</itemizedlist>The main reason for that is the TCP/IP based |
55 |
|
|
communication between the LinuxSampler and its front-ends, enabling the |
56 |
|
|
sampler to be controlled from another computer or device, which may have |
57 |
|
|
different display requirements and limitations.</para> |
58 |
|
|
</section> |
59 |
|
|
|
60 |
|
|
<section> |
61 |
|
|
<title>What is a JSampler distribution?</title> |
62 |
|
|
|
63 |
|
|
<para>A JSampler distribution consist of the JSampler core and at least |
64 |
|
|
one view, providing the GUI implementation. Each distribution has its |
65 |
|
|
own name, which is based on the integrated view extension. Currently, |
66 |
|
|
there are two distributions:</para> |
67 |
|
|
|
68 |
|
|
<para><itemizedlist> |
69 |
|
|
<listitem> |
70 |
|
|
<para>JS Classic - A distribution with a standard GUI, capable of |
71 |
|
|
controlling all features available in LinuxSampler at the time of |
72 |
|
|
this writing. JS Classic also provides some additional features to |
73 |
|
|
facilitate the every day work with the sampler and to automate the |
74 |
|
|
most frequently used configurations.</para> |
75 |
|
|
</listitem> |
76 |
|
|
|
77 |
|
|
<listitem> |
78 |
iliev |
1285 |
<para>Fantasia - A distribution with a modern skin based view |
79 |
|
|
(initial graphic design by Olivier Boyer).</para> |
80 |
iliev |
1144 |
</listitem> |
81 |
|
|
</itemizedlist></para> |
82 |
|
|
</section> |
83 |
|
|
</chapter> |
84 |
|
|
|
85 |
|
|
<chapter> |
86 |
|
|
<title>Screenshots</title> |
87 |
|
|
|
88 |
iliev |
1285 |
<para>JS Classic with left pane, LS console, statusbar and toolbars</para> |
89 |
iliev |
1144 |
|
90 |
iliev |
1285 |
<para><ulink url="images/js-classic1.png"><inlinegraphic |
91 |
|
|
fileref="images/js-classic1-preview.png" /></ulink></para> |
92 |
|
|
|
93 |
iliev |
1144 |
<para>JS Classic without left pane, LS console, statusbar and |
94 |
iliev |
1285 |
toolbars</para> |
95 |
iliev |
1144 |
|
96 |
iliev |
1285 |
<para><ulink url="images/js-classic2.png"><inlinegraphic |
97 |
|
|
fileref="images/js-classic2-preview.png" /></ulink></para> |
98 |
|
|
|
99 |
|
|
<para>Fantasia</para> |
100 |
|
|
|
101 |
|
|
<para><ulink url="images/fantasia.png"><inlinegraphic |
102 |
|
|
fileref="images/fantasia-preview.png" /></ulink></para> |
103 |
iliev |
1144 |
</chapter> |
104 |
|
|
|
105 |
|
|
<chapter> |
106 |
|
|
<title>Installation</title> |
107 |
|
|
|
108 |
|
|
<para></para> |
109 |
|
|
|
110 |
iliev |
1285 |
<section id="download"> |
111 |
|
|
<title>What to download?</title> |
112 |
iliev |
1144 |
|
113 |
iliev |
1285 |
<para>Currently, there are two distributions available for download - |
114 |
|
|
<ulink |
115 |
iliev |
1445 |
url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.7a.jar">JS |
116 |
iliev |
1285 |
Classic</ulink> and <ulink |
117 |
iliev |
1445 |
url="http://downloads.sourceforge.net/jsampler/Fantasia-0.7a.jar">Fantasia</ulink>.</para> |
118 |
iliev |
1144 |
|
119 |
|
|
<para>The source code is available in the <ulink |
120 |
iliev |
1445 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.7a.tar.bz2">JSampler |
121 |
iliev |
1144 |
package</ulink>, which also contains this manual and startup scripts |
122 |
|
|
that can be used to run a particular JSampler distribution.</para> |
123 |
|
|
|
124 |
|
|
<para>The latest source code can be obtained from cvs with the following |
125 |
|
|
command:</para> |
126 |
|
|
|
127 |
|
|
<para><command>cvs -z3 |
128 |
|
|
-d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co |
129 |
|
|
jsampler</command></para> |
130 |
|
|
</section> |
131 |
|
|
|
132 |
iliev |
1285 |
<section id="requirements"> |
133 |
|
|
<title lang="" xreflabel="">Requirements</title> |
134 |
iliev |
1144 |
|
135 |
iliev |
1204 |
<para>To run JSampler you need Java Runtime Environment (JRE) version 6 |
136 |
iliev |
1144 |
or higher. The latest version can be downloaded from <ulink |
137 |
|
|
url="http://java.sun.com/javase/downloads/">here</ulink>.</para> |
138 |
|
|
|
139 |
|
|
<para>To build JSampler distribution from source you need JDK version |
140 |
iliev |
1204 |
6.0 or higher and the <ulink url="http://ant.apache.org/">Ant |
141 |
iliev |
1144 |
tool</ulink>.</para> |
142 |
|
|
</section> |
143 |
|
|
|
144 |
iliev |
1285 |
<section id="running-js-dist"> |
145 |
|
|
<title>Running a JSampler distribution</title> |
146 |
iliev |
1144 |
|
147 |
|
|
<para>Let's assume that you want to run from the command line |
148 |
iliev |
1285 |
<code>JS_Classic-0.6a.jar</code>, which is located in |
149 |
iliev |
1144 |
<code>/home/me/soft</code> directory. First you should check whether the |
150 |
|
|
<code>java</code> command is in your path and the version requirements |
151 |
|
|
are met. This can be done by issuing the following command:</para> |
152 |
|
|
|
153 |
|
|
<para><command>java -version</command></para> |
154 |
|
|
|
155 |
iliev |
1204 |
<para>If the version is 1.6.0 or higher you can run JS Classic by |
156 |
iliev |
1144 |
issuing the following command:</para> |
157 |
|
|
|
158 |
|
|
<para><command>java -jar |
159 |
iliev |
1285 |
/home/me/soft/JS_Classic-0.6a.jar</command></para> |
160 |
iliev |
1144 |
|
161 |
|
|
<para>Otherwise, if the shell response is something like</para> |
162 |
|
|
|
163 |
|
|
<para><command>bash: java: command not found</command></para> |
164 |
|
|
|
165 |
|
|
<para>or the version requirements are not met, make sure that you have |
166 |
|
|
installed JRE (or JDK) with the proper version and find its |
167 |
|
|
location:</para> |
168 |
|
|
|
169 |
|
|
<para><literallayout><command>updatedb |
170 |
|
|
locate bin/java</command></literallayout></para> |
171 |
|
|
|
172 |
|
|
<para>The shell should return something like:</para> |
173 |
|
|
|
174 |
|
|
<para><literallayout><command>/opt/jdk1.6.0/bin/java |
175 |
|
|
/opt/jdk1.6.0/bin/javac |
176 |
|
|
/opt/jdk1.6.0/bin/javadoc |
177 |
|
|
/opt/jdk1.6.0/bin/javah |
178 |
|
|
/opt/jdk1.6.0/bin/javap |
179 |
|
|
/opt/jdk1.6.0/jre/bin/java |
180 |
|
|
/usr/bin/java</command></literallayout></para> |
181 |
|
|
|
182 |
|
|
<para>Now, we know that we have a JDK with a proper version installed |
183 |
|
|
and its location is <code>/opt/jdk1.6.0</code>. In that case, to run JS |
184 |
|
|
Classic issue the following command:</para> |
185 |
|
|
|
186 |
|
|
<para><command>/opt/jdk1.6.0/bin/java -jar |
187 |
iliev |
1285 |
/home/me/soft/JS_Classic-0.6a.jar</command></para> |
188 |
iliev |
1144 |
|
189 |
|
|
<para><note> |
190 |
|
|
<para>On some systems double clicking on the jar file will be |
191 |
|
|
enough.</para> |
192 |
|
|
</note></para> |
193 |
|
|
</section> |
194 |
|
|
|
195 |
|
|
<section> |
196 |
|
|
<title>Using a script to run a JSampler distribution</title> |
197 |
|
|
|
198 |
|
|
<para>There are scripts In the <code>scripts</code> directory of the |
199 |
|
|
<ulink |
200 |
iliev |
1445 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.7a.tar.bz2">JSampler |
201 |
iliev |
1144 |
package</ulink> that, with a little adjustments (if needed), can be used |
202 |
|
|
to run a JSampler distribution. Copy them to a desired location and edit |
203 |
|
|
with your preferred editor.</para> |
204 |
|
|
</section> |
205 |
|
|
|
206 |
|
|
<section> |
207 |
|
|
<title>Telling Gnome how to handle jar files</title> |
208 |
|
|
|
209 |
|
|
<para>This configuration is optional, but necessary if you want to run |
210 |
|
|
jar files by (double) clicking on them. In Gnome, by default jar files |
211 |
|
|
are opened with the Archive Manager. To change that, run a file browser, |
212 |
|
|
right click on an arbitrary jar file and choose |
213 |
|
|
<guimenu>Properties</guimenu>, than go to the <guilabel>Open |
214 |
|
|
With</guilabel> tab and click the <guibutton>Add</guibutton> |
215 |
|
|
button.</para> |
216 |
|
|
|
217 |
|
|
<para><graphic fileref="images/file-properties.png" /></para> |
218 |
|
|
|
219 |
|
|
<para>In the <guilabel>Add Application</guilabel> dialog click onto |
220 |
|
|
<guilabel>Use a custom command</guilabel> label and a text field will |
221 |
|
|
appear below. If the location of your JRE is <code>/opt/jre1.6.0</code>, |
222 |
|
|
then enter the following command in the text box:</para> |
223 |
|
|
|
224 |
|
|
<para><command>/opt/jre1.6.0/bin/java -jar</command></para> |
225 |
|
|
|
226 |
|
|
<para>And then click the <guibutton>Add</guibutton> button.</para> |
227 |
|
|
|
228 |
|
|
<para><graphic fileref="images/add-application.png" /></para> |
229 |
|
|
</section> |
230 |
|
|
|
231 |
|
|
<section> |
232 |
|
|
<title>Adding an application launcher to a Gnome panel</title> |
233 |
|
|
|
234 |
|
|
<para>To add an application launcher to a Gnome panel, right click on |
235 |
|
|
the panel and choose <guimenu>Add to Panel</guimenu>.</para> |
236 |
|
|
|
237 |
|
|
<para><graphic fileref="images/add-to-panel.png" /></para> |
238 |
|
|
|
239 |
|
|
<para>Then select <guilabel>Custom Application Launcher</guilabel> and |
240 |
|
|
click the <guibutton>Add</guibutton> button. In the |
241 |
|
|
<guilabel>Command</guilabel> field, of the <guilabel>Create |
242 |
|
|
Launcher</guilabel> dialog, fill in the exact command that you use to |
243 |
|
|
run the JSampler. For more information on how to run a JSampler |
244 |
|
|
distribution from the command line <link linkend="running-js-dist">click |
245 |
|
|
here</link>.</para> |
246 |
|
|
|
247 |
|
|
<para><graphic |
248 |
|
|
fileref="images/add-to-panel-create-launcher.png" /></para> |
249 |
|
|
</section> |
250 |
|
|
|
251 |
|
|
<section> |
252 |
|
|
<title>Running JSampler on Windows</title> |
253 |
|
|
|
254 |
|
|
<para>To run JSampler distribution on Windows, put a shortcut on the |
255 |
|
|
Desktop or Quick Launch, right click on the shortcut and choose |
256 |
|
|
<guimenu>Properties</guimenu>. In the <guilabel>Target</guilabel> field |
257 |
|
|
insert the command <code>javaw -jar</code> in the beginning.</para> |
258 |
|
|
|
259 |
|
|
<para><graphic fileref="images/win-shortcut.png" /></para> |
260 |
|
|
</section> |
261 |
|
|
</chapter> |
262 |
|
|
|
263 |
|
|
<chapter> |
264 |
|
|
<title>Building from source</title> |
265 |
|
|
|
266 |
|
|
<para>If you want to build a JSampler distribution from source, first make |
267 |
|
|
sure that all <link linkend="requirements">requirements</link> are |
268 |
|
|
met.</para> |
269 |
|
|
|
270 |
|
|
<section> |
271 |
|
|
<title>Building from CVS</title> |
272 |
|
|
|
273 |
|
|
<para>When building from CVS, there are some additional steps that |
274 |
|
|
should be done. JSampler uses two additional libraries, that should be |
275 |
|
|
downloaded and placed in the <code>lib/required</code> directory:</para> |
276 |
|
|
|
277 |
|
|
<para><itemizedlist> |
278 |
|
|
<listitem> |
279 |
|
|
<para><ulink |
280 |
|
|
url="http://sourceforge.net/projects/jlscp/">jlscp</ulink> - A |
281 |
|
|
java LinuxSampler control protocol API</para> |
282 |
|
|
</listitem> |
283 |
|
|
|
284 |
|
|
<listitem> |
285 |
|
|
<para><ulink |
286 |
|
|
url="http://sourceforge.net/projects/juife/">juife</ulink> - Java |
287 |
|
|
User Interface Framework Extensions</para> |
288 |
|
|
</listitem> |
289 |
|
|
</itemizedlist>Download these libraries, create a |
290 |
|
|
<code>lib/required</code> directory in the JSampler root and copy the |
291 |
|
|
<code>jlscp.jar</code> and <code>juife.jar</code> files in that |
292 |
|
|
directory:</para> |
293 |
|
|
|
294 |
|
|
<para><literallayout><command>cd /home/me/soft |
295 |
iliev |
1204 |
wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.5a.tar.bz2 |
296 |
|
|
tar -xjf jlscp-0.5a.tar.bz2 |
297 |
iliev |
1144 |
wget -c http://downloads.sourceforge.net/juife/juife-0.4a.tar.bz2 |
298 |
|
|
tar -xjf juife-0.4a.tar.bz2 |
299 |
|
|
cvs -z3 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co jsampler |
300 |
|
|
cd jsampler |
301 |
|
|
mkdirhier lib/required |
302 |
iliev |
1204 |
cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar |
303 |
iliev |
1144 |
cp ../juife-0.4a/lib/juife.jar lib/required/juife.jar</command></literallayout></para> |
304 |
|
|
|
305 |
|
|
<para>Then follow the steps in the next section.</para> |
306 |
|
|
</section> |
307 |
|
|
|
308 |
|
|
<section> |
309 |
|
|
<title>Compilation</title> |
310 |
|
|
|
311 |
|
|
<para>To build a JSampler distribution, first set the |
312 |
|
|
<code>JAVA_HOME</code> environment variable to point to your JDK |
313 |
|
|
directory. If the JDK is installed in /opt/jdk1.6.0 directory, this can |
314 |
|
|
be done by issuing the following command:</para> |
315 |
|
|
|
316 |
|
|
<para><command>export JAVA_HOME=/opt/jdk1.6.0</command></para> |
317 |
|
|
|
318 |
|
|
<para>Windows users should do something like:</para> |
319 |
|
|
|
320 |
|
|
<para><command>set JAVA_HOME=c:\jdk1.6.0</command></para> |
321 |
|
|
|
322 |
|
|
<para>Go to the JSampler root directory and issue the following |
323 |
|
|
command:</para> |
324 |
|
|
|
325 |
|
|
<para><command>ant [target]</command></para> |
326 |
|
|
|
327 |
|
|
<para>Where <code>target</code> can be one of the following:</para> |
328 |
|
|
|
329 |
|
|
<para><itemizedlist> |
330 |
|
|
<listitem> |
331 |
|
|
<para><command>build-jsclassic</command> - Builds a JS Classic |
332 |
|
|
distribution.</para> |
333 |
|
|
</listitem> |
334 |
|
|
|
335 |
|
|
<listitem> |
336 |
|
|
<para><command>clean-jsclassic</command> - Removes the JS Classic |
337 |
|
|
distribution.</para> |
338 |
|
|
</listitem> |
339 |
|
|
|
340 |
|
|
<listitem> |
341 |
|
|
<para><command>build-fantasia</command> - Builds a Fantasia |
342 |
|
|
distribution.</para> |
343 |
|
|
</listitem> |
344 |
|
|
|
345 |
|
|
<listitem> |
346 |
|
|
<para><command>clean-fantasia</command> - Removes the Fantasia |
347 |
|
|
distribution.</para> |
348 |
|
|
</listitem> |
349 |
|
|
|
350 |
|
|
<listitem> |
351 |
|
|
<para><command>build-coredoc</command> - Generates the API |
352 |
|
|
documentation for the JSampler core.</para> |
353 |
|
|
</listitem> |
354 |
|
|
|
355 |
|
|
<listitem> |
356 |
|
|
<para><command>clean-coredoc</command> - Removes the API |
357 |
|
|
documentation for the JSampler core.</para> |
358 |
|
|
</listitem> |
359 |
|
|
</itemizedlist></para> |
360 |
|
|
|
361 |
|
|
<para>So, if you want to build a JS Classic distribution, just issue the |
362 |
|
|
following command:</para> |
363 |
|
|
|
364 |
|
|
<para><command>ant build-jsclassic</command></para> |
365 |
|
|
|
366 |
|
|
<para>Then copy the jar file from the <code>dist</code> directory to the |
367 |
|
|
desired location.</para> |
368 |
|
|
</section> |
369 |
|
|
</chapter> |
370 |
|
|
</book> |