/jEdit/tags/jedit-4-0-pre5/doc/users-guide/launcher-guide.xml
XML | 531 lines | 480 code | 39 blank | 12 comment | 0 complexity | 05122521582cbbc5e1013d7d78b93751 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
1<!-- jEdit buffer-local properties: -->
2<!-- :tabSize=2:indentSize=1:noTabs=true:maxLineLen=72: -->
3
4<!-- jEditLauncher 3.2 (R2) Quick Guide -->
5<!-- Copyright (C) 2001 John Gellene -->
6
7<!-- $Id: launcher-guide.xml 4001 2002-01-31 05:35:49Z spestov $
8-->
9
10<appendix id="launcher-guide"><title>jEditLauncher for Windows</title>
11
12<sect1 id="launcher-intro"><title>Introduction</title>
13 <para>
14 The jEditLauncher package is a set of
15 lightweight components for running jEdit under the Windows
16 group of operating systems. The package is designed to run
17 on Windows 95, Windows 98, Windows Me, Windows NT (versions 4.0 and
18 greater), Windows 2000 and Windows XP. <!-- This version is designed to work with
19 jEdit version 3.2pre4 and later. It will not work with earlier
20 versions. -->
21 </para>
22
23 <para>
24 While jEdit does not make available a component-type interface, it does
25 contains an <quote>EditServer</quote> that listens on a socket for
26 requests to load scripts written in the BeanShell scripting
27 language. When the server activates, it writes
28 the server port number and a pseudo-random, numeric authorization key to
29 a text file. By default, the file is named <filename>server</filename>
30 and is located in the settings directory (see
31 <xref linkend="settings-directory" />).
32 </para>
33
34 <para>
35 The jEditLauncher component locates and reads this file,
36 opens a socket and attempts to connect to the indicated port. If
37 successful, it transmits the appropriate BeanShell script to the server.
38 If unsuccessful, it attempts to start jEdit and repeats the socket
39 transmission once it can obtain the port and key information. The
40 component will abandon the effort to connect roughly twenty seconds after
41 it launches the application.
42 </para>
43</sect1>
44
45<sect1 id="launcher-starting"><title>Starting jEdit</title>
46 <para>
47 The main component of the jEditLauncher package is a client
48 application
49 entitled <command>jedit.exe</command>. It may be executed either
50 from Windows Explorer, or the command line. It uses the jEditLauncher
51 COM component to open files in jEdit that are listed as command line
52 parameters. It supports Windows and UNC file
53 specifications as well as wild cards. If called without parameters, it
54 will launch jEdit. If jEdit is already running<!-- and has an active
55 EditServer -->, it will simply open a new, empty buffer.
56 </para>
57
58 <para>
59 <command>jedit.exe</command> supports four command-line
60 options.
61 If any of these options
62 are invoked correctly, the application will not load files or
63 execute jEdit.
64 </para>
65
66 <itemizedlist>
67 <listitem>
68 <para>
69 The option <userinput>/h</userinput> causes a window to be displayed
70 with a brief description of the application and its various options.
71 </para>
72 </listitem>
73
74 <listitem>
75 <para>
76 The option <userinput>/p</userinput> will activate a dialog window
77 displaying the command-line parameters to be used when calling jEdit.
78 This option can also be triggered by selecting <guilabel>Set
79 jEdit Parameters</guilabel> from the <guilabel>jEdit</guilabel>
80 section of the Windows Programs menu.
81 </para>
82
83 <para>
84 Using the dialog, you can change parameters specifying the executable for
85 the Java interpreter, the JAR archive file or class name used as the
86 target of the interpreter, and command line options for both. If the
87 <userinput>-jar</userinput> option is not used for the Java executable,
88 the principal jEdit class of
89 <classname>org.gjt.sp.jedit.jEdit</classname> is set as fixed data. The
90 working directory for the Java interpreter's process can also be
91 specified. A read-only window at the bottom of the dialog displays
92 the full command-line that jEditLauncher will invoke.
93 </para>
94
95 <para>
96 Before committing changes to the command line parameters,
97 <command>jedit.exe</command> validates the paths for the Java
98 and jEdit targets as well as the working directory. It will complain if
99 the paths are invalid. It will not validate command-line options, but it
100 will warn you if it finds the <userinput>-noserver</userinput> option
101 used for jEdit, since this will deactivate the edit
102 server and make it
103 impossible for jEditLauncher to open files.
104 </para>
105
106 <para>
107 Note that due to the design of
108 <application>jEditLauncher</application>,
109 platform-independent command line options
110 handled by jEdit itself (such as
111 <command>-background</command> and
112 <command>-norestore</command>) must be entered in the
113 <quote>Set jEdit Parameters</quote> dialog box, and cannot be
114 specified on the <command>jedit.exe</command> command line
115 directly. For information about platform-independent command
116 line options, see <xref linkend="cli-usage" />.
117 </para>
118 </listitem>
119
120 <listitem>
121 <para>
122 The option <userinput>/i</userinput> is not mentioned in the help window
123 for <filename>jedit.exe</filename>. It is intended primarily to be used
124 in conjunction with jEdit's Java installer, but it can also be used to
125 install or reinstall jEditLauncher manually. When accompanied by a second
126 parameter specifying the directory where your preferred Java interpreter
127 is located, jEditLauncher will install itself and set a reasonable
128 initial set of command line parameters for executing jEdit. You can
129 change these parameters later by running <filename>jedit.exe</filename>
130 with the<userinput>/p</userinput> option.
131 </para>
132 </listitem>
133
134 <listitem>
135 <para>
136 The option <userinput>/u</userinput> will cause jEditLauncher
137 to be uninstalled by removing its registry entries.
138 This option does not delete any jEditLauncher or jEdit files.
139 </para>
140 </listitem>
141 </itemizedlist>
142
143</sect1>
144
145<sect1 id="launcher-menu"><title>The Context Menu Handler</title>
146 <para>
147 The jEditLauncher package also implements a context menu handler for the Windows
148 shell. It is intended to be be installed as a handler available for any
149 file. When you right-click on a file or shortcut icon, the context
150 menu that appears will include an item displaying the jEdit icon and
151 captioned <guilabel>Open with jEdit</guilabel>. If the file has an extension,
152 another item will appear captioned <guilabel>Open *.XXX with jEdit</guilabel>,
153 where XXX is the extension of the selected file. Clicking this item will
154 cause jEdit to load all files with the same extension in the same directory
155 as the selected file. Multiple file selections are also supported; in this
156 circumstance only the <guilabel>Open with jEdit</guilabel> item appears.
157 </para>
158 <para>
159 If a single file with a <filename>.bsh</filename> extension
160 is selected, the menu
161 will also contain an item captioned <guilabel>Run script in
162 jEdit</guilabel>. Selecting this item will cause jEditLauncher to
163 run the selected file as a BeanShell script.
164 </para>
165 <para>
166 If exactly two files are selected, the menu will contain an entry
167 for <guilabel>Show diff in jEdit</guilabel>. Selecting this item will
168 load the two files in jEdit and have them displayed side-by-side
169 with their differences highlighted by the
170 <application>JDiff</application> plugin. The file selected first will
171 be treated as the base for comparison purposes. If the plugin is not
172 installed, an error message will be displayed in jEdit. See <xref
173 linkend="using-plugins" /> for more information about installing
174 plugins.
175 </para>
176</sect1>
177
178
179
180<sect1 id="launcher-uninstall"><title>Uninstalling jEdit and jEditLauncher</title>
181 <para>
182
183 </para>
184 <para>
185 There are three ways to uninstall jEdit and jEditLauncher.
186 </para>
187
188 <itemizedlist>
189 <listitem>
190 <para>
191 First, you can run <filename>unlaunch.exe</filename> in the
192 jEdit installation directory.
193 </para>
194 </listitem>
195 <listitem>
196 <para>
197 Second, you can choose <guilabel>Uninstall jEdit</guilabel> from the
198 <guilabel>jEdit</guilabel> section of the Programs menu. <!-- This will
199 uninstall the <quote>primary</quote> version of jEdit (and will
200 designate a new primary version if any versions remain). -->
201 </para>
202 </listitem>
203 <listitem>
204 <para>
205 Third, you can choose the uninstall option for jEdit in the Control
206 Panel's Add/Remove Programs applet.
207 <!-- This allows you to specify
208 unambiguously the version of jEdit that you wish to remove. -->
209 </para>
210 </listitem>
211 </itemizedlist>
212
213 <para>
214 Each of these options will deactivate jEditLauncher and delete all files
215 in jEdit's installation directory. As a safeguard, jEditLauncher
216 displays a warning window and requires the user to confirm an uninstall operation.
217 Because the user's settings directory can be set and changed from
218 one jEdit session to another, user settings files must be
219 deleted manually.
220 </para>
221
222 <para>
223 To deactivate jEditLauncher without deleting any files, run
224 <filename>jedit /u</filename> from any command prompt where the jEdit
225 installation directory is in the search path. This will remove the
226 entries for jEditLauncher from the Windows registry, and disable the
227 context menu handler, and the automatic launching and scripting
228 capabilities. The package can reactivated by executing
229 <command>jedit.exe</command> again, and jEdit can be started in the
230 same manner as any other Java application on your system.
231 </para>
232</sect1>
233
234<sect1 id="launcher-interface"> <title>The jEditLauncher Interface</title>
235 <para>
236 The core of the jEditLauncher package is a COM component that can
237 communicate with the EditServer, or open jEdit if it is not running or
238 is otherwise refusing a connection. The component supports both Windows
239 and UNC file specifications, including wild cards. It will resolve
240 shortcut links to identify and transmit the name of the underlying file.
241 </para>
242
243 <para>
244 Because it is implemented with a <quote>dual interface</quote>, the
245 functions of jEditLauncher are available to scripting languages in the
246 Windows environment such as VBScript, JScript, Perl (using the
247 Win32::OLE package) and Python (using the win32com.client package).
248 </para>
249
250 <para>
251 The scriptable interface consists of two read-only properties and
252 six functions:
253 </para>
254 <para>
255 <emphasis>Properties</emphasis>
256 </para>
257 <itemizedlist>
258 <listitem>
259 <para>
260 <varname>ServerPort</varname> - a read-only property that returns the
261 port number found in jEdit's server file; the value is not tested for
262 authenticity. It returns zero if the server information file cannot
263 be located.
264 </para>
265 </listitem>
266
267 <listitem>
268 <para>
269 <varname>ServerKey</varname> - a read-only property that returns the numeric
270 authorization key found in jEdit's server file; the value is not tested
271 for authenticity. It returns zero if the server information file cannot
272 be located.
273 </para>
274 </listitem>
275 </itemizedlist>
276
277 <para>
278 <emphasis>Functions</emphasis>
279 </para>
280 <itemizedlist>
281 <listitem>
282 <para>
283 <function>OpenFile</function> - a method that takes a single file name
284 (with or without wild card characters) as a parameter.
285 </para>
286 </listitem>
287
288 <listitem>
289 <para>
290 <function>OpenFiles</function> - this method takes a array of file names
291 (with or without wild card characters) as a parameter. The form of the
292 array is that which is used for arrays in the scripting environment. In
293 JScript, for example the data type of the <type>VARIANT</type> holding
294 the array is <type>VT_DISPATCH</type>; in VBScript, it is <type>VT_ARRAY
295 | VT_VARIANT</type>, with array members having data type
296 <type>VT_BSTR</type>.
297 </para>
298 </listitem>
299
300 <listitem>
301 <para>
302 <function>Launch</function> - this method with no parameters attempts to
303 open jEdit without loading additional files.
304 </para>
305 </listitem>
306
307 <listitem>
308 <para>
309 <function>RunScript</function> - this method takes a file name or full file
310 path as a parameter and runs the referenced file as a BeanShell script in jEdit.
311 The predefined variables <varname>view</varname>, <varname>editPane</varname>,
312 <varname>textArea</varname> and <varname>buffer</varname> are available to the
313 script. If more than one view is open, the variable are
314 initialized with reference to the earliest opened view. If no path is
315 given for the file it will use the working directory of the calling process.
316 </para>
317 </listitem>
318
319 <listitem>
320 <para>
321 <function>EvalScript</function> - this method takes a string as a
322 parameter containing one or more BeanShell statements and runs the script
323 in jEdit's BeanShell interpreter. The
324 predefined variables are available on the same basis as in
325 <function>RunScript</function>.
326 </para>
327 </listitem>
328
329 <listitem>
330 <para>
331 <function>RunDiff</function> - this method takes two strings
332 representing file names as parameters. If the
333 <application>JDiff</application> plugin is installed, this method
334 will activate the JDiff plugin and display the two files in the
335 plugin's graphical <quote>dual diff</quote> format. The first
336 parameter is treated as the base for display purposes. If the
337 <application>JDiff</application> plugin is not installed, a
338 error message box will be displayed in jEdit.
339 </para>
340 </listitem>
341 </itemizedlist>
342</sect1>
343
344<sect1 id="launcher-examples"><title>Scripting Examples</title>
345 <para>
346 Here are some brief examples of scripts using jEditLauncher. The first
347 two will run under Windows Script Host, which is either installed or
348 available for download for 32-bit Windows operating systems. The next
349 example is written in Perl and requires the Win32::OLE package. The
350 last is written in Python and requires the win32gui and win32com.client
351 extensions.
352 </para>
353 <para>
354 If Windows Script Host is installed, you can run the first two
355 scripts by typing the name of the file containing the script at a
356 command prompt. In jEdit's <application>Console</application>
357 plugin, you can type
358 <userinput>cmd /c <replaceable>script_path</replaceable></userinput> or
359 <userinput>wscript <replaceable>script_path</replaceable></userinput>.
360 </para>
361
362<informalexample><programlisting>' Example VBSscript using jEditLauncher interface
363dim launcher
364set launcher = CreateObject("JEdit.JEditLauncher")
365a = Array("I:\Source Code Files\shellext\jeditshell\*.h", _
366 "I:\Source Code Files\shellext\jeditshell\*.cpp")
367MsgBox "The server authorization code is " + _
368 FormatNumber(launcher.ServerKey, 0, 0, 0, 0) + ".", _
369 vbOKOnly + vbInformation, "jEditLauncher"
370launcher.openFiles(a)
371myScript = "jEdit.newFile(view); textArea.setSelectedText(" _
372 & CHR(34) _
373 & "Welcome to jEditLauncher." _
374 & CHR(34) & ");"
375launcher.evalScript(myScript)</programlisting></informalexample>
376
377<informalexample><programlisting>/* Example JScript using jEditLauncher interface
378 * Note: in contrast to VBScript, JScript does not
379 * directly support message boxes outside a browser window
380 */
381var launcher = WScript.createObject("JEdit.JEditLauncher");
382var a = new Array("I:\\weather.html", "I:\\test.txt");
383b = "I:\\*.pl";
384launcher.openFiles(a);
385launcher.openFile(b);
386c = "G:\\Program Files\\jEdit\\macros\\Misc"
387 + "\\Properties\\System_properties.bsh";
388launcher.runScript(c);</programlisting></informalexample>
389
390<informalexample><programlisting># Example Perl script using jEditLauncher interface
391use Win32::OLE;
392$launcher = Win32::OLE->new('JEdit.JEditLauncher') ||
393 die "JEditLauncher: not found !\n";
394@files = ();
395foreach $entry (@ARGV) {
396 @new = glob($entry);
397 push(@files,@new);
398}
399$launcher->openFiles(\@files);
400my($script) = "Macros.message(view, \"I found "
401 .(scalar @files)." files.\");";
402$launcher->evalScript($script);</programlisting></informalexample>
403
404<informalexample><programlisting># Example Python script using jEditLauncher interface
405import win32gui
406import win32com.client
407o = win32com.client.Dispatch("JEdit.JEditLauncher")
408port = o.ServerPort
409if port == 0:
410 port = "inactive. We will now launch jEdit"
411win32gui.MessageBox(0, "The server port is %s." % port,
412 "jEditLauncher", 0)
413path = "C:\\WINNT\\Profiles\\Administrator\\Desktop\\"
414o.RunDiff(path + "Search.bsh", path + "Search2.bsh")
415</programlisting></informalexample>
416
417</sect1>
418
419<!-- open sect1 -->
420<sect1 id="launcher-logging"><title>jEditLauncher Logging</title>
421<para>
422 The jEditLauncher package has a logging facility that is separate from jEdit's
423 Activity Log to provide a record of events occurring outside the Java
424 virtual machine environemnt in which jEdit operates. The logging
425 facility maintains two log files: <filename>jelaunch.log</filename> for
426 events relating to starting jEdit, loading files and running scripts,
427 and <filename>install.log</filename> for jEditLauncher installation
428 activity. Both files are maintained in the directory in which jEdit
429 is installed. They are cumulative from session to seesion, but may be
430 manually deleted at any time without affecting program execution.
431</para>
432
433
434</sect1>
435
436<!-- <sect1 id="launcher-install"><title>Standalone Installation</title>
437 <para>
438 Installation of jEditLauncher occurs as part of the installation of the
439 jEdit package for Windows. If a full jEdit installation fails, you can
440 install jEditLauncher by placing the following files in the same
441 directory as <filename>jedit.jar</filename>, the archive containing the
442 Java application:
443 </para>
444 <itemizedlist>
445 <listitem>
446 <para>
447 <filename>jedit.exe</filename>
448 </para>
449 </listitem>
450 <listitem>
451 <para>
452 <filename>jedinit.exe</filename>
453 </para>
454 </listitem>
455 <listitem>
456 <para>
457 <filename>jeshlstb.dll</filename>
458 </para>
459 </listitem>
460 <listitem>
461 <para>
462 <filename>jedinstl.dll</filename>
463 </para>
464 </listitem>
465 <listitem>
466 <para>
467 <filename>jeditsvr.exe</filename>
468 </para>
469 </listitem>
470 <listitem>
471 <para>
472 <filename>jeservps.dll</filename>
473 </para>
474 </listitem>
475 <listitem>
476 <para>
477 <filename>unlaunch.exe</filename>
478 </para>
479 </listitem>
480 </itemizedlist>
481 <para>
482 Anytime <filename>jedit.exe</filename> is executed (either directly or
483 indirectly through a call to <filename>jedinit.exe</filename>),
484 jEditLauncher checks to see if it is properly installed. If it is not,
485 it will offer to install itself. If you agree, you will then be asked to
486 supply the path to a Java interpreter. The directory you choose should
487 contain <filename>javaw.exe</filename>, which the installer uses as a
488 default; you can change the interpreter later with a call to
489 <filename>jedinit.exe</filename>.
490 </para>
491</sect1> -->
492
493<sect1 id="launcher-legalnotice">
494 <title>Legal Notice</title>
495 <para>
496 All source code and software distributed as the jEditLauncher package in
497 which the author holds the copyright is made available under the GNU
498 General Public License (<quote>GPL</quote>). A copy of the GPL is
499 included in the file <filename>COPYING.txt</filename> included with jEdit.
500 </para>
501
502 <para>
503 Notwithstanding the terms of the General Public License, the author
504 grants permission to compile and link object code generated by the
505 compilation of this program with object code and libraries that are not
506 subject to the GNU General Public License, provided that the executable
507 output of such compilation shall be distributed with source code on
508 substantially the same basis as the jEditLauncher package of which this
509 source code and software is a part. By way of example, a distribution
510 would satisfy this condition if it included a working Makefile for any
511 freely available make utility that runs on the Windows family of
512 operating systems. This condition does not require a licensee of this
513 software to distribute any proprietary software (including header files
514 and libraries) that is licensed under terms prohibiting or limiting
515 redistribution to third parties.
516 </para>
517
518 <para>
519 The purpose of this specific permission is to allow a user to link files
520 contained or generated by the source code with library and other files
521 licensed to the user by Microsoft or other parties, whether or not that
522 license conforms to the requirements of the GPL. This permission
523 should not be construed to expand the terms of any license for any
524 source code or other materials used in the creation of
525 jEditLauncher.
526 </para>
527
528</sect1>
529
530</appendix>
531