LpexView (LPEX API Reference)

Overview

Package

Class

Tree

Serialized

Deprecated

Index

Help

LPEX
4.4.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ibm.lpex.core
Class LpexView

java.lang.Object
  com.ibm.lpex.core.LpexView

public class LpexView
extends Object
extends Object

Use this class to manage an LPEX document view. It essentially provides all the editor widget programming support.

Creating an instance of this class creates a document view. When you are just extending an existing LPEX-based application, view management (creation, disposal) is usually that application's responsibility.

Lines and elements

The LPEX document maintains a list of elements. An element in this list constitutes any line of textual information that may be displayed in the edit area of a view of the document. Elements are:

text elements (lines) - each text element represents one line (or record) in the actual document (and its underlying file). The current line number is displayed on the LPEX status line
show elements - show elements are typically used by document parsers and their associated tools to present informational and error messages. They may also be used, for instance, to embed the (read only) contents of include (copy) files into the main document. During a compare session, lines deleted from the current document are displayed as embedded show lines.
Each show element in the document's list of elements is created for, and belongs exclusively to, one particular view. Show elements are not saved with the document.

Most methods that access the document contents use as argument an element ordinal number. The ordinal numbers of elements change as elements are being inserted and removed, as a result of, for example, the user editing the document and parsers adding and removing error messages.

In general, a document parser skips and ignores show elements:

 
 if (view.show(elementNumber))
  {
   // embedded message - skip it 
  }
 else
  {
   // text line - parse it
   // . . .
  }

LpexCharStream also ignores show elements, and does not send them to the token manager.

During the processing of one parse unit (i.e., during one total-parse or one incremental-parse call from LpexCommonParser), requests to addMessage(), removeMessages(), addDocumentMessage(), and removeDocumentMessages() are stacked, and only processed afterwards. In other words, during one such call, the parser will see the same element numbers throughout the document - the messages will only be added and removed by LpexCommonParser when the parser returns.

In view of the above, a parser should not concern itself with changes in element numbers during a parse operation. If, however, your parser keeps (caches) information across parse calls from LpexCommonParser, you may consider keeping it in term of lines rather than elements. To determine the document line number of a text element, you can use lineOfElement(). Marks may also be set to tag particular elements for this purpose (see the mark editor parameter).

If your code itself inserts a series of show lines (for example, compiler error messages) in a view, outside a parsing operation, the easiest way to do it is starting from the last (i.e., from the highest element number), and proceeding towards the first (lowest element number).

See Also:: LpexWindow

Nested Class Summary
`static class`	`LpexView.ViewInstantiationException` Indicates a failed attempt to create a new document view.

Constructor Summary
`LpexView()` Use this constructor to create an untitled document.
`LpexView(boolean updateProfile)` Use this constructor to create an untitled document, indicating whether the updateProfile command should be called.
`LpexView(LpexView lpexView)` Use this constructor to create a new document view from the specified document view.
`LpexView(LpexView lpexView, boolean updateProfile)` Use this constructor to create a new document view from the specified document view, indicating whether the updateProfile command should be called.
`LpexView(String fileName)` Use this constructor to create a document from the specified file name.
`LpexView(String fileName, boolean updateProfile)` Use this constructor to create a document from the specified file name, indicating whether the updateProfile command should be called.
`LpexView(String fileName, String fileEncoding, boolean updateProfile)` Use this constructor to create a document from the given file name, specifying its character encoding and indicating whether the updateProfile command should be called.

Method Summary
`LpexAction`	`action(String actionName)` Returns the specified user-defined editor action.
`boolean`	`actionAvailable(int actionId)` Returns whether the specified action is available.
`boolean`	`actionChecked(int actionId)` Returns whether the specified action has a checked status.
`int`	`actionId(String actionName)` Returns the id of the specified default or user-defined editor action.
`String`	`actionKey(int actionId)` Returns the primary key associated with the specified action.
`String`	`actionKeyText(int actionId)` Returns a translated text version of the primary key for the specified action.
`void`	`addLpexCursorListener(LpexCursorListener cursorListener)` Adds a cursor listener to this document view.
`void`	`addLpexDocumentAdjustListener(LpexDocumentListener documentAdjustListener)` Adds a document-adjust listener to the editor document of this view.
`void`	`addLpexDocumentListener(LpexDocumentListener documentListener)` Adds a document listener to the editor document of this view.
`void`	`addLpexDocumentSectionListener(LpexDocumentSectionListener sectionListener)` Adds a document-section listener to the editor document of this view.
`void`	`addLpexKeyListener(LpexKeyListener keyListener)` Adds an LPEX key listener to this document view.
`void`	`addLpexMarkListener(int markId, LpexMarkListener markListener)` Adds a mark listener to the specified mark.
`void`	`addLpexViewListener(LpexViewListener viewListener)` Adds a view listener to this document view.
`int`	`charOffset(LpexDocumentLocation documentLocation, int eolLength)` Returns a document (or document section) location's Unicode-character offset in its underlying file (section).
`long`	`classMask(String classNames)` Returns the bit-mask allocated in this view for the registered element class(es) named.
`LpexCommand`	`command(String commandName)` Returns the specified user-defined command.
`int`	`currentElement()` Returns the ordinal number of the current (cursor) element in the document (or section of the document that is currently loaded in the editor).
`int`	`currentPosition()` Convenience method to retrieve the current (cursor) position within the current (cursor) element.
`boolean`	`defaultActionAvailable(int actionId)` Checks whether the specified default editor action is available.
`LpexAction`	`defineAction(String actionName, LpexAction lpexAction)` Defines a user action.
`LpexCommand`	`defineCommand(String commandName, LpexCommand lpexCommand)` Defines a user command.
`String`	`deletedMarkName(int markId)` Returns the name of the deleted mark with the id specified.
`void`	`dispose()` This method disposes the document view.
`void`	`doAction(int actionId)` Runs the specified action.
`boolean`	`doCommand(LpexDocumentLocation documentLocation, String commandString)` Runs the specified command at the specified document (or document section) location.
`boolean`	`doCommand(String commandString)` Runs the specified command.
`LpexDocumentLocation`	`documentLocation()` Returns the view's current (cursor) location in the document (or section of the document that is currently loaded in the editor).
`LpexDocumentLocation`	`documentLocation(int charOffset, int eolLength)` Returns the location in the document (or section of the document that is currently loaded in the editor) which corresponds to the given Unicode-character offset in its underlying file (section).
`void`	`doDefaultAction(int actionId)` Runs the default editor action for the specified action id.
`boolean`	`doDefaultCommand(LpexDocumentLocation documentLocation, String commandString)` Runs the specified default editor command.
`boolean`	`doDefaultCommand(String commandString)` Runs the specified default editor command.
`static boolean`	`doGlobalCommand(String commandString)` Runs the specified default editor global command.
`long`	`elementClasses(int element)` Returns the bit-mask of the element classes set in an element of the document (or document section that is currently loaded in the editor).
`String`	`elementFullText(int element)` Returns the full text (i.e., including the sequence numbers, if set) of an element in the document (or document section currently loaded in the editor).
`int`	`elementOfLine(int line)` Returns the element for the specified line.
`int`	`elementOfRow(int row)` Returns the element in the document (or that section of the document that is currently loaded in the editor) which is displayed on the given screen row.
`void`	`elementParsed(int element)` Removes the specified element from the parse-pending list of this document view.
`int`	`elements()` Returns the number of elements in the document (or section of the document that is currently loaded in the editor).
`String`	`elementStyle(int element)` Returns the style string for an element in the document (or document section currently loaded in the editor).
`String`	`elementText(int element)` Returns the text of an element in the document (or document section currently loaded in the editor).
`static void`	`extendInstallProfile(Properties extension)` Extends the editor install profile.
`LpexView`	`getBlockView()` Returns the view with the selection, if any, in this view's block instance.
`org.eclipse.swt.graphics.Font`	`getFont()` Returns the font in this view.
`static String`	`getLpexHelpPage(String lpexItem)` Returns the default HTML help panel for the editor item specified.
`LpexView[]`	`getLpexViews()` Returns an array of the views currently open on this view's document.
`static String`	`globalQuery(String parameter)` Queries a global editor parameter.
`boolean`	`isDisposed()` Returns whether the document view has been disposed.
`void`	`jump(int element, int position)` Moves the cursor to the specified position in the document (or section of the document that is currently loaded in the editor).
`void`	`jump(LpexDocumentLocation documentLocation)` Moves the cursor to the specified position in the document (or section of the document that is currently loaded in the editor).
`boolean`	`keyAssigned(String keyString)` Checks whether the specified key is associated with an action.
`static String`	`keyText(String keyString)` Returns a translated text version of a key definition.
`String`	`lineFullText(int line)` Returns the full text (i.e., including the sequence numbers, if set) of a line in the document (or document section currently loaded in the editor).
`int`	`lineOfElement(int element)` Returns the line for the specified element.
`int`	`linesAfterEnd()` Returns the number of lines in the document following the currently-loaded document section.
`int`	`linesBeforeStart()` Returns the number of lines in the document prior to the currently-loaded document section.
`boolean`	`load(Reader reader)` Loads the entire text of the document (or document section) from the specified Reader.
`LpexView`	`lpexView(String documentName)` Returns a view handling the given document, if any.
`LpexNls`	`nls()` Returns the LpexNls object associated with this LpexView.
`int`	`parsePending(int element)` Returns the parse-pending state of the specified element.
`LpexParser`	`parser()` Returns the current document parser for this view.
`String`	`query(String parameter)` Queries an editor parameter.
`String`	`query(String parameter, LpexDocumentLocation documentLocation)` Queries an editor parameter.
`int`	`queryInt(String parameter)` Convenience method to query an editor integer parameter.
`int`	`queryInt(String parameter, LpexDocumentLocation documentLocation)` Convenience method to query an editor integer parameter.
`boolean`	`queryOn(String parameter)` Convenience method to query an editor on/off parameter.
`boolean`	`queryOn(String parameter, LpexDocumentLocation documentLocation)` Convenience method to query an editor on/off parameter.
`long`	`registerClass(String className)` Registers the specified element class in this view.
`void`	`removeLpexCursorListener(LpexCursorListener cursorListener)` Removes a cursor listener from this document view.
`void`	`removeLpexDocumentAdjustListener(LpexDocumentListener documentAdjustListener)` Removes a document-adjust listener from the editor document of this view.
`void`	`removeLpexDocumentListener(LpexDocumentListener documentListener)` Removes a document listener from the editor document of this view.
`void`	`removeLpexDocumentSectionListener(LpexDocumentSectionListener sectionListener)` Removes a document-section listener from the editor document of this view.
`void`	`removeLpexKeyListener(LpexKeyListener keyListener)` Removes the specified LPEX key listener from this document view.
`void`	`removeLpexMarkListener(int markId, LpexMarkListener markListener)` Removes a mark listener from the specified mark.
`void`	`removeLpexMarkListener(LpexMarkListener markListener)` Removes a mark listener from all the marks in this document view for which it is registered.
`void`	`removeLpexViewListener(LpexViewListener viewListener)` Removes a view listener from this document view.
`boolean`	`save(Writer writer)` Saves the entire text of the document (or document section currently loaded in the editor) to the specified Writer.
`void`	`setBaseEncoding(String fileEncoding)`
`void`	`setBlockInstance(LpexView lpexView)` Sets the block instance of this view.
`static void`	`setClassLoader(ClassLoader classLoader)` Sets an alternative class loader to be used by the editor.
`void`	`setElementClasses(int element, long classes)` Sets the element classes bit-mask in an element of the document (or document section that is currently loaded in the editor).
`void`	`setElementStyle(int element, String style)` Sets the style string for an element in the document (or section of the document that is currently loaded in the editor).
`void`	`setElementText(int element, String text)` Sets the text for an element in the document (or document section that is currently loaded in the editor).
`void`	`setFieldsProvider(LpexFieldsProvider fieldsProvider)` Sets or removes a fields-setting provider for the text elements in this document view.
`void`	`setFont(org.eclipse.swt.graphics.Font swtFont)` Sets a new font in this view.
`boolean`	`setLinesOutsideDocumentSection(int linesBeforeStart, int linesAfterEnd)` Sets the number of lines in the complete document that are outside the boundaries of the currently-loaded document section.
`void`	`setOwnerDrawMargin(boolean ownerDraw)` Sets whether the prefix-area margin of this view is being painted by an editor extension.
`void`	`setParserOverrideName(String name)` Sets the name of the parser to be used instead of the associated parser.
`void`	`setSaveWriter(Writer writer)` Sets the `Writer` object for the saveToWriter action.
`void`	`setText(String text)` Sets the entire text of the document (or document section).
`void`	`setWindow(LpexWindow lpexWindow)` Use this method to associate an LPEX window with this document view.
`boolean`	`show(int element)` Returns the show setting for an element in the document (or document section that is currently loaded in the editor).
`String`	`text()` Returns the entire text of the document (or document section currently loaded in the editor).
`void`	`triggerAction(int actionId)` Runs the specified action.
`void`	`triggerAction(int actionId, boolean record)` Runs the specified action and optionally records it if keystroke recording is in progress.
`boolean`	`viewShow(int element)` Returns whether the specified element in the document (or document section that is currently loaded in the editor) is a show element for this document view.
`LpexWindow`	`window()` Returns the LPEX window currently associated with this view.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

LpexView

public LpexView(String fileName,
                String fileEncoding,
                boolean updateProfile)

Use this constructor to create a document from the given file name, specifying its character encoding and indicating whether the updateProfile command should be called.

If you specify null for fileEncoding, the native (platform's default) encoding will be used. If you specify an empty String (""), the editor will attempt to detect the file encoding, and will default to the native encoding if unsuccessful.

If you specify true for updateProfile, then the updateProfile command will be called with the default settings. If you specify false, then updateProfile will not be called; you can then change updateProfile. settings and issue the updateProfile command later.

LpexView

public LpexView(String fileName,
                boolean updateProfile)

Use this constructor to create a document from the specified file name, indicating whether the updateProfile command should be called. The file's character encoding is assumed to be the native (platform's default) encoding.

If you specify true for updateProfile, then the updateProfile command will be called with the default settings. If you specify false, then updateProfile will not be called; you can then change the updateProfile settings and issue the updateProfile command later.

LpexView

public LpexView(String fileName)

Use this constructor to create a document from the specified file name. The file's character encoding is assumed to be the native (platform's default) encoding.

The updateProfile command will be called, with the default settings.

LpexView

public LpexView()

Use this constructor to create an untitled document.

The updateProfile command will be called, with the default settings.

LpexView

public LpexView(boolean updateProfile)

Use this constructor to create an untitled document, indicating whether the updateProfile command should be called.

If you specify true for updateProfile, then the updateProfile command will be called with the default settings. If you specify false, then updateProfile will not be called; you can then change the updateProfile settings and issue the updateProfile command later.

LpexView

public LpexView(LpexView lpexView)
         throws LpexView.ViewInstantiationException

Use this constructor to create a new document view from the specified document view.

The updateProfile command will be called, with the default settings.

Throws:: LpexView.ViewInstantiationException - if an additional view on the document cannot be created. Possible reasons: a null lpexView parameter was specified, or document-section management is in effect.

LpexView

public LpexView(LpexView lpexView,
                boolean updateProfile)
         throws LpexView.ViewInstantiationException

Use this constructor to create a new document view from the specified document view, indicating whether the updateProfile command should be called.

If you specify true for updateProfile, then the updateProfile command will be called with the default settings. If you specify false, then updateProfile will not be called; you can then change the updateProfile settings and issue the updateProfile command later.

Throws:: LpexView.ViewInstantiationException - if an additional view on the document cannot be created. Possible reasons: a null lpexView parameter was specified, or document-section management is in effect.

Method Detail

dispose

public void dispose()

This method disposes the document view.

isDisposed

public boolean isDisposed()

Returns whether the document view has been disposed.

See Also:: dispose(), LpexViewListener.disposed(LpexView)

setWindow

public void setWindow(LpexWindow lpexWindow)

Use this method to associate an LPEX window with this document view.

window

public LpexWindow window()

Returns the LPEX window currently associated with this view.

getLpexViews

public LpexView[] getLpexViews()

Returns an array of the views currently open on this view's document.

nls

public LpexNls nls()

Returns the LpexNls object associated with this LpexView. The multicultural support functions in the editor are accessible via this object.

See Also:: LpexNls

setText

public void setText(String text)

Sets the entire text of the document (or document section).

This method is similar to the load editor command. It will clear the undo stack, reset the changes count, and issue updateProfile for all of the views of the current document.

See Also:: text()

text

public String text()

Returns the entire text of the document (or document section currently loaded in the editor).

See Also:: setText(java.lang.String), save(Writer)

load

public boolean load(Reader reader)

Loads the entire text of the document (or document section) from the specified Reader.

This method is similar to the load editor command. It will clear the undo stack, reset the changes count, and issue updateProfile for all of the views of the current document.

Returns:: true if the text was loaded successfully

save

public boolean save(Writer writer)

Saves the entire text of the document (or document section currently loaded in the editor) to the specified Writer.

Parameters:: writer - a Writer object, for example a StringWriter, an OutputStringWriter (one that uses the default character encoding or one that uses a named encoding), etc.
Returns:: true if the text was saved successfully
See Also:: text()

setParserOverrideName

public void setParserOverrideName(String name)

Sets the name of the parser to be used instead of the associated parser. The parser for the view is changed and initialized.

setSaveWriter

public void setSaveWriter(Writer writer)

Sets the Writer object for the saveToWriter action. The saveToWriter action will then run the save command to the specified Writer, rather than to the document's file. The save command makes use of certain settings, such as save.textLimit, to determine what text is actually saved.

Example of using saveToWriter with an OutputStreamWriter:

 
 ByteArrayOutputStream bytes = new ByteArrayOutputStream();
 OutputStreamWriter writer = new OutputStreamWriter(bytes, "UTF-8"); 
 lpexView.setSaveWriter(writer);
 lpexView.triggerAction(lpexView.actionId("saveToWriter"));
 lpexView.setSaveWriter(null);

Example of using saveToWriter to save to a String:

 
 StringWriter writer = new StringWriter();
 lpexView.setSaveWriter(writer);
 lpexView.doAction(lpexView.actionId("saveToWriter")); 
 lpexView.setSaveWriter(null);
 String savedDocument = writer.toString();

Parameters:: writer - a Writer object, for example a StringWriter, an OutputStringWriter (one that uses the default character encoding or one that uses a named encoding), etc.

defineCommand

public LpexCommand defineCommand(String commandName,
                                 LpexCommand lpexCommand)

Defines a user command.

Returns:: the previously user-defined command for this commandName, or null if none
See Also:: LpexCommand

command

public LpexCommand command(String commandName)

Returns the specified user-defined command. Example:

 
 LpexCommand myInsertTextCommand = lpexView.command("myInsertText");

doDefaultCommand

public boolean doDefaultCommand(String commandString)

Runs the specified default editor command. Example:

 
 lpexView.doDefaultCommand("insertText xyz");

Parameters:: commandString - command name and optional parameters
Returns:: true if the command string is valid (correct command name and parameters), or
false if the command string is not valid

doDefaultCommand

public boolean doDefaultCommand(LpexDocumentLocation documentLocation,
                                String commandString)

Runs the specified default editor command. If the command requires a document location, then the specified document (or document section) location will be used. If the command changes the view's document location, then the specified document location will be updated; the view's actual current (cursor) document location will not be affected, to the extent that its underlying text is not affected.

Parameters:: documentLocation - a document location (element, position) in the document section currently loaded in the editor; commandString - command name and optional parameters
Returns:: true if valid arguments and command string (correct command name and parameters), false otherwise

doCommand

public boolean doCommand(String commandString)

Runs the specified command.

A user-defined command modifies the editor command set available in an LPEX view by overriding or extending a default editor command, or by adding an entirely new command. If there is no user-defined command for the specified command string, this method will run the default editor command, if any.

Parameters:: commandString - command name and optional parameters
Returns:: true if the command string is valid (correct command name and parameters), or
false if the command string is not valid
See Also:: doDefaultCommand(String)

doCommand

public boolean doCommand(LpexDocumentLocation documentLocation,
                         String commandString)

Runs the specified command at the specified document (or document section) location. If the command requires a document location, then the specified document (or document section) location will be used. If the command changes the view's document location, then the given document location will be updated; the view's actual current (cursor) document location will not be affected, to the extent that its underlying text is not affected.

Parameters:: documentLocation - a document location (element, position) in the document section currently loaded in the editor; commandString - command name and optional parameters
Returns:: true if valid arguments and command string (correct command name and parameters), false otherwise
See Also:: doDefaultCommand(LpexDocumentLocation,String)

doGlobalCommand

public static boolean doGlobalCommand(String commandString)

Runs the specified default editor global command. The command should be a globally-scoped command, that is, one that does not require a document view. Examples:

 
 LpexView.doGlobalCommand("updateProfile all");
 LpexView.doGlobalCommand("set default.print.footer %p");

Parameters:: commandString - command name and optional parameters
Returns:: true if the command string is valid (correct command name and parameters), or
false if the command string is not valid

defineAction

public LpexAction defineAction(String actionName,
                               LpexAction lpexAction)

Defines a user action. An action which overrides a default editor action will keep the editor action's id. A new action will be allocated the next available running action id; note that the id of such an action redefined each time the updateProfile command is run will, consequently, change.

Returns:: the previously user-defined action for this actionName, if any
See Also:: LpexAction, actionId(String)

actionId

public int actionId(String actionName)

Returns the id of the specified default or user-defined editor action.

Returns:: 0 if the action is not defined

action

public LpexAction action(String actionName)

Returns the specified user-defined editor action.

doDefaultAction

public void doDefaultAction(int actionId)

Runs the default editor action for the specified action id.

Parameters:: actionId - id of a default editor action

defaultActionAvailable

public boolean defaultActionAvailable(int actionId)

Checks whether the specified default editor action is available.

Parameters:: actionId - id of a default editor action

doAction

public void doAction(int actionId)

Runs the specified action. Use this method instead of triggerAction() if you are implementing your own command or action. No screen refresh will be done after the action has completed. A user-defined action will be invoked regardless of its availability.

Note that the LPEX built-in action ids defined in LpexActionConstants (for example, LpexActionConstants.ACTION_BLOCK_COPY) are reserved for the internal use of the editor, and change between releases. You must query, and eventually cache, the id of a built-in action before using it, for example:

 
 int blockCopyId = lpexView.actionId("blockCopy"); 
 lpexView.triggerAction(blockCopyId);

Parameters:: actionId - id of a default or user-defined editor action
See Also:: triggerAction(int), actionId(java.lang.String)

triggerAction

public void triggerAction(int actionId)

Runs the specified action. Use this method instead of doAction() if you are processing anything other than your own action or command (for example, a listener notification, a menu or toolbar action, etc.). This method ensures that the screen will be refreshed.

 
 int blockCopyId = lpexView.actionId("blockCopy"); 
 lpexView.triggerAction(blockCopyId);

Parameters:: actionId - id of a default or user-defined editor action
See Also:: doAction(int), actionId(java.lang.String)

triggerAction

public void triggerAction(int actionId,
                          boolean record)

Runs the specified action and optionally records it if keystroke recording is in progress. Applications which employ their own mechanism of mapping (selected) key events to LPEX actions may still want to ensure that these triggered actions are recorded by the keystroke recorder, as if the LPEX widget itself was processing these keys.

Parameters:: actionId - id of a default or user-defined editor action; record - record this action in the keystroke recorder
See Also:: triggerAction(int)

actionAvailable

public boolean actionAvailable(int actionId)

Returns whether the specified action is available.

Parameters:: actionId - id of a default or user-defined editor action

actionChecked

public boolean actionChecked(int actionId)

Returns whether the specified action has a checked status.

Parameters:: actionId - id of a default or user-defined editor action

actionKey

public String actionKey(int actionId)

Returns the primary key associated with the specified action.

Parameters:: actionId - id of a default or user-defined editor action
Returns:: primary key definition, for example, "a-pageDown.t"
See Also:: actionKeyText(int)

actionKeyText

public String actionKeyText(int actionId)

Returns a translated text version of the primary key for the specified action.

Parameters:: actionId - id of a default or user-defined editor action
Returns:: primary key, for example, "Alt+Page down"
See Also:: actionKey(int)

keyText

public static String keyText(String keyString)

Returns a translated text version of a key definition.

Parameters:: keyString - a key definition, for example, "a-pageDown.t"
Returns:: key text, for example, "Alt+Page down"

keyAssigned

public boolean keyAssigned(String keyString)

Checks whether the specified key is associated with an action. A key associated with action nullAction is considered unassigned. This method allows to associate actions to keys without overriding previous assignments.

For example,

 
 boolean assigned = keyAssigned("c-o.t");

returns true if an action was defined and associated with Ctrl+O in the text area.

elements

public int elements()

Returns the number of elements in the document (or section of the document that is currently loaded in the editor). Elements include show lines and non-show lines. Show lines are not saved when the document is saved.

Note: the elements editor parameter always returns the number of elements in the complete document.

jump

public void jump(int element,
                 int position)

Moves the cursor to the specified position in the document (or section of the document that is currently loaded in the editor).

Note: the locate editor command always applies to elements or lines in the complete document.

Parameters:: element - an element in the document section currently loaded in the editor; position - the position in the element (the position of the first character in an element is 1)
See Also:: jump(LpexDocumentLocation)

jump

public void jump(LpexDocumentLocation documentLocation)

Moves the cursor to the specified position in the document (or section of the document that is currently loaded in the editor).

Note: the locate editor command always applies to elements or lines in the complete document.

Parameters:: documentLocation - a document location (element, position) in the document section currently loaded in the editor
See Also:: jump(int,int)

parser

public LpexParser parser()

Returns the current document parser for this view.

parsePending

public int parsePending(int element)

Returns the parse-pending state of the specified element. The state of an element in the parse-pending list consists of one or more of these flags: LpexConstants.PARSE_PENDING_CHANGE_MASK, LpexConstants.PARSE_PENDING_INSERT_MASK, LpexConstants.PARSE_PENDING_NEXT_DELETED_MASK, LpexConstants.PARSE_PENDING_PREV_DELETED_MASK, LpexConstants.PARSE_PENDING_NEXT_SHOW_DELETED_MASK, LpexConstants.PARSE_PENDING_PREV_SHOW_DELETED_MASK, LpexConstants.PARSE_PENDING_UNDO_MASK. For an element which is not in the parse-pending list of this document view, the method will return 0.

Note that additional flags may be defined in future releases.

Returns:: element's parse-pending state bit-mask

elementParsed

public void elementParsed(int element)

Removes the specified element from the parse-pending list of this document view. This view's document parser will not be called for this element until after a subsequent change.

elementText

public String elementText(int element)

Returns the text of an element in the document (or document section currently loaded in the editor). If there is no such element, null is returned. If the element has no text, an empty String is returned.

Note: the text editor parameter applies to the current element.

Parameters:: element - an element in the document section currently loaded in the editor

elementFullText

public String elementFullText(int element)

Returns the full text (i.e., including the sequence numbers, if set) of an element in the document (or document section currently loaded in the editor). If there is no such element, null is returned. If the element has no text (and no sequence numbers are set), an empty String is returned.

Parameters:: element - an element in the document section currently loaded in the editor
See Also:: elementText(int), lineFullText(int)

lineFullText

public String lineFullText(int line)

Returns the full text (i.e., including the sequence numbers, if set) of a line in the document (or document section currently loaded in the editor). If there is no such line, null is returned. If the line has no text (and no sequence numbers are set), an empty String is returned.

Parameters:: line - a line in the document section currently loaded in the editor
See Also:: elementFullText(int)

setElementText

public void setElementText(int element,
                           String text)

Sets the text for an element in the document (or document section that is currently loaded in the editor).

Note: the text editor parameter applies to the current element.

Parameters:: element - an element in the document section currently loaded in the editor; text - the text to set

show

public boolean show(int element)

Returns the show setting for an element in the document (or document section that is currently loaded in the editor).

Note: the show editor parameter applies to the current element.

Parameters:: element - an element in the document section currently loaded in the editor
Returns:: true if the specified element is a show element in this or another view of the document; or
false if the element is not available in the document or is not a show element
See Also:: viewShow(int)

viewShow

public boolean viewShow(int element)

Returns whether the specified element in the document (or document section that is currently loaded in the editor) is a show element for this document view.

The code example below checks whether errorElement is a parser embedded message of another view:

 
 boolean otherShow = lpexView.show(errorElement) && !lpexView.viewShow(errorElement);

Parameters:: element - an element in the document section currently loaded in the editor
Returns:: true if the specified element is a show element for this view of the document; or
false if the element is not available in the document, or is not a show element, or is a show element that belongs to another view
See Also:: show(int)

elementStyle

public String elementStyle(int element)

Returns the style string for an element in the document (or document section currently loaded in the editor). If there is no such element, null is returned. If the element has no style string set, an empty String is returned.

Note: the style editor parameter applies to the current element.

Parameters:: element - an element in the section of the document that is currently loaded in the editor

setElementStyle

public void setElementStyle(int element,
                            String style)

Sets the style string for an element in the document (or section of the document that is currently loaded in the editor).

Note: the style editor parameter applies to the current element.

Parameters:: element - an element in the document section currently loaded in the editor; style - the style string to set

elementClasses

public long elementClasses(int element)

Returns the bit-mask of the element classes set in an element of the document (or document section that is currently loaded in the editor).

Note: the elementClasses editor parameter applies to the current element.

Parameters:: element - an element in the document section currently loaded in the editor
Returns:: the classes bit-mask set in the given element, or 0 if the element was not found

setElementClasses

public void setElementClasses(int element,
                              long classes)

Sets the element classes bit-mask in an element of the document (or document section that is currently loaded in the editor).

Note: the elementClasses editor parameter applies to the current element.

Parameters:: element - an element in the document section currently loaded in the editor; classes - bit-mask of the element class(es) to set

registerClass

public long registerClass(String className)

Registers the specified element class in this view. This method is equivalent to the command set class.className on.

Returns:: the allocated bit-mask of this element class in this view
See Also:: classMask(java.lang.String)

classMask

public long classMask(String classNames)

Returns the bit-mask allocated in this view for the registered element class(es) named.

See Also:: registerClass(java.lang.String)

currentElement

public int currentElement()

Returns the ordinal number of the current (cursor) element in the document (or section of the document that is currently loaded in the editor). If there is no current element (no elements are visible in the document), this method returns 0. Elements include show lines and non-show lines. Show lines are not saved when the document is saved.

Note: the element editor parameter returns the ordinal number of the (current) element in the complete document.

See Also:: lineOfElement(int), currentPosition(), documentLocation()

currentPosition

public int currentPosition()

Convenience method to retrieve the current (cursor) position within the current (cursor) element. An equivalent command to query the position editor parameter is:

 
 lpexView.queryInt("position");

See Also:: currentElement(), documentLocation()

documentLocation

public LpexDocumentLocation documentLocation()

Returns the view's current (cursor) location in the document (or section of the document that is currently loaded in the editor). If no elements are currently visible, the returned LpexDocumentLocation.element will be 0.

Note: the element editor parameter returns the ordinal number of the (current) element in the complete document.

See Also:: currentElement(), currentPosition()

documentLocation

public LpexDocumentLocation documentLocation(int charOffset,
                                             int eolLength)

Returns the location in the document (or section of the document that is currently loaded in the editor) which corresponds to the given Unicode-character offset in its underlying file (section). If the specified offset is beyond the end of the document (section), the location returned will be the end of the document (section).

This method assumes that a consistent line separator is used throughout the underlying file (section).

Parameters:: charOffset - ZERO-based character offset from the start of the file; eolLength - length of file's line separator, for example, 2 for CRLF ("\r\n")
See Also:: charOffset(com.ibm.lpex.core.LpexDocumentLocation, int)

charOffset

public int charOffset(LpexDocumentLocation documentLocation,
                      int eolLength)

Returns a document (or document section) location's Unicode-character offset in its underlying file (section). If the specified location is beyond the end of the document (section), the offset returned will be for the end of the document (section).

This method assumes that a consistent line separator is used throughout the underlying file (section).

Parameters:: documentLocation - a location (element, position) in the document section currently loaded in the editor; eolLength - length of file's line separator, for example, 2 for CRLF ("\r\n")
Returns:: ZERO-based character offset from the start of the file
See Also:: documentLocation(int,int)

lpexView

public LpexView lpexView(String documentName)

Returns a view handling the given document, if any.

Parameters:: documentName - a document name
Returns:: a view for the specified document, or
null if the document name is null or it is not opened in the editor

setBlockInstance

public void setBlockInstance(LpexView lpexView)

Sets the block instance of this view. By default, all the document views of the current instance of the editor participate in one global block (selection) instance. This allows block operations to be performed between all the LPEX documents and document views.

Use this method to assign a different block instance for the view. When a view is used as a text widget, for example as a text field in a dialog, it is preferable that it doesn't participate in the global block instance, but have its own instead. Also, several such widgets may share one private block instance.

Parameters:: lpexView - null = use the default block instance, or this = create own block instance, or an existing lpexView = use the block instance of the given view

getBlockView

public LpexView getBlockView()

Returns the view with the selection, if any, in this view's block instance.

Returns:: the document view with the selection, or null if there is no selection

query

public String query(String parameter)

Queries an editor parameter.

queryInt

public int queryInt(String parameter)

Convenience method to query an editor integer parameter. Shortcut for

 
 String value = query(parameter);
 return (value != null)? Integer.parseInt(value) : -1;

Note that if the underlying query returns null, this method returns -1.

See Also:: query(String)

queryOn

public boolean queryOn(String parameter)

Convenience method to query an editor on/off parameter. Shortcut for

 
 String value = query(parameter);
 return value != null && value.equals("on");

Returns:: true for a valid editor parameter whose value is "on"
See Also:: query(String)

query

public String query(String parameter,
                    LpexDocumentLocation documentLocation)

Queries an editor parameter. If the parameter requires a document location, then the specified document (or document section) location will be used rather than the view's actual current document (or document section) location.

Parameters:: documentLocation - a document location (element, position) in the document section currently loaded in the editor

queryInt

public int queryInt(String parameter,
                    LpexDocumentLocation documentLocation)

Convenience method to query an editor integer parameter. Shortcut for

 
 String value = query(parameter, documentLocation);
 return (value != null)? Integer.parseInt(value) : -1;

Note that if the underlying query returns null, this method returns -1.

Parameters:: documentLocation - a document location (element, position) in the document section currently loaded in the editor
See Also:: query(String,LpexDocumentLocation)

queryOn

public boolean queryOn(String parameter,
                       LpexDocumentLocation documentLocation)

Convenience method to query an editor on/off parameter. Shortcut for

 
 String value = query(parameter, documentLocation); 
 return value != null && value.equals("on");

Parameters:: documentLocation - a document location (element, position) in the document section currently loaded in the editor
Returns:: true for a valid editor parameter whose value is "on"
See Also:: query(String,LpexDocumentLocation)

elementOfRow

public int elementOfRow(int row)

Returns the element in the document (or that section of the document that is currently loaded in the editor) which is displayed on the given screen row. Screen rows are 1 .. n, where n is specified by the rows editor parameter.

Elements include show lines and text lines. Show lines are not saved when the document is saved.

Parameters:: row - ONE-based screen row
Returns:: row's element, or 0 if the row doesn't display a visible element

elementOfLine

public int elementOfLine(int line)

Returns the element for the specified line. Both the specified line and the returned element are defined inside the document section that is currently loaded in the editor.

Elements include show lines and text lines. Show lines are not saved when the document is saved.

Note: the element editor parameter returns the ordinal number of the (current) element in the complete document.

Returns:: 0 if the line doesn't exist in the document (or currently loaded section of it)
See Also:: lineOfElement(int), Lines and elements

lineOfElement

public int lineOfElement(int element)

Returns the line for the specified element. Both the specified element and the returned line are defined inside the document section that is currently loaded in the editor.

Elements include show lines and text lines. Show lines are not saved when the document is saved.

If the element is a show element, the first document line above it is returned. If the element does not exist, or if there is no document line corresponding to the given element (for example, one or more show elements at the top of the document), this method returns 0.

Note: the line editor parameter returns the ordinal number of the (current) line in the complete document.

See Also:: currentElement(), elementOfLine(int), Lines and elements

deletedMarkName

public String deletedMarkName(int markId)

Returns the name of the deleted mark with the id specified. Can be used during the processing of LpexMarkListener markDeleted() notifications.

globalQuery

public static String globalQuery(String parameter)

Queries a global editor parameter. The parameter should be a globally-scoped parameter, i.e., one that does not require a document view. Example:

 
 LpexView.globalQuery("version");

setLinesOutsideDocumentSection

public boolean setLinesOutsideDocumentSection(int linesBeforeStart,
                                              int linesAfterEnd)

Sets the number of lines in the complete document that are outside the boundaries of the currently-loaded document section.

This feature is only provided for certain specific applications. Normally, the editor loads and operates on a complete document (file).

A call to this method may fail under certain circumstances. For example, you cannot use the document section feature when several views have been opened on the same document. In such a case false will be returned.

Returns:: false if unsuccessful
See Also:: LpexDocumentSectionListener

linesBeforeStart

public int linesBeforeStart()

Returns the number of lines in the document prior to the currently-loaded document section. Normally, the complete document is loaded in the editor, and this method will return 0.

See Also:: LpexDocumentSectionListener

linesAfterEnd

public int linesAfterEnd()

Returns the number of lines in the document following the currently-loaded document section. Normally, the complete document is loaded in the editor, and this method will return 0.

See Also:: LpexDocumentSectionListener

setFieldsProvider

public void setFieldsProvider(LpexFieldsProvider fieldsProvider)

Sets or removes a fields-setting provider for the text elements in this document view.

Parameters:: fieldsProvider - a (new) fields-setting provider, or null to remove any previously set provider
See Also:: LpexFieldsProvider

addLpexViewListener

public void addLpexViewListener(LpexViewListener viewListener)

Adds a view listener to this document view. A listener is only registered once, subsequent calls to add the same listener have no effect.

See Also:: LpexViewListener, removeLpexViewListener(com.ibm.lpex.core.LpexViewListener)

removeLpexViewListener

public void removeLpexViewListener(LpexViewListener viewListener)

Removes a view listener from this document view. Removes the specified listener if it is registered with this view.

addLpexCursorListener

public void addLpexCursorListener(LpexCursorListener cursorListener)

Adds a cursor listener to this document view. A listener is only registered once, subsequent calls to add the same listener have no effect.

See Also:: LpexCursorListener, removeLpexCursorListener(com.ibm.lpex.core.LpexCursorListener)

removeLpexCursorListener

public void removeLpexCursorListener(LpexCursorListener cursorListener)

Removes a cursor listener from this document view. Removes the specified listener if it is registered with this view.

addLpexMarkListener

public void addLpexMarkListener(int markId,
                                LpexMarkListener markListener)

Adds a mark listener to the specified mark. Does nothing if the mark is not found.

Parameters:: markId - id of a mark in this document view; markListener - listener to add
See Also:: LpexMarkListener, removeLpexMarkListener(int,LpexMarkListener), removeLpexMarkListener(LpexMarkListener)

removeLpexMarkListener

public void removeLpexMarkListener(int markId,
                                   LpexMarkListener markListener)

Removes a mark listener from the specified mark. Does nothing if the mark is not found or the specified listener is not set for the mark.

Parameters:: markId - id of a mark in this document view; markListener - listener to remove

removeLpexMarkListener

public void removeLpexMarkListener(LpexMarkListener markListener)

Removes a mark listener from all the marks in this document view for which it is registered.

Parameters:: markListener - listener to remove

addLpexDocumentListener

public void addLpexDocumentListener(LpexDocumentListener documentListener)

Adds a document listener to the editor document of this view. In general, the incremental-parser calls are sufficient for an application.

A listener is only registered once, subsequent calls to add the same listener have no effect.

See Also:: LpexDocumentListener, removeLpexDocumentListener(com.ibm.lpex.core.LpexDocumentListener), addLpexDocumentAdjustListener(com.ibm.lpex.core.LpexDocumentListener)

removeLpexDocumentListener

public void removeLpexDocumentListener(LpexDocumentListener documentListener)

Removes a document listener from the editor document of this view. Removes the specified listener if it is registered with this view's document.

addLpexDocumentAdjustListener

public void addLpexDocumentAdjustListener(LpexDocumentListener documentAdjustListener)

Adds a document-adjust listener to the editor document of this view. In certain cases, text being set in LPEX will be adjusted depending on the editor settings in effect. While client code which sets text in LPEX will temporarily disable its own document listener during a text-setting operation, it may still need to listen to the text adjustments carried out in the editor.

Examples of text being further adjusted when set in the editor: padding of the text up to (the end of) the sequence-numbers area; reinterpretation of document text as sequence numbers; resequencing; MBCS bytes vs. Unicode characters inconsistencies in sequence-numbers columns; MBCS adjustment with spaces added prior to the sequence-numbers area.

A listener is only registered once, subsequent calls to add the same listener have no effect.

See Also:: LpexDocumentListener, addLpexDocumentListener(com.ibm.lpex.core.LpexDocumentListener), removeLpexDocumentAdjustListener(com.ibm.lpex.core.LpexDocumentListener)

removeLpexDocumentAdjustListener

public void removeLpexDocumentAdjustListener(LpexDocumentListener documentAdjustListener)

Removes a document-adjust listener from the editor document of this view. Removes the specified listener if it is registered with this view's document.

addLpexDocumentSectionListener

public void addLpexDocumentSectionListener(LpexDocumentSectionListener sectionListener)

Adds a document-section listener to the editor document of this view. A listener is only registered once, subsequent calls to add the same listener have no effect.

See Also:: LpexDocumentSectionListener, removeLpexDocumentSectionListener(com.ibm.lpex.core.LpexDocumentSectionListener)

removeLpexDocumentSectionListener

public void removeLpexDocumentSectionListener(LpexDocumentSectionListener sectionListener)

Removes a document-section listener from the editor document of this view. Removes the specified listener if it is registered with this view's document.

setClassLoader

public static void setClassLoader(ClassLoader classLoader)

Sets an alternative class loader to be used by the editor. This method is needed, for example, in the Eclipse workbench, where the LPEX plug-in cannot load a class outside its own runtime library, and consequently cannot process commands such as set updateProfile.parserClass for a parser shipped by another plug-in.

Class loaders registered through this method are only used when a class cannot be loaded by the current LPEX loader. Used for loading the user profile, user-defined commands and actions, and document parsers.

extendInstallProfile

public static void extendInstallProfile(Properties extension)

Extends the editor install profile. On a platform on which one LPEX instance is shared by several applications (such as the Eclipse platform, where one LPEX plug-in may be used by various solution plug-ins), each application may extend the install profile with additional installation settings of editor parameters. Such settings may be, for example, new document parsers being made available to all the other applications, and their file-extension associations.

This method should be called before any document views are created. Any of the editor parameters that are available with the install parameter can have installation settings specified in the install profile. Only new "install." values should be set in this manner.

Here is the Install.properties file shipped with LPEX.

Example:

 
 Properties sabreTalkProperties = new Properties();
 sabreTalkProperties.setProperty("install.updateProfile.parserClass.sabreTalk", 
                                 "com.ibm.etools.tpf.sbt.SabreTalkParser");
 sabreTalkProperties.setProperty("install.updateProfile.parserAssociation.sbt",
                                 "sabreTalk");
 sabreTalkProperties.setProperty("install.updateProfile.parserAssociation.SBT",
                                 "sabreTalk");
 LpexView.extendInstallProfile(sabreTalkProperties);

getLpexHelpPage

public static String getLpexHelpPage(String lpexItem)

Returns the default HTML help panel for the editor item specified. The help panels are defined in the LPEX-help map, com.ibm.lpex.core.HelpCommand.properties. If no suitable help is found, the help panel corresponding to the key "default_help" in the LPEX-help map is returned.

For example, getLpexHelpPage("tabs"); will return "ref/rlptabs.htm".

An application using LPEX must redefine the help command (by implementing the LpexCommand interface) to use its own help-delivery mechanism.

See Also:: LpexCommand

setOwnerDrawMargin

public void setOwnerDrawMargin(boolean ownerDraw)

Sets whether the prefix-area margin of this view is being painted by an editor extension. This prevents flickering caused by the margin being first painted by LPEX and then drawn over by an LPEX extension. When such an extension is uninstalled, this method should be called to restore margin painting back to the editor.

addLpexKeyListener

public void addLpexKeyListener(LpexKeyListener keyListener)

Adds an LPEX key listener to this document view. A keyPressed(Event) notification is sent by LPEX when a key is pressed. LPEX ignores the key press if the listener consumes the key by setting the doit field of the event to false.

A listener is only registered once, subsequent calls to add the same listener have no effect.

See Also:: LpexKeyListener, removeLpexKeyListener(com.ibm.lpex.core.LpexKeyListener)

removeLpexKeyListener

public void removeLpexKeyListener(LpexKeyListener keyListener)

Removes the specified LPEX key listener from this document view. Removes the specified listener if it is registered with this view.

See Also:: addLpexKeyListener(com.ibm.lpex.core.LpexKeyListener)

setFont

public void setFont(org.eclipse.swt.graphics.Font swtFont)

Sets a new font in this view. The font passed in is an SWT Font.

getFont

public org.eclipse.swt.graphics.Font getFont()

Returns the font in this view. The font returned is an SWT Font.

setBaseEncoding

public void setBaseEncoding(String fileEncoding)

Overview

Package

Class

Tree

Serialized

Deprecated

Index

Help

LPEX
4.4.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Copyright � 2016 IBM Corp. All Rights Reserved.

Note: This documentation is for part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

com.ibm.lpex.core Class LpexView

LpexView

LpexView

LpexView

LpexView

LpexView

LpexView

LpexView

dispose

isDisposed

setWindow

window

getLpexViews

nls

setText

text

load

save

setParserOverrideName

setSaveWriter

defineCommand

command

doDefaultCommand

doDefaultCommand

doCommand

doCommand

doGlobalCommand

defineAction

actionId

action

doDefaultAction

defaultActionAvailable

doAction

triggerAction

triggerAction

actionAvailable

actionChecked

actionKey

actionKeyText

keyText

keyAssigned

elements

jump

jump

parser

parsePending

elementParsed

elementText

elementFullText

lineFullText

setElementText

show

viewShow

elementStyle

setElementStyle

elementClasses

setElementClasses

registerClass

classMask

currentElement

currentPosition

documentLocation

documentLocation

charOffset

lpexView

setBlockInstance

getBlockView

query

queryInt

queryOn

query

queryInt

queryOn

elementOfRow

elementOfLine

lineOfElement

deletedMarkName

globalQuery

setLinesOutsideDocumentSection

linesBeforeStart

com.ibm.lpex.core
Class LpexView