1 ;;; reftex-sel.el --- the selection modes for RefTeX
3 ;; Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
4 ;; 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
6 ;; Author: Carsten Dominik <dominik@science.uva.nl>
7 ;; Maintainer: auctex-devel@gnu.org
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
30 (eval-when-compile (require 'cl))
35 (defvar reftex-select-label-map nil
36 "Keymap used for *RefTeX Select* buffer, when selecting a label.
37 This keymap can be used to configure the label selection process which is
38 started with the command \\[reftex-reference].")
40 (defun reftex-select-label-mode ()
41 "Major mode for selecting a label in a LaTeX document.
42 This buffer was created with RefTeX.
43 It only has a meaningful keymap when you are in the middle of a
45 To select a label, move the cursor to it and press RET.
46 Press `?' for a summary of important key bindings.
48 During a selection process, these are the local bindings.
50 \\{reftex-select-label-map}"
53 (kill-all-local-variables)
54 (when (featurep 'xemacs)
55 ;; XEmacs needs the call to make-local-hook
56 (make-local-hook 'pre-command-hook)
57 (make-local-hook 'post-command-hook))
58 (setq major-mode 'reftex-select-label-mode
60 (set (make-local-variable 'reftex-select-marked) nil)
61 (when (syntax-table-p reftex-latex-syntax-table)
62 (set-syntax-table reftex-latex-syntax-table))
63 ;; We do not set a local map - reftex-select-item does this.
64 (run-hooks 'reftex-select-label-mode-hook))
66 (defvar reftex-select-bib-map nil
67 "Keymap used for *RefTeX Select* buffer, when selecting a BibTeX entry.
68 This keymap can be used to configure the BibTeX selection process which is
69 started with the command \\[reftex-citation].")
71 (defun reftex-select-bib-mode ()
72 "Major mode for selecting a citation key in a LaTeX document.
73 This buffer was created with RefTeX.
74 It only has a meaningful keymap when you are in the middle of a
76 In order to select a citation, move the cursor to it and press RET.
77 Press `?' for a summary of important key bindings.
79 During a selection process, these are the local bindings.
81 \\{reftex-select-label-map}"
83 (kill-all-local-variables)
84 (when (featurep 'xemacs)
85 ;; XEmacs needs the call to make-local-hook
86 (make-local-hook 'pre-command-hook)
87 (make-local-hook 'post-command-hook))
88 (setq major-mode 'reftex-select-bib-mode
90 (set (make-local-variable 'reftex-select-marked) nil)
91 ;; We do not set a local map - reftex-select-item does this.
92 (run-hooks 'reftex-select-bib-mode-hook))
94 ;; (defun reftex-get-offset (buf here-am-I &optional typekey toc index file)
95 ;; ;; Find the correct offset data, like insert-docstruct would, but faster.
96 ;; ;; Buffer BUF knows the correct docstruct to use.
97 ;; ;; Basically this finds the first docstruct entry after HERE-I-AM which
98 ;; ;; is of allowed type. The optional arguments specify what is allowed.
100 ;; (with-current-buffer buf
101 ;; (reftex-access-scan-info)
102 ;; (let* ((rest (memq here-am-I (symbol-value reftex-docstruct-symbol)))
104 ;; (while (setq entry (pop rest))
105 ;; (if (or (and typekey
106 ;; (stringp (car entry))
107 ;; (or (equal typekey " ")
108 ;; (equal typekey (nth 1 entry))))
109 ;; (and toc (eq (car entry) 'toc))
110 ;; (and index (eq (car entry) 'index))
112 ;; (memq (car entry) '(bof eof file-error))))
113 ;; (throw 'exit entry)))
116 (defun reftex-get-offset (buf here-am-I &optional typekey toc index file)
117 ;; Find the correct offset data, like insert-docstruct would, but faster.
118 ;; Buffer BUF knows the correct docstruct to use.
119 ;; Basically this finds the first docstruct entry before HERE-I-AM which
120 ;; is of allowed type. The optional arguments specify what is allowed.
122 (with-current-buffer buf
123 (reftex-access-scan-info)
124 (let* ((rest (symbol-value reftex-docstruct-symbol))
126 (while (setq entry (pop rest))
128 (stringp (car entry))
129 (or (equal typekey " ")
130 (equal typekey (nth 1 entry))))
131 (and toc (eq (car entry) 'toc))
132 (and index (eq (car entry) 'index))
134 (memq (car entry) '(bof eof file-error))))
135 (setq lastentry entry))
136 (if (eq entry here-am-I)
137 (throw 'exit (or lastentry entry))))
140 (defun reftex-insert-docstruct
141 (buf toc labels index-entries files context counter show-commented
142 here-I-am xr-prefix toc-buffer)
143 ;; Insert an excerpt of the docstruct list.
144 ;; Return the data property of the entry corresponding to HERE-I-AM.
145 ;; BUF is the buffer which has the correct docstruct-symbol.
146 ;; LABELS non-nil means to include labels into the list.
147 ;; When a string, indicates the label type to include
148 ;; FILES non-nil means to display file boundaries.
149 ;; CONTEXT non-nil means to include label context.
150 ;; COUNTER means to count the labels.
151 ;; SHOW-COMMENTED means to include also labels which are commented out.
152 ;; HERE-I-AM is a member of the docstruct list. The function will return
153 ;; a used member near to this one, as a possible starting point.
154 ;; XR-PREFIX is the prefix to put in front of labels.
155 ;; TOC-BUFFER means this is to fill the toc buffer.
156 (let* ((font (reftex-use-fonts))
162 (if toc (make-string (* 7 reftex-level-indent) ?\ ) "")))
165 (if toc (make-string (* 7 reftex-level-indent) ?\ ) "")))
167 (if (memq reftex-highlight-selection '(mouse both))
168 reftex-mouse-selected-face
170 (label-face (reftex-verified-face reftex-label-face
171 'font-lock-constant-face
172 'font-lock-reference-face))
173 (index-face (reftex-verified-face reftex-index-face
174 'font-lock-constant-face
175 'font-lock-reference-face))
176 all cell text label typekey note comment master-dir-re
177 prev-inserted offset from to index-tag docstruct-symbol)
179 ;; Pop to buffer buf to get the correct buffer-local variables
180 (with-current-buffer buf
182 ;; Ensure access to scanning info
183 (reftex-access-scan-info)
185 (setq docstruct-symbol reftex-docstruct-symbol
186 all (symbol-value reftex-docstruct-symbol)
187 reftex-active-toc nil
189 (concat "\\`" (regexp-quote
190 (file-name-directory (reftex-TeX-master-file))))))
192 (set (make-local-variable 'reftex-docstruct-symbol) docstruct-symbol)
193 (set (make-local-variable 'reftex-prefix)
194 (cdr (assoc labels reftex-typekey-to-prefix-alist)))
195 (if (equal reftex-prefix " ") (setq reftex-prefix nil))
197 ;; Walk the docstruct and insert the appropriate stuff
198 (while (setq cell (pop all))
205 ((memq (car cell) '(bib thebib label-numbers appendix
206 master-dir bibview-cache is-multi xr xr-doc)))
207 ;; These are currently ignored
209 ((memq (car cell) '(bof eof file-error))
210 ;; Beginning or end of a file
212 (setq prev-inserted cell)
213 ; (if (eq offset 'attention) (setq offset cell))
215 " File " (if (string-match master-dir-re (nth 1 cell))
216 (substring (nth 1 cell) (match-end 0))
218 (cond ((eq (car cell) 'bof) " starts here\n")
219 ((eq (car cell) 'eof) " ends here\n")
220 ((eq (car cell) 'file-error) " was not found\n")))
223 (put-text-property from to
224 'face reftex-file-boundary-face))
227 (put-text-property from (1- to)
228 'mouse-face mouse-face))
229 (put-text-property from to :data cell))))
231 ((eq (car cell) 'toc)
232 ;; a table of contents entry
234 (<= (nth 5 cell) reftex-toc-max-level))
235 (setq prev-inserted cell)
236 ; (if (eq offset 'attention) (setq offset cell))
237 (setq reftex-active-toc cell)
238 (insert (concat toc-indent (nth 2 cell) "\n"))
241 (put-text-property from to
242 'face reftex-section-heading-face))
245 (put-text-property from (1- to)
246 'mouse-face mouse-face))
247 (put-text-property from to :data cell))
250 ((stringp (car cell))
252 (when (null (nth 2 cell))
253 ;; No context yet. Quick update.
254 (setcdr cell (cdr (reftex-label-info-update cell)))
255 (put docstruct-symbol 'modified t))
257 (setq label (car cell)
265 (string= typekey labels)
266 (string= labels " "))
267 (or show-commented (null comment)))
269 ;; Yes we want this one
271 (setq prev-inserted cell)
272 ; (if (eq offset 'attention) (setq offset cell))
274 (setq label (concat xr-prefix label))
275 (when comment (setq label (concat "% " label)))
276 (insert label-indent label)
280 (- (point) (length label)) to
282 'font-lock-comment-face
286 (insert (if counter (format " (%d) " cnt) "")
287 (if comment " LABEL IS COMMENTED OUT " "")
288 (if (stringp note) (concat " " note) "")
293 (insert context-indent text "\n")
295 (put-text-property from to :data cell)
297 (put-text-property from (1- to)
298 'mouse-face mouse-face))
301 ((eq (car cell) 'index)
303 (when (and index-entries
304 (or (eq t index-entries)
305 (string= index-entries (nth 1 cell))))
306 (setq prev-inserted cell)
307 ; (if (eq offset 'attention) (setq offset cell))
308 (setq index-tag (format "<%s>" (nth 1 cell)))
310 (put-text-property 0 (length index-tag)
311 'face reftex-index-tag-face index-tag))
312 (insert label-indent index-tag " " (nth 7 cell))
317 (- (point) (length (nth 7 cell))) to
324 (insert context-indent (nth 2 cell) "\n")
326 (put-text-property from to :data cell)
328 (put-text-property from (1- to)
329 'mouse-face mouse-face))
332 (if (eq cell here-I-am)
333 (setq offset 'attention))
334 (if (and prev-inserted (eq offset 'attention))
335 (setq offset prev-inserted))
338 (when (reftex-refontify)
339 ;; we need to fontify the buffer
340 (reftex-fontify-select-label-buffer buf))
341 (run-hooks 'reftex-display-copied-context-hook)
344 (defun reftex-find-start-point (fallback &rest locations)
345 ;; Set point to the first available LOCATION. When a LOCATION is a list,
346 ;; search for such a :data text property. When it is an integer,
347 ;; use is as line number. FALLBACK is a buffer position used if everything
350 (goto-char (point-min))
353 (setq loc (pop locations))
357 (setq pos (text-property-any (point-min) (point-max) :data loc))
362 (when (<= loc (count-lines (point-min) (point-max)))
363 (goto-char (point-min))
364 (forward-line (1- loc))
366 (goto-char fallback))))
368 (defvar reftex-last-data nil)
369 (defvar reftex-last-line nil)
370 (defvar reftex-select-marked nil)
372 (defun reftex-select-item (reftex-select-prompt help-string keymap
375 ;; Select an item, using REFTEX-SELECT-PROMPT.
376 ;; The function returns a key indicating an exit status, along with a
377 ;; data structure indicating which item was selected.
378 ;; HELP-STRING contains help. KEYMAP is a keymap with the available
379 ;; selection commands.
380 ;; OFFSET can be a label list item which will be selected at start.
381 ;; When it is t, point will start out at the beginning of the buffer.
382 ;; Any other value will cause restart where last selection left off.
383 ;; When CALL-BACK is given, it is a function which is called with the index
385 ;; CB-FLAG is the initial value of that flag.
386 (let (ev reftex-select-data last-data (selection-buffer (current-buffer)))
388 (setq reftex-select-marked nil)
392 (save-window-excursion
393 (setq truncate-lines t)
395 ;; Find a good starting point
396 (reftex-find-start-point
397 (point-min) offset reftex-last-data reftex-last-line)
398 (beginning-of-line 1)
399 (set (make-local-variable 'reftex-last-follow-point) (point))
403 (use-local-map keymap)
404 (add-hook 'pre-command-hook 'reftex-select-pre-command-hook nil t)
405 (add-hook 'post-command-hook 'reftex-select-post-command-hook nil t)
406 (princ reftex-select-prompt)
407 (set-marker reftex-recursive-edit-marker (point))
408 ;; XEmacs does not run post-command-hook here
409 (and (featurep 'xemacs) (run-hooks 'post-command-hook))
412 (set-marker reftex-recursive-edit-marker nil)
413 (with-current-buffer selection-buffer
415 (remove-hook 'pre-command-hook 'reftex-select-pre-command-hook t)
416 (remove-hook 'post-command-hook
417 'reftex-select-post-command-hook t))
418 ;; Kill the mark overlays
419 (mapc (lambda (c) (reftex-delete-overlay (nth 1 c)))
420 reftex-select-marked)))))
422 (set (make-local-variable 'reftex-last-line)
423 (+ (count-lines (point-min) (point)) (if (bolp) 1 0)))
424 (set (make-local-variable 'reftex-last-data) last-data)
425 (reftex-kill-buffer "*RefTeX Help*")
426 (setq reftex-callback-fwd (not reftex-callback-fwd)) ;; ;-)))
428 (list ev reftex-select-data last-data)))
430 ;; The following variables are all bound dynamically in `reftex-select-item'.
431 ;; The defvars are here only to silence the byte compiler.
435 (defvar reftex-select-data)
436 (defvar reftex-select-prompt)
441 ;; The selection commands
443 (defun reftex-select-pre-command-hook ()
444 (reftex-unhighlight 1)
445 (reftex-unhighlight 0))
447 (defun reftex-select-post-command-hook ()
449 (setq reftex-select-data (get-text-property (point) :data))
450 (setq last-data (or reftex-select-data last-data))
452 (when (and reftex-select-data cb-flag
453 (not (equal reftex-last-follow-point (point))))
454 (setq reftex-last-follow-point (point))
455 (funcall call-back reftex-select-data reftex-callback-fwd
456 (not reftex-revisit-to-follow)))
457 (if reftex-select-data
458 (setq b (or (previous-single-property-change
461 e (or (next-single-property-change
464 (setq b (point) e (point)))
465 (and (memq reftex-highlight-selection '(cursor both))
466 (reftex-highlight 1 b e))
467 (if (or (not (pos-visible-in-window-p b))
468 (not (pos-visible-in-window-p e)))
470 (unless (current-message)
471 (princ reftex-select-prompt))))
473 (defun reftex-select-next (&optional arg)
474 "Move to next selectable item."
476 (setq reftex-callback-fwd t)
477 (or (eobp) (forward-char 1))
478 (re-search-forward "^[^. \t\n\r]" nil t arg)
479 (beginning-of-line 1))
480 (defun reftex-select-previous (&optional arg)
481 "Move to previous selectable item."
483 (setq reftex-callback-fwd nil)
484 (re-search-backward "^[^. \t\n\r]" nil t arg))
485 (defun reftex-select-jump (arg)
486 "Jump to a specific section. E.g. '3 z' jumps to section 3.
487 Useful for large TOC's."
489 (goto-char (point-min))
491 (concat "^ *" (number-to-string (if (numberp arg) arg 1)) " ")
494 (defun reftex-select-next-heading (&optional arg)
495 "Move to next table of contentes line."
498 (re-search-forward "^ " nil t arg)
500 (defun reftex-select-previous-heading (&optional arg)
501 "Move to previous table of contentes line."
503 (re-search-backward "^ " nil t arg))
504 (defun reftex-select-quit ()
505 "Abort selection process."
508 (defun reftex-select-keyboard-quit ()
509 "Abort selection process."
512 (defun reftex-select-jump-to-previous ()
513 "Jump back to where previous selection process left off."
517 ((and (local-variable-p 'reftex-last-data (current-buffer))
519 (setq pos (text-property-any (point-min) (point-max)
520 :data reftex-last-data)))
522 ((and (local-variable-p 'reftex-last-line (current-buffer))
523 (integerp reftex-last-line))
524 (goto-char (point-min))
525 (forward-line (1- reftex-last-line)))
527 (defun reftex-select-toggle-follow ()
528 "Toggle follow mode: Other window follows with full context."
530 (setq reftex-last-follow-point -1)
531 (setq cb-flag (not cb-flag)))
533 (defvar reftex-refstyle) ; from reftex-reference
535 (defun reftex-select-toggle-varioref ()
536 "Toggle the macro used for referencing the label between \\ref and \\vref."
538 (if (string= reftex-refstyle "\\ref")
539 (setq reftex-refstyle "\\vref")
540 (setq reftex-refstyle "\\ref"))
541 (force-mode-line-update))
542 (defun reftex-select-toggle-fancyref ()
543 "Toggle the macro used for referencing the label between \\ref and \\vref."
545 (setq reftex-refstyle
546 (cond ((string= reftex-refstyle "\\ref") "\\fref")
547 ((string= reftex-refstyle "\\fref") "\\Fref")
549 (force-mode-line-update))
550 (defun reftex-select-show-insertion-point ()
551 "Show the point from where selection was started in another window."
553 (let ((this-window (selected-window)))
556 (switch-to-buffer-other-window
557 (marker-buffer reftex-select-return-marker))
558 (goto-char (marker-position reftex-select-return-marker))
560 (select-window this-window))))
561 (defun reftex-select-callback ()
562 "Show full context in another window."
564 (if reftex-select-data (funcall call-back reftex-select-data reftex-callback-fwd nil) (ding)))
565 (defun reftex-select-accept ()
566 "Accept the currently selected item."
568 (throw 'myexit 'return))
569 (defun reftex-select-mouse-accept (ev)
570 "Accept the item at the mouse click."
573 (setq reftex-select-data (get-text-property (point) :data))
574 (setq last-data (or reftex-select-data last-data))
575 (throw 'myexit 'return))
576 (defun reftex-select-read-label ()
577 "Use minibuffer to read a label to reference, with completion."
579 (let ((label (completing-read
580 "Label: " (symbol-value reftex-docstruct-symbol)
581 nil nil reftex-prefix)))
582 (unless (or (equal label "") (equal label reftex-prefix))
583 (throw 'myexit label))))
584 (defun reftex-select-read-cite ()
585 "Use minibuffer to read a citation key with completion."
587 (let* ((key (completing-read "Citation key: " found-list))
588 (entry (assoc key found-list)))
590 ((or (null key) (equal key "")))
592 (setq reftex-select-data entry)
593 (setq last-data reftex-select-data)
594 (throw 'myexit 'return))
595 (t (throw 'myexit key)))))
597 (defun reftex-select-mark (&optional separator)
600 (let* ((data (get-text-property (point) :data))
602 (or data (error "No entry to mark at point"))
603 (if (assq data reftex-select-marked)
604 (error "Entry is already marked"))
605 (setq boe (or (previous-single-property-change (1+ (point)) :data)
607 eoe (or (next-single-property-change (point) :data) (point-max)))
608 (setq ovl (reftex-make-overlay boe eoe))
609 (push (list data ovl separator) reftex-select-marked)
610 (reftex-overlay-put ovl 'face reftex-select-mark-face)
611 (reftex-overlay-put ovl 'before-string
613 (format "*%c%d* " separator
614 (length reftex-select-marked))
615 (format "*%d* " (length reftex-select-marked))))
616 (message "Entry has mark no. %d" (length reftex-select-marked))))
618 (defun reftex-select-mark-comma ()
619 "Mark the entry and store the `comma' separator."
621 (reftex-select-mark ?,))
622 (defun reftex-select-mark-to ()
623 "Mark the entry and store the `to' separator."
625 (reftex-select-mark ?-))
626 (defun reftex-select-mark-and ()
627 "Mark the entry and store `and' to separator."
629 (reftex-select-mark ?+))
631 (defun reftex-select-unmark ()
634 (let* ((data (get-text-property (point) :data))
635 (cell (assq data reftex-select-marked))
640 (error "No marked entry at point"))
641 (and ovl (reftex-delete-overlay ovl))
642 (setq reftex-select-marked (delq cell reftex-select-marked))
643 (setq cnt (1+ (length reftex-select-marked)))
646 (reftex-overlay-put (nth 1 c) 'before-string
648 (format "*%c%d* " sep (decf cnt))
649 (format "*%d* " (decf cnt)))))
650 reftex-select-marked)
651 (message "Entry no longer marked")))
653 (defun reftex-select-help ()
654 "Display a summary of the special key bindings."
656 (with-output-to-temp-buffer "*RefTeX Help*"
658 (reftex-enlarge-to-fit "*RefTeX Help*" t))
660 ;; Common bindings in reftex-select-label-map and reftex-select-bib-map
661 (let ((map (make-sparse-keymap)))
662 (substitute-key-definition
663 'next-line 'reftex-select-next map global-map)
664 (substitute-key-definition
665 'previous-line 'reftex-select-previous map global-map)
666 (substitute-key-definition
667 'keyboard-quit 'reftex-select-keyboard-quit map global-map)
668 (substitute-key-definition
669 'newline 'reftex-select-accept map global-map)
672 '((" " . reftex-select-callback)
673 ("n" . reftex-select-next)
674 ([(down)] . reftex-select-next)
675 ("p" . reftex-select-previous)
676 ([(up)] . reftex-select-previous)
677 ("f" . reftex-select-toggle-follow)
678 ("\C-m" . reftex-select-accept)
679 ([(return)] . reftex-select-accept)
680 ("q" . reftex-select-quit)
681 ("." . reftex-select-show-insertion-point)
682 ("?" . reftex-select-help))
683 do (define-key map (car x) (cdr x)))
685 ;; The mouse-2 binding
686 (if (featurep 'xemacs)
687 (define-key map [(button2)] 'reftex-select-mouse-accept)
688 (define-key map [(mouse-2)] 'reftex-select-mouse-accept)
689 (define-key map [follow-link] 'mouse-face))
693 (loop for key across "0123456789" do
694 (define-key map (vector (list key)) 'digit-argument))
695 (define-key map "-" 'negative-argument)
698 (setq reftex-select-label-map map)
699 (setq reftex-select-bib-map (copy-keymap map)))
701 ;; Specific bindings in reftex-select-label-map
702 (loop for key across "aAcgFlrRstx#%" do
703 (define-key reftex-select-label-map (vector (list key))
705 "Press `?' during selection to find out about this key."
706 '(interactive) (list 'throw '(quote myexit) key))))
709 '(("b" . reftex-select-jump-to-previous)
710 ("z" . reftex-select-jump)
711 ("v" . reftex-select-toggle-varioref)
712 ("V" . reftex-select-toggle-fancyref)
713 ("m" . reftex-select-mark)
714 ("u" . reftex-select-unmark)
715 ("," . reftex-select-mark-comma)
716 ("-" . reftex-select-mark-to)
717 ("+" . reftex-select-mark-and)
718 ([(tab)] . reftex-select-read-label)
719 ("\C-i" . reftex-select-read-label)
720 ("\C-c\C-n" . reftex-select-next-heading)
721 ("\C-c\C-p" . reftex-select-previous-heading))
723 (define-key reftex-select-label-map (car x) (cdr x)))
725 ;; Specific bindings in reftex-select-bib-map
726 (loop for key across "grRaAeE" do
727 (define-key reftex-select-bib-map (vector (list key))
729 "Press `?' during selection to find out about this key."
730 '(interactive) (list 'throw '(quote myexit) key))))
733 '(("\C-i" . reftex-select-read-cite)
734 ([(tab)] . reftex-select-read-cite)
735 ("m" . reftex-select-mark)
736 ("u" . reftex-select-unmark))
737 do (define-key reftex-select-bib-map (car x) (cdr x)))
740 ;;; reftex-sel.el ends here