This package provides the base implementation of the LPEX editor widget.

Whenever possible, function has been implemented in the base editor rather than making it the responsibility of the application writer.  The main responsibility of an application is to provide document open and close functions, and keep track of the list of open documents.

Two main classes are used to program LPEX.  The first, {@link com.ibm.lpex.core.LpexView}, is a view on a document.  Documents are not instantiated directly - the first LpexView created by the application also creates the document.  Additional LpexView objects may then be created to operate on the same document.

The second class, {@link com.ibm.lpex.core.LpexWindow}, is a Swing JComponent in AWT LPEX, and an SWT Composite in SWT LPEX.  It contains a text edit area with scroll bars (visible when necessary), a status line, a message line, and a multipurpose command line.  The application is responsible for associating an LpexView object with an LpexWindow.  Until an LpexView object is associated with the LpexWindow object, the LpexWindow is an empty, unusable window.  The application may switch the LpexView object that is displayed in the LpexWindow to allow the user to edit multiple documents in the same window.

Editor commands

LPEX is programmable through an extensive set of commands and parameters.  Editor commands and parameters can be used to customize the editor window, search for, change, and sort text in the document, and perform many other functions.

In addition to the editor's built-in commands, user-defined commands can be created to extend or override the command language, by implementing the {@link com.ibm.lpex.core.LpexCommand} interface.  In order for the editor to recognize the new command, you can

Commands can be entered from the LPEX command line, or they can be called programmatically with, for example, the {@link com.ibm.lpex.core.LpexView#doCommand(java.lang.String) doCommand()} method.

Example user-defined commands are provided in the {@link com.ibm.lpex.samples samples} package.

Editor actions

LPEX features a large set of edit actions which may be assigned to keys, series of keys, mouse events, or pop-up menu items.  Application writers may assign actions to toolbar items and pull-down menu items.  Unlike commands, actions do not accept parameters and have an availability state associated with them.  The availability state determines, for example, whether a menu item associated with an action will be enabled or not (grayed out).

In addition to the editor's built-in actions, user-defined actions can be created to override or extend the action set, by implementing the {@link com.ibm.lpex.core.LpexAction} interface.  A base abstract implementation of this interface, {@link com.ibm.lpex.core.LpexBaseAction}, provides several additional features (context help / tool tip text, check marks for associated menu items).

In order for the editor to recognize the new action, you can

In general,

User-defined actions can be used in the same manner as built-in actions.  An action is run when the key, mouse event, menu item, or toolbar item that it is associated with is selected.  Actions can also be run with the action command.  Actions are run programmatically with, for example, the {@link com.ibm.lpex.core.LpexView#doAction(int) doAction()} method.

Example user-defined actions, and an example user profile which defines several actions, are provided in the {@link com.ibm.lpex.samples samples} package.

Editor parameters

Editor parameters cannot be overridden in the same manner that the default editor commands and actions can.  You can, however, define new editor parameters, which allow you to associate various settings with the editor, at different scope levels, in a manner similar to the built-in editor parameters.  Refer to the userParameter editor parameter for additional information.

You may also associate various properties, at different scope levels, with document parsers.

User profile

A user can customize editing settings in a user profile.  The user profile is run during the processing of the updateProfile command.  The updateProfile command is normally run when a document view is created, and it may be issued at any time to allow the document view to reflect changes to the profile.

An example user profile {@link com.ibm.lpex.samples.TestUserProfile} is available in the {@link com.ibm.lpex.samples samples} package.

Document parsers

Document parsers are classes that implement the {@link com.ibm.lpex.core.LpexParser} interface.  Each document view may have an instance of a parser class associated with it.  The parser is responsible for providing the language specific characteristics of the edit session.  For example, the {@link com.ibm.lpex.java.JavaParser} tokenizes the text of a Java source file; colorizes comments, keywords, and operators; flags several lexical errors; recognizes classes and method headers for code folding purposes; and defines several keywords for template expansion.

{@link com.ibm.lpex.core.LpexCommonParser}, an abstract class for document parsers, adds several services to the LpexParser interface, simplifying parser development, and provides methods for a common look-and-feel to the parsers extending it.  All the parsers shipping with LPEX extend LpexCommonParser.

An example of developing a simple document parser is available in the {@link com.ibm.lpex.samples samples} package:  see {@link com.ibm.lpex.samples.TestParser1} and {@link com.ibm.lpex.samples.TestParser2}.

Multicultural support

See the {@link com.ibm.lpex.core.LpexNls} class for details.

Customization

Customization of the edit widget in an LPEX-based editor is performed by changing the settings of the updateProfile command.

Listeners

These listeners are available:

Debugging

Certain LPEX features are also useful during the development of editor applications and extensions, and in the diagnosing of problems.

You can use the command line to query and set all the available editor parameters, and to run all the built-in and user-defined commands and actions.  The parameters include, for example, the element classes and styles that have been set by a document parser.

The editor logging facility records uncaught exceptions thrown by user-defined commands, actions, user profiles, document parsers, and certain listeners.  See the editorLog parameter.

Some parameters are available solely for development and debugging purposes.  Use them with caution.  Due to their specific and experimental nature, these parameters are only documented here.

systemProperty parameter

This parameter provides access to the java.lang.System properties (for example, java.home, os.name, user.dir, and any -D Java invocation setting).  Other 'properties' accessible through this parameter: _locale, to query the default locale; _env, to query an environment variable; _memory [gc] to query the JVM memory status or ask to run the garbage collector.

Please note that modifying any system property may not be effective, as LPEX has already initialized, its properties files for the active locale have been loaded, etc.  Moreover, modifying a system property using this command may adversely affect other classes running in the same Java virtual machine.

Scope

Global.

Syntax

query systemProperty.property
set systemProperty.property 

Examples

query systemProperty.java.home
query systemProperty._locale 

traceKeys parameter

Use this parameter to display key-event information on the message line.  Key-release events are not traced.  Regular message display is suspended when this setting is in effect. This parameter may be useful, for example, in determining which key events are not received by the LPEX widget from the enclosing application or running platform.

Scope

The current view.

Syntax

query traceKeys
set traceKeys { on | off } 

traceMouseEvents parameter

Use this parameter to display mouse-event information on the message line.  Regular message display is suspended when this setting is in effect.

Scope

The current view.

Syntax

query traceMouseEVents
set traceMouseEvents { on | off }