PageRenderTime 44ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

/jEdit/tags/jedit-4-0-pre3/doc/users-guide/launcher-guide.xml

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