Name: icon

Type: property

Syntax: set the icon to {<imageID> | <imageName>}

Syntax: set the icon of {<button> | <stack>} to {<imageID> | <imageName>}

Summary:
Specifies an <image> that is displayed in a <button>, or used as the
<desktop> icon of a <stack file> or application.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
set the icon of this stack to kStackIcon

Example:
set the icon of button "Help" to "Question Mark"

Example:
set the icon to the myAppIcon of stack "Main Settings"

Parameters:
imageID:
The id of the image to use for the button or stack icon or current
application's dock icon

imageName:
The short name of the image to use for the button or stack icon or
current application's dock icon

Value:
By default, the <icon> property is set to zero (no icon). The <icon> of
newly created <button|buttons> and <stacks> is set to zero (no <icon>)
by <default>.

Description:
Use the <icon> <property> to change a <button(object)|button's>
appearance, or to set the <icon> used for a <stack> or <application> in
the <OS X> dock.

LiveCode looks for the specified image in the following order:

* 1. The stack of the object's <behavior> (if applicable)
* 2. The stack of the owner of the object's <behavior> (if applicable)
*    ...
* n. The stack of the object's stack's <behavior> (if applicable)
* A. The object's stack
* B. The object's stack's mainstack (if a substack)
* C. The object's stack's mainstack's substacks
* D. The list of open stacks, in order they were loaded

If a button has been clicked during the current session and its
visitedIcon <property> is set, its <visitedIcon> is displayed instead of
its <icon>. If the button is disabled and its <disabledIcon> <property>
is set, its <disabledIcon> is displayed instead of its <icon>.

>*Cross-platform note:* On <OS X|OS X systems>, a <stack|stack's>
> <icon> is displayed in the dock when the stack is minimized. On
> <Unix|Unix systems>, the <stack|stack's> <icon> is displayed on the
> <desktop> when the <stack> is <iconify|iconified>. Setting a
> <stack|stack's> <icon> <property> has no effect on <Mac OS> and
> <Windows|Windows systems>.

>*Cross-platform note:* On OS X systems, the global <icon> property
> specifies the current application's <dock (glossary)> <icon>. 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 <global> icon <property> has no effect on <Mac OS>,
> <Unix>, or <Windows|Windows systems>.

>*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. 

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 <icon> was a
<button(keyword)> and <stack> <property> but not a <global|global
property>, and the <icon> of a <stack> had no effect on <OS X|OS X
systems>. 

Changes:
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.

References: global (command), stacks (function), property (glossary),
OS X (glossary), global (glossary), stack file (glossary),
dock (glossary), desktop (glossary), Windows (glossary),
Mac OS (glossary), Unix (glossary), iconify (glossary),
application (glossary), default (keyword), image (keyword),
button (keyword), iconifyStack (message), stack (object), button (object),
visitedIcon (property), hilitedIcon (property), icon (property),
behavior (property), armedIcon (property), disabledIcon (property)

Tags: file system

