SemanticItem Client Object
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
class SemanticItem
{
SemanticItem(sco, ID, targetElement, targetAttribute,
bindOnChanged, bindAtServer, autoPostback,
onClientChanged, onClientConfirmed, hiddenFieldID,
value, state);
SetText(string text, boolean isConfirmed);
Clear();
Empty();
GetAttribute(string key);
SetAttribute(string key, object value);
IsEmpty();
NeedsConfirmation();
IsConfirmed();
Encode();
object value; // Read-only
string state; // Read-only
object attributes;
array alternates;
}
Members
ID Property
Gets or sets a string that uniquely identifies the control on the page.
The ID value of the client object should be identical to the server-side ID value.
state Property
The semantic state of the client SemanticItem object. Read-only.
Possible values of the state property are:
- Empty
- NeedsConfirmation
- Confirmed
The client-side state property corresponds to the State property of the server-side control. The server-side State property is read/write. The client-side state property is intended to be treated as read-only, even though JScript does not support such restriction of access.
To set the client-side state property, use the SetText method as follows.
MySemanticItem.SetText(MySemanticItem.value,true);
Clear Method
Sets the state property of the client SemanticItem to Empty and sets its value property to null. Setting the state to Empty causes RunSpeech to reactivate the QA and validator controls associated with the SemanticItem control to repeat the prompt and the validation of the user's response.
Currently, the attributes property is not cleared.
Authors can use the Clear method to force the repetition of a question without preserving the user's previous answer.
semanticitemobject.Clear();
Empty Method
Sets the state property of the client SemanticItem to Empty and leaves its value property unchanged. Setting the state to Empty causes RunSpeech to reactivate the QA and validator controls associated with the SemanticItem control to repeat the prompt and the validation of the user's response.
Currently, the attributes property is not cleared.
Authors can use the Empty method to force the repetition of a question while preserving the user's previous answer.
semanticitemobject.Empty();
IsEmpty Method
Returns true if the state property of the SemanticItem is Empty; otherwise, it returns false.
boolean = semanticitemobject.IsEmpty();
NeedsConfirmation Method
Returns true if the state property of the SemanticItem is NeedsConfirmation; otherwise, it returns false.
boolean = semanticitemobject.NeedsConfirmation();
IsConfirmed Method
Returns true if the state property of the SemanticItem is Confirmed; otherwise, it returns false.
boolean = semanticitemobject.IsConfirmed();
value Property
Contains the text value of the client-side SemanticItem. Read-only.
The client-side value property corresponds to the Text property of the server-side control. The server-side Text property is read/write. The client-side value property is intended to be treated as read-only, even though JScript does not support such restriction of access. Use the SetText function to set this value rather than change the property value explicitly.
SetText Method
Changes the value property and state property of SemanticItem.
semanticitemobject.SetText(string text, boolean isConfirmed);
| Parameter | Description |
|---|---|
text |
A string that becomes the value property of SemanticItem. |
isConfirmed |
A Boolean that sets the state property of SemanticItem. If true, SetText sets the state to Confirmed; if false, SetText sets the state to NeedsConfirmation. |
attributes Property
A collection of name/value pairs that passes user-defined information to the client-side SemanticItem object.
Use the attributes collection to pass user-defined information to the client-side SemanticItem and back to the server (they are kept synchronized). To set attributes programmatically, use the GetAttribute and SetAttribute methods.
The attributes property is not cleared when the SemanticItem object is reset by semantic processing or by an explicit call to the Clear method. If authors want to reset the attributes, they must do so explicitly.
GetAttribute Method
Gets an attribute value from the attributes collection. The key parameter should be a string variable.
string = semanticitemobject.GetAttribute(string key);
SetAttribute Method
Sets an attribute value in the attributes collection. Both the key and the value parameters should be string variables.
semanticitemobject.SetAttribute(string key, string value);
Application authors should not initialize any attribute to null; doing so causes a run-time error.
alternates Property
Gets the list of alternate recognitions returned by the speech recognition (SR) engine. Read-only.
The SR engine can return more than one recognition of a phrase. The best recognition (that is, the recognition with the highest confidence factor) is always returned as the recognition. A nbest parameter specifies the number of alternate recognitions to be returned. The number of alternates returned is always less than or equal to the value of nbest. If an nbest value is specified, the recognition result is always included with the alternates as the top-ranked alternate. By default, nbest is off, which specifies that the SR engine should return one primary result and no alternates.
When RunSpeech processes the recognition results for an Answer control, it places alternate recognitions into an array of Alternate objects. The alternates property returns this array.
The following code shows the Alternate class.
class Alternate
{
SemanticItem();
int id;
float confidence;
XmlNode value;
}
Example
In the following example, QA1 prompts a user for a city name and sets nbest to a value of 3. Code called by the ClientNormalizationFunction property of QA1 builds a list of the alternate city names. The PromptSelectFunction of QA2 returns this list as the prompt text for QA2.
<form id="Form1" method="post" >
...
<speech:qa id="QA1" SpeechIndex="100" >
<Answers>
<speech:Answer SemanticItem="siDst" XPathTrigger="/SML/ToCity"
ClientNormalizationFunction="myGetAlternates">
</speech:Answer>
</Answers>
<Reco ID="QA1_Reco">
<Params>
<speech:Param Name="nbest">3</speech:Param>
</Params>
<Grammars>
<speech:Grammar Src="http://localhost/Grammars/Cities.grxml#Dest">
</speech:Grammar>
</Grammars>
</Reco>
<Prompt InlinePrompt="What is your destination?"></Prompt>
</speech:qa>
<speech:qa id="QA2" SpeechIndex="200" >
<Prompt PromptSelectFunction="mySpeakAlternates"></Prompt>
</speech:qa>
...
<script>
var alts = "";
function myGetAlternates() {
for(var i=0; i<siDst.alternates.length; i++) {
alts += siDst.alternates[i].value.text + " ";
}
return null;
}
function mySpeakAlternates() {
return alts;
}
</script>
...
</form>
Run-time Behavior
The following lists show the execution order for transitions from Empty to NeedsConfirmation and for transitions from NeedsConfirmation to Confirmed:
- Client-side binding (if needed)
- Client-side event
- If (AutoPostBack), trigger submit
On the server, the order of execution:
- Server-side binding (if needed)
- Server-side event
If the SemanticItem object is programmatically changed on the server, no events are raised, either on the server or on the client.
If the BindOnChanged property is false, the AutoPostBack property is true, and Changed and Confirmed handlers are both specified, the Changed event is triggered first, followed by the Confirmed event.
If an event handler is specified, Changed events are raised on the server even if the server-side value is the same as the previous value.
If AutoPostBack is set to true, the controls cause two postbacks, synchronized with onChanged and onConfirmed.