<doc>
  <legacy_id>1556</legacy_id>
  <name>name</name>
  <type>property</type>
  <syntax>
    <example>set the [long | abbr[ev[iated] | short] name of <i>object </i>to<i> string</i></example>
    <example>get the name</example>
  </syntax>
  <library></library>
  <objects>
    <stack/>
    <card/>
    <group/>
    <field/>
    <button/>
    <graphic/>
    <scrollbar/>
    <player/>
    <image/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Objects &amp; Messages</category>
    <category>Standalone Applications</category>
  </classification>
  <references>
    <function tag="clickStack">clickStack Function</function>
    <function tag="mainStacks">mainStacks Function</function>
    <message tag="nameChanged">nameChanged Message</message>
    <property tag="hilitedButtonName">hilitedButtonName Property</property>
    <command tag="libURLSetLogField">libURLSetLogField Command</command>
    <property tag="titleWidth">titleWidth Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary>Specifies the name of an <glossary tag="object">object</glossary>.</summary>
  <examples>
    <example>set the name of the target to it</example>
    <example>set the name of last card button to "Bing!"</example>
  </examples>
  <description>
    <p>Use an object's <b>name</b> <glossary tag="property">property</glossary> to refer to the <glossary tag="object">object</glossary>.</p><p/><p><b>Value:</b></p><p>The <b>name</b> of an <glossary tag="object">object</glossary> is a <keyword tag="string">string</keyword>.</p><p/><p><b>Comments:</b></p><p>The short name of an object is simply the name that the object has been assigned. When you set an object's <b>name</b> <glossary tag="property">property</glossary> or type it into the <glossary tag="object">object's</glossary> <glossary tag="property inspector">property inspector</glossary>, the short name is what you provide.</p><p/><p>The abbreviated name of an object is the <glossary tag="object">object's</glossary> type followed by the <glossary tag="object">object's</glossary> short name in quotes. For example, if a <glossary tag="player">player's</glossary> short name is Heaven, its abbreviated name is player "Heaven". If you don't specify a modifier for the <b>name</b> <glossary tag="property">property</glossary>, the abbreviated name is what you get.</p><p/><p>The long name of an object includes information about its <property tag="owner">owner</property> (and about the <property tag="owner">owner</property> of that <glossary tag="object">object</glossary>, and so forth). For example, suppose a <object tag="stack">stack</object> named "My <object tag="stack">stack</object>" contains a <keyword tag="card">card</keyword> named "My Card". This <keyword tag="card">card</keyword> has a <command tag="group">group</command> named "My Group" which contains a <keyword tag="button">button</keyword> named "My Button". The <keyword tag="card">card</keyword> also has a <glossary tag="card control">card field</glossary> named "My Field". If "My Stack" is a <glossary tag="main stack">main stack</glossary> and it's in a <keyword tag="file">file</keyword> whose <glossary tag="file path">path</glossary> is "/Drive/Folder/Stack.rev", the long names of these <glossary tag="object">objects</glossary> look like this:</p><p/><p>* The stack:</p><p>   stack "/Drive/Folder/Stack.rev"</p><p>* The group:</p><p>   group "My Group" of stack "/Drive/Folder/Stack.rev"</p><p>* The card:</p><p>   card "My Card" of stack "/Drive/Folder/Stack.rev"</p><p>* The grouped button:</p><p>   button "My Button" of group "My Group" of card "My Card" of stack "/Drive/Folder/Stack.rev"</p><p>* The card field:</p><p>   field "My Field" of card "My Card" of stack "/Drive/Folder/Stack.rev"</p><p/><p><img src="202653"/> <b>Important!</b> On <glossary tag="OS X">OS X systems</glossary>, <glossary tag="standalone application">standalone applications</glossary> are stored as <glossary tag="application bundle">application bundles</glossary>. A <glossary tag="application bundle">bundle</glossary> behaves like a <keyword tag="file">file</keyword> but is actually a <property tag="defaultFolder">folder</property>, and the <glossary tag="main stack">main stack</glossary> of a <glossary tag="standalone application">standalone application</glossary> is inside this <property tag="defaultFolder">folder</property>. The long name of a stack in an application is the location of the application inside the <glossary tag="application bundle">bundle</glossary>, not the <glossary tag="application bundle">bundle's</glossary> location. For example, if the <glossary tag="application bundle">bundle'sfile path</glossary> is "/Volumes/Disk/MyApp.app/", the long name of the application's main stack might be "/Volumes/Disk/MyApp.app/Contents/MacOS/MyApp".</p><p/><p>If the stack is a substack, its name is included in the long names of its objects, before the path of the main stack:</p><p>  stack "My Substack" of stack "/Drive/Folder/Stack.rev"</p><p/><p>The long <b>name</b> of a <command tag="group">group</command> includes the name of the <glossary tag="current card">current card</glossary>. If the <command tag="group">group</command> does not appear on the <glossary tag="current card">current card</glossary>, requesting its <b>name</b> results in an <glossary tag="execution error">execution error</glossary>. If you need to get the name of a <command tag="group">group</command> that is not on the <glossary tag="current card">current card</glossary>, use the "<object tag="group">background</object>" terminology instead.</p><p/><p>The long <b>name</b> of a <object tag="group">background</object> includes the name of the <glossary tag="current card">current card</glossary>, if the <object tag="group">background</object> appears on the <glossary tag="current card">current card</glossary>. If not, the long name of the <object tag="group">background</object> includes the name of the first <keyword tag="card">card</keyword> the <object tag="group">background</object> appears on.</p><p/><p>You can use an object's <b>name</b> to refer to the <glossary tag="object">object</glossary> in a <glossary tag="statement">statement</glossary>. However, the <b>name</b> need not be seen on screen, even if the <glossary tag="object">object</glossary> is one that normally has a visible name (such as a <keyword tag="button">button</keyword>). If a <object tag="stack">stack</object> or <glossary tag="control">control's</glossary> <property tag="label">label</property> <glossary tag="property">property</glossary> is not empty, the <property tag="label">label</property> <glossary tag="property">property</glossary> is used when a visible label is displayed. If a <glossary tag="stack">stack's</glossary> <property tag="label">label</property> <glossary tag="property">property</glossary> is empty, its <b>name</b> is used as the window title. Likewise, if a <glossary tag="control">control's</glossary> <property tag="label">label</property> <glossary tag="property">property</glossary> is empty, its <b>name</b> is used as the label. This means that you can use any <keyword tag="string">string</keyword> you want for the <b>name</b> without worrying about the user-interface impact on your application: if the <b>name</b> is not user-friendly, set the <property tag="label">label</property> to something that is.</p><p/><p>A stack's <b>name</b> cannot be empty. (Other <glossary tag="object">objects</glossary> can have empty names.) Attempting to set a <glossary tag="stack">stack's</glossary> <b>name</b> to empty does not rename it.</p><p/><p>If an object's <b>name</b> is empty, getting its <property tag="name">name</property> yields its <property tag="ID">ID</property> <glossary tag="property">property</glossary> instead. In this case, the abbreviated ID form is always reported, regardless of what form of the <b>name</b> <glossary tag="property">property</glossary> you request.</p><p/><p><img src="202650"/> <b>Caution!</b> Avoid naming an <glossary tag="object">object</glossary> with a number. Doing so may cause LiveCode to become confused by <href tag="reference/object_reference.rev">object references</href> that specify that number, since they might be referring to the <glossary tag="object">object</glossary> by name or to a different <glossary tag="object">object</glossary> by number.</p><p/><p><img src="202650"/> <b>Caution!</b> Avoid giving two <glossary tag="control">controls</glossary> in the same <object tag="stack">stack</object> the same name. Doing so may cause problems if you use the Geometry <glossary tag="pane">pane</glossary> in the <glossary tag="property inspector">property inspector</glossary> or the Animation Builder.</p><p/><p><img src="202650"/> <b>Caution!</b> Avoid using "rev" as the first three <keyword tag="characters">characters</keyword> of a <glossary tag="stack">stack's </glossary> <b>name</b>. These <keyword tag="characters">characters</keyword> are reserved for <function tag="stacks">stacks</function> that are part of the LiveCode <glossary tag="development environment">development environment</glossary>, and giving a non-LiveCode <object tag="stack">stack</object> such a name may cause menus or buttons to be inappropriately disabled, or other problems. You can use the <keyword tag="characters">characters</keyword> "rev" anywhere in a <object tag="stack">stack</object> <b>name</b> except the beginning. If you want a name beginning with "rev" to appear in a stack's title bar, set the stacks' <property tag="label">label property</property> instead.</p><p/><p><b>Note:</b> If a stack's <property tag="HCAddressing">HCAddressing property</property> is set to true, the <keyword tag="long">long</keyword> or <keyword tag="abbreviated">abbreviated</keyword> <b>name</b> of a <keyword tag="control">control</keyword> in that <object tag="stack">stack</object> begins with the word "background" if the <keyword tag="control">control</keyword> is part of a <command tag="group">group</command>, and with the word "card" if not.</p>
  </description>
</doc>