Package org.eclipse.jface.text.templates

# Class TemplateProposal

java.lang.Object
org.eclipse.jface.text.templates.TemplateProposal

All Implemented Interfaces:
  `ICompletionProposal`, `ICompletionProposalExtension`, `ICompletionProposalExtension2`, `ICompletionProposalExtension3`

public class TemplateProposal extends Object implements ICompletionProposal, ICompletionProposalExtension, ICompletionProposalExtension2, ICompletionProposalExtension3
A template completion proposal.

Clients may subclass.

Since:
  3.0

## Constructor Summary

Constructors
Constructor
Description
`TemplateProposal(Template template, TemplateContext context, IRegion region, Image image)`
Creates a template proposal with a template and its context.
`TemplateProposal(Template template, TemplateContext context, IRegion region, Image image, int relevance)`
Creates a template proposal with a template and its context.

## Method Summary

Modifier and Type
Method
Description
`final void`
`apply(IDocument document)`
Deprecated.
This method is no longer called by the framework and clients should overwrite `apply(ITextViewer, char, int, int)` instead
`void`
`apply(IDocument document, char trigger, int offset)`
Deprecated.
This method is no longer called by the framework and clients should overwrite `apply(ITextViewer, char, int, int)` instead
`void`
`apply(ITextViewer viewer, char trigger, int stateMask, int offset)`
Inserts the template offered by this proposal into the viewer's document and sets up a `LinkedModeUI` on the viewer to edit any of the template's unresolved variables.
`String`
`getAdditionalProposalInfo()`
Returns optional additional information about the proposal.
`protected final TemplateContext`
`getContext()`
Returns the context in which the template was requested.
`IContextInformation`
`getContextInformation()`
Returns optional context information associated with this proposal.
`int`
`getContextInformationPosition()`
Returns the position to which the computed context information refers to or `-1` if no context information can be provided by this completion proposal.
`String`
`getDisplayString()`
Returns the string to be displayed in the list of completion proposals.
`Image`
`getImage()`
Returns the image to be displayed in the list of completion proposals.
`IInformationControlCreator`
`getInformationControlCreator()`
Returns the information control creator of this completion proposal.
`int`
`getPrefixCompletionStart(IDocument document, int completionOffset)`
Returns the document offset at which the receiver would insert its proposal.
`CharSequence`
`getPrefixCompletionText(IDocument document, int completionOffset)`
Returns the string that would be inserted at the position returned from `ICompletionProposalExtension3.getPrefixCompletionStart(IDocument, int)` if this proposal was applied.
`int`
`getRelevance()`
Returns the relevance.
`protected final int`
`getReplaceEndOffset()`
Returns the end offset of the range in the document that will be replaced by applying this template.
`protected final int`
`getReplaceOffset()`
Returns the offset of the range in the document that will be replaced by applying this template.
`Point`
`getSelection(IDocument document)`
Returns the new selection after the proposal has been applied to the given document in absolute document coordinates.
`protected final Template`
`getTemplate()`
Returns the template of this proposal.
`char[]`
`getTriggerCharacters()`
Returns the characters which trigger the application of this completion proposal.
`boolean`
`isValidFor(IDocument document, int offset)`
Returns whether this completion proposal is valid for the given position in the given document.
`void`
`selected(ITextViewer viewer, boolean smartToggle)`
Called when the proposal is selected.
`final void`
`setInformationControlCreator(IInformationControlCreator informationControlCreator)`
Sets the information control creator for this completion proposal.
`void`
`unselected(ITextViewer viewer)`
Called when the proposal is unselected.
`boolean`
`validate(IDocument document, int offset, DocumentEvent event)`
Requests the proposal to be validated with respect to the document event.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### TemplateProposal

public TemplateProposal(Template template, TemplateContext context, IRegion region, Image image)
Creates a template proposal with a template and its context.

Parameters:
  `template` - the template
  `context` - the context in which the template was requested.
  `region` - the region this proposal is applied to
  `image` - the icon of the proposal.

### TemplateProposal

public TemplateProposal(Template template, TemplateContext context, IRegion region, Image image, int relevance)
Creates a template proposal with a template and its context.

Parameters:
  `template` - the template
  `context` - the context in which the template was requested.
  `image` - the icon of the proposal.
  `region` - the region this proposal is applied to
  `relevance` - the relevance of the proposal

## Method Details

### setInformationControlCreator

public final void setInformationControlCreator(IInformationControlCreator informationControlCreator)
Sets the information control creator for this completion proposal.

Parameters:
  `informationControlCreator` - the information control creator
Since:
  3.1

### getTemplate

protected final Template getTemplate()
Returns the template of this proposal.

Returns:
  the template of this proposal
Since:
  3.1

### getContext

protected final TemplateContext getContext()
Returns the context in which the template was requested.

Returns:
  the context in which the template was requested
Since:
  3.1

### apply

@Deprecated public final void apply(IDocument document)
Deprecated.
This method is no longer called by the framework and clients should overwrite `apply(ITextViewer, char, int, int)` instead
Inserts the proposed completion into the given document.

Specified by:
  `apply` in interface `ICompletionProposal`
Parameters:
  `document` - the document into which to insert the proposed completion

### apply

public void apply(ITextViewer viewer, char trigger, int stateMask, int offset)
Inserts the template offered by this proposal into the viewer's document and sets up a `LinkedModeUI` on the viewer to edit any of the template's unresolved variables.

Specified by:
  `apply` in interface `ICompletionProposalExtension2`
Parameters:
  `viewer` - the text viewer into which to insert the proposed completion
  `trigger` - the trigger to apply the completion
  `stateMask` - the state mask of the modifiers
  `offset` - the offset at which the trigger has been activated

### getReplaceOffset

protected final int getReplaceOffset()
Returns the offset of the range in the document that will be replaced by applying this template.

Returns:
  the offset of the range in the document that will be replaced by applying this template
Since:
  3.1

### getReplaceEndOffset

protected final int getReplaceEndOffset()
Returns the end offset of the range in the document that will be replaced by applying this template.

Returns:
  the end offset of the range in the document that will be replaced by applying this template
Since:
  3.1

### getSelection

public Point getSelection(IDocument document)
Description copied from interface: `ICompletionProposal`
Returns the new selection after the proposal has been applied to the given document in absolute document coordinates. If it returns `null`, no new selection is set. A document change can trigger other document changes, which have to be taken into account when calculating the new selection. Typically, this would be done by installing a document listener or by using a document position during `ICompletionProposal.apply(IDocument)`.

Specified by:
  `getSelection` in interface `ICompletionProposal`
Parameters:
  `document` - the document into which the proposed completion has been inserted
Returns:
  the new selection in absolute document coordinates

### getAdditionalProposalInfo

public String getAdditionalProposalInfo()
Description copied from interface: `ICompletionProposal`
Returns optional additional information about the proposal. The additional information will be presented to assist the user in deciding if the selected proposal is the desired choice.

If `ICompletionProposalExtension5` is implemented, this method should not be called any longer. This method may be deprecated in a future release.

Specified by:
  `getAdditionalProposalInfo` in interface `ICompletionProposal`
Returns:
  the additional information or `null`

### getDisplayString

public String getDisplayString()
Description copied from interface: `ICompletionProposal`
Returns the string to be displayed in the list of completion proposals.

Specified by:
  `getDisplayString` in interface `ICompletionProposal`
Returns:
  the string to be displayed
See Also:
  - `ICompletionProposalExtension6.getStyledDisplayString()`
  - `ICompletionProposalExtension7.getStyledDisplayString(IDocument, int, BoldStylerProvider)`

### getImage

public Image getImage()
Description copied from interface: `ICompletionProposal`
Returns the image to be displayed in the list of completion proposals. The image would typically be shown to the left of the display string.

Specified by:
  `getImage` in interface `ICompletionProposal`
Returns:
  the image to be shown or `null` if no image is desired

### getContextInformation

public IContextInformation getContextInformation()
Description copied from interface: `ICompletionProposal`
Returns optional context information associated with this proposal. The context information will automatically be shown if the proposal has been applied.

Specified by:
  `getContextInformation` in interface `ICompletionProposal`
Returns:
  the context information for this proposal or `null`

### getRelevance

public int getRelevance()
Returns the relevance.

Returns:
  the relevance

### getInformationControlCreator

public IInformationControlCreator getInformationControlCreator()
Description copied from interface: `ICompletionProposalExtension3`
Returns the information control creator of this completion proposal.

Specified by:
  `getInformationControlCreator` in interface `ICompletionProposalExtension3`
Returns:
  the information control creator, or `null` if no custom control creator is available

### selected

public void selected(ITextViewer viewer, boolean smartToggle)
Description copied from interface: `ICompletionProposalExtension2`
Called when the proposal is selected.

Specified by:
  `selected` in interface `ICompletionProposalExtension2`
Parameters:
  `viewer` - the text viewer.
  `smartToggle` - the smart toggle key was pressed

### unselected

public void unselected(ITextViewer viewer)
Description copied from interface: `ICompletionProposalExtension2`
Called when the proposal is unselected.

Specified by:
  `unselected` in interface `ICompletionProposalExtension2`
Parameters:
  `viewer` - the text viewer.

### validate

public boolean validate(IDocument document, int offset, DocumentEvent event)
Description copied from interface: `ICompletionProposalExtension2`
Requests the proposal to be validated with respect to the document event. If the proposal cannot be validated, the methods returns `false`. If the document event was `null`, only the caret offset was changed, but not the document. This method replaces `ICompletionProposalExtension.isValidFor(IDocument, int)`

Specified by:
  `validate` in interface `ICompletionProposalExtension2`
Parameters:
  `document` - the document
  `offset` - the caret offset
  `event` - the document event, may be `null`
Returns:
  boolean

### getPrefixCompletionText

public CharSequence getPrefixCompletionText(IDocument document, int completionOffset)
Description copied from interface: `ICompletionProposalExtension3`
Returns the string that would be inserted at the position returned from `ICompletionProposalExtension3.getPrefixCompletionStart(IDocument, int)` if this proposal was applied. If the replacement string cannot be determined, `null` may be returned.

Specified by:
  `getPrefixCompletionText` in interface `ICompletionProposalExtension3`
Parameters:
  `document` - the document that the receiver applies to
  `completionOffset` - the offset into `document` where the completion takes place
Returns:
  the replacement string or `null` if it cannot be determined

### getPrefixCompletionStart

public int getPrefixCompletionStart(IDocument document, int completionOffset)
Description copied from interface: `ICompletionProposalExtension3`
Returns the document offset at which the receiver would insert its proposal.

Specified by:
  `getPrefixCompletionStart` in interface `ICompletionProposalExtension3`
Parameters:
  `document` - the document that the receiver applies to
  `completionOffset` - the offset into `document` where the completion takes place
Returns:
  the offset at which the proposal would insert its proposal

### apply

@Deprecated public void apply(IDocument document, char trigger, int offset)
Deprecated.
This method is no longer called by the framework and clients should overwrite `apply(ITextViewer, char, int, int)` instead
Applies the proposed completion to the given document. The insertion has been triggered by entering the given character at the given offset. This method assumes that `ICompletionProposalExtension.isValidFor(IDocument, int)` returns `true` if called for `offset`.

Specified by:
  `apply` in interface `ICompletionProposalExtension`
Parameters:
  `document` - the document into which to insert the proposed completion
  `trigger` - the trigger to apply the completion
  `offset` - the offset at which the trigger has been activated

### isValidFor

public boolean isValidFor(IDocument document, int offset)
Description copied from interface: `ICompletionProposalExtension`
Returns whether this completion proposal is valid for the given position in the given document.

Specified by:
  `isValidFor` in interface `ICompletionProposalExtension`
Parameters:
  `document` - the document for which the proposal is tested
  `offset` - the offset for which the proposal is tested
Returns:
  `true` iff valid

### getTriggerCharacters

public char[] getTriggerCharacters()
Description copied from interface: `ICompletionProposalExtension`
Returns the characters which trigger the application of this completion proposal.

Specified by:
  `getTriggerCharacters` in interface `ICompletionProposalExtension`
Returns:
  the completion characters for this completion proposal or `null` if no completion other than the new line character is possible

### getContextInformationPosition

public int getContextInformationPosition()
Description copied from interface: `ICompletionProposalExtension`
Returns the position to which the computed context information refers to or `-1` if no context information can be provided by this completion proposal.

Specified by:
  `getContextInformationPosition` in interface `ICompletionProposalExtension`
Returns:
  the position to which the context information refers to or `-1` for no information