Name: cancel

Type: command

Syntax: cancel <messageQueueID>

Summary:
Removes a <message> that was queued with the <send> <command>
and is waiting to be sent.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server

Example:
cancel 2298

Example:
cancel item 1 of last line of the pendingMessages

Example:
# Assume these two handlers in a card script.
# Call scheduleBeep to queue a message
# Call cancelBeep to cancel the pending message

local sMessageID

on scheduleBeep
  send "beep" to this card in 20 seconds
  put the result into sMessageID
end scheduleBeep

on cancelBeep
  cancel sMessageID
end cancelBeep

Parameters:
messageQueueID (integer):
The ID number of the message.

Description:
Use the <cancel> <command> to get rid of <message|messages> that were
set up but are no longer required.

The ID number of the message is returned by the <send> <command> that
sent the <message>. This number is also the first <item> of the line
corresponding to the message in the <pendingMessages> <function>.

All <pendingMessages|pending messages> are automatically canceled when 
the application quits.

It is common to need to <cancel> a number of <message|messages> when
leaving a <card> or <stack>, if the <message|messages> only pertain to
that card or stack. For example, you might have queued a number of
<message|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 <messageQueueID>
in a <script local variable>, a <global> <variable>, or a 
<custom property> at the time the <message> is sent. Then you can 
<cancel> all those <message|messages> in a <repeat> <loop> :

    global gMyPendingMessages # you've stored the message IDs here
    on closeCard
      repeat for each line tThisMessageID in gMyPendingMessages
        cancel tThisMessageID
      end repeat
    end closeCard


References: send (command), function (control structure),
repeat (control structure), flushEvents (function), 
pendingMessages (function), result (function), command (glossary), 
custom property (glossary), global (glossary), loop (glossary), 
message (glossary), script local variable (glossary), 
variable (glossary), item (keyword), card (object), stack (object)

Tags: messages