docs/commands/OnClipboardChange.htm

<!DOCTYPE HTML>
<html lang="en">
<head>
<title>OnClipboardChange - Syntax &amp; Usage | AutoHotkey v2</title>
<meta name="description" content="The OnClipboardChange function registers a function or function object to run whenever the clipboard's content changes." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>OnClipboardChange</h1>

<p>Registers a <a href="../Functions.htm">function</a> or <a href="../objects/Functor.htm">function object</a> to run whenever the clipboard's content changes.</p>

<pre class="Syntax"><span class="func">OnClipboardChange</span> Func <span class="optional">, AddRemove</span></pre>
<h2>Parameters</h2>
<dl>

  <dt>Func</dt>
  <dd>
    <p>Type: <a href="../Concepts.htm#strings">String</a> or <a href="../Concepts.htm#objects">Object</a></p>
    <p>A function name or <a href="../objects/Functor.htm">function object</a> to call. The function's parameter and return value are described <a href="#Func">below</a>.</p>
  </dd>
  
  <dt>AddRemove</dt>
  <dd>
    <p>Type: <a href="../Concepts.htm#numbers">Integer</a></p>
    <p>One of the following values:<br>
    <strong>1</strong> (the default): Call the function after any previously registered functions.<br>
    <strong>-1</strong>: Call the function before any previously registered functions.<br>
    <strong>0</strong>: Do not call the function.</p>
  </dd>

</dl>

<h2 id="Func">Func</h2>
<pre class="Syntax"><i>FunctionName</i>(Type)</pre>
<dl>
  <dt>Type</dt>
  <dd>
    <p>Type: <a href="../Concepts.htm#numbers">Integer</a></p>
    <p>Contains one of the following values:<br>
    <strong>0</strong> if the clipboard is now empty;<br>
    <strong>1</strong> if it contains something that can be expressed as text (this includes <a href="../misc/A_Clipboard.htm#CopiedFiles">files copied</a> from an Explorer window);<br>
    <strong>2</strong> if it contains something entirely non-text such as a picture.</p>
  </dd>
  
  <dt><em>Return Value</em></dt>
  <dd>
    <p>Type: <a href="../Concepts.htm#numbers">Integer</a></p>
    <p>If this is the last or only OnClipboardChange function, the return value is ignored. Otherwise, the function can return a non-zero integer to prevent subsequent functions from being called.</p>
  </dd>
</dl>

<h2>Remarks</h2>
<p>If the clipboard changes while an OnClipboardChange function is already running, that notification event is lost. If this is undesirable, use <a href="Critical.htm">Critical</a>. However, this will also buffer/defer other <a href="../misc/Threads.htm">threads</a> (such as the press of a hotkey) that occur while the OnClipboardChange thread is running.</p>
<p>If the script itself changes the clipboard, its OnClipboardChange functions are typically not executed immediately; that is, functions immediately below the function that changed the clipboard are likely to execute beforehand. To force the functions to execute immediately, use a short delay such as <code><a href="Sleep.htm">Sleep</a> 20</code> after changing the clipboard.</p>

<h2>Related</h2>
<p><a href="../misc/A_Clipboard.htm">A_Clipboard</a>, <a href="OnExit.htm">OnExit</a>, <a href="OnMessage.htm">OnMessage</a>, <a href="CallbackCreate.htm">CallbackCreate</a></p>

<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: The following script will briefly display a ToolTip for each clipboard change:</p>
<pre>OnClipboardChange("ClipChanged")
return

ClipChanged(clip_type) {
    ToolTip "Clipboard data type: " clip_type
    Sleep 1000
    ToolTip  <em>; Turn off the tip.</em>
}</pre>
</div>

</body>
</html>