PageRenderTime 228ms CodeModel.GetById 212ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-1-pre5/doc/users-guide/launcher-guide.xml

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