new repository

1 files changed, 37 insertions, 0 deletions

diff --git a/devdocs/elisp/distinguish-interactive.html b/devdocs/elisp/distinguish-interactive.html
new file mode 100644
index 00000000..a876fed8
--- /dev/null
+++ b/devdocs/elisp/distinguish-interactive.html
@@ -0,0 +1,37 @@
+ <h3 class="section">Distinguish Interactive Calls</h3>   <p>Sometimes a command should display additional visual feedback (such as an informative message in the echo area) for interactive calls only. There are three ways to do this. The recommended way to test whether the function was called using <code>call-interactively</code> is to give it an optional argument <code>print-message</code> and use the <code>interactive</code> spec to make it non-<code>nil</code> in interactive calls. Here’s an example: </p> <div class="example"> <pre class="example">(defun foo (&amp;optional print-message)
+  (interactive "p")
+  (when print-message
+    (message "foo")))
+</pre>
+</div> <p>We use <code>"p"</code> because the numeric prefix argument is never <code>nil</code>. Defined in this way, the function does display the message when called from a keyboard macro. </p> <p>The above method with the additional argument is usually best, because it allows callers to say “treat this call as interactive”. But you can also do the job by testing <code>called-interactively-p</code>. </p> <dl> <dt id="called-interactively-p">Function: <strong>called-interactively-p</strong> <em>kind</em>
+</dt> <dd>
+<p>This function returns <code>t</code> when the calling function was called using <code>call-interactively</code>. </p> <p>The argument <var>kind</var> should be either the symbol <code>interactive</code> or the symbol <code>any</code>. If it is <code>interactive</code>, then <code>called-interactively-p</code> returns <code>t</code> only if the call was made directly by the user—e.g., if the user typed a key sequence bound to the calling function, but <em>not</em> if the user ran a keyboard macro that called the function (see <a href="keyboard-macros">Keyboard Macros</a>). If <var>kind</var> is <code>any</code>, <code>called-interactively-p</code> returns <code>t</code> for any kind of interactive call, including keyboard macros. </p> <p>If in doubt, use <code>any</code>; the only known proper use of <code>interactive</code> is if you need to decide whether to display a helpful message while a function is running. </p> <p>A function is never considered to be called interactively if it was called via Lisp evaluation (or with <code>apply</code> or <code>funcall</code>). </p>
+</dd>
+</dl> <p>Here is an example of using <code>called-interactively-p</code>: </p> <div class="example"> <pre class="example">(defun foo ()
+  (interactive)
+  (when (called-interactively-p 'any)
+    (message "Interactive!")
+    'foo-called-interactively))
+</pre>
+
+<pre class="example">;; <span class="roman">Type <kbd>M-x foo</kbd>.</span>
+     -| Interactive!
+</pre>
+
+<pre class="example">(foo)
+     ⇒ nil
+</pre>
+</div> <p>Here is another example that contrasts direct and indirect calls to <code>called-interactively-p</code>. </p> <div class="example"> <pre class="example">(defun bar ()
+  (interactive)
+  (message "%s" (list (foo) (called-interactively-p 'any))))
+</pre>
+
+<pre class="example">;; <span class="roman">Type <kbd>M-x bar</kbd>.</span>
+     -| (nil t)
+</pre>
+</div><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Distinguish-Interactive.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Distinguish-Interactive.html</a>
+  </p>
+</div>