Operations Summary: | |
void | addResultListener(in ResultListener listener) |
void | removeResultListener(in ResultListener listener) |
ResultToken | getBestToken(in long tokNum) raises |
ResultTokenArray | getBestTokens() |
Grammar | getGrammar() |
long | getResultState() |
ResultTokenArray | getUnfinalizedTokens() |
long | numTokens() |
Operations Inherited from Bonobo::Unknown | |
ref, unref, queryInterface |
Operation Details: |
Request notifications of events of related to this
Result
. An application can attach multiple
listeners to a Result
. A listener can be
removed with the removeResultListener
method.
ResultListener
objects can also be attached to a
Recognizer
and to any Grammar
. A
listener attached to the Recognizer
receives
all events for all results produced by that Recognizer
.
A listener attached to a Grammar
receives all
events for all results that have been finalized for that
Grammar
(all events starting with and including
the GRAMMAR_FINALIZED
event).
A ResultListener
attached to a Result
only receives events following the point in time at which the
listener is attached. Because the listener can only be attached
during or after the RESULT_CREATED
, it will not
receive the RESULT_CREATED
event. Only
ResultListeners
attached to the
Recognizer
receive RESULT_CREATED
events.
removeResultListener
Recognizer#addResultListener
Grammar#addResultListener
Remove a listener from this Result
.
addResultListener
Recognizer#removeResultListener
Grammar#removeResultListener
Returns the best guess for the tokNum'th
token.
tokNum
must be in the range 0 to numTokens()-1.
If the result has zero tokens (possible in both the
UNFINALIZED
and REJECTED
states) an
exception is thrown.
If the result is in the REJECTED
state, then the
returned tokens are likely to be incorrect. In the
ACCEPTED
state (not rejected) the recognizer is
confident that the tokens are correct but applications should
consider the possibility that the tokens are incorrect.
The FinalRuleResult
and
FinalDictationResult
interfaces provide
getAlternativeTokens
methods that return alternative
token guesses for finalized results.
tokNum'th
token. tokNum'th
token. getUnfinalizedTokens
getBestTokens
FinalRuleResult#getAlternativeTokens
FinalDictationResult#getAlternativeTokens
Returns all the best guess tokens for this result. If the result has zero tokens, the return value is null.
Return the Grammar
matched by the best-guess
finalized tokens of this result or null if the grammar is
not known. The return value is null before a
GRAMMAR_FINALIZED
event and non-null afterwards.
The grammar is guaranteed to be non-null for an accepted result.
The grammar may be null or non-null for a rejected result,
depending upon whether a GRAMMAR_FINALIZED
event
was issued prior to finalization.
For a finalized result, an application should determine the type
of matched grammar with an instanceof
test. For a
result that matches a RuleGrammar
, the methods of
FinalRuleResult
can be used (the methods of
FinalDictationResult
throw an error). For a result
that matches a DictationGrammar
, the methods of
FinalDictationResult
can be used (the methods of
FinalRuleResult
throw an error). The methods of
FinalResult
can be used for a result matching either
kind of grammar.
Grammar
matched by the best-guess finalized tokens of this result or null if the grammar is not known. getResultState
Returns the current state of the Result object:
UNFINALIZED
, ACCEPTED
or
REJECTED
. The details of a Result
in each state are described above.
UNFINALIZED
ACCEPTED
REJECTED
In the UNFINALIZED
state, return the current guess
of the tokens following the finalized tokens. Unfinalized tokens
provide an indication of what a recognizer is considering as
possible recognition tokens for speech following the finalized
tokens.
Unfinalized tokens can provide users with feedback on the
recognition process. The array may be any length (zero or more
tokens), the length may change at any time, and successive calls to
getUnfinalizedTokens
may return different tokens
or even different numbers of tokens. When the unfinalized tokens
are changed, a RESULT_UPDATED
event is issued to
the ResultListener
. The RESULT_ACCEPTED
and RESULT_REJECTED
events finalize a result and
always guarantee that the return value is null. A new result
created with a RESULT_CREATED
event may have a
null or non-null value.
The returned array is null if there are currently no unfinalized
tokens, if the recognizer does not support unfinalized tokens, or
after a Result
is finalized (in the
ACCEPTED
or REJECTED
state).
ResultEvent#isUnfinalizedTokensChanged
ResultEvent#RESULT_UPDATED
ResultEvent#RESULT_ACCEPTED
ResultEvent#RESULT_REJECTED
Returns the number of finalized tokens in a Result
.
Tokens are numbered from 0 to numTokens()-1 and are obtained
through the getBestToken
and getBestTokens
method of this (Result
) interface and the
getAlternativeTokens
methods of the
FinalRuleResult
and FinalDictationResult
interfaces for a finalized result.
Starting from the RESULT_CREATED
event and while the
result remains in the UNFINALIZED
state, the number
of finalized tokens may be zero or greater and can increase as
tokens are finalized. When one or more tokens are finalized in
the UNFINALIZED
state, a RESULT_UPDATED
event is issued with the tokenFinalized
flag set true.
The RESULT_ACCEPTED
and RESULT_REJECTED
events which finalize a result can also indicate that one or more
tokens have been finalized.
In the ACCEPTED
and REJECTED
states,
numTokens
indicates the total number of tokens that
were finalized. The number of finalized tokens never changes in
these states. An ACCEPTED
result must have one or
more finalized token. A REJECTED
result may have
zero or more tokens.
Result
. ResultEvent#RESULT_UPDATED
getBestToken
getBestTokens
FinalRuleResult#getAlternativeTokens
FinalDictationResult#getAlternativeTokens