Overview

Package

Class

Use

Tree

Serialized

Deprecated

Index

Help

SWT LPEX
v3.0.0

PREV PACKAGE NEXT PACKAGE

FRAMES NO FRAMES

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.
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.
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.
LpexViewListener	Listener to document view events.

Class Summary

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 critical LPEX errors.
LpexMatch	Match parentheses, braces, square brackets, angle brackets.
LpexMultiWindow	The split-window parent of one or more LpexWindows.
LpexNls	This class provides national language support (NLS) functions.
LpexPaletteAttributes	Class LpexPaletteAttributes 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 code-performance measurements.
LpexUtilities	This class implements utilities which resolve differences between supported development platforms and/or operating systems.
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.

Exception Summary

LpexView.ViewInstantiationException

Indicates a failed attempt to create a new 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. An application's main responsibility 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 programatically with, for example, the doCommand() method.

Example user-defined commands are provided in the samples package.

Editor actions

LPEX also has 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. 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.

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 programatically 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.

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.

National-language 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 - document has been renamed
  • readonly - an attempt has been made to edit a readonly 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 calls are sufficient for most editor applications; the 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

• LpexDocumentSectionListener - notifications for the specialized management of document sections:
  • addLines - the currently-loaded document section must be extended

• LpexKeyListener (SWT LPEX only) - a key listener able to consume LPEX's keys
• LpexParser - a document parser is called for incremental parsing after changes to the document.

Debugging

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

The command line can be used 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.

Two parameters are available solely for development and debugging purposes. These parameters should be used with caution. Due to their specific nature, these debug 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). Another 'property' accessible through this parameter is _locale, which may be used to query the default locale. 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

This parameter can be used 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 } 

Examples

query traceKeys
set traceKeys on