<doc>

<legacy_id>1041</legacy_id>

<name>cancel</name>

<type>command</type>

<syntax>

<example>cancel <i>messageQueueID</i></example>

</syntax>

<synonyms>

</synonyms>

<summary>Removes a <keyword tag="message box">message</keyword> that was queued with the <command tag="send">send</command> <glossary tag="command">command</glossary> and is waiting to be sent.</summary>

<examples>

<example>cancel 2298</example>

<example>cancel item 1 of last line of the pendingMessages</example>

</examples>

<history>

<introduced version="1.0">Added.</introduced>

<deprecated version=""></deprecated>

<removed version=""></removed>

<experimental version=""></experimental>

<nonexperimental version=""></nonexperimental>

</history>

<objects>

</objects>

<platforms>

<mac/>

<windows/>

<linux/>

<ios/>

<android/>

</platforms>

<classes>

<desktop/>

<server/>

<web/>

</classes>

<security>

</security>

<classification>

<category>Objects &amp; Messages</category>

</classification>

<references>

<function tag="pendingMessages">pendingMessages Function</function>

<function tag="flushEvents">flushEvents Function</function>

<command tag="send">send Command</command>

</references>

<description>Use the <b>cancel</b> <glossary tag="command">command</glossary> to get rid of <glossary tag="message">messages</glossary> that were set up but are no longer required.<p></p><p><b>Parameters:</b></p><p>The <i>messageQueueID</i> is the ID number of the <keyword tag="message box">message</keyword>.</p><p></p><p><b>Comments:</b></p><p>The ID number of the message is returned by the <b>send</b> <glossary tag="command">command</glossary> that sent the <keyword tag="message box">message</keyword>. This number is also the first <keyword tag="item">item</keyword> of the line corresponding to the message in the <function tag="pendingMessages">pendingMessages</function> <control_st tag="function">function</control_st>.</p><p></p><p>All pending messages are automatically canceled when the application quits.</p><p></p><p>It is common to need to cancel a number of messages when leaving a card or stack, if the messages only pertain to that card or stack. For example, you might have queued a number of messages that create an animated display on the current card, and need to cancel them when the user goes to another card. The best solution in a case like this is to place each message ID number in a global variable or custom property at the time the <keyword tag="message box">message</keyword> is sent. Then you can cancel all those <glossary tag="message">messages</glossary> in a <control_st tag="repeat">repeat</control_st> <glossary tag="loop">loop</glossary>:</p><p></p><p></p><p> global myPendingMessages -- you've stored the message IDs here</p><p> repeat for each line thisMessageID in myPendingMessages</p><p> cancel thisMessageID</p><p> end repeat</p><p> end closeCard</p></description>

</doc>