popup.el is a visual popup user interface library for Emacs. This provides a basic API and common UI widgets such as popup tooltips and popup menus.
Tooltip
Popup Menu
Popup Cascade Menu
You can install popup.el
from MELPA with package.el.
popwin is tested under GNU Emacs 24 or later.
Alternatively, users of Debian 9 or later or Ubuntu 16.04 or later may
simply apt-get install elpa-popup
.
Elements of popup-list
have to be popup items. A popup item is
substantially a string but it may involve some text-properties. There
are two ways to make popup items. One is just using strings. Another
is to use the popup-make-item
function, which just returns the string
after adding text-properties of its keywords. Effective text-properties
are:
value
-- This represents the real value of the item. This will be used when returning the value but not the item (or string) from some synchronous functions such aspopup-menu*
.face
-- The background face of the item. The value ofpopup-face
will be overridden.selection-face
-- The selection face of the item. The value ofpopup-selection-face
will be overridden.document
-- The documentation string or function of the item.summary
-- The summary string of the item. This will be shown inline with the item.symbol
-- The symbol character of the item.sublist
-- The sublist of the item. This is effective only withpopup-cascade-menu
.
All of properties can be accessed by popup-item-<property>
utility function.
popup-item-propertize item &rest properties => item
Same as propertize
except that this avoids overriding existed value
with nil
property.
popup-make-item name &key value popup-face selection-face sublist
document symbol summary => item
The utility function of popup-item-propertize
.
This section describes the basic data structures and operations of popups.
Any instance of popup
structure has the following fields (some
unimportant fields are not listed):
point
row
-- The line number.column
width
-- Max width ofpopup
instance.height
-- Max height ofpopup
instance.min-height
current-height
direction
-- Positive number means forward, negative number means backward.parent
-- The parent ofpopup
instance.face
-- The background face.selection-face
margin-left
margin-right
scroll-bar
-- Non-nil meanspopup
instance has a scroll bar.symbol
-- Non-nil meanspopup
instance has a space for displaying symbols of item.cursor
-- The current position oflist
.scroll-top
-- The offset of scrolling.list
-- The contents ofpopup
instance in a list of items (strings).original-list
-- Same aslist
except that this is not filtered.
All of these fields can be accessed by popup-<field>
function.
popup-create point width height &key min-height max-width around face
selection-face scroll-bar margin-left margin-right symbol parent
parent-offset => popup
Create a popup instance at POINT
with WIDTH
and HEIGHT
.
MIN-HEIGHT
is the minimal height of the popup. The default value is 0.
MAX-WIDTH
is the maximum width of the popup. The default value is
nil (no limit). If a floating point, the value refers to the ratio of
the window. If an integer, limit is in characters.
If AROUND
is non-nil, the popup will be displayed around the point
but not at the point.
FACE
is the background face of the popup. The default value is
popup-face
.
SELECTION-FACE
is the foreground (selection) face of the popup The
default value is popup-face
.
If SCROLL-BAR
is non-nil, the popup will have a scroll bar at the
right.
If MARGIN-LEFT
is non-nil, the popup will have a margin at the left.
If MARGIN-RIGHT
is non-nil, the popup will have a margin at the
right.
SYMBOL
is a single character which indicates the kind of the item.
PARENT
is the parent popup instance. If PARENT
is omitted, the popup
will be a root instance.
PARENT-OFFSET
is a row offset from the parent popup.
Here is an example:
(setq popup (popup-create (point) 10 10))
(popup-set-list popup '("Foo" "Bar" "Baz"))
(popup-draw popup)
;; do something here
(popup-delete popup)
popup-delete popup
Delete the POPUP
.
popup-live-p popup => boolean
popup-set-list popup list
Set the contents of the POPUP
. LIST
has to be popup items.
popup-draw popup
Draw the contents of the POPUP
.
popup-hide popup
Hide the POPUP
. To show again, call popup-draw
.
Function: popup-hidden-p
popup-hidden-p popup
Return non-nil if the POPUP
is hidden.
popup-select popup index
Select the item of INDEX
of the POPUP
.
popup-selected-item popup => item
Return the selected item of the POPUP
.
Return non-nil if the POPUP
is still alive.
popup-next popup
Select the next item of the POPUP
.
popup-previous popup
Select the next item of the POPUP
.
popup-scroll-down popup n
Scroll down N
items of the POPUP
. This won't wrap.
popup-scroll-up popup n
Scroll up N
items of the POPUP
. This won't wrap.
popup-isearch popup &key cursor-color keymap callback help-delay
=> boolean
Enter incremental search event loop of POPUP
.
A tooltip is an useful visual UI widget for displaying information something about what cursor points to.
popup-tip string &key point around width height min-height max-width
truncate margin margin-left margin-right scroll-bar parent
parent-offset nowait nostrip prompt
Show a tooltip with message STRING
at POINT
. This function is
synchronized unless NOWAIT
specified. Almost all arguments are same as
popup-create
except for TRUNCATE
, NOWAIT
, NOSTRIP
and PROMPT
.
If TRUNCATE
is non-nil, the tooltip can be truncated.
If NOWAIT
is non-nil, this function immediately returns the tooltip
instance without entering event loop.
If NOSTRIP
is non-nil, STRING
properties are not stripped.
PROMPT
is a prompt string used when reading events during the event
loop.
Here is an example:
(popup-tip "Hello, World!")
;; reach here after the tooltip disappeared
Popup menu is an useful visual UI widget for prompting users to select an item of a list.
popup-menu* list &key point around width height margin margin-left
margin-right scroll-bar symbol parent parent-offset keymap
fallback help-delay nowait prompt isearch isearch-filter isearch-cursor-color
isearch-keymap isearch-callback initial-index => selected-value
Show a popup menu of LIST
at POINT
. This function returns the value
of the selected item. Almost all arguments are same as popup-create
except for KEYMAP
, FALLBACK
, HELP-DELAY
, PROMPT
, ISEARCH
,
ISEARCH-FILTER
, ISEARCH-CURSOR-COLOR
, ISEARCH-KEYMAP
and ISEARCH-CALLBACK
.
If KEYMAP
is provided, it is a keymap which is used when processing
events during event loop.
If FALLBACK
is provided, it is a function taking two arguments; a key
and a command. FALLBACK
is called when no special operation is found
on the key. The default value is popup-menu-fallback
, which does
nothing.
HELP-DELAY
is a delay of displaying helps.
If NOWAIT
is non-nil, this function immediately returns the menu
instance without entering event loop.
PROMPT
is a prompt string when reading events during event loop.
If ISEARCH
is non-nil, do isearch as soon as displaying the popup
menu.
ISEARCH-FILTER
is a filtering function taking two arguments:
search pattern and list of items. Returns a list of matching items.
ISEARCH-CURSOR-COLOR
is a cursor color during isearch. The default
value is `popup-isearch-cursor-color'.
ISEARCH-KEYMAP
is a keymap which is used when processing events
during event loop. The default value is popup-isearch-keymap
.
ISEARCH-CALLBACK
is a function taking one argument. popup-menu
calls ISEARCH-CALLBACK
, if specified, after isearch finished or
isearch canceled. The arguments is whole filtered list of items.
If INITIAL-INDEX
is non-nil, this is an initial index value for
popup-select
. Only positive integer is valid.
Here is an example:
(popup-menu* '("Foo" "Bar" "Baz"))
;; => "Baz" if you select Baz
(popup-menu* (list (popup-make-item "Yes" :value t)
(popup-make-item "No" :value nil)))
;; => t if you select Yes
Same as popup-menu
except that an element of LIST
can be also a
sub-menu if the element is a cons cell formed (ITEM . SUBLIST)
where
ITEM
is an usual item and SUBLIST
is a list of the sub menu.
Here is an example:
(popup-cascade-menu '(("Top1" "Sub1" "Sub2") "Top2"))
Function used to construct a regexp from a pattern. You may for instance
provide a function that replaces spaces by '.+' if you like helm or ivy style
of completion. Default value is #'regexp-quote
.
Copyright (C) 2011-2015 Tomohiro Matsuyama <[email protected]>
Copyright (C) 2020-2021 Jen-Chieh Shen <[email protected]>