<doc>

<legacy_id>2181</legacy_id>

<name>switch</name>

<type>control structure</type>

<syntax>

<example>

switch [<i>switchExpression</i>]

<p> case {<i>caseValue</i> | <i>caseCondition</i>}</p>

<p> [<i>statementList</i>]</p>

<p> [default</p>

<p> <i>defaultStatementList</i>]</p>

<p>end switch</p>

</example>

</syntax>

<synonyms>

</synonyms>

<summary>Chooses among several possible <glossary tag="value">values</glossary> for an <glossary tag="expression">expression</glossary>, and <glossary tag="execute">executes</glossary> a set of <glossary tag="statement">statements</glossary> that depends on the <function tag="value">value</function>. </summary>

<examples>

</examples>

<history>

<introduced version="1.0">Added. </introduced>

<deprecated version=""></deprecated>

<removed version=""></removed>

</history>

<objects>

</objects>

<platforms>

<mac/>

<windows/>

<linux/>

<ios/>

<android/>

</platforms>

<classes>

<mobile/>

</classes>

<security>

</security>

<classification>

<category>Writing LiveCode</category>

</classification>

<references>

<keyword tag="case">case Keyword</keyword>

<keyword tag="default">default Keyword</keyword>

<keyword tag="end switch">end swicth Keyword</keyword>

<control_st tag="break">break Control Structure</control_st>

<control_st tag="if">if Control Structure</control_st>

</references>

<description>

<overview>Use the <b>switch</b> <glossary tag="control structure">control structure</glossary> to select among multiple possible conditions, performing a different set of actions for each possibility. <p></p><p><b>Form:</b></p><p>The <b>switch</b> <glossary tag="control structure">control structure</glossary> begins with the word switch on a single line, with an optional <i>switchExpression</i>. </p><p></p><p>The <b>switch</b> line is followed by one or more <keyword tag="case">case</keyword> sections. Each <keyword tag="case">case</keyword> section begins with the <keyword tag="case">case</keyword> <glossary tag="keyword">keyword</glossary>, followed by either a <i>caseValue</i> (if a <i>switchExpression</i> was included on the <b>switch</b> line) or a <i>caseCondition</i> (if no <i>switchExpression</i> was included). If the <i>caseValue</i> is equal to the <i>switchExpression</i>, or the <i>caseCondition</i> <glossary tag="evaluate">evaluates</glossary> to true, LiveCode begins <glossary tag="execute">executing</glossary> the following <glossary tag="statement">statements</glossary>. </p><p></p><p>The <b>case</b> sections may be followed by an optional <keyword tag="default">default</keyword> section. If no <b>break</b> <glossary tag="statement">statement</glossary> has been encountered yet in the <control_st tag="switch">switch</control_st> <glossary tag="control structure">control structure</glossary>, the <glossary tag="statement">statements</glossary> in the <keyword tag="default">default</keyword> section are executed. </p><p></p><p>The <b>switch</b> structure ends with an <keyword tag="end switch">end switch</keyword> <glossary tag="statement">statement</glossary>. </p></overview>

<parameters>

<parameter>The <i>switchExpression</i> is any expression.</parameter>

<parameter>The <i>caseValue</i> is any <glossary tag="expression">expression</glossary>. (If the <i>caseValue</i> evaluates to the same <function tag="value">value</function> as the <i>switchExpression</i>, the condition is matched for that <keyword tag="case">case</keyword> section.)</parameter>

<parameter>The <i>caseCondition</i> is any <glossary tag="expression">expression</glossary> that <glossary tag="evaluate">evaluates</glossary> to true or false. (If the <i>caseCondition</i> <glossary tag="evaluate">evaluates</glossary> to true, the condition is matched for that <keyword tag="case">case</keyword> section.)</parameter>

<parameter>Each <i>statementList</i> consists of one or more <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>, and can also include <control_st tag="if">if</control_st>, <control_st tag="switch">switch</control_st>, <control_st tag="try">try</control_st>, or <control_st tag="repeat">repeat</control_st> <glossary tag="control structure">control structures</glossary>.</parameter>

<parameter>The <i>defaultStatementList</i> consists of one or more <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>.</parameter>

</parameters>

<value></value>

<comments>Flow of control in a <b>switch</b> <glossary tag="control structure">structure</glossary> is less complicated than it looks. In general, when LiveCode enters a <b>switch</b> <glossary tag="control structure">control structure</glossary>, it looks for the first <keyword tag="case">case</keyword> section whose <i>caseValue</i> is equal to the <i>switchExpression</i>, or whose <i>caseCondition</i> is true. When a matching condition is found, all <glossary tag="statement">statements</glossary> following it are executed--even statements in another <keyword tag="case">case</keyword> section--until either a <control_st tag="break">break</control_st> <glossary tag="statement">statement</glossary> is encountered or the <b>switch</b> <glossary tag="control structure">control structure</glossary> ends.<p></p><p>This means that if you do not end a <b>case</b> section's <i>statementList</i> with a <control_st tag="break">break</control_st> <glossary tag="statement">statement</glossary>, the <glossary tag="statement">statements</glossary> in all the following <keyword tag="case">case</keyword> sections (and the <keyword tag="default">default</keyword> section) are <glossary tag="execute">executed</glossary> even if those <keyword tag="case">case</keyword> sections don't have a matching <i>caseValue</i> or a true <i>caseCondition</i>. Occasionally, this behavior is useful. However, in most cases, you should place a <control_st tag="break">break</control_st> <glossary tag="statement">statement</glossary> at the end of each <i>statementList</i>. This ensures that only one <i>statementList</i> is <glossary tag="execute">executed</glossary>, and the rest are skipped.</p><p></p><p>This also means that you can attach more than one <i>caseValue</i> or <i>caseCondition</i> to the same <i>statementList</i>, simply by placing one <keyword tag="case">case</keyword> line above the next. The following example beeps if the <glossary tag="current card">current card</glossary> is either the last or first <keyword tag="card">card</keyword>, and goes to the next <keyword tag="card">card</keyword> otherwise:</p><p></p><p> switch (the number of this card)</p><p> case 1</p><p> case (the number of cards)</p><p> -- <i>both of the above case conditions execute the following</i></p><p> -- <i>statements:</i></p><p> beep</p><p> break</p><p> default</p><p> go next card</p><p> end switch</p><p></p><p>There is no limit to the number of <b>case</b> sections you can include in a <b>switch</b> <glossary tag="control structure">control structure</glossary>, although the more <keyword tag="case">case</keyword> sections there are, the more <glossary tag="expression">expressions</glossary> LiveCode must <glossary tag="evaluate">evaluate</glossary> and the more slowly the <b>switch</b> <glossary tag="control structure">structure</glossary> <glossary tag="execute">executes</glossary>. </p><p></p><p><b>Note:</b> The <b>switch</b> <glossary tag="control structure">control structure</glossary> is implemented internally as a <glossary tag="command">command</glossary> and appears in the <function tag="commandNames">commandNames</function>.</p></comments>

</description>

</doc>