205 lines
8.0 KiB
EmacsLisp
205 lines
8.0 KiB
EmacsLisp
;;; company-quickhelp.el --- Popup documentation for completion candidates
|
|
|
|
;; Copyright (C) 2016, Lars Andersen
|
|
|
|
;; Author: Lars Andersen <expez@expez.com>
|
|
;; URL: https://www.github.com/expez/company-quickhelp
|
|
;; Package-Version: 20160826.806
|
|
;; Keywords: company popup documentation quickhelp
|
|
;; Version: 1.4.0
|
|
;; Package-Requires: ((emacs "24.4") (company "0.8.9") (pos-tip "0.4.6"))
|
|
|
|
;; This file is not part of GNU Emacs.
|
|
|
|
;; This program is free software: you can redistribute it and/or modify
|
|
;; it under the terms of the GNU General Public License as published by
|
|
;; the Free Software Foundation, either version 3 of the License, or
|
|
;; (at your option) any later version.
|
|
|
|
;; This program is distributed in the hope that it will be useful,
|
|
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
;; GNU General Public License for more details.
|
|
|
|
;; You should have received a copy of the GNU General Public License
|
|
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
;;; Commentary:
|
|
|
|
;; When idling on a completion candidate the documentation for the
|
|
;; candidate will pop up after `company-quickhelp-idle-delay' seconds.
|
|
|
|
;;; Usage:
|
|
;; put (company-quickhelp-mode 1) in you init.el to activate
|
|
;; `company-quickhelp-mode'.
|
|
|
|
;; You can adjust the time it takes for the documentation to pop up by
|
|
;; changing `company-quickhelp-delay'
|
|
|
|
;;; Code:
|
|
(require 'company)
|
|
(require 'pos-tip)
|
|
(require 'cl-lib)
|
|
|
|
(defgroup company-quickhelp nil
|
|
"Documentation popups for `company-mode'"
|
|
:group 'company)
|
|
|
|
(defcustom company-quickhelp-delay 0.5
|
|
"Delay, in seconds, before the quickhelp popup appears.
|
|
|
|
If set to nil the popup won't automatically appear, but can still
|
|
be triggered manually using `company-quickhelp-show'."
|
|
:type '(choice (number :tag "Delay in seconds")
|
|
(const :tag "Don't popup help automatically" nil))
|
|
:group 'company-quickhelp)
|
|
|
|
(defcustom company-quickhelp-max-lines nil
|
|
"When not NIL, limits the number of lines in the popup."
|
|
:type '(choice (integer :tag "Max lines to show in popup")
|
|
(const :tag "Don't limit the number of lines shown" nil))
|
|
:group 'company-quickhelp)
|
|
|
|
(defvar company-quickhelp--timer nil
|
|
"Quickhelp idle timer.")
|
|
|
|
(defvar company-quickhelp--original-tooltip-width company-tooltip-minimum-width
|
|
"The documentation popup breaks inexplicably when we transition
|
|
from a large pseudo-tooltip to a small one. We solve this by
|
|
overriding `company-tooltip-minimum-width' and save the
|
|
original value here so we can restore it.")
|
|
|
|
(defun company-quickhelp-frontend (command)
|
|
"`company-mode' front-end showing documentation in a `pos-tip' popup."
|
|
(pcase command
|
|
(`post-command (when company-quickhelp-delay
|
|
(company-quickhelp--set-timer)))
|
|
(`hide
|
|
(when company-quickhelp-delay
|
|
(company-quickhelp--cancel-timer))
|
|
(pos-tip-hide))))
|
|
|
|
(defun company-quickhelp--doc-and-meta (doc)
|
|
;; The company backend can either return a buffer with the doc or a
|
|
;; cons containing the doc buffer and a position at which to start
|
|
;; reading.
|
|
(let ((doc-buffer (if (consp doc) (car doc) doc))
|
|
(doc-begin (when (consp doc) (cdr doc))))
|
|
(with-current-buffer doc-buffer
|
|
(let ((truncated t))
|
|
(goto-char (or doc-begin (point-min)))
|
|
(if company-quickhelp-max-lines
|
|
(forward-line company-quickhelp-max-lines)
|
|
(goto-char (point-max)))
|
|
(beginning-of-line)
|
|
(when (= (line-number-at-pos)
|
|
(save-excursion (goto-char (point-max)) (line-number-at-pos)))
|
|
(setq truncated nil))
|
|
(while (and (not (= (line-number-at-pos) 1))
|
|
(or
|
|
;; [back] appears at the end of the help elisp help buffer
|
|
(looking-at-p "\\[back\\]")
|
|
;; [source] cider's help buffer contains a link to source
|
|
(looking-at-p "\\[source\\]")
|
|
(looking-at-p "^\\s-*$")))
|
|
(forward-line -1))
|
|
(list :doc (buffer-substring-no-properties (point-min) (point-at-eol))
|
|
:truncated truncated)))))
|
|
|
|
(defun company-quickhelp--completing-read (prompt candidates &rest rest)
|
|
"`cider', and probably other libraries, prompt the user to
|
|
resolve ambiguous documentation requests. Instead of failing we
|
|
just grab the first candidate and press forward."
|
|
(car candidates))
|
|
|
|
(defun company-quickhelp--doc (selected)
|
|
(cl-letf (((symbol-function 'completing-read)
|
|
#'company-quickhelp--completing-read))
|
|
(let* ((doc (company-call-backend 'doc-buffer selected))
|
|
(doc-and-meta (when doc
|
|
(company-quickhelp--doc-and-meta doc)))
|
|
(truncated (plist-get doc-and-meta :truncated))
|
|
(doc (plist-get doc-and-meta :doc)))
|
|
(unless (string= doc "")
|
|
(if truncated
|
|
(concat doc "\n\n[...]")
|
|
doc)))))
|
|
|
|
(defun company-quickhelp-manual-begin ()
|
|
"Manually trigger the `company-quickhelp' popup for the
|
|
currently active `company' completion candidate."
|
|
(interactive)
|
|
;; This might seem a bit roundabout, but when I attempted to call
|
|
;; `company-quickhelp--show' in a more direct manner it triggered a
|
|
;; redisplay of company's list of completion candidates which looked
|
|
;; quite weird.
|
|
(let ((company-quickhelp-delay 0.01))
|
|
(company-quickhelp--set-timer)))
|
|
|
|
(defun company-quickhelp--show ()
|
|
(company-quickhelp--ensure-compatibility)
|
|
(company-quickhelp--cancel-timer)
|
|
(let* ((selected (nth company-selection company-candidates))
|
|
(doc (company-quickhelp--doc selected))
|
|
(ovl company-pseudo-tooltip-overlay)
|
|
(overlay-width (* (frame-char-width)
|
|
(if ovl (overlay-get ovl 'company-width) 0)))
|
|
(overlay-position (* (frame-char-width)
|
|
(- (if ovl (overlay-get ovl 'company-column) 1) 1)))
|
|
(x-gtk-use-system-tooltips nil))
|
|
(when (and ovl doc)
|
|
(with-no-warnings
|
|
(pos-tip-show doc nil (overlay-start ovl) nil 300 80 nil
|
|
(+ overlay-width overlay-position) 1)))))
|
|
|
|
(defun company-quickhelp--set-timer ()
|
|
(when (null company-quickhelp--timer)
|
|
(setq company-quickhelp--timer
|
|
(run-with-idle-timer company-quickhelp-delay nil
|
|
'company-quickhelp--show))))
|
|
|
|
(defun company-quickhelp--cancel-timer ()
|
|
(when (timerp company-quickhelp--timer)
|
|
(cancel-timer company-quickhelp--timer)
|
|
(setq company-quickhelp--timer nil)))
|
|
|
|
(defun company-quickhelp-hide ()
|
|
(company-cancel))
|
|
|
|
(defun company-quickhelp--ensure-compatibility ()
|
|
;; Originally this code was in `company-quickhelp-enable' but that
|
|
;; caused trouble for --daemon users reported in #16.
|
|
(cond
|
|
((or (not (fboundp 'x-hide-tip))
|
|
(not (fboundp 'x-show-tip)))
|
|
(user-error "Company-quickhelp doesn't work on your system.
|
|
Most likely this means you're on a mac with an Emacs build using Cocoa instead of X"))
|
|
((or (null window-system)
|
|
(eq window-system 'pc))
|
|
(user-error "Company-quickhelp doesn't work in the terminal"))))
|
|
|
|
(defun company-quickhelp--enable ()
|
|
(add-hook 'focus-out-hook #'company-quickhelp-hide)
|
|
(setq company-quickhelp--original-tooltip-width company-tooltip-minimum-width
|
|
company-tooltip-minimum-width (max company-tooltip-minimum-width 40))
|
|
(add-to-list 'company-frontends 'company-quickhelp-frontend :append))
|
|
|
|
(defun company-quickhelp--disable ()
|
|
(remove-hook 'focus-out-hook #'company-quickhelp-hide)
|
|
(company-quickhelp--cancel-timer)
|
|
(setq company-tooltip-minimum-width company-quickhelp--original-tooltip-width
|
|
company-frontends
|
|
(delq 'company-quickhelp-frontend company-frontends)))
|
|
|
|
;;;###autoload
|
|
(define-minor-mode company-quickhelp-mode
|
|
"Provides documentation popups for `company-mode' using `pos-tip'."
|
|
:global t
|
|
(if company-quickhelp-mode
|
|
(company-quickhelp--enable)
|
|
(company-quickhelp--disable)))
|
|
|
|
(provide 'company-quickhelp)
|
|
|
|
;;; company-quickhelp.el ends here
|