1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
popup.el
========
[![Build Status](https://secure.travis-ci.org/auto-complete/popup-el.svg)](http://travis-ci.org/auto-complete/popup-el) [![melpa badge][melpa-badge]][melpa-link] [![melpa stable badge][melpa-stable-badge]][melpa-stable-link]
Overview
--------
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.
Screenshots
-----------
**Tooltip**
![](https://raw.githubusercontent.com/auto-complete/popup-el/master/etc/images/popup1.png)
**Popup Menu**
![](https://raw.githubusercontent.com/auto-complete/popup-el/master/etc/images/popup2.png)
**Popup Cascade Menu**
![](https://raw.githubusercontent.com/auto-complete/popup-el/master/etc/images/popup3.png)
Installation
------------
You can install `popup.el` from [MELPA](http://melpa.org/) with package.el.
popwin is tested under GNU Emacs 24 or later.
Popup Items
-----------
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 as `popup-menu*`.
* `face` -- The background face of the item. The value of `popup-face`
will be overridden.
* `selection-face` -- The selection face of the item. The value of
`popup-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 with
`popup-cascade-menu`.
All of properties can be accessed by `popup-item-<property>` utility function.
### Function: `popup-item-propertize`
popup-item-propertize item &rest properties => item
Same as `propertize` except that this avoids overriding existed value
with `nil` property.
### Function: `popup-make-item`
popup-make-item name &key value popup-face selection-face sublist
document symbol summary => item
The utility function of `popup-item-propertize`.
Popups
------
This section describes the basic data structures and operations of
popups.
### Struct: `popup`
Any instance of `popup` structure has the following fields (some
unimportant fields are not listed):
* `point`
* `row` -- The line number.
* `column`
* `width` -- Max width of `popup` instance.
* `height` -- Max height of `popup` instance.
* `min-height`
* `current-height`
* `direction` -- Positive number means forward, negative number means
backward.
* `parent` -- The parent of `popup` instance.
* `face` -- The background face.
* `selection-face`
* `margin-left`
* `margin-right`
* `scroll-bar` -- Non-nil means `popup` instance has a scroll bar.
* `symbol` -- Non-nil means `popup` instance has a space for
displaying symbols of item.
* `cursor` -- The current position of `list`.
* `scroll-top` -- The offset of scrolling.
* `list` -- The contents of `popup` instance in a list of items
(strings).
* `original-list` -- Same as `list` except that this is not filtered.
All of these fields can be accessed by `popup-<field>` function.
### Function: `popup-create`
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)
### Function: `popup-delete`
popup-delete popup
Delete the `POPUP`.
### Function: `popup-live-p`
popup-live-p popup => boolean
### Function: `popup-set-list`
popup-set-list popup list
Set the contents of the `POPUP`. `LIST` has to be popup items.
### Function: `popup-draw`
popup-draw popup
Draw the contents of the `POPUP`.
### Function: `popup-hide`
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.
### Function: `popup-select`
popup-select popup index
Select the item of `INDEX` of the `POPUP`.
### Function: `popup-selected-item`
popup-selected-item popup => item
Return the selected item of the `POPUP`.
Return non-nil if the `POPUP` is still alive.
### Function: `popup-next`
popup-next popup
Select the next item of the `POPUP`.
### Function: `popup-previous`
popup-previous popup
Select the next item of the `POPUP`.
### Function: `popup-scroll-down`
popup-scroll-down popup n
Scroll down `N` items of the `POPUP`. This won't wrap.
### Function: `popup-scroll-up`
popup-scroll-up popup n
Scroll up `N` items of the `POPUP`. This won't wrap.
### Function: `popup-isearch`
popup-isearch popup &key cursor-color keymap callback help-delay
=> boolean
Enter incremental search event loop of `POPUP`.
Tooltips
--------
A tooltip is an useful visual UI widget for displaying information
something about what cursor points to.
### Function: `popup-tip`
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 Menus
-----------
Popup menu is an useful visual UI widget for prompting users to
select an item of a list.
### Function: `popup-menu*`
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
### Function: `popup-cascade-menu`
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"))
----
Copyright (C) 2011-2015 Tomohiro Matsuyama <<m2ym.pub@gmail.com>>
[melpa-link]: http://melpa.org/#/popup
[melpa-stable-link]: http://stable.melpa.org/#/popup
[melpa-badge]: http://melpa.org/packages/popup-badge.svg
[melpa-stable-badge]: http://stable.melpa.org/packages/popup-badge.svg
|