<doc>
  <legacy_id>2215</legacy_id>
  <name>lockCursor</name>
  <type>property</type>
  <syntax>
    <example>set the lockCursor to {true | false}</example>
  </syntax>
  <library></library>
  <objects>
    <global/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>User Interaction</category>
  </classification>
  <references>
    <command tag="lock cursor">lock cursor Command</command>
    <command tag="unlock cursor">unlock cursor Command</command>
    <property tag="lockLocation">lockLocation Property</property>
    <property tag="lockScreen">lockScreen Property</property>
    <property tag="cursor">cursor Property</property>
    <property tag="defaultCursor">defaultCursor Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
  </classes>
  <security>
  </security>
  <summary>Specifies whether the <property tag="cursor">cursor</property> shape changes depending on the current <function tag="tool">tool</function> and what the <glossary tag="mouse pointer">mouse pointer</glossary> is over.</summary>
  <examples>
    <example>set the lockCursor to true</example>
  </examples>
  <description>
    <p>Use the <b>lockCursor</b> <glossary tag="property">property</glossary> to set a custom <property tag="cursor">cursor</property> that persists after the <glossary tag="handler">handler</glossary> <glossary tag="exit">exits</glossary>.</p><p/><p><b>Value:</b></p><p>The <b>lockCursor</b> is true or false.</p><p/><p>By default, the <b>lockCursor</b> <glossary tag="property">property</glossary> is set to false.</p><p/><p><b>Comments:</b></p><p>If the <b>lockCursor</b> <glossary tag="property">property</glossary> is set to true, the <property tag="cursor">cursor</property> shape can be set only by a <glossary tag="handler">handler</glossary>, and does not change shape automatically as the mouse moves. (For example, the <property tag="cursor">cursor</property> normally turns into an arrow over a <keyword tag="menu">menu</keyword>, an I-beam over an editable <keyword tag="field">field</keyword>, and so on.) If the <b>lockCursor</b> is false, the <property tag="cursor">cursor</property> automatically changes shape according to its location.</p><p/><p>For example, to set a custom cursor while the mouse pointer is over a certain field, set the <b>lockCursor</b> to true and then set the <property tag="cursor">cursor</property> to the desired shape in a <message tag="mouseEnter">mouseEnter</message> <glossary tag="handler">handler</glossary>. In the <glossary tag="field">field's</glossary> <message tag="mouseLeave">mouseLeave</message> <glossary tag="handler">handler</glossary>, set the <b>lockCursor</b> to false to allow the <property tag="cursor">cursor</property> to automatically change shape.</p><p/><p><code/><img src="202653"/> <b>Important!</b><code/> If the <b>lockCursor</b> is true, changes made by a <glossary tag="handler">handler</glossary> to the <property tag="cursor">cursor</property> still take effect. This means that if a stack locks the <property tag="cursor">cursor</property> and a <glossary tag="handler">handler</glossary> in another stack sets the <property tag="cursor">cursor</property> to another shape, the <property tag="cursor">cursor</property> changes to that shape and does not change back until the <property tag="cursor">cursor</property> is changed or the <b>lockCursor</b> is set to false. If you <glossary tag="lock">lock</glossary> the <property tag="cursor">cursor</property>, make sure to unlock it as soon as the <object tag="stack">stack</object> no longer needs it.</p>
  </description>
</doc>