Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech::Recognition
interface Result
Files: GNOME_Speech.idl
GNOME-Speech-Recognition-Result-inheritance GNOME-Speech-Recognition-FinalResult.html GNOME-Speech-SpeechObject.html Bonobo-Unknown.html
Operations Summary:
 voidaddResultListener(in ResultListener listener)
 voidremoveResultListener(in ResultListener listener)
ResultTokengetBestToken(in long tokNum) raises
ResultTokenArraygetBestTokens()
GrammargetGrammar()
 longgetResultState()
ResultTokenArraygetUnfinalizedTokens()
 longnumTokens()

Operations Inherited from Bonobo::Unknown
ref, unref, queryInterface

Operation Details:
 void addResultListener(in ResultListener listener)

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.

Parameters:
listener - the result listener to add.
See Also:
removeResultListener
Recognizer#addResultListener
Grammar#addResultListener


 void removeResultListener(in ResultListener listener)

Remove a listener from this Result.

Parameters:
listener - the result listener to remove.
See Also:
addResultListener
Recognizer#removeResultListener
Grammar#removeResultListener


ResultToken getBestToken(in long tokNum) raises (IllegalArgumentException)

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.

Parameters:
tokNum - the tokNum'th token.
Return:
the best guess for the tokNum'th token.
See Also:
getUnfinalizedTokens
getBestTokens
FinalRuleResult#getAlternativeTokens
FinalDictationResult#getAlternativeTokens


ResultTokenArray getBestTokens()

Returns all the best guess tokens for this result. If the result has zero tokens, the return value is null.

Return:
all the best guess tokens for this result.


Grammar getGrammar()

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.

Return:
the Grammar matched by the best-guess finalized tokens of this result or null if the grammar is not known.
See Also:
getResultState


 long getResultState()

Returns the current state of the Result object: UNFINALIZED, ACCEPTED or REJECTED. The details of a Result in each state are described above.

Return:
the current state of the Result object.
See Also:
UNFINALIZED
ACCEPTED
REJECTED


ResultTokenArray getUnfinalizedTokens()

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).

Return:
the current guess of the tokens following the finalized tokens.
See Also:
ResultEvent#isUnfinalizedTokensChanged
ResultEvent#RESULT_UPDATED
ResultEvent#RESULT_ACCEPTED
ResultEvent#RESULT_REJECTED


 long numTokens()

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.

Return:
the number of finalized tokens in a Result.
See Also:
ResultEvent#RESULT_UPDATED
getBestToken
getBestTokens
FinalRuleResult#getAlternativeTokens
FinalDictationResult#getAlternativeTokens