# com.bea.ide.sourceeditor.driver
ILanguageDriver Interface

public interface ILanguageDriver

Implementations of this driver provide customization for working with the languages in the source view. The methods require understanding of the lexical structure of the language for correct implemention. Note that one document may make use of several language drivers, since a single document type may contain several nested languages.

All Known Implementing Classes
  `DefaultLanguageDriver`

## Nested Class Summary

`public static interface` | `ILanguageDriver.IAutoCorrection` IAutoCorrection objects are returned by the `getAutoCorrection``` method.
`public static interface` | `ILanguageDriver.IAutoFill` Object describing an auto-fill.
`public static interface` | `ILanguageDriver.IBlockDelim` Defines one end of a block.
`public static interface` | `ILanguageDriver.IBlockInfo` Summary of the information gathered by the `ILanguageDriver.IBlockInfo.findMatchingOpenBlock(int, char)``` or `ILanguageDriver.IBlockInfo.findMatchingCloseBlock(int, char)``` methods.
`public static interface` | `ILanguageDriver.IParameterHelp` IParameterHelp objects define individual options to be displayed in a parameter help popup.

## Method Summary

`public boolean` | `canAutoCorrect`(`String` diagnosticCode) Allows this driver to specify the types of errors for which it can offer auto-corrections.
`public `ILanguageDriver.IBlockInfo`` | `findMatchingCloseBlock`(int pos, char ch) Returns the block whose close delimiter matches that found at the position given.
`public `ILanguageDriver.IBlockInfo`` | `findMatchingOpenBlock`(int pos, char ch) Returns the block whose open delimiter matches that found at the position given.
`public `ILanguageDriver.IAutoCorrection`` | `getAutoCorrection`(`String` diagnosticCode, int offset, int length, `ILanguageDriver.IAutoCorrection` innerCorrection) Allows this driver to returns auto-correction suggestions for various errors found in the source code.
`public `ILanguageDriver.IAutoFill`` | `getAutoFill`(`Range` selection, char typed) Allows the driver to return an auto-fill text range replacement for keystrokes sent to the source view.
`public `URI`[]` | `getHelpContextList`(`Range` range) Returns the list of context help URIs for the given range.
`public int` | `getOpenBlockCount`(`ISourceModel.Line` line, `ILanguageDriver.IBlockDelim` delim, int length) Returns the number of non-matching open-blocks on the given line.
`public `ILanguageDriver.IParameterHelp`[]` | `getParameterHelp`(int offset, char typed) Returns an array of objects used to build the parameter help popup.
`public int` | `getWordWrapPosition`(`Range` range) Returns the position within a range of text on a line on which it would be best to wrap to the next line during printing.
`public boolean` | `isCloseChar`(char ch) Determines whether the given character might close a block.
`public boolean` | `isOpenChar`(char ch) Determines whether the given character might open a block.
`public boolean` | `parameterHelpAvailable`(int offset, char typed) Called after a user types a character in the source editor to determine if the specified character and offset may initiate parameter popup help.
`public void` | `setDocument`(`IDocument` doc) Sets the source document upon which this document will act.
`public boolean` | `suppportsCtrlHover`(`String` tokenTypeName) Allows this driver to define which types of tokens support ctrl-hover and ctrl-click definition information features.

## Method Detail

### canAutoCorrect(String) Method

    public boolean canAutoCorrect(String diagnosticCode)

Allows this driver to specify the types of errors for which it can offer auto-corrections. Calls to this method should be very fast, as it may be called many times during each compilation notification. If an error is correctable, this driver may or may not ever receive a request for the actual IAutoCorrection object via `getAutoCorrection```.

#### Parameters

diagnosticCode
  The type of error found.

#### Returns

a boolean indicating whether this driver can correct the specified error.

### findMatchingCloseBlock(int, char) Method

    public ILanguageDriver.IBlockInfo findMatchingCloseBlock(int pos,
                                                             char ch)

Returns the block whose close delimiter matches that found at the position given. If neither delimiter is found null is returned. If a mismatch is found then a block is found with only the close delimiter. Use the faster short circuit `isOpenChar` method first.

#### Parameters

pos
  Offset of character `ch` in document.

ch
  Close character.

#### Returns

Corresponding block object, null if not found.

### findMatchingOpenBlock(int, char) Method

    public ILanguageDriver.IBlockInfo findMatchingOpenBlock(int pos,
                                                            char ch)

Returns the block whose open delimiter matches that found at the position given. If neither delimiter is found null is returned. If a mismatch is found then a block is found with only the close delimiter. Use the faster short circuit `isCloseChar` method first.

#### Parameters

pos
  Offset of character `ch` in document.

ch
  Close character.

#### Returns

Corresponding block object, null if not found.

### getAutoCorrection(String, int, int, ILanguageDriver.IAutoCorrection) Method

    public ILanguageDriver.IAutoCorrection getAutoCorrection(String diagnosticCode,
                                                             int offset,
                                                             int length,
                                                             ILanguageDriver.IAutoCorrection innerCorrection)

Allows this driver to returns auto-correction suggestions for various errors found in the source code. If this driver is not able to provide a correction, the inner language's correction (if present) should be returned, unless this driver wants to explicitly hide that correction.

#### Parameters

diagnosticCode
  The type of error found.

offset
  The location of the error within this driver's document.

length
  The length of text to which the error applies.

innerCorrection
  The auto-correction provided by inner language nodes, if any. This parameter is frequently null.

#### Returns

An IAutoCorrection object corresponding to corrections for the specified error.

### getAutoFill(Range, char) Method

    public ILanguageDriver.IAutoFill getAutoFill(Range selection,
                                                 char typed)

Allows the driver to return an auto-fill text range replacement for keystrokes sent to the source view. If this driver doesn't wish to provide auto-fill it can return `null` in which case a default action will be taken for the character. A typical auto-fill example is for indenting new lines, e.g. '\n' -> "{indent}\n".

This method is only called for printable characters, e.g. > 0x20, and for the new-line character '\n'. CONSIDER:This doesn't allow access to modifier keystrokes, CTRL, ALT, etc. Should we have another method, say public InputMap getKeymap()?

#### Parameters

selection
  The (normalized) range of the selection within this driver's document.

typed
  The character typed.

#### Returns

An auto-fill replacement object, null for default action.

### getHelpContextList(Range) Method

    public URI[] getHelpContextList(Range range)

Returns the list of context help URIs for the given range.

### getOpenBlockCount(ISourceModel.Line, ILanguageDriver.IBlockDelim, int) Method

    public int getOpenBlockCount(ISourceModel.Line line,
                                 ILanguageDriver.IBlockDelim delim,
                                 int length)

Returns the number of non-matching open-blocks on the given line. The block end given will be the open-block of the pair. The `length` parameter is the number of character in the line's text that should be examined for open blocks.

#### Parameters

line
  Line to examine for open blocks.

delim
  Type of block to scan for.

length
  Length of `line` to examine from start.

#### Returns

Number of non-matching open block delimiters on first `length` characters of `line`.

### getParameterHelp(int, char) Method

    public ILanguageDriver.IParameterHelp[] getParameterHelp(int offset,
                                                           char typed)

Returns an array of objects used to build the parameter help popup.

#### Parameters

offset
  the offset of the caret

typed
  the potential parameter help initiation character

#### Returns

An array of IParameterHelp objects defining the available parameter help options.

### getWordWrapPosition(Range) Method

    public int getWordWrapPosition(Range range)

Returns the position within a range of text on a line on which it would be best to wrap to the next line during printing.

#### Parameters

range
  represents a character range in the source document which exactly fits on one line (after indenting).

#### Returns

the position closest to range.getEnd() that is an acceptable word break. The character at that position will begin the next line. Valid return values are anything after range.getStart(), up to and including range.getEnd().

### isCloseChar(char) Method

    public boolean isCloseChar(char ch)

Determines whether the given character might close a block.

### isOpenChar(char) Method

    public boolean isOpenChar(char ch)

Determines whether the given character might open a block.

### parameterHelpAvailable(int, char) Method

    public boolean parameterHelpAvailable(int offset,
                                          char typed)

Called after a user types a character in the source editor to determine if the specified character and offset may initiate parameter popup help.

#### Parameters

offset
  the offset of the caret

typed
  the potential parameter help initiation character

#### Returns

boolean indicating whether parameter help can be initiated at this location.

### setDocument(IDocument) Method

    public void setDocument(IDocument doc)

Sets the source document upon which this document will act. This method will be called immediately after instantiation.

### suppportsCtrlHover(String) Method

    public boolean suppportsCtrlHover(String tokenTypeName)

Allows this driver to define which types of tokens support ctrl-hover and ctrl-click definition information features. If this method returns true for a given token type, more expensive calls utilizing the object mappers defined in the IDE extension's "urn:com-bea-ide:sourceeditor:sourceinfo" XML extension will be used to determine if definition information is actually available.

#### Parameters

tokenTypeName
  the language specific name for a particular token type, such as "java.identifier".

#### Returns

boolean indicating whether tokens of this type ever support ctrl-hover behavior.