public interface BracesMatcher
BracesMatcherFactory and
will be used by the editor infrastructure to find areas of matching characters
in a document.
Generally, BracesMatchers operate within a MatcherContext
that describes a position in a document where the search should start.
The matcher first looks in the document at that position to determine if it contains
a character or a sequence of characters that normally come in pairs. This can
be a single brace or an XML tag or anything that the matcher wishes to recognize.
This area is called the original area and its boundaries - beginning and ending
offsets - should be returned from BracesMatcher.findOrigin() method. The infrastructure
will then ask the matcher to find the other matching areas by calling its
BracesMatcher.findMatches() method.
Besides of describing the position in a document where the search should start
the MatcherContext also tells the matcher in which direction
it should be looking for the original area. The direction can either be
backward to look towards the beginning of the document or it can be forward
to look towards the end of the document. The search direction can be determined
by calling MatcherContext.isSearchingBackward().
The search for the original area should only be attempted in the near proximity
of the caret. The maximum distance from the caret where the matcher is supposed
to look can be obtained from MatcherContext.getSearchLookahead().
While there can only be one original area, the area in the document where the search start, the matcher may report multiple areas matching the original one. Typically, though, there will only be one matching area too.
In the situation when the matcher reported an original area, but was unable to find any matching areas, the original area will be marked as mismatched, which may be indicated visually to a user.
Cancellable tasks
It is important to understand that matching is generally initiated in response
to a moving caret in a text component on screen. Therefore there can be many
requests for matching started, but only the last one provides results interesting
for a user. In order not to flood the system with background tasks that are computing
results nobody is interested in, it is essential to implement both findOrigin
and findMatches methods in a way that makes their work possible
to interrupt and cancel.
The infrastructre uses RequestProcessor for spawning a background
thread that runs the asynchronous matching tasks. When the infrastructure wants
to cancel a task it simply interrupts its thread. The task must
check up on its thread status periodically and quit immediately when the
thread is interruped. The example below shows how this can be implemented:
public int [] findMatches() {
while(stillSearching) {
// look a bit furter in the document ....
if (MatcherContext.isTaskCanceled()) {
return null;
}
}
}
| Modifier and Type | Interface and Description |
|---|---|
static interface |
BracesMatcher.ContextLocator
Mixin interface, which provides context ranges for brace matches.
|
| Modifier and Type | Method and Description |
|---|---|
int[] |
findMatches()
Finds all areas matching the original one.
|
int[] |
findOrigin()
Checks if the
MatcherContext is positioned in an area suitable
for matching. |
int[] findOrigin()
throws InterruptedException,
BadLocationException
MatcherContext is positioned in an area suitable
for matching. This check should be very simple and fast. The matcher
should only try to find the original area within the search lookahead
from the caret offset that it obtains from MatcherContext.
Normally this method is supposed to return offset boundaries of the
original area or null if the original area can't be found.
The infrastructure will highlight the whole original area according to
the result of the findMatches call. If for some reason the
matcher does not want to highlight the whole original area it can return
additional offset pairs for areas that should be highlighted instead.
The infrastructure does not lock the document prior calling this method.
null
if the matcher can't detect the origin area within the lookahead distance.
If null is returned the infrastructure will never call
the findMatches method on this instance.InterruptedException - If the thread was engaged in a
call that resulted in InterruptedException, the exception
should be rethrown.BadLocationException - If a document operation fails.int[] findMatches()
throws InterruptedException,
BadLocationException
MatcherContext.
The infrastructure does not lock the document prior calling this method.
It is essential for all implementations to respond when thread running this method is interrupted and abort the task and return immediately. This can be done simply by checking the thread's status like in the code below.
if (MatcherContext.isTaskCanceled()) {
return;
}
null if no matching areas can be found. If the returned array
is not null, it should have even number of elements.InterruptedException - If the thread was engaged in a
call that resulted in InterruptedException, the exception
should be rethrown.BadLocationException - If a document operation fails.