<doc>
<legacy_id>1364</legacy_id>
<name>function</name>
<type>control structure</type>
<syntax>
<example>function <i>functionName </i>[<i>parametersList</i>] <i>statementList</i> end <i>functionName</i></example>
</syntax>
<synonyms>
</synonyms>
<summary>Defines a custom function <glossary tag="handler">handler</glossary>.</summary>
<examples>
<example><p>function myFunctioneturn "test"</p><p>end myFunction</p></example>
</examples>
<history>
<introduced version="1.0">Added.</introduced>
<deprecated version=""></deprecated>
<removed version=""></removed>
<experimental version=""></experimental>
<nonexperimental version=""></nonexperimental>
</history>
<objects>
</objects>
<platforms>
<mac/>
<windows/>
<linux/>
<ios/>
<android/>
</platforms>
<classes>
<desktop/>
<server/>
<web/>
<mobile/>
</classes>
<security>
</security>
<classification>
<category>Writing LiveCode</category>
</classification>
<references>
<function tag="param">param Function</function>
<function tag="paramCount">paramCount Function</function>
<function tag="functionNames">functionNames Function</function>
<keyword tag="private">private Keyword</keyword>
<keyword tag="$">$ Keyword</keyword>
<keyword tag="end">end Keyword</keyword>
<control_st tag="exit">exit Control Structure</control_st>
</references>
<description>Use the <b>function</b> <glossary tag="control structure">control structure</glossary> to implement a custom function.<p></p><p><b>Form:</b></p><p>The first line of a <b>function</b> <glossary tag="handler">handler</glossary> consists of the word "function" followed by the function's name. If the function has any <glossary tag="parameter">parameters</glossary>, their names come after the function name, separated by commas.</p><p></p><p>The last line of a <b>function</b> <glossary tag="handler">handler</glossary> consists of the word "end" followed by the function's name.</p><p></p><p><b>Parameters:</b></p><p>The <i>functionName</i> is a <keyword tag="string">string</keyword> up to 65,535 <keyword tag="characters">characters</keyword> in length.</p><p></p><p>The <i>parametersList</i> consists of one or more <glossary tag="parameter">parameter</glossary> names, separated by commas.</p><p></p><p>The <i>statementList</i> consists of one or more <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>.</p><p></p><p><b>Comments:</b></p><p>The purpose of a function is to compute a value and return it to the handler that called the function. The function's value is returned by a <b>return</b> <glossary tag="control structure">control structure</glossary> within the <b>function</b> <glossary tag="handler">handler</glossary>.</p><p></p><p>A function handler can contain any set of LiveCode statements. Most functions contain a <b>return</b> <glossary tag="statement">statement</glossary>, which <glossary tag="return">returns</glossary> the value to the <glossary tag="caller">calling handler</glossary>. This example of a custom function uses two <glossary tag="parameter">parameters</glossary> and <glossary tag="return">returns</glossary> a <keyword tag="string">string</keyword>:</p><p></p><p>function reversedName firstName,lastName</p><p><i>-- firstName and lastName are parameters</i></p><p>put lastName,firstName into constructedName</p><p>return constructedName</p><p>end reversedName</p><p></p><p>You create a custom function by writing a function handler for it. When you use the function in a script, the function call is passed through the message path. When it reaches the object whose script contains the <b>function</b> <glossary tag="handler">handler</glossary>, the <glossary tag="statement">statements</glossary> in the <glossary tag="handler">handler</glossary> are <glossary tag="execute">executed</glossary>.</p><p></p><p>A custom function is called by name, just like a built-in function, as part of an expression. For example, this handler calls the custom function above:</p><p></p><p>on mouseUp</p><p>ask "What is your first name?"</p><p>put it into firstParam</p><p>ask "What is your last name?"</p><p>put it into secondParam</p><p>put reversedName(firstParam,secondParam) into field "Name"</p><p>end mouseUp</p><p></p><p>A function can call itself. The following example calls itself to compute the factorial of an integer:</p><p></p><p>function factorial theNumber</p><p>if theNumber = 1 then return 1</p><p>else return theNumber * factorial(theNumber -1)</p><p>end factorial</p><p></p><p></p><p></p><p></p><note>To declare a function that is local to the script it is contained in, prefix the declaration with <keyword tag="private">private</keyword>. For more information about this see the dictionary entry for the <keyword tag="private">private keyword</keyword>.</note><p></p><p></p><p></p><p></p><note>As the <function tag="result">result</function> is a global property, if you do not explicitly <control_st tag="return">return</control_st> a value, then <function tag="result">the result</function> will not change, but reflect the last engine command, engine function or command or function handler that did return a value.</note><p></p><p></p><p></p><p></p><change></change>The ability to declare private functions using the private keyword was added in LiveCode 2.8.1</description>
</doc>
0 commit comments