Function: org-capture

org-capture is an autoloaded, interactive and byte-compiled function defined in org-capture.el.gz.

Signature

(org-capture &optional GOTO KEYS)

Documentation

Capture something.

This will let you select a template from org-capture-templates, and then file the newly captured information. The text is immediately inserted at the target location, and an indirect buffer is shown where you can edit it. Pressing C-c C-c (org-capture-finalize) brings you back to the previous state of Emacs, so that you can continue your work.

When called interactively with a C-u (universal-argument) prefix argument GOTO, don't capture anything, just go to the file/headline where the selected template stores its notes.

With a C-u (universal-argument) C-u (universal-argument) prefix argument, go to the last note stored.

When called with a C-0 (zero) prefix, insert a template at point.

When called with a C-1 (one) prefix, force prompting for a date when a datetree entry is made.

Elisp programs can set KEYS to a string associated with a template in org-capture-templates. In this case, interactive selection will be bypassed.

If org-capture-use-agenda-date is non-nil, capturing from the agenda will use the date at point as the default date. Then, a C-1 prefix will tell the capture process to use the HH:MM time of the day at point (if any) or the current HH:MM time.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-capture.el.gz
;;;###autoload
(defun org-capture (&optional goto keys)
  "Capture something.
\\<org-capture-mode-map>
This will let you select a template from `org-capture-templates', and
then file the newly captured information.  The text is immediately
inserted at the target location, and an indirect buffer is shown where
you can edit it.  Pressing `\\[org-capture-finalize]' brings you back to the \
previous
state of Emacs, so that you can continue your work.

When called interactively with a `\\[universal-argument]' prefix argument \
GOTO, don't
capture anything, just go to the file/headline where the selected
template stores its notes.

With a `\\[universal-argument] \\[universal-argument]' prefix argument, go to \
the last note stored.

When called with a `C-0' (zero) prefix, insert a template at point.

When called with a `C-1' (one) prefix, force prompting for a date when
a datetree entry is made.

Elisp programs can set KEYS to a string associated with a template
in `org-capture-templates'.  In this case, interactive selection
will be bypassed.

If `org-capture-use-agenda-date' is non-nil, capturing from the
agenda will use the date at point as the default date.  Then, a
`C-1' prefix will tell the capture process to use the HH:MM time
of the day at point (if any) or the current HH:MM time."
  (interactive "P")
  (when (and org-capture-use-agenda-date
	     (eq major-mode 'org-agenda-mode))
    (setq org-overriding-default-time
	  (org-get-cursor-date (equal goto 1))))
  (cond
   ((equal goto '(4))  (org-capture-goto-target keys))
   ((equal goto '(16)) (org-capture-goto-last-stored))
   (t
    (let* ((orig-buf (current-buffer))
	   (annotation (if (and (boundp 'org-capture-link-is-already-stored)
				org-capture-link-is-already-stored)
			   (plist-get org-store-link-plist :annotation)
			 (ignore-errors (org-store-link nil))))
	   (entry (or org-capture-entry (org-capture-select-template keys)))
	   initial)
      (setq initial (or org-capture-initial
			(and (org-region-active-p)
			     (buffer-substring (point) (mark)))))
      (when (stringp initial)
	(remove-text-properties 0 (length initial) '(read-only t) initial))
      (when (stringp annotation)
	(remove-text-properties 0 (length annotation)
				'(read-only t) annotation))
      (cond
       ((equal entry "C")
	(customize-variable 'org-capture-templates))
       ((equal entry "q")
	(user-error "Abort"))
       (t
	(org-capture-set-plist entry)
	(org-capture-get-template)
	(org-capture-put :original-buffer orig-buf
			 :original-file (or (buffer-file-name orig-buf)
					    (and (featurep 'dired)
						 (car (rassq orig-buf
							     dired-buffers))))
			 :original-file-nondirectory
			 (and (buffer-file-name orig-buf)
			      (file-name-nondirectory
			       (buffer-file-name orig-buf)))
			 :annotation annotation
			 :initial initial
			 :return-to-wconf (current-window-configuration)
			 :default-time (or org-overriding-default-time
					   (org-current-time)))
	(org-capture-set-target-location (and (equal goto 0) 'here))
	(condition-case error
	    (org-capture-put :template (org-capture-fill-template))
	  ((error quit)
	   (if (get-buffer "*Capture*") (kill-buffer "*Capture*"))
	   (error "Capture abort: %s" (error-message-string error))))

	(setq org-capture-clock-keep (org-capture-get :clock-keep))
	(condition-case error
	    (org-capture-place-template
	     (eq (car (org-capture-get :target)) 'function))
	  ((error quit)
	   (when (and (buffer-base-buffer (current-buffer))
		      (string-prefix-p "CAPTURE-" (buffer-name)))
	     (kill-buffer (current-buffer)))
	   (set-window-configuration (org-capture-get :return-to-wconf))
	   (error "Capture template `%s': %s"
		  (org-capture-get :key)
		  (error-message-string error))))
	(when (and (derived-mode-p 'org-mode) (org-capture-get :clock-in))
	  (condition-case nil
	      (progn
		(when (org-clock-is-active)
		  (org-capture-put :interrupted-clock
				   (copy-marker org-clock-marker)))
		(org-clock-in)
		(setq-local org-capture-clock-was-started
                            (copy-marker org-clock-marker)))
	    (error "Could not start the clock in this capture buffer")))
	(when (org-capture-get :immediate-finish)
	  (org-capture-finalize))))))))