<doc>
	<legacy_id>1750</legacy_id>
	<name>cursor</name>
	<type>property</type>

	<syntax>
		<example>set the cursor to {<i>cursorName</i> | <i>imageID</i>}</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Specifies the shape of the <property tag="cursor">cursor</property>.</summary>

	<examples>
<example>set the cursor to watch</example>
<example>set the cursor to arrow</example>
<example><p>set the cursor to 21403</p></example>
	</examples>

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

	<objects>
		<global/>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
	</platforms>

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

	<security>
	</security>


	<classification>
		<category>User Interaction</category>
	</classification>

	<references>
		<command tag="lock cursor">lock cursor Command</command>
		<property tag="yHot">yHot Property</property>
		<property tag="lockCursor">lockCursor Property</property>
	</references>

	<description>Use the <b>cursor</b> <glossary tag="property">property</glossary> to signal the status of a <glossary tag="handler">handler</glossary> to the user or to indicate what kind of data the <glossary tag="mouse pointer">mouse pointer</glossary> is over. For example, a watch <property tag="cursor">cursor</property> shows the user that a <glossary tag="handler">handler</glossary> is <glossary tag="execute">executing</glossary>, while an I-beam <property tag="cursor">cursor</property> indicates that the text under the <glossary tag="mouse pointer">mouse pointer</glossary> is editable.<p></p><p><b>Value:</b></p><p>The <b>cursor</b> is the <property tag="ID">ID</property> of an <keyword tag="image">image</keyword> to use for a <property tag="cursor">cursor</property>. </p><p></p><p>LiveCode looks for the specified image in the following order:</p><p></p><p>1) The stack of the current object's <property tag="behavior">behavior</property> (if applicable)</p><p>2) The stack of the owner of the current object's <property tag="behavior">behavior</property> (if applicable)</p><p> ...</p><p>n) The stack of the current object's stack's <property tag="behavior">behavior</property> (if applicable)</p><p>A) The current object's stack</p><p>B) The current object's stack's mainstack (if a substack)</p><p>C) The current object's stack's mainstacks substacks</p><p>D) The list of open stacks, in order they were loaded</p><p></p><p>LiveCode includes several built-in cursors whose names you can use in place of their image IDs.</p><p></p><p><b>Comments:</b></p><p>The built-in cursors and their recommended uses are:</p><p>        * <b>none</b>: Hides the cursor</p><p>        * <b>busy</b>: Use repeatedly during a long handler</p><p>        * <b>watch</b>: Use during a moderately long handler</p><p>        * <b>arrow</b>: Use for <glossary tag="select">selecting</glossary> objects</p><p>        * <b>cross</b>: Use for painting, drawing, or <glossary tag="select">selecting</glossary> a <keyword tag="point">point</keyword> or small area</p><p>        * <b>hand</b>: Use for clicking <glossary tag="hypertext">hypertext</glossary> links</p><p>        * <b>iBeam</b>: Use for <glossary tag="select">selecting</glossary> text in a field</p><p>        * <b>plus</b>: Use for <glossary tag="select">selecting</glossary> <keyword tag="items">items</keyword> such as spreadsheet cells</p><p>        * <b>help</b>: Use for getting online help</p><p></p><p>The <b>busy</b> cursor is a rotating beach ball. Each time you use the statement set the cursor to busy, the beach ball advances in its rotation. For example, the following statements cause the <property tag="cursor">cursor</property> to appear to spin as long as the <control_st tag="repeat">repeat</control_st> <glossary tag="loop">loop</glossary> is running:</p><p></p><p>  repeat until someCondition is true</p><p>    set the cursor to busy <i>-- spins a bit further</i></p><p>    doSomething <i>-- insert whatever you want the loop to do here</i></p><p>  end repeat</p><p></p><p>You can also set the cursor property to the <b>ID</b> of an image. Custom cursor <glossary tag="image">images</glossary> must contain three colors: black, white, and a transparent color.</p><p></p><p></p><cp_note></cp_note><p>&#9;* Windows XP and above support full alpha-blended cursors up to 64x64</p><p>&#9;* More recent Linux distributions support alpha-blended cursors up to a size of 64x64</p><p>&#9;* Mac OS X supports alpha-blended cursors up to 256x256</p><p></p><p></p><note>Alpha-blending support depends on the current screen depth on some platforms.</note><p></p><p>If the <b>lockCursor</b> <glossary tag="property">property</glossary> is set to false, LiveCode automatically sets the <property tag="cursor">cursor</property> according to its location once the <glossary tag="handler">handler</glossary> finishes. (For example, the <property tag="cursor">cursor</property> normally turns into an arrow over a menu, an I-beam over an editable text <keyword tag="field">field</keyword>, and so on.) To retain the <b>cursor</b> <glossary tag="property">property</glossary> after a <glossary tag="handler">handler</glossary> finishes, use the <command tag="lock cursor">lock cursor</command> <glossary tag="command">command</glossary>.</p><p></p><p>You can force LiveCode to use the operating system's cursors with the following two statements:</p><p></p><p>  delete stack &quot;revCursors&quot;</p><p>  reset cursors</p><p></p><p><b>Caution!</b> If you use the <command tag="delete stack">delete stack</command> command to remove the &quot;revCursors&quot; <object tag="stack">stack</object>, LiveCode's <glossary tag="cursor">cursors</glossary> are permanently deleted and you will need to <glossary tag="download">download</glossary> a new cursors <object tag="stack">stack</object> to restore them.</p><p></p><p>If you change the set of built-in LiveCode cursors in the &quot;revCursors&quot; stack, you must either quit and restart the application or use the <b>reset cursors</b> <glossary tag="command">command</glossary> to begin using the new <property tag="cursor">cursor</property> shapes.</p><p></p><p></p><change><p>The order in which LiveCode searches for cursors was changed in version 3.5. Previously, the current stack was searched first, followed by the list of open stacks.</p><p>The ability to use large and alpha-blended cursors was introduced in version 4.0.</p></change></description>
</doc>