Package com.ibm.lpex.core

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

See:
Description

Interface Summary

LpexAction	Interface LpexAction can be implemented to define a user action.
LpexActionConstants	Editor action constants.
LpexActiveWindowListener	Implement this interface to listen to changes in the active window of an LpexMultiWindow.
LpexCommand	Interface LpexCommand can be implemented to define a user command.
LpexConstants	Editor constants.
LpexCursorListener	Interface LpexCursorListener can be implemented to listen to cursor (caret) events in the edit window of a document view.
LpexDocumentListener	Interface LpexDocumentListener can be implemented to listen to text changes and adjustments in the document.
LpexDocumentSectionListener	Interface LpexDocumentSectionListener can be implemented to manage the document section currently loaded in the editor.
LpexFieldsProvider	Interface LpexFieldsProvider defines a provider of field settings for the text elements in a document view.
LpexKeyListener	Key listener on the Eclipse Platform, able to consume LPEX's keys.
LpexMarkListener	Interface LpexMarkListener can be implemented to listen to mark events.
LpexMessageConstants	Editor message constants.
LpexParameters	Editor parameter constants.
LpexParser	Interface LpexParser can be implemented to define a document parser.
LpexPreferencesConstants	Editor constants related to the preference pages.
LpexSubparser	Interface for document subparsers.
LpexViewListener	Listener to document view events.
ProfileHandler	Interface ProfileHandler can be implemented to define a handler for the LPEX defaults profile (persistent user settings).
StatusLineListener	Interface StatusLineListener can be implemented to listen to changes in the status line information of an LPEX window.

Class Summary

COPYRIGHT
LpexBaseAction	Base implementation of an LPEX action.
LpexCharStream	A stream interface for LPEX document parsers.
LpexCommonParser	LpexCommonParser is a base, abstract class for document parsers.
LpexDocumentLocation	This class is used to represent a location in a document (or in the document section that is currently loaded in the editor).
LpexLog	Facility to log LPEX messages and critical errors.
LpexMatch	Matches parentheses, braces, square brackets, angle brackets.
LpexMultiWindow	The split-window parent of one or more LpexWindows.
LpexNls	This class provides several multicultural support functions.
LpexPaletteAttributes	This class provides a mechanism for converting style attributes to a specified palette.
LpexResources	This class can be used to access a resource file of the editor.
LpexStringTokenizer	The string tokenizer class allows an application to break a string into tokens.
LpexTime	This class facilitates elementary code-performance measurements.
LpexUtilities	This class implements various utilities which have dependency on a particular development platform and/or operating system.
LpexView	Use this class to manage an LPEX document view.
LpexViewAdapter	Abstract adapter class for receiving document view event notifications.
LpexWindow	This class manages an LPEX window.
TextWindowDropTargetEffect	This class extends SWT's DropTargetEffect (which provides no visual feedback) for TextWindow.
Utilities	Various LPEX internal-use (non-API) utilities.

Exception Summary

LpexView.ViewInstantiationException

Indicates a failed attempt to create a new document view.

Package com.ibm.lpex.core Description

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, 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, 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 LpexCommand interface. In order for the editor to recognize the new command, you can

• create an instance of the command and call defineCommand(), or
• use the set commandClass command, or
• use the set updateProfile.userCommands command.

Commands can be entered from the LPEX command line, or they can be called programmatically with, for example, the doCommand() method.

Example user-defined commands are provided in the 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 LpexAction interface. A base abstract implementation of this interface, 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

• create an instance of the action and call defineAction(), or
• use the set actionClass command, or
• use the set updateProfile.userActions command.

In general,

• you should redefine default editor actions that must use specific services in your editor application, such as save and help
• when you simply want to offer an alternative behavior, you should define a new action, and associate it with the relevant key. This way, the user can choose to restore the original behavior on their system.

  LPEX-shipped document parsers do not associate actions to any keys which have already been assigned elsewhere. At the least, a parser should not reassign keys that are defined in the current.updateProfile.userKeyActions setting, that is, keys that the user most probably (re)defined through a preference page.

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 doAction() method.

Example user-defined actions, and an example user profile which defines several actions, are provided in the 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 TestUserProfile is available in the samples package.

Document parsers

Document parsers are classes that implement the 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 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.

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 samples package: see TestParser1 and TestParser2.

Multicultural support

See the 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:

• LpexViewListener (see also LpexViewAdapter) - notifications are sent for these view events:
  • showing - the screen is about to be displayed (refreshed)
  • shown - screen display (refresh) is complete
  • saving - the document is about to be saved (the listener can cancel the operation)
  • saved - document has been saved
  • renaming - the document is about to be renamed (the listener can cancel the operation)
  • renamed - the document name, source name, or view id has changed
  • readonly - an attempt has been made to edit a read-only document
  • updateProfile - the updateProfile command has completed
  • disposed - the document view is disposed
• LpexMarkListener - notifications are sent for these mark events:
  • markChanged - the text associated with a mark has been changed
  • markDeleted - all the text associated with a mark has been deleted
• LpexCursorListener:
  • elementChanged - the cursor has been positioned on a new element
• LpexDocumentListener - in general, the document parser incremental-parse callbacks (also available through extending the default parse editor command) are sufficient for most editor applications; the significant performance overhead of creating this specialized listener's notifications should be taken into consideration before using it:
  • documentChanged - a text change occurring in the document
• LpexCommonParser - a document parser (see also the parse editor command) is called for incremental parsing after changes to the document:
  • parseElement - parse change(s) to the document
• LpexCommonParser - a document parser is notified of changes to any of its properties:
  • propertySet - a parser property was set in the scope of this parser instance
• LpexDocumentSectionListener - notifications for the specialized management of document sections:
  • addLines - the currently-loaded document section must be extended.

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 }