Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech::Recognition
interface Grammar
Files: GNOME_Speech.idl
GNOME-Speech-Recognition-Grammar-inheritance GNOME-Speech-Recognition-RuleGrammar.html GNOME-Speech-Recognition-DictationGrammar.html GNOME-Speech-SpeechObject.html Bonobo-Unknown.html
Operations Summary:
 voidaddGrammarListener(in GrammarListener listener)
 voidremoveGrammarListener(in GrammarListener listener)
 voidaddResultListener(in ResultListener listener)
 voidremoveResultListener(in ResultListener listener)
 longgetActivationMode()
 stringgetName()
RecognizergetRecognizer()
 booleanisActive()
 booleanisEnabled()
 voidsetActivationMode(in long mode) raises
 voidsetEnabled(in boolean enabled)

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

Operation Details:
 void addGrammarListener(in GrammarListener listener)

Request notifications of events of related to this Grammar. An application can attach multiple listeners to a Grammar.

Parameters:
listener - grammar listener to add.
See Also:
removeGrammarListener


 void removeGrammarListener(in GrammarListener listener)

Remove a listener from this Grammar.

Parameters:
listener - grammar listener to remove.
See Also:
addGrammarListener


 void addResultListener(in ResultListener listener)

Request notifications of events from any Result that matches this Grammar. An application can attach multiple ResultListeners to a Grammar. A listener is removed with the removeResultListener method.

A ResultListener attached to a Grammar receives result events starting from the GRAMMAR_FINALIZED event - the event which indicates that the matched grammar is known. A ResultListener attached to a Grammar will never receive a RESULT_CREATED event and does not receive any RESULT_UPDATED events that occurred before the GRAMMAR_FINALIZED event. A ResultListener attached to a Grammar is guaranteed to receive a result finalization event - RESULT_ACCEPTED or RESULT_REJECTED - some time after the GRAMMAR_FINALIZED event.

ResultListener objects can also be attached to a Recognizer and to any Result. A listener attached to the Recognizer receives all events for all results produced by that Recognizer. A listener attached to a Result receives all events for that result from the time at which the listener is attached.

Parameters:
listener - result listener to add.
See Also:
removeResultListener
Recognizer#addResultListener
Result#addResultListener
ResultEvent#RESULT_CREATED
ResultEvent#GRAMMAR_FINALIZED
ResultEvent#RESULT_ACCEPTED
ResultEvent#RESULT_REJECTED


 void removeResultListener(in ResultListener listener)

Remove a ResultListener from this Grammar.

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


 long getActivationMode()

Return the current activation mode for the Grammar. The default value for a grammar is RECOGNIZER_FOCUS.

Return:
the current activation mode for the Grammar.
See Also:
setActivationMode
setEnabled
isActive


 string getName()

Get the name of a grammar. A grammar's name must be unique for a recognizer. Grammar names use a similar naming convention to Java classes. The naming convention are defined in the Java Speech Grammar Format Specification.

Grammar names are used with a RuleGrammar for resolving imports and references between grammars. The name of a RuleGrammar is set when the grammar is created (either by loading a grammar formatted document or creating a new RuleGrammar).

The name of a DictationGrammar should reflect the language domain it supports. For example: com.acme.dictation.us.general for general US Dictation from Acme corporation. Since a DictationGrammar is built into a Recognizer, its name is determined by the Recognizer.

Return:
the name of the grammar.
See Also:
DictationGrammar
RuleGrammar


Recognizer getRecognizer()

Returns a reference to the Recognizer that owns this grammar.

Return:
a reference to the Recognizer that owns this grammar.


 boolean isActive()

Test whether a Grammar is currently active for recognition. When a grammar is active, the recognizer is matching incoming audio against the grammar (and other active grammars) to detect speech that matches the grammar.

A Grammar is activated for recognition if the enabled property is set to true and the activation conditions are met. Activation is not directly controlled by applications and so can only be tested (there is no setActive method).

Rules of a RuleGrammar can be individuallly enabled and disabled. However all rules share the same ActivationMode and the same activation state. Thus, when a RuleGrammar is active, all the enabled rules of the grammar are active for recognition. Changes in the activation state are indicated by GRAMMAR_ACTIVATED and GRAMMAR_DEACTIVATED events issued to the GrammarListener. A change in activation state can follow these RecognizerEvents:

Return:
a boolean indication of whether this grammar is active.
See Also:
setEnabled
setActivationMode
GrammarEvent#GRAMMAR_ACTIVATED
GrammarEvent#GRAMMAR_DEACTIVATED
RecognizerEvent#CHANGES_COMMITTED
RecognizerEvent#FOCUS_GAINED
RecognizerEvent#FOCUS_LOST


 boolean isEnabled()

Return the enabled property of the Grammar. More specialized behaviour is specified by the RuleGrammar interface.

Return:
the enabled property of the Grammar.
See Also:
setEnabled
RuleGrammar#isEnabled
RuleGrammar#isEnabledWithRuleName


 void setActivationMode(in long mode) raises (IllegalArgumentException)

Set the activation mode of a Grammar as RECOGNIZER_FOCUS, RECOGNIZER_MODAL, or GLOBAL. The role of the activation mode in the activation conditions for a Grammar are described above. The default activation mode - RECOGNIZER_FOCUS - should be used unless there is a user interface design reason to use another mode.

The individual rules of a RuleGrammar can be separately enabled and disabled. However, all rules share the same ActivationMode since the mode is a property of the complete Grammar. A consequence is that all enabled rules of a RuleGrammar are activated and deactivated together.

A change in activation mode only takes effect once changes are committed. For some recognizers changing the activation mode is computationally expensive.

The activation mode of a grammar can be tested by the getActivationMode method.

[Note: future releases may modify the set of activation modes.]

Parameters:
mode - the grammar activation mode.
See Also:
getActivationMode
RECOGNIZER_FOCUS
RECOGNIZER_MODAL
GLOBAL
setEnabled
isActive
Recognizer#commitChanges


 void setEnabled(in boolean enabled)

Set the enabled property of a Grammar. A change in the enabled property takes effect only after grammar changes are committed. Once a grammar is enabled and when the activation conditions are met, it is activated for recognition. When a grammar is activated, the Recognizer listens to incoming audio for speech that matches the grammar and produces a Result when matching speech is detected.

The enabled property of a grammar is tested with the isEnabled method. The activation state of a grammar is tested with the isActive method.

The RuleGrammar interface extends the enabling property to allow individual rules to be enabled and disabled.

Parameters:
enabled - the state for the enabled property of a Grammar.
See Also:
Recognizer#commitChanges
Grammar#setEnabled
RuleGrammar#setEnabledForRule
RuleGrammar#setEnabledForRuleArray
RuleGrammar#isEnabled