<doc>
  <legacy_id>1967</legacy_id>
  <name>dragDrop</name>
  <type>message</type>
  <syntax>
    <example>dragDrop</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>User Interaction</category>
  </classification>
  <references>
    <function tag="dropChunk">dropChunk Function</function>
    <message tag="dragEnd">dragEnd Message</message>
    <function tag="dragSource">dragSource Function</function>
    <property tag="dragData">dragData Property</property>
    <property tag="dragAction">dragAction Property</property>
    <property tag="dragImageOffset">dragImageOffset Property</property>
  </references>
  <history>
    <introduced version="2.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
  </classes>
  <security>
  </security>
  <summary>Sent to the <glossary tag="object">object</glossary> where data was dropped when a <glossary tag="drag and drop">drag and drop</glossary> finishes.</summary>
  <examples>
    <example>on dragDrop <code><i>-- check whether a file is being dropped</i></code></p><p>  if the dragData["files"] is empty then beep 2</p><p>  pass dragDrop</p><p>end dragDrop</example>
  </examples>
  <description>
    <p>Handle the <b>dragDrop</b> <keyword tag="message box">message</keyword> to perform an action when the user drops data, or <glossary tag="trap">trap</glossary> the <keyword tag="message box">message</keyword> to prevent text from being dropped.</p><p/><p><b>Comments:</b></p><p>The <b>dragDrop</b> <keyword tag="message box">message</keyword> is sent to the <keyword tag="control">control</keyword> where data is being dragged.</p><p/><p><code/><img src="202653"/> <b>Important!</b><code/> If the <property tag="acceptDrop">acceptDrop</property> <glossary tag="property">property</glossary> is set to false at the time the drop occurs, no <b>dragDrop</b> <keyword tag="message box">message</keyword> is sent.</p><p/><p>LiveCode automatically handles the mechanics of dragging and dropping text between and within unlocked fields. To support this type of drag and drop operation, you don't need to do any scripting: the text is dropped into the field automatically when LiveCode receives the <b>dragDrop</b> <keyword tag="message box">message</keyword>.</p><p/><p>To prevent an unlocked field from accepting a drag and drop, trap the <b>dragDrop</b> <keyword tag="message box">message</keyword>. If you don't want to allow a particular <keyword tag="field">field</keyword> to accept text drops, place a <b>dragDrop</b> <glossary tag="handler">handler</glossary> in the field that does not contain a <control_st tag="pass">pass</control_st> <glossary tag="control structure">control structure</glossary>:</p><p/><p><code>  on dragDrop </code><code><i>-- in script of field or one of its owners</i></code></p><p><code>    </code><code><i>-- do nothing, but trap the message</i></code></p><p><code>  end dragDrop</code></p><p/><p>On the other hand, if you want to perform some action when text is dropped into an unlocked field, you need to pass the <b>dragDrop</b> <keyword tag="message box">message</keyword> once you're done with it in order to allow the drop to take place:</p><p/><p><code>  on dragDrop</code></p><p><code>    set the cursor to 9023</code></p><p><code>    pass dragDrop </code><code><i>-- needed for drop to occur</i></code></p><p><code>  end dragDrop</code></p><p/><p>To accept drops to a locked field or a control other than a field, handle the <b>dragDrop</b> message, using the <property tag="dragData">dragData</property> <glossary tag="property">property</glossary> to determine what data is being dragged. For these objects, your <b>dragDrop</b> <glossary tag="handler">handler</glossary> must get the dragged data and put it into the <glossary tag="object">object</glossary> (or perform whatever action you want to do on a drop); the behavior is not automated as it is for <glossary tag="unlock">unlocked</glossary> <glossary tag="field">fields</glossary>.</p>
  </description>
</doc>