PageRenderTime 123ms CodeModel.GetById 108ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 1ms

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

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