Function: sit-for

sit-for is a byte-compiled function defined in subr.el.gz.

Signature

(sit-for SECONDS &optional NODISP)

Documentation

Redisplay, then wait for SECONDS seconds; stop when input is available.

SECONDS may be a floating-point value.
(On operating systems that do not support waiting for fractions of a
second, floating-point values are rounded down to the nearest integer.)

If there's pending input, return nil immediately without redisplaying and without waiting. If optional arg NODISP is t, don't redisplay, just wait for input (but still return nil immediately if there's pending input).

Value is t if waited the full time with no input arriving, and nil otherwise.

View in manual

Probably introduced at or before Emacs version 1.4.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun sit-for (seconds &optional nodisp)
  "Redisplay, then wait for SECONDS seconds; stop when input is available.
SECONDS may be a floating-point value.
\(On operating systems that do not support waiting for fractions of a
second, floating-point values are rounded down to the nearest integer.)

If there's pending input, return nil immediately without redisplaying
and without waiting.
If optional arg NODISP is t, don't redisplay, just wait for input (but
still return nil immediately if there's pending input).

Value is t if waited the full time with no input arriving, and nil otherwise."
  ;; This used to be implemented in C until the following discussion:
  ;; https://lists.gnu.org/r/emacs-devel/2006-07/msg00401.html
  ;; Then it was moved here using an implementation based on an idle timer,
  ;; which was then replaced by the use of read-event.
  (cond
   (noninteractive
    (sleep-for seconds)
    t)
   ((input-pending-p t)
    nil)
   ((or (<= seconds 0)
        ;; We are going to call read-event below, which will record
        ;; the next key as part of the macro, even if that key
        ;; invokes kmacro-end-macro, so if we are recording a macro,
        ;; the macro will recursively call itself.  In addition, when
        ;; that key is removed from unread-command-events, it will be
        ;; recorded the second time, so the macro will have each key
        ;; doubled.  This used to happen if a macro was defined with
        ;; Flyspell mode active (because Flyspell calls sit-for in its
        ;; post-command-hook, see bug #21329.)  To avoid all that, we
        ;; simply disable the wait when we are recording a macro.
        defining-kbd-macro)
    (or nodisp (redisplay)))
   (t
    (or nodisp (redisplay))
    ;; FIXME: we should not read-event here at all, because it's much too
    ;; difficult to reliably "undo" a read-event by pushing it onto
    ;; unread-command-events.
    ;; For bug#14782, we need read-event to do the keyboard-coding-system
    ;; decoding (hence non-nil as second arg under POSIX ttys).
    ;; For bug#15614, we need read-event not to inherit-input-method.
    ;; So we temporarily suspend input-method-function.
    (let ((read (let ((input-method-function nil))
                  (read-event nil t seconds))))
      (or (null read)
	  (progn
            ;; https://lists.gnu.org/r/emacs-devel/2006-10/msg00394.html
            ;; We want `read' appear in the next command's this-command-event
            ;; but not in the current one.
            ;; By pushing (cons t read), we indicate that `read' has not
            ;; yet been recorded in this-command-keys, so it will be recorded
            ;; next time it's read.
            ;; And indeed the `seconds' argument to read-event correctly
            ;; prevented recording this event in the current command's
            ;; this-command-keys.
	    (push (cons t read) unread-command-events)
	    nil))))))