# jEditLauncher for Windows

## Introduction

The jEditLauncher package is a set of lightweight components for running jEdit under the Windows group of operating systems. The package is designed to run on Windows 95, Windows 98, Windows Me, Windows NT (versions 4.0 and greater), Windows 2000 and Windows XP.

While jEdit does not make available a component-type interface, it does contains an EditServer that listens on a socket for requests to load scripts written in the BeanShell scripting language. When the server activates, it writes the server port number and a pseudo-random, numeric authorization key to a text file. By default, the file is named `server` and is located in the settings directory (see ).

The jEditLauncher component locates and reads this file, opens a socket and attempts to connect to the indicated port. If successful, it transmits the appropriate BeanShell script to the server. If unsuccessful, it attempts to start jEdit and repeats the socket transmission once it can obtain the port and key information. The component will abandon the effort to connect roughly twenty seconds after it launches the application.

## Starting jEdit

The main component of the jEditLauncher package is a client application entitled `jedit.exe`. It may be executed either from either Windows Explorer, a shortcut icon or the command line. It uses the jEditLauncher COM component to open files in jEdit that are listed as command line parameters. It supports Windows and UNC file specifications as well as wild cards. If called without parameters, it will launch jEdit. If jEdit is already running, it will simply open a new, empty buffer.

`jedit.exe` supports five command-line options. Except for the `/1` option, if any of these options are invoked correctly, the application will not load files or execute jEdit.

- The option `/h` causes a window to be displayed with a brief description of the application and its various options.

- The option `/p` will activate a dialog window displaying the command-line parameters to be used when calling jEdit. This option can also be triggered by selecting Set jEdit Parameters from the jEdit section of the Windows Programs menu, or by running the utility program `jedinit.exe`

  Using the dialog, you can change parameters specifying the executable for the Java application loader (either `java.exe` or `javaw.exe`), the location of the jEdit archive file, `jedit.jar`, and command line options for both.

  - The input fields for Java options and jEdit options are separate. If you insert an option in the wrong place it will not be properly executed.

  - If the `-jar` option is not used with the Java application loader the principal jEdit class of org.gjt.sp.jedit.jEdit is set as fixed data.

  - The working directory for the Java interpreter's process can also be specified.

  A read-only window at the bottom of the dialog displays the full command line that jEditLauncher will invoke.

  Before committing changes to the command line parameters, `jedit.exe` validates the paths for the Java and jEdit targets as well as the working directory. It will complain if the paths are invalid. It will not validate command line options, but it will warn you if it finds the `-noserver` option used for jEdit, since this will deactivate the edit server and make it impossible for jEditLauncher to open files.

  Note that due to the design of jEditLauncher, platform-independent command line options handled by jEdit itself (such as `-background` and `-norestore`) must be entered in the Set jEdit Parameters dialog box, and cannot be specified on the `jedit.exe` command line directly. For information about platform-independent command line options, see .

- The option `/1` is intended for use in circumstances where a single file name is passed to jEdit for opening, and quotation marks cannot be used to delimit file names containing whitespace. The launcher reads the entire command line following the `/1` options as a single file path, regardless of the presence of whitespace, and passes the resulting string as a single file name parameter to jEdit.

  This option allows jEdit to be used with version 5 or greater of Internet Explorer as an alternate text editor or as the target of the View Source command. Included with the jEditLauncher distribution is a file named `jEdit_IE.reg.txt` containing an example of a Window registry file that you can use to register jEdit as a HTML editor with Internet Explorer. Instructions for the file's use are included in the text.

  The use of the `/1` option with multiple file names or other parameters will lead to program errors or unpredictable results.

- The option `/i` is not mentioned in the help window for `jedit.exe`. It is intended primarily to be used in conjunction with jEdit's Java installer, but it can also be used to install or reinstall jEditLauncher manually. When accompanied by a second parameter specifying the directory where your preferred Java interpreter is located, jEditLauncher will install itself and set a reasonable initial set of command line parameters for executing jEdit. You can change these parameters later by running `jedinit.exe` or `jedit.exe` with the`/p` option.

- The option `/u` will cause jEditLauncher to be uninstalled by removing its registry entries. This option does not delete any jEditLauncher or jEdit files.

## The Context Menu Handler

The jEditLauncher package also implements a context menu handler for the Windows shell. It is intended to be be installed as a handler available for any file. When you right-click on a file or shortcut icon, the context menu that appears will include an item displaying the jEdit icon and captioned Open with jEdit. If the file has an extension, another item will appear captioned Open *.XXX with jEdit, where XXX is the extension of the selected file. Clicking this item will cause jEdit to load all files with the same extension in the same directory as the selected file. Multiple file selections are also supported; in this circumstance only the Open with jEdit item appears.

If a single file with a `.bsh` extension is selected, the menu will also contain an item captioned Run script in jEdit. Selecting this item will cause jEditLauncher to run the selected file as a BeanShell script.

If exactly two files are selected, the menu will contain an entry for Show diff in jEdit. Selecting this item will load the two files in jEdit and have them displayed side-by-side with their differences highlighted by the JDiff plugin. The file selected first will be treated as the base for comparison purposes. If the plugin is not installed, an error message will be displayed in jEdit. See for more information about installing plugins.

## Using jEdit and jEditLauncher as a Diff Utility

As noted above, you can create a graphical diff display comparing the contents of two text files by selecting the two files in an Explorer window, right-clicking to produce a context menu, and selecting the Show diff in jEdit menu item. The utility `jedidiff.exe` allows you to perform this operation from a command line. The command takes the two files to be compared as parameters; they should be delimited by quotation marks if their paths contain whitespace.

## Uninstalling jEdit and jEditLauncher

There are three ways to uninstall jEdit and jEditLauncher.

- First, you can run `unlaunch.exe` in the jEdit installation directory.

- Second, you can choose Uninstall jEdit from the jEdit section of the Programs menu.

- Third, you can choose the uninstall option for jEdit in the Control Panel's Add/Remove Programs applet.

Each of these options will deactivate jEditLauncher and delete all files in jEdit's installation directory. As a safeguard, jEditLauncher displays a warning window and requires the user to confirm an uninstall operation. Because the user's settings directory can be set and changed from one jEdit session to another, user settings files must be deleted manually.

To deactivate jEditLauncher without deleting any files, run `jedit /u` from any command prompt where the jEdit installation directory is in the search path. This will remove the entries for jEditLauncher from the Windows registry. It will also disable the context menu handler and the automatic launching and scripting capabilities. The package can reactivated by executing `jedit.exe` again, and jEdit can be started in the same manner as any other Java application on your system.

## The jEditLauncher Interface

The core of the jEditLauncher package is a COM component that can communicate with the EditServer, or open jEdit if it is not running or is otherwise refusing a connection. The component supports both Windows and UNC file specifications, including wild cards. It will resolve shortcut links to identify and transmit the name of the underlying file.

Because it is implemented with a dual interface, the functions of jEditLauncher are available to scripting languages in the Windows environment such as VBScript, JScript, Perl (using the Win32::OLE package) and Python (using the win32com.client package).

The scriptable interface consists of two read-only properties and six functions:

Properties

- `ServerPort` - a read-only property that returns the port number found in jEdit's server file; the value is not tested for authenticity. It returns zero if the server information file cannot be located.

- `ServerKey` - a read-only property that returns the numeric authorization key found in jEdit's server file; the value is not tested for authenticity. It returns zero if the server information file cannot be located.

Functions

- `OpenFile` - a method that takes a single file name (with or without wild card characters) as a parameter.

- `OpenFiles` - this method takes an array of file names (with or without wild card characters) as a parameter. The form of the array is that which is used for arrays in the scripting environment. In JScript, for example the data type of the VARIANT holding the array is VT_DISPATCH; in VBScript, it is VT_ARRAY | VT_VARIANT, with array members having data type VT_BSTR.

- `Launch` - this method with no parameters attempts to open jEdit without loading additional files.

- `RunScript` - this method takes a file name or full file path as a parameter and runs the referenced file as a BeanShell script in jEdit. The predefined variables `view`, `editPane`, `textArea` and `buffer` are available to the script. If more than one view is open, the variable are initialized with reference to the earliest opened view. If no path is given for the file it will use the working directory of the calling process.

- `EvalScript` - this method takes a string as a parameter containing one or more BeanShell statements and runs the script in jEdit's BeanShell interpreter. The predefined variables are available on the same basis as in `RunScript`.

- `RunDiff` - this method takes two strings representing file names as parameters. If the JDiff plugin is installed, this method will activate the JDiff plugin and display the two files in the plugin's graphical dual diff format. The first parameter is treated as the base for display purposes. If the JDiff plugin is not installed, a error message box will be displayed in jEdit.

## Scripting Examples

Here are some brief examples of scripts using jEditLauncher. The first two will run under Windows Script Host, which is either installed or available for download for 32-bit Windows operating systems. The next example is written in Perl and requires the Win32::OLE package. The last is written in Python and requires the win32gui and win32com.client extensions.

If Windows Script Host is installed, you can run the first two scripts by typing the name of the file containing the script at a command prompt. In jEdit's Console plugin, you can type `cmd /c script_path` or `wscript script_path`.

    ' Example VBScript using jEditLauncher interface
    dim launcher
    set launcher = CreateObject("JEdit.JEditLauncher")
    a = Array("I:\Source Code Files\shellext\jeditshell\*.h", _
    	"I:\Source Code Files\shellext\jeditshell\*.cpp")
    MsgBox "The server authorization code is " + _
    	FormatNumber(launcher.ServerKey, 0, 0, 0, 0) + ".", _
    	vbOKOnly + vbInformation, "jEditLauncher"
    launcher.openFiles(a)
    myScript = "jEdit.newFile(view); textArea.setSelectedText(" _
      & CHR(34) _
      & "Welcome to jEditLauncher." _
      & CHR(34) & ");"
    launcher.evalScript(myScript)

    /* Example JScript using jEditLauncher interface
     * Note: in contrast to VBScript, JScript does not
     * directly support message boxes outside a browser window
     */
    var launcher = WScript.createObject("JEdit.JEditLauncher");
    var a = new Array("I:\\weather.html", "I:\\test.txt");
    b = "I:\\*.pl";
    launcher.openFiles(a);
    launcher.openFile(b);
    c = "G:\\Program Files\\jEdit\\macros\\Misc"
      + "\\Properties\\System_properties.bsh";
    launcher.runScript(c);

    # Example Perl script using jEditLauncher interface
    use Win32::OLE;
    $launcher = Win32::OLE->new('JEdit.JEditLauncher') ||
       die "JEditLauncher: not found !\n";
    @files = ();
    foreach $entry (@ARGV) {
        @new = glob($entry);
        push(@files,@new);
    }
    $launcher->openFiles(\@files);
    my($script) = "Macros.message(view, \"I found "
        .(scalar @files)." files.\");";
    $launcher->evalScript($script);

    # Example Python script using jEditLauncher interface
    import win32gui
    import win32com.client
    o = win32com.client.Dispatch("JEdit.JEditLauncher")
    port = o.ServerPort
    if port == 0:
      port = "inactive. We will now launch jEdit"
    win32gui.MessageBox(0, "The server port is %s." % port,
        "jEditLauncher", 0)
    path = "C:\\WINNT\\Profiles\\Administrator\\Desktop\\"
    o.RunDiff(path + "Search.bsh", path + "Search2.bsh")

## jEditLauncher Logging

The jEditLauncher package has a logging facility that is separate from jEdit's Activity Log to provide a record of events occurring outside the Java virtual machine environment in which jEdit operates. The logging facility maintains two log files: `jelaunch.log` for events relating to starting jEdit, loading files and running scripts, and `install.log` for jEditLauncher installation activity. Both files are maintained in the directory in which jEdit is installed. They are cumulative from session to session, but may be manually deleted at any time without affecting program execution.

## Legal Notice

All source code and software distributed as the jEditLauncher package in which the author holds the copyright is made available under the GNU General Public License (GPL). A copy of the GPL is included in the file `COPYING.txt` included with jEdit.

Notwithstanding the terms of the General Public License, the author grants permission to compile and link object code generated by the compilation of this program with object code and libraries that are not subject to the GNU General Public License, provided that the executable output of such compilation shall be distributed with source code on substantially the same basis as the jEditLauncher package of which this source code and software is a part. By way of example, a distribution would satisfy this condition if it included a working Makefile for any freely available make utility that runs on the Windows family of operating systems. This condition does not require a licensee of this software to distribute any proprietary software (including header files and libraries) that is licensed under terms prohibiting or limiting redistribution to third parties.

The purpose of this specific permission is to allow a user to link files contained or generated by the source code with library and other files licensed to the user by Microsoft or other parties, whether or not that license conforms to the requirements of the GPL. This permission should not be construed to expand the terms of any license for any source code or other materials used in the creation of jEditLauncher.