Event Handler Elements

The following elements support event handling.

OnButton

Defines the actions that occur when a button is pressed. The actions defined within this event handler override the default actions of the button when one of the child ActionSets are executed.

The OnButton element may contain one or more ActionSet elements.

Attribute Description
Button The name of the button. These may change based on the final design of the device. The current values are: PlayPause, Next, Previous, VolumeUp, VolumeDown, Forward, Back, Option1, and Help
Action The button action to which this event handler applies. Possible values are Press, Release, and Hold. The Hold event is fired once a second when the button is held down.

OnStart and OnFinish

The OnStart element contains actions to be beformed at the beginning of a segment of audio content.

The OnFinish elements contains actions to be beformed at the end of a segment of audio content. Also when a Goto element jumps to an end of a container, the actions within the OnFinish element are executed before moving to the next container.

Both elements may contain one or more ActionSet elements.

Example

The following example is from a shared block of audio content that tells a user that he has selected the wrong answer. After playing, the audio returns to the location that was previously pushed onto the stack.

<File ID="WrongAnswer" Href="wronganswer.mp3">
   <OnFinish>
         <Goto>
               <PopStack/>
         </Goto>
   </OnFinish>
</File>

ActionSet

The ActionSet is used within a OnButton, OnStart or OnFinish element.

ActionSet defines the set of action elements to be executed when an event occurs. Optionally the ActionSet element can also contain FlagTest which must all evaluate to *true* for the ActionSet to be executed.

If the parent OnButton, OnStart or OnFinish element contains more than one ActionSet element, the first actionset element whose FlagTest elements evaluate to *true* is executed.

Example

The following example handles the Option1 button, when it is pressed during a wrong answer. Each time the user presses the button during the wrong answer he is told that he has selected the wrong answer and is returned to the beginning of the list of answers. However, the first time the user selects the wrong answer, he receives a hint.

In this case, the first ActionSet contains a FlagTest, while the second does not. This functions similarly to an if-else, switch-case-default, or xsl:choose-xsl:when-xsl:otherwise construct.

<OnButton Button="Option1" Action="Release">
   <ActionSet>
       <FlagTest Flag="AnsweredWrongBefore" Test="IsFalse"/>
       <PushStack>
            <Location Ref="Hint"/>
            <Location Target="Beginning" Class="Answers"/>
       </PushStack>
       <SetFlag Flag="AnsweredWrongBefore" Value="True"/>
       <Goto>
             <Location Ref="WrongAnswer"/>
       </Goto>
   </ActionSet>
   <ActionSet>
       <PushStack>
            <Location Target="Beginning" Class="Answers"/>
       </PushStack>
       <Goto>
             <Location Ref="WrongAnswer"/>
       </Goto>
   </ActionSet>
</OnButton>

FlagTest

FlagTest is used within an ActionSet element to conditionally control execution of that actionset.

Flags are set within other event handlers using the SetFlag action. Flags are scoped within the parent Package container.

Attribute Description
Flag The unique identifier of the flag. These IDs are scoped within the Package container.
Test The test to apply to the flag value. Valid values are "IsTrue", and "IsFalse". If a flag has not been assigned a value, it is assumed to be false.

The example is a Block that contains a multiple choice question. If the user clicks the Option button during the playback of correct choice (between 45 and 53 seconds in the audio track), the "CorrectChoice" flag will record that they answered correctly. The OnFinish event handler will tell them whether they answered correctly.

<File Href="question23.mp3" Class="Question">
     <OnStart>
          <ActionSet>
                <SetFlag Flag="CorrectChoice" Value="false"/>
          </ActionSet>
     </OnStart>
     <OnFinish>
           <ActionSet>
                  <FlagTest Flag="CorrectChoice" Test="IsTrue"/>
                  <PushStack>
                        <Location Class="Question" Target="Next"/>
                  </PushStack>
                  <Goto>
                        <Location Ref="YouAreCorrect"/>
                  </Goto>
           </ActionSet>
           <ActionSet>
                  <PushStack>
                        <Location Class="Question" Target="Next"/>
                  </PushStack>
                  <Goto>
                        <Location Ref="ImSorryThatIsNotCorrect"/>
                  </Goto>
            </ActionSet>
     </OnFinish>
     <Block Offset="45000" Length="8000">
          <OnButton Button="Option1" Action="Release">
                <ActionSet>
                     <SetFlag Flag="CorrectChoice" Value="true"/>
                </ActionSet>
          <OnButton>
     </Block>
</File>