PageRenderTime 183ms CodeModel.GetById 169ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/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
  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  &amp; CHR(34) _
373  &amp; "Welcome to jEditLauncher." _
374  &amp; CHR(34) &amp; ");"
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