Name: setProp

Type: control structure

Syntax:
setProp <propertyName> <newValue>
   <statementList>
end <propertyName>

Summary:
<handle|Handles> the <trigger> sent to an <object(glossary)> when you
change one of its <custom property|custom properties>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Parameters:
newValue (string):


statementList:
The statementList consists of one or more LiveCode statements, and can
also include if, switch, try, or repeat control structures.

propertyName (string):
A string up to 65,535 characters in length.

Description:
Use the <setProp> <control structure> to check the range of a 
<custom property> that is being set, or to change other 
<property|properties> or do other tasks at the same time a
<custom property> is set. 

**Form:** The first line of a <setProp> <handler> consists of the word 
"setProp" followed by the name of the <custom property>.

The last line of a <setProp> <handler> consists of the word "end"
followed by the <property|property's> name.

A <setProp> <handler> can contain any set of <LiveCode>
<statement|statements>. 

The <propertyName> is the name of the <custom property> whose <value> is
being changed with the <set> <command>.

>*Note:* You cannot use a <setProp> <handler> to intercept a built-in
> <property>. The <setProp> <control structure> can be used only for
> <custom property|custom properties>.

The <setProp> <trigger> passes through the <message path>, the same as
any other <message>, so a <setProp> <handler> for an <object(glossary)>
can be located in the <object|object's> <script> or in the <script> of
any <object(glossary)> further in the <message path>. For example, a
<setProp> <handler> for a card <property> may be located in the <script>
of the <stack> that the <card> belongs to.

If you use the set <command> within a <setProp> <control structure> to
set the same <custom property> for the current <object(glossary)>, no
<setProp> <trigger> is sent to the <object(glossary)>. (This is to avoid
runaway <recursion>, where the <setProp> <handler> <trigger|triggers>
itself.) 

This is only the case for the custom property that the current <setProp>
<handler> applies to. Setting a different <custom property> sends a
<setProp> <trigger>. So does setting the <handler|handler's> 
<custom property> for an <object(glossary)> other than the one whose
script contains the <setProp> <handler>.

>*Warning:*  If a <setProp> <handler> in one <object|object's> <script>
> sets the <custom property> for a different <object(glossary)>, and the
> first <object(glossary)> is in the second <object|object's>
> <message path>, a runaway <recursion> will result. For example, if the
> following <handler> is in a <card> <script>, and you set the
> "myCustomProperty" of a <button(object)> on the <card>, runaway
> <recursion> will result:

    setProp myCustomProperty pValue
        set the myCustomProperty of the target to pValue + 1
        -- Because the target is the button, and this handler is in
        -- the card, the above statement sends another setProp trigger
        -- to the button.
    end myCustomProperty


To avoid this problem, set the lockMessages property to true before
setting the custom property.

You can include as many <setProp> <handler|handlers> in a <script> as
you need. The <property> that a <setProp> <handler> controls is
determined by the <propertyName> <parameter> in the first line of the
<handler>. (If a <script> contains two <setProp> <handler|handlers> for
the same <property>, the first one is used.)

If the custom property you want to control is in a custom property set,
use array notation in the first line of the <setProp> <handler>, as in
the following example:

    setProp mySet[pProperty] pValue
        if pProperty is "that" then put pValue into me
    end setProp


The above <setProp> <handler> responds to changes in the
<custom property> named "that", which is a member of the custom
<custom property set|property set> named "mySet".

>*Important:*  You must either include the <pass> <control structure> or
> set the <property> explicitly in a <setProp> <handler>, if you want
> LiveCode to set the <custom property>. Otherwise, the <setProp>
> <handler> <trap|traps> the <call> to set the <property>, and its
> <value> is not changed.

Changes:
In version 2.0 and later, setting a custom property (other than the one
that the current setProp handler applies to) inside a setProp handler
sends a setProp trigger. In previous versions, setting a custom property
within a setProp handler never sent a setProp trigger, regardless of
which custom property you set.

References: call (command), set (command), pass (control structure),
exit (control structure), setProp (control structure),
propertyNames (function), paramCount (function), value (function),
object (glossary), statement (glossary), handler (glossary),
property (glossary), recursion (glossary), command (glossary),
LiveCode (glossary), control structure (glossary),
custom property set (glossary), trigger (glossary),
custom property (glossary), handle (glossary), message path (glossary),
trap (glossary), message (glossary), parameter (glossary),
script (glossary), card (keyword), $ (keyword), stack (object),
button (object), properties (property), customPropertySets (property),
customProperties (property)

