SemanticItem Client Object

Artigo
07/05/2006

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 value of the ID 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 and 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 will cause RunSpeech to reactivate the QA and validator controls associated with the SemanticItem control, in order 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 will cause RunSpeech to reactivate the QA and validator controls associated with the SemanticItem control, in order 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 the SemanticItem.

semanticitemobject.SetText(string text, boolean isConfirmed);

text
A string that will become the value property of the SemanticItem.
isConfirmed
A Boolean that sets the state property of the 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 is reset by semantic processing or by an explicit call to the Clear method. If authors wish 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 will cause a run-time error.

alternates property

Gets the list of alternate recognitions returned by the speech recognition (SR) engine. Read-only.

The Speech Recognition (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 parameter called nbest 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 diagram 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" runat="server">
  ...
  <speech:qa id="QA1" SpeechIndex="100" runat="server">
    <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="https://localhost/Grammars/Cities.grxml#Dest">
        </speech:Grammar>
      </Grammars>
    </Reco>
    <Prompt InlinePrompt="What is your destination?"></Prompt>
  </speech:qa>

  <speech:qa id="QA2" SpeechIndex="200" runat="server">
    <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

Following is the order of execution 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 is:

Server-side binding (if needed)
Server-side event.

If the SemanticItem is programmatically changed in 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, then the Changed event is triggered first, followed by the Confirmed event.

If an event handler is specified, Changed events are raised in 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.

Partilhar via