New hooks for commands attaching themselves to the TAB key.

Three new hooks are available for commands to attach themselves to the
TAB key.

lisp/ChangeLog

@@ -1,3 +1,12 @@
+2009-04-21  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.el (org-tab-first-hook)
+	(org-tab-after-check-for-table-hook)
+	(org-tab-after-check-for-cycling-hook): New hooks.
+	(org-cycle-internal-global, org-cycle-internal-local): New
+	functions, split out from `org-cycle'.
+	(org-cycle): Call the new hooks.
+
 2009-04-19  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org-exp.el (org-export-preprocess-string): Reset the list of

lisp/org.el

@@ -4560,19 +4560,26 @@ If KWD is a number, get the corresponding match group."
 ;;;###autoload
 
 (defvar org-inlinetask-min-level)
+
 (defun org-cycle (&optional arg)
-  "Visibility cycling for Org-mode.
+  "TAB-action and visibility cycling for Org-mode.
+
+This is the command invoked in Org-moe by the TAB key.  It's main purpose
+is outine visibility cycling, but it also invokes other actions
+in special contexts.
 
 - When this function is called with a prefix argument, 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.
-  When called with two C-u C-u prefixes, switch to the startup visibility,
+  When called with two `C-u C-u' prefixes, switch to the startup visibility,
   determined by the variable `org-startup-folded', and by any VISIBILITY
   properties in the buffer.
-  When called with three C-u C-u C-u prefixed, show the entire buffer,
+  When called with three `C-u C-u C-u' prefixed, show the entire buffer,
-  including drawers.
+  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)
@@ -4595,6 +4602,7 @@ If KWD is a number, get the corresponding match group."
   But only if also the variable `org-cycle-global-at-bob' is t."
   (interactive "P")
   (org-load-modules-maybe)
+  (unless (run-hook-with-args-until-success 'org-tab-first-hook)
     (let* ((limit-level
 	    (or org-cycle-max-level
 		(and (boundp 'org-inlinetask-min-level)
@@ -4643,8 +4651,64 @@ If KWD is a number, get the corresponding match group."
 		(org-table-justify-field-maybe)
 		(call-interactively 'org-table-next-field)))))
        
-     ((eq arg t) ;; Global cycling
+       ((run-hook-with-args-until-success
+	 'org-tab-after-check-for-table-hook))
        
+       ((eq arg t) ;; Global cycling
+	(org-cycle-internal-global))
+       
+       ((and org-drawers org-drawer-regexp
+	     (save-excursion
+	       (beginning-of-line 1)
+	       (looking-at org-drawer-regexp)))
+	;; Toggle block visibility
+	(org-flag-drawer
+	 (not (get-char-property (match-end 0) 'invisible))))
+       
+       ((integerp arg)
+	;; Show-subtree, ARG levels up from here.
+	(save-excursion
+	  (org-back-to-heading)
+	  (outline-up-heading (if (< arg 0) (- arg)
+				(- (funcall outline-level) arg)))
+	  (org-show-subtree)))
+       
+       ((and (save-excursion (beginning-of-line 1) (looking-at outline-regexp))
+	     (or (bolp) (not (eq org-cycle-emulate-tab 'exc-hl-bol))))
+	
+	(org-cycle-internal-local))
+       
+       ;; 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))
+       
+       ((org-try-structure-completion))
+       
+       ((org-try-cdlatex-tab))
+       
+       ((and (eq org-cycle-emulate-tab 'exc-hl-bol)
+	     (or (not (bolp))
+		 (not (looking-at outline-regexp))))
+	(call-interactively (global-key-binding "\t")))
+       
+       ((if (and (memq org-cycle-emulate-tab '(white whitestart))
+		 (save-excursion (beginning-of-line 1) (looking-at "[ \t]*"))
+		 (or (and (eq org-cycle-emulate-tab 'white)
+			  (= (match-end 0) (point-at-eol)))
+		     (and (eq org-cycle-emulate-tab 'whitestart)
+			  (>= (match-end 0) pos))))
+	    t
+	  (eq org-cycle-emulate-tab t))
+	(call-interactively (global-key-binding "\t")))
+       
+       (t (save-excursion
+	    (org-back-to-heading)
+	    (org-cycle)))))))
+
+(defun org-cycle-internal-global ()
+  "Do the global cycling action."
   (cond
    ((and (eq last-command this-command)
 	 (eq org-cycle-global-status 'overview))
@@ -4674,25 +4738,8 @@ If KWD is a number, get the corresponding match group."
     (setq org-cycle-global-status 'overview)
     (run-hook-with-args 'org-cycle-hook 'overview))))
 
-     ((and org-drawers org-drawer-regexp
+(defun org-cycle-internal-local ()
-	   (save-excursion
+  "Do the local cycling action."
-	     (beginning-of-line 1)
-	     (looking-at org-drawer-regexp)))
-      ;; Toggle block visibility
-      (org-flag-drawer
-       (not (get-char-property (match-end 0) 'invisible))))
-
-     ((integerp arg)
-      ;; Show-subtree, ARG levels up from here.
-      (save-excursion
-	(org-back-to-heading)
-	(outline-up-heading (if (< arg 0) (- arg)
-			      (- (funcall outline-level) arg)))
-	(org-show-subtree)))
-
-     ((and (save-excursion (beginning-of-line 1) (looking-at outline-regexp))
-	   (or (bolp) (not (eq org-cycle-emulate-tab 'exc-hl-bol))))
-      ;; At a heading: rotate between three different views
   (org-back-to-heading)
   (let ((goal-column 0) eoh eol eos)
     ;; First, some boundaries
@@ -4750,32 +4797,6 @@ If KWD is a number, get the corresponding match group."
       (setq org-cycle-subtree-status 'folded)
       (run-hook-with-args 'org-cycle-hook 'folded)))))
 
-     ;; TAB emulation and template completion
-     (buffer-read-only (org-back-to-heading))
-
-     ((org-try-structure-completion))
-
-     ((org-try-cdlatex-tab))
-
-     ((and (eq org-cycle-emulate-tab 'exc-hl-bol)
-	   (or (not (bolp))
-	       (not (looking-at outline-regexp))))
-      (call-interactively (global-key-binding "\t")))
-
-     ((if (and (memq org-cycle-emulate-tab '(white whitestart))
-	       (save-excursion (beginning-of-line 1) (looking-at "[ \t]*"))
-	       (or (and (eq org-cycle-emulate-tab 'white)
-			(= (match-end 0) (point-at-eol)))
-		   (and (eq org-cycle-emulate-tab 'whitestart)
-			(>= (match-end 0) pos))))
-	  t
-	(eq org-cycle-emulate-tab t))
-      (call-interactively (global-key-binding "\t")))
-
-     (t (save-excursion
-	  (org-back-to-heading)
-	  (org-cycle))))))
-
 ;;;###autoload
 (defun org-global-cycle (&optional arg)
   "Cycle the global visibility.  For details see `org-cycle'.
@@ -13925,7 +13946,32 @@ executes context-dependent commands.
 Each function will be called with no arguments.  The function must check
 if the context is appropriate for it to act.  If yes, it should do its
 thing and then return a non-nil value.  If the context is wrong,
-just do nothing.")
+just do nothing and return nil.")
+
+(defvar org-tab-first-hook nil
+  "Hook for functions to attach themselves to TAB.
+See `org-ctrl-c-ctrl-c-hook' for more information.
+This hook runs as the first action when TAB is pressed, even before
+`org-cycle' messes around with the `outline-regexp' to cater for
+inline tasks and plain list item folding.
+If any function in this hook returns t, not other actions like table
+field motion visibility cycling will be done.")
+
+(defvar org-tab-after-check-for-table-hook nil
+  "Hook for functions to attach themselves to TAB.
+See `org-ctrl-c-ctrl-c-hook' for more information.
+This hook runs after it has been established that the cursor is not in a 
+table, but before checking if the cursor is in a headline or if global cycling
+should be done.
+If any function in this hook returns t, not other actions like visibility
+cycling will be done.")
+
+(defvar org-tab-after-check-for-cycling-hook nil
+  "Hook for functions to attach themselves to TAB.
+See `org-ctrl-c-ctrl-c-hook' for more information.
+This hook runs after it has been established that not table field motion and
+not visibility should be done because of current context.  This is probably
+the place where a package like yasnippets can hook in.")
 
 (defvar org-metaleft-hook nil
   "Hook for functions attaching themselves to `M-left'.