I want to show a popup menu similar to that used in Magit. It seems like Magit has separate package that manages all that popup business, so I started reading source of magit-popup.el. It's not big, but not small either, 1k+ lines of code. That's not obvious how to write something much simpler using the same concept.

I see that magit-popup.el uses button.el built-in package, so I started to read documentation of that package too (I'm not familiar with it). Right now I don't know where to start, I just want to show a little window with buttons, there should be only one section with several rows, like this:

Some title with my project-specific info.

Commands:

a one command  e ...
b another one  f ...
c ...          g ...
d ...          h ...

So the solution should have the following specific features:

• it should display all items to choose from at once;
• every item should be selectable with one key pressing (user enters character corresponding to desired menu item);
• buffer itself should be shown in separate window at the bottom of currently active window.

Ideally I would like to get nil (if user aborts the popup with C-g for example), or name of command (this is probably different from normal usage where something is automatically called, as I understand).

Can you tell me how do I write something like this? Should I use define-button-type, then somehow define all the buttons and then insert them into newly created buffer? Does the buffer just read one key press or does it handle it via some key map?

This question doesn't beg for code, it asks for tools (functions, libraries) that can be used to simplify creating of such an interface element.

Question

I would like to create user interface in form of popup menu, popup menu similar to that used in Magit.

Features

Definition of Popup

Popup in context of this question means little temporary window that contains collection of menu items so that user can select one and only one of these items.

Position on the Screen

The popup is allowed to appear in any part of the screen, but it's desirable that it should be quite obvious and thus it should appear beside currently active window.

Contents of Popup Buffer

Items should be displayed in form of pretty table. Pretty is context of the question means visually appealing, this effect can be most easily achieved by putting menu items into straight rows, see complete--insert-string for example. This paragraph serves for additional clarification, you can do it in your own way, this won't render your answer incorrect.

Selection of Menu Item

The selection is expected to be performed by a single key-pressing or, optionally with a mouse (although it's not that important so answers containing propositions that don't support mouse are legal). If you propose solution that supports mouse, please note that user should be able to select a menu item in an intuitive way, that is, by left-button clicking on desired choice.

N.B. mouse can be used in many ways and alternative ways to indicate a choice are also welcomed.

Elimination of Popup

Once user has selected a menu item in a way described above, the buffer and thus its window should be eliminated from view as well as killed. The window that has been active before invocation of the popup menu should get focus (that is, become active) again.

Returned Value and Arguments

Preferably, this consequence of actions should result in a Lisp object returned. The Lisp object can be either:

• nil — this indicates that user has aborted the popup menu either by pressing C-g or in some other way †.

• string — string (it's allowed to use a symbol) should be string-equal to one of the strings supplied to the popup menu as collection of actual items.

Alternative ways to let the rest of program know user's choice, or, possibly, its absence, are acceptable. However, if it's not clear how else it can be performed I ask all answerers improvise and don't ask me for further clarification of this aspect.

This is all for returned value. As for input parameters, they should at least include collection of strings which represent possible choices (that is, menu items).

Acceptable Answers

Expected answer can be of the following forms:

• Sufficient code snippet that allows educated reader to write function like that described above; it's not expected or necessary to write entire working function. However, to avoid uncertainty (can considerable parts of code be omitted?), I should note that missing parts of the snippet should be described in textual component of answer.

• A link to existing library that implements similar functionality. To avoid uncertainty, I should note that similar in our case means that the library can be used to create popup (see definition above) that has at least 2 or 3 features described above. If proposed library is different to the point where the previously stated condition cannot be met, each such case will be judged independently and will be always upvoted if OP deems it useful.

• Description of built-in Emacs functions or third-party ones that can be used to implement any feature described in section «Features», see above. To avoid uncertainty, please state clearly how your answer can be useful for future readers who want to implement popup, popup menu similar to that used in Magit.

† Alternative ways to abort the popup menu may include the following (but not limited to these):

• clicking outside of popup menu window;

• killing of buffer containing the popup without making a choice.

I want to show a popup menu similar to that used in Magit. It seems like Magit has separate package that manages all that popup business, so I started reading source of magit-popup.el. It's not big, but not small either, 1k+ lines of code. That's not obvious how to write something much simpler using the same concept.

I see that magit-popup.el uses button.el built-in package, so I started to read documentation of that package too (I'm not familiar with it). Right now I don't know where to start, I just want to show a little window with buttons, there should be only one section with several rows, like this:

Some title with my project-specific info.

Commands:

a one command  e ...
b another one  f ...
c ...          g ...
d ...          h ...

ideally I would like to get nil (if user aborts the popup with C-g for example), or name of command (this is probably different from normal usage where something is automatically called, as I understand).

Can you tell me how do I write something like this? Should I use define-button-type, then somehow define all the buttons and then insert them into newly created buffer? Does the buffer just read one key press or does it handle it via some key map?

I want to show a popup menu similar to that used in Magit. It seems like Magit has separate package that manages all that popup business, so I started reading source of magit-popup.el. It's not big, but not small either, 1k+ lines of code. That's not obvious how to write something much simpler using the same concept.

I see that magit-popup.el uses button.el built-in package, so I started to read documentation of that package too (I'm not familiar with it). Right now I don't know where to start, I just want to show a little window with buttons, there should be only one section with several rows, like this:

Some title with my project-specific info.

Commands:

a one command  e ...
b another one  f ...
c ...          g ...
d ...          h ...

So the solution should have the following specific features:

• it should display all items to choose from at once;
• every item should be selectable with one key pressing (user enters character corresponding to desired menu item);
• buffer itself should be shown in separate window at the bottom of currently active window.

Ideally I would like to get nil (if user aborts the popup with C-g for example), or name of command (this is probably different from normal usage where something is automatically called, as I understand).

Can you tell me how do I write something like this? Should I use define-button-type, then somehow define all the buttons and then insert them into newly created buffer? Does the buffer just read one key press or does it handle it via some key map?

This question doesn't beg for code, it asks for tools (functions, libraries) that can be used to simplify creating of such an interface element.