Name: setProp

Type: control structure

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

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

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,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 <Revolution|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> can be located in the <object|object's> <script> or in the <script> of any <object> 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>, no <setProp> <trigger> is sent to the <object>. (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> 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>, and the first <object> 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> on the <card>, runaway <recursion> will result:

  setProp myCustomProperty newValue
    set the myCustomProperty of the target to newValue + 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[thisProperty] newValue
    if thisProperty is "that" then put newValue 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: properties (property), customPropertySets (property), customProperties (property), call (command), set (command), card (keyword), $ (keyword), stack (object), object (object), propertyNames (function), paramCount (function), value (function), pass (control_st), exit (control_st), setProp (control_st), statement (glossary), handler (glossary), property (glossary), recursion (glossary), command (glossary), Revolution (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), button (glossary)
