Function: org-cycle
org-cycle is an autoloaded, interactive and byte-compiled function
defined in org-cycle.el.gz.
Signature
(org-cycle &optional ARG)
Documentation
TAB-action and visibility cycling for Org mode.
This is the command invoked in Org mode by the TAB key. Its main
purpose is outline visibility cycling, but it also invokes other actions
in special contexts.
When this function is called with a C-u (universal-argument) prefix, rotate the entire
buffer through 3 states (global cycling)
1. OVERVIEW: Show only top-level headlines.
2. CONTENTS: Show all headlines of all levels, but no body text.
3. SHOW ALL: Show everything.
With a C-u (universal-argument) C-u (universal-argument) prefix argument, switch to the startup visibility,
determined by the variable org-startup-folded, and by any VISIBILITY
properties in the buffer.
With a C-u (universal-argument) C-u (universal-argument) C-u (universal-argument) prefix argument, show the entire buffer, including
any drawers.
When inside a table, re-align the table and move to the next field.
When point is at the beginning of a headline, rotate the subtree started
by this line through 3 different states (local cycling)
1. FOLDED: Only the main headline is shown.
2. CHILDREN: The main headline and the direct children are shown.
From this state, you can move to one of the children
and zoom in further.
3. SUBTREE: Show the entire subtree, including body text.
If there is no subtree, switch directly from CHILDREN to FOLDED.
When point is at the beginning of an empty headline and the variable
org-cycle-level-after-item/entry-creation is set, cycle the level
of the headline by demoting and promoting it to likely levels. This
speeds up creation document structure by pressing TAB once or several
times right after creating a new headline.
When there is a numeric prefix, go up to a heading with level ARG, do
a show-subtree and return to the previous cursor position. If ARG
is negative, go up that many levels.
When point is not at the beginning of a headline, execute the global
binding for TAB, which is re-indenting the line. See the option
org-cycle-emulate-tab for details.
As a special case, if point is at the very beginning of the buffer, if
there is no headline there, and if the variable org-cycle-global-at-bob
is non-nil, this function acts as if called with prefix argument (C-u (universal-argument) TAB,
same as S-TAB) also when called without prefix argument.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/org/org-cycle.el.gz
;;;###autoload
(defun org-cycle (&optional arg)
"TAB-action and visibility cycling for Org mode.
This is the command invoked in Org mode by the `TAB' key. Its main
purpose is outline visibility cycling, but it also invokes other actions
in special contexts.
When this function is called with a `\\[universal-argument]' prefix, rotate \
the entire
buffer through 3 states (global cycling)
1. OVERVIEW: Show only top-level headlines.
2. CONTENTS: Show all headlines of all levels, but no body text.
3. SHOW ALL: Show everything.
With a `\\[universal-argument] \\[universal-argument]' prefix argument, \
switch to the startup visibility,
determined by the variable `org-startup-folded', and by any VISIBILITY
properties in the buffer.
With a `\\[universal-argument] \\[universal-argument] \
\\[universal-argument]' prefix argument, show the entire buffer, including
any drawers.
When inside a table, re-align the table and move to the next field.
When point is at the beginning of a headline, rotate the subtree started
by this line through 3 different states (local cycling)
1. FOLDED: Only the main headline is shown.
2. CHILDREN: The main headline and the direct children are shown.
From this state, you can move to one of the children
and zoom in further.
3. SUBTREE: Show the entire subtree, including body text.
If there is no subtree, switch directly from CHILDREN to FOLDED.
When point is at the beginning of an empty headline and the variable
`org-cycle-level-after-item/entry-creation' is set, cycle the level
of the headline by demoting and promoting it to likely levels. This
speeds up creation document structure by pressing `TAB' once or several
times right after creating a new headline.
When there is a numeric prefix, go up to a heading with level ARG, do
a `show-subtree' and return to the previous cursor position. If ARG
is negative, go up that many levels.
When point is not at the beginning of a headline, execute the global
binding for `TAB', which is re-indenting the line. See the option
`org-cycle-emulate-tab' for details.
As a special case, if point is at the very beginning of the buffer, if
there is no headline there, and if the variable `org-cycle-global-at-bob'
is non-nil, this function acts as if called with prefix argument \
\(`\\[universal-argument] TAB',
same as `S-TAB') also when called without prefix argument."
(interactive "P")
(org-load-modules-maybe)
(unless (or (run-hook-with-args-until-success 'org-cycle-tab-first-hook)
(and org-cycle-level-after-item/entry-creation
(or (org-cycle-level)
(org-cycle-item-indentation))))
(when (and org-cycle-max-level
(or (not (integerp org-cycle-max-level))
(< org-cycle-max-level 1)))
(user-error "`org-cycle-max-level' must be a positive integer"))
(let* ((limit-level
(or org-cycle-max-level
(and (boundp 'org-inlinetask-min-level)
org-inlinetask-min-level
(1- org-inlinetask-min-level))))
(nstars
(and limit-level
(if org-odd-levels-only
(1- (* 2 limit-level))
limit-level)))
(org-outline-regexp
(format "\\*%s " (if nstars (format "\\{1,%d\\}" nstars) "+"))))
(cond
((equal arg '(16))
(setq last-command 'dummy)
(org-cycle-set-startup-visibility)
(org-unlogged-message "Startup visibility, plus VISIBILITY properties"))
((equal arg '(64))
(org-fold-show-all)
(org-unlogged-message "Entire buffer visible, including drawers"))
((equal arg '(4)) (org-cycle-internal-global))
;; Show-subtree, ARG levels up from here.
((integerp arg)
(save-excursion
(org-back-to-heading)
(outline-up-heading (if (< arg 0) (- arg)
(- (funcall outline-level) arg)))
(org-fold-show-subtree)))
;; Global cycling at BOB: delegate to `org-cycle-internal-global'.
((and org-cycle-global-at-bob
(bobp)
(not (looking-at org-outline-regexp)))
(let ((org-cycle-hook
(remq 'org-cycle-optimize-window-after-visibility-change
org-cycle-hook)))
(org-cycle-internal-global)))
;; Try CDLaTeX TAB completion.
((org-try-cdlatex-tab))
;; Inline task: delegate to `org-inlinetask-toggle-visibility'.
((and (featurep 'org-inlinetask)
(org-inlinetask-at-task-p)
(or (bolp) (not (eq org-cycle-emulate-tab 'exc-hl-bol))))
(org-inlinetask-toggle-visibility))
(t
(let ((pos (point))
(element (org-element-at-point)))
(cond
;; Try toggling visibility for block at point.
((org-fold-hide-block-toggle nil t element))
;; Try toggling visibility for drawer at point.
((org-fold-hide-drawer-toggle nil t element))
;; Table: enter it or move to the next field.
((and (org-match-line "[ \t]*[|+]")
(org-element-lineage element 'table t))
(if (and (org-element-type-p element 'table)
(eq 'table.el (org-element-property :type element)))
(message (substitute-command-keys "\\<org-mode-map>\
Use `\\[org-edit-special]' to edit table.el tables"))
(org-table-justify-field-maybe)
(call-interactively #'org-table-next-field)))
((run-hook-with-args-until-success
'org-tab-after-check-for-table-hook))
;; At an item/headline: delegate to `org-cycle-internal-local'.
((and (or (and org-cycle-include-plain-lists
(let ((item (org-element-lineage element
'(item plain-list)
t)))
(and item
(= (line-beginning-position)
(org-element-post-affiliated
item)))))
(org-match-line org-outline-regexp))
(or (bolp) (not (eq org-cycle-emulate-tab 'exc-hl-bol))))
(org-cycle-internal-local))
;; From there: TAB emulation and template completion.
(buffer-read-only (org-back-to-heading))
((run-hook-with-args-until-success
'org-tab-after-check-for-cycling-hook))
((run-hook-with-args-until-success
'org-tab-before-tab-emulation-hook))
((and (eq org-cycle-emulate-tab 'exc-hl-bol)
(or (not (bolp))
(not (looking-at org-outline-regexp))))
(call-interactively (global-key-binding (kbd "TAB"))))
((or (eq org-cycle-emulate-tab t)
(and (memq org-cycle-emulate-tab '(white whitestart))
(save-excursion (forward-line 0) (looking-at "[ \t]*"))
(or (and (eq org-cycle-emulate-tab 'white)
(= (match-end 0) (line-end-position)))
(and (eq org-cycle-emulate-tab 'whitestart)
(>= (match-end 0) pos)))))
(call-interactively (global-key-binding (kbd "TAB"))))
(t
(save-excursion
(org-back-to-heading)
(org-cycle))))))))))