<doc>
	<legacy_id>1367</legacy_id>
	<name>icon</name>
	<type>property</type>

	<syntax>
		<example>set the icon to {<i>imageID</i> | <i>imageName</i>}</example>
		<example>set the icon of {<i>button</i> | <i>stack</i>} to {<i>imageID</i> | <i>imageName</i>}</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Specifies an <keyword tag="image">image</keyword> that is displayed in a <keyword tag="button">button</keyword>, or used as the <glossary tag="desktop">desktop</glossary> icon of a <glossary tag="stack file">stack file</glossary> or application.</summary>

	<examples>
<example>set the icon of this stack to kStackIcon</example>
<example>set the icon of button "Help" to "Question Mark"</example>
<example><p>set the icon to the myAppIcon of stack "Main Settings"</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="3.5">3.5</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
		<global/>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Appearance &amp; Positioning</category>
		<category>Files, Folders, &amp; Resources</category>
	</classification>

	<references>
		<property tag="armedIcon">armedIcon Property</property>
		<property tag="hilitedIcon">hilitedIcon Property</property>
		<message tag="iconifyStack">iconifyStack Message</message>
	</references>

	<description>
	<overview>Use the <b>icon</b> <glossary tag="property">property</glossary> to change a <glossary tag="button">button's</glossary> appearance, or to set the <property tag="icon">icon</property> used for a <object tag="stack">stack</object> or <glossary tag="application">application</glossary> in the <glossary tag="OS X">OS X</glossary> dock.</overview>

		<parameters>
<parameter>
<name>imageID</name>
<description>The id of the image to use for the button or stack icon or current application's dock icon </description>
</parameter>
<parameter>
<name>imageName</name>
<description>The short name of the image to use for the button or stack icon or current application's dock icon </description>
</parameter>		</parameters>

	<value>By default, the <b>icon</b> property is set to zero (no icon). The <b>icon</b> of newly created <glossary tag="button">buttons</glossary> and <function tag="stacks">stacks</function> is set to zero (no <property tag="icon">icon</property>) by <keyword tag="default">default</keyword>.</value>
	<comments>LiveCode looks for the specified image in the following order:<p></p><p>1) The stack of the object's <property tag="behavior">behavior</property> (if applicable)</p><p>2) The stack of the owner of the object's <property tag="behavior">behavior</property> (if applicable)</p><p> ...</p><p>n) The stack of the object's stack's <property tag="behavior">behavior</property> (if applicable)</p><p>A) The object's stack</p><p>B) The object's stack's mainstack (if a substack)</p><p>C) The object's stack's mainstacks substacks</p><p>D) The list of open stacks, in order they were loaded</p><p></p><p>If a button has been clicked during the current session and its <b>visitedIcon</b> <glossary tag="property">property</glossary> is set, its <property tag="visitedIcon">visitedIcon</property> is displayed instead of its <b>icon</b>. If the button is disabled and its <property tag="disabledIcon">disabledIcon</property> <glossary tag="property">property</glossary> is set, its <property tag="disabledIcon">disabledIcon</property> is displayed instead of its <b>icon</b>.</p><p></p><p></p><cp_note>On <glossary tag="OS X">OS X systems</glossary>, a <glossary tag="stack">stack's </glossary><b>icon</b> is displayed in the dock when the stack is minimized. On <glossary tag="Unix">Unix systems</glossary>, the <glossary tag="stack">stack's</glossary><b>icon</b> is displayed on the <glossary tag="desktop">desktop</glossary> when the <object tag="stack">stack</object> is <glossary tag="iconify">iconified</glossary>. Setting a <glossary tag="stack">stack's</glossary><b>icon</b><glossary tag="property">property</glossary> has no effect on <glossary tag="Mac OS">Mac OS</glossary> and <glossary tag="Windows">Windows systems</glossary>.</cp_note><p></p><p></p><cp_note>On OS X systems, the global <b>icon</b> property specifies the current application's <glossary tag="dock">dock </glossary><property tag="icon">icon</property>. The engine will attempt to find an image with the given id, resize it to 128x128 and then set it as the dock icon for the application. The setting of the <command tag="global">global</command><b> icon </b><glossary tag="property">property</glossary> has no effect on <glossary tag="Mac OS">Mac OS</glossary>, <glossary tag="Unix">Unix</glossary>, or <glossary tag="Windows">Windows systems</glossary>.</cp_note><p></p><note>The image is only guaranteed to persist while the application runs, although in some cases the OS does appear to cache it beyond this.</note><p></p><change><p>The order in which LiveCode searches for icons was changed in version 3.5. Previously, the current stack was searched first, followed by the list of open stacks.</change><p></p><p>The ability to specify an icon for an application or stack file on OS X systems was added in version 2.1. In previous versions, the <b>icon</b> was a <keyword tag="button">button</keyword> and <object tag="stack">stack</object> <glossary tag="property">property</glossary> but not a <glossary tag="global">global property</glossary>, and the <b>icon</b> of a <object tag="stack">stack</object> had no effect on <glossary tag="OS X">OS X systems</glossary>.</p></comments>
	</description>
</doc>