jEditLauncher 3.2.2 installation and use guide

John Gellene

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections", "Front-Cover Texts" or "Back-Cover Texts", each as defined in the license. A copy of the license is included in the file COPYING.DOC.txt included with jEditLauncher.

Revision History
Revision 1.0 May 5, 2001  
Revision 3.1 May 29, 2001  
Revision 3.2 July 18, 2001  
Revision 3.2, release 2 July 30, 2001  
Revision 3.2, release 3 August 4, 2001  
Revision 3.2 final August 28, 2001  
Revision 3.2.1 September 1, 2001  
Revision 3.2.2 December 29, 2001  

Introduction

This is an installation and use guide for jEditLauncher - a set of lightweight components for using the jEdit text editor with the Windows group of operating systems. The jEditLauncher package is designed to run on Windows 95, Windows 98, Windows ME, Windows NT (versions 3.51 and greater), Windows 2000 and Windows XP. This version is designed to work with jEdit versions beginning with 3.2 (including the development versions in the 4.0 series). It will not work with earlier versions.

How it works

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 same directory as other jEdit files containing user settings. The jEditLauncher components locate and read this file, open a socket and attempt to connect to the indicated port. If successful, jEditLauncher 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.

Version 3.2.2 and 4.0 of jEdit use different protocols for accepting data. The jEditLauncher module will automtically detect which protocol is required.

Files in the jEditLauncher package

The jEditLauncher package consists of the following files:

  • jeshlstb.dll - an extension for the Windows shell that provides a context menu handler for jEdit

  • jeditsvr.exe - a COM server that sends request to open files and run scripts to jEdit

  • jeservps.dll - a COM "proxy/stub" component that marshals multiple data request across process boundaries to the COM component

  • jedit.exe - an application for launching jEdit and loading files

  • jedinit.exe - a utility program for setting jEdit's command line parameters using a dialog interface

  • jedinstl.dll - a executable file containing the install and uninstall routines for the package

  • unlaunch.exe - a utility program that uninstalls jEditLauncher and jEdit

  • ltslog.dll - a executable file that provides logging capability for other components in the jEditLauncher package

The COM component

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). A low-level interface for client code in previous version has been removed in favor of a server that marshall data across process boundaries.

The jEditLauncher interface

The jEditLauncher interface is set forth in the definition of the abstract C++ class IJEditLauncher. It is a "interface" or pure abstract class derived from the IDispatch interface used for components that can be addressed using Microsoft's "Automation" technology. The "IJEditLauncher" interface has two parts: a scriptable interface tied to IDispatch, and a "direct client" interface with methods that use primitive data types.

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 a 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 BeanSAhell 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 VBSscript 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")

The context menu handler

The COM component 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 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.

jedit.exe - a utility for launching jEdit

Another component of the jEditLauncher package is a client application entitled jedit.exe. It may be executed either from the command line or the graphical shell. It uses the jEditLauncher COM component to open files in jEdit that are listed as command line parameters. Like the component, 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 and has an active EditServer, it will simply open a new, empty buffer.

From the command line, jedit.exe has four command-line options. If any option is 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.

    Using the dialog, you can change parameters specifying the executable for the Java interpreter, the jar archive file or class name used as the target of the interpreter, and command line options for both. If the -jar option is not used for the Java executable, 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 EditServer and make it impossible for jEditLauncher to open files.

  • 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 jedit.exe with the/p option.

  • The option /u will cause jEditLauncher to be uninstalled by removing its registration entries. This option currently does not delete any jEditLauncher or jEdit files. To perform a full uninstall, run the unlaunch.exe utility.

jedinit - a utility for setting jEdit parameters

The jEditLauncher package includes jedinit.exe as a shortcut to the dialog interface used by jedit.exe to set command line parameters. This allows you to set parameters directly from the Windows shell without having to enter jedit /p from a command line. Its only operating requirement is that it is located in the same directory as jedit.exe.

unlaunch - a utility for uninstalling jEdit

The final standalone executable in the jEditLauncher package is unlaunch.exe. Running this file will uninstall jEditLauncher and jEdit from the directory in which jereomve is located. Since the Java installer that does the bulk of jEdit's installation does not keep a record of files to be deleted, the uninstall routine takes the approach of deleting all files in the installation directory after obtaining confirmation of a request to uninstall.

If you wish to save files in the the installation directory or any of its subdirectories, you should move them to another location before running jeremove.

Installation

To install jEditLauncher following a successful install of jEdit, the following files should be placed in the same directory as jedit.jar, the archive containing the Java application:

  • jedit.exe

  • jedinit.exe

  • jeshlstb.dll

  • jedinstl.dll

  • jeditsvr.exe

  • jeservps.dll

  • unlaunch.exe

  • ltslog.dll

Whenever jedit.exe is executed (either directly or indirectly through a call to jedinit.exe), jEditLauncher checks to see if it is properly installed. If it is not, it will offer to install itself. If you agree, you will then be asked to supply the path to a Java application loader. The directory you choose should contain javaw.exe, which the installer uses as a default; you can change the application loader later with a call to jedinit.exe.

Shortcuts

The jEditLauncher installation routine creates shortcuts for the "primary" version of jEdit on the Windows desktop, in the Start menu and in the Programs menu. Any of these may be deleted manually without compromising the performance of jEdit or jEditLauncher.

Logging

Time-stamped logging of application events is currently provided for the installation routine and for direct calls to jedit.exe. Installation logging data are written to install.log, and log entries for jedit.exe and the launcher component, jeditsrv.exe, are written to jelaunch.log. Both files are located in the directory in which jEdit and jEditLauncher are installed.

To assist with debugging and other troubleshooting, log entries are cumulative and the log files are not deleted each time the logging facility is activated. The log files themeselves may be deleted manually without impairing performance.

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 in 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 anpother, 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 serach path. This will remove the entries for jEditLauncher from the Windows registry, and 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.

Acknowledgements

The original edit server client code in jEditLauncher borrowed liberally from the jEditOpener application written by Joe Laffey and Stefan Radig. It has been replaced with code from the Win32 SDK. The Perl scripting example in this guide is adapted from code written by Hans-Joachim Wüllner. The author is grateful to those who tested and provided feedback on earlier versions, especially Joe Polanik.

Source Code

Source code for jEditLauncher is made available separately from the package itself. As one might expect, the source code for the package relies heavily on template classes and headers for COM objects that are supplied with Microsoft's Visual C++ 6.0 product. Because of licensing restrictions, those files are not part of the source code distribution. The executables were compiled using the Microsoft Visual Studio 6.0 IDE. Makefiles generated by the IDE are included, They are written for Microsoft's NMAKE utility and are not compatible with POSIX make syntax.

The source code distribution should be sufficient to allow for compilation of jEditLauncher's four executables file in the Visual Studio IDE. Besides the source for the four executable files, the distribution includes code for a utility for testing the installation module.

If you are interested in building jEditLauncher from its source code, you should first examine the IDE settings for "Custom Build" to enable or disable (as you choose) automatic registration of the COM component following compilation. The project files will not register the COM component as a context menu handler. You should also modify the directory settings to conform to your own file layout.

The executables included with this distribution are the "ReleaseMinDependency" build of the COM component and the "Release" build of the other executables.

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.

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the author or any other contributor be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use of or other dealings in the software.

Permission is granted to copy, distribute and/or modify this guide under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections", "Front-Cover Texts" or "Back-Cover Texts", each as defined in the license. A copy of the license is included in the file COPYING.DOC.txt included with jEdit.

History

  • version 4.0

    • Introduced logging for launcher module.

    • Revised installation module to accommodate new version and import prior version's settings.

    • Added binary protocol for jEdit 4.0pre4 EditServer; launcher remains backwards compatible with earlier versions.

  • version 3.2.2

    • Fixed bug that failed to write "Working Directory" registry entry.

    • Added logging capability in separate executable module.

    • Modified label text in parameter setting dialog.

    • Documentation ported from DocBook SGML to DocBook XML.

  • version 3.2.1

    • Changed default parameters for command line to run Java interpreter with -jar option.

  • version 3.2 final

    • Reversed execution flag in unlaunch.exe to fix bug.

    • Fixed bug that prevented zero-length files from being loaded by launcher.exe under Windows NT (workaround for bug in IShellLink::Resolve()).

    • Added dialog to installation module to allow users to retain command line parameters from existing version.

  • version 3.2, release 3

    • Added unlaunch.exe to package and redirected uninstall shortcuts to this file.

    • Fixed bug in script writing engine to conform to new EditServer.handleClient() API in jEdit3.2pre7.

  • version 3.2, release 2

    • Replaced in-process COM server with out-of-process server running in its own process to queue file and script requests and remove duplicate requests to launch jEdit

    • Separated context menu handler from other components; this memory-resident component need not be replaced in subsequent installations.

    • Fixed bug in script writer code causing access exceptions when selecting files without extensions.

    • Fixed bug in installer code calling Windows SDK function not available to all Windows versions.

  • version 3.2

    • Replaced routine for sending data to EditServer with classes encapsulating socket connection and script writing functions.

    • Added custom waitable timer to allow desktop repaint while jEdit is loading.

    • Added RunScript(), EvalScript() and RunDiff API.

    • Miscellaneous bug fixes in installer routine.

    • Disabled full uninstallation routine pending integration with jEdit.

  • version 3.1

    • Changed versioning to conform to current jEdit version.

    • Modified COM component to expand wild-card characters when [jEdit.jEditLauncher].OpenFiles() is called or when jedit.exe is called with multiple arguments.

    • Added custom install/uninstall facility integrated with jEdit Java installer, permitting multiple installations of different versions of jEdit and user selection of "primary" version for purposes of context menu handler, scripting and shell shortcuts.

    • Revised documentation to describe new features.

  • version 1.0

    • Added dialog interface for setting command line parameters.

    • Added automatic registration of COM component and uninstall utility.

    • Change persistence routine to store and retreive jEdit parameters in the Windows registry.

    • Added automatic recognition of location of edit server information file generated by jEdit.

    • Added additional error reporting.

    • Revised documentation and ported primary format to DocBook.

  • version 1.0beta3

    • Removed numerous calls to 32-bit functions to enable operation on Windows 95/98/Me.

    • Revised registration/unregistration routine to include context menu handler; uninstal.vbs eliminated as unnecessary.

    • Added JEDIT_SERVER_FILE to install script; script now reads existing environment variables and displays them as default values.

    • Expanded readme file.

    • Added express license terms to prinicpal source code files.

  • version 1.0beta2

    • Removed calls to WinNT/2000 specific functions in Launch_jEdit().

    • Revised menu code to use IContextMenu interface only, so that users with shell32.dll versions below 4.71 could have a fully functioning context menu handler.

    • Revised environment variables to conform more closely with variable used by jEditOpener.

    • Revised jeditme client to launch jEdit when called without parameters; it now also displays the jEdit icon.

    • Revised example scripts.

  • version1.0beta1

    • Initial development release.

Feedback

Comments, bug reports and requests for enhancements are most welcome. They may be emailed to the author or posted to the jedit-users mailing list. The mailing list is the preferred destination because it allows other users and developers to read and respond to comments. Information about the mailing list may be obtained from the jEdit web site.