public interface TypedTextInterceptor
KeyEvent
s that reach a default keymap action (ie.
there is no entry in the editor's keymap for this particular KeyEvent
).
Registration: TypedTextInterceptor
s can be plugged in the editor infrastructure
by implementing the TypedTextInterceptor.Factory
interface and registering it in MimeLookup
under the appropriate mimetype (ie MimePath
).
The instances created from the Factory
will be reused for processing
all keyboard input received by all documents of the same mime type, which the interceptor
instances were registered for (including documents that contain embedded sections
of that mime type). As described in the general concepts of Typing Hooks SPI
the interceptors are guaranteed to be called in AWT thread only, which means that
they should not need any internal synchronization model.
Processing rules: If there are multiple instances of TypedTextInterceptor
registered
for the same mime type the infrastructure will queue them up in their registration
order and when processing an event it will call them all until the processing is done
or terminated.
The interceptor has several methods that are called at different stages of the key typed event processing. When processing an event the infrastructure will call the methods in the order as they are listed below. Moreover, if there are multiple interceptors queued up for processing an event each method is first called on all the queued interceptors before moving on to the next stage and calling next method.
TypedTextInterceptor.beforeInsert(Context)
- It's called before any text is inserted
into a document. No document lock is held when this method is called. The method
can't modify the text that will be inserted (and it's not supposed to do any tricks to
break this rule). An interceptor can stop further processing of the event by returning
true
from this method. If it does so, no other interceptors'
beforeInsert
method will be called and the processing will be terminated
without inserting any text.
TypedTextInterceptor.insert(MutableContext)
- This method is called during the text
insertion stage immediately before the text is inserted into a document. At this
time the document is already write locked, but the interceptors are not expected
to modify its content directly. Instead they can change the text that will be
inserted by calling TypedTextInterceptor.MutableContext.setText(java.lang.String, int)
method.
The text insertion is strictly controlled by the infrastructure and has to obey some
additional rules (eg. correctly replacing selected text, handling insert vs override
modes of the caret, etc). The first interceptor that modifies the insertion text
will win and no other interceptor's insert
method will be called.
TypedTextInterceptor.afterInsert(Context)
- This is the last method in the processing
chain and it will be called when the text is already inserted in the document.
Similarly as in beforeInsert
the document is not locked when
this method is called.
TypedTextInterceptor.cancelled(Context)
- This is an additional method that will be called
when the processing is terminated in the before-insertion stage (ie. by an interceptor
returning true
from its beforeInsert
method).
The infrastructure will only call this method on interceptors that have already
had their beforeInsert
method called, but not on those that
have not yet been called at all.
Errors recovery: If an exception is thrown from any of the methods when calling an interceptor the infrastructure will catch it and log it, but it will not stop further processing. The infrastructure may blacklist the offending interceptor and exclude it from processing future events.
Modifier and Type | Interface and Description |
---|---|
static class |
TypedTextInterceptor.Context
The context class providing information about the edited document, its
editor pane, insertion offset and text.
|
static interface |
TypedTextInterceptor.Factory
The factory interface for registering
TypedTextInterceptor s
in MimeLookup . |
static class |
TypedTextInterceptor.MutableContext
This context class allows to modify the insertion text and the caret position
after the text is inserted into a document.
|
Modifier and Type | Method and Description |
---|---|
void |
afterInsert(TypedTextInterceptor.Context context)
This method is called after text is inserted into a document and its editor's
caret is adjusted.
|
boolean |
beforeInsert(TypedTextInterceptor.Context context)
This method is called before any text is inserted into a document.
|
void |
cancelled(TypedTextInterceptor.Context context)
This method is called when the normal processing is terminated by some
interceptor's
beforeInsert method. |
void |
insert(TypedTextInterceptor.MutableContext context)
This method is called immediately before the text is inserted into a document.
|
boolean beforeInsert(TypedTextInterceptor.Context context) throws BadLocationException
This method can be used for stopping further processing of the current
key typed event. If this method returns true
the processing will
be terminated and TypedTextInterceptor.cancelled(Context)
will be called for all the intercetors
that have already had their beforeInsert
method called (including
the one that terminated the processing). The rest of the interceptors waiting
in the queue will not be called at all.
Locking: When this method is called the document is not locked by the infrastructure.
context
- The context object providing information necessary for processing
the event.true
the further processing will be stopped. Normally
the method should return false
.BadLocationException
- Since the document is not locked prior calling this
method the processing may fail when working with stale context data.void insert(TypedTextInterceptor.MutableContext context) throws BadLocationException
MutableContext
to modify the text
that will be inserted into a document. The first interceptor that mutates
the insertion text will win and the method will not be called on the rest
of the queued interceptors. The interceptors are not supposed to modify the
document directly.
Locking: When this method is called the infrastructure has already write locked the document.
context
- The context object providing information necessary for processing
the event and allowing to modify the insertion text.BadLocationException
- If the processing fails.void afterInsert(TypedTextInterceptor.Context context) throws BadLocationException
Locking: When this method is called the document is not locked by the infrastructure.
context
- The context object providing information necessary for processing
the event. The TypedTextInterceptor.Context.getText()
method will return text that was
inserted into the document at the end of the text-insertion stage.BadLocationException
- Since the document is not locked prior calling this
method the processing may fail when working with stale context data.void cancelled(TypedTextInterceptor.Context context)
beforeInsert
method. Please note that this
method will not be called if the beforeInsert
method was not
called.context
- The context object used for calling the beforeInsert
method.