{"id":13711412,"url":"https://github.com/auto-complete/popup-el","last_synced_at":"2025-05-15T13:08:47.844Z","repository":{"id":37390972,"uuid":"1410546","full_name":"auto-complete/popup-el","owner":"auto-complete","description":"Visual Popup Interface Library for Emacs","archived":false,"fork":false,"pushed_at":"2025-04-22T23:12:27.000Z","size":249,"stargazers_count":455,"open_issues_count":37,"forks_count":95,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-23T00:23:17.523Z","etag":null,"topics":["auto-complete","emacs","popup-el"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auto-complete.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"jcs090218"}},"created_at":"2011-02-25T10:53:52.000Z","updated_at":"2025-04-22T23:12:31.000Z","dependencies_parsed_at":"2024-03-27T07:27:03.509Z","dependency_job_id":"e238b43a-ff02-4320-8978-7345e8c9fa96","html_url":"https://github.com/auto-complete/popup-el","commit_stats":{"total_commits":184,"total_committers":29,"mean_commits":6.344827586206897,"dds":0.7010869565217391,"last_synced_commit":"c83d6e5f5fa693e08a542ea9ad7c06eced652de9"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-complete%2Fpopup-el","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-complete%2Fpopup-el/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-complete%2Fpopup-el/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auto-complete%2Fpopup-el/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auto-complete","download_url":"https://codeload.github.com/auto-complete/popup-el/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auto-complete","emacs","popup-el"],"created_at":"2024-08-02T23:01:07.948Z","updated_at":"2025-05-15T13:08:42.835Z","avatar_url":"https://github.com/auto-complete.png","language":"Emacs Lisp","funding_links":["https://github.com/sponsors/jcs090218"],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![melpa badge][melpa-badge]][melpa-link] \n[![melpa stable badge][melpa-stable-badge]][melpa-stable-link]\n\n# popup.el\n\n[![CI](https://github.com/auto-complete/popup-el/actions/workflows/test.yml/badge.svg)](https://github.com/auto-complete/popup-el/actions/workflows/test.yml)\n\n## Overview\n\npopup.el is a visual popup user interface library for Emacs. This\nprovides a basic API and common UI widgets such as popup tooltips and\npopup menus.\n\n## Screenshots\n\n| Tooltip                                                                                    | Popup Menu                                                                                 | Popup Cascade Menu                                                                         |\n|:-------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------|\n| ![](https://raw.githubusercontent.com/auto-complete/popup-el/master/etc/images/popup1.png) | ![](https://raw.githubusercontent.com/auto-complete/popup-el/master/etc/images/popup2.png) | ![](https://raw.githubusercontent.com/auto-complete/popup-el/master/etc/images/popup3.png) |\n\n## Installation\n\nYou can install `popup.el` from [MELPA](https://melpa.org/) with package.el.\npopwin is tested under GNU Emacs 24 or later.\n\nAlternatively, users of Debian 9 or later or Ubuntu 16.04 or later may\nsimply `apt-get install elpa-popup`.\n\n## Popup Items\n\nElements of `popup-list` have to be popup items. A popup item is\nsubstantially a string but it may involve some text-properties. There\nare two ways to make popup items. One is just using strings. Another\nis to use the `popup-make-item` function, which just returns the string\nafter adding text-properties of its keywords. Effective text-properties\nare:\n\n* `value` -- This represents the **real** value of the item. This will\n  be used when returning the value but not the item (or string) from\n  some synchronous functions such as `popup-menu*`.\n* `face` -- The background face of the item. The value of `popup-face`\n  will be overridden.\n* `selection-face` -- The selection face of the item. The value of\n  `popup-selection-face` will be overridden.\n* `document` -- The documentation string or function of the item.\n* `summary` -- The summary string of the item. This will be shown\n  inline with the item.\n* `symbol` -- The symbol character of the item.\n* `sublist` -- The sublist of the item. This is effective only with\n  `popup-cascade-menu`.\n\nAll of properties can be accessed by `popup-item-\u003cproperty\u003e` utility function.\n\n### Function: `popup-item-propertize`\n\n```\npopup-item-propertize item \u0026rest properties =\u003e item\n```\n\nSame as `propertize` except that this avoids overriding existed value\nwith `nil` property.\n\n### Function: `popup-make-item`\n\n```\npopup-make-item name \u0026key value popup-face selection-face sublist\ndocument symbol summary =\u003e item\n```\n\nThe utility function of `popup-item-propertize`.\n\n## Popups\n\nThis section describes the basic data structures and operations of\npopups.\n\n### Struct: `popup`\n\nAny instance of `popup` structure has the following fields (some\nunimportant fields are not listed):\n\n* `point`\n* `row` -- The line number.\n* `column`\n* `width` -- Max width of `popup` instance.\n* `height` -- Max height of `popup` instance.\n* `min-height`\n* `current-height`\n* `direction` -- Positive number means forward, negative number means backward.\n* `parent` -- The parent of `popup` instance.\n* `face` -- The background face.\n* `selection-face`\n* `margin-left`\n* `margin-right`\n* `scroll-bar` -- Non-nil means `popup` instance has a scroll bar.\n* `symbol` -- Non-nil means `popup` instance has a space for displaying symbols of item.\n* `cursor` -- The current position of `list`.\n* `scroll-top` -- The offset of scrolling.\n* `list` -- The contents of `popup` instance in a list of items (strings).\n* `original-list` -- Same as `list` except that this is not filtered.\n\nAll of these fields can be accessed by `popup-\u003cfield\u003e` function.\n\n### Function: `popup-create`\n\n```\npopup-create point width height \u0026key min-height max-width around face\nselection-face scroll-bar margin-left margin-right symbol parent\nparent-offset =\u003e popup\n```\n\nCreate a popup instance at `POINT` with `WIDTH` and `HEIGHT`.\n\n`MIN-HEIGHT` is the minimal height of the popup. The default value is 0.\n\n`MAX-WIDTH` is the maximum width of the popup. The default value is\nnil (no limit). If a floating point, the value refers to the ratio of\nthe window. If an integer, limit is in characters.\n\nIf `AROUND` is non-nil, the popup will be displayed around the point\nbut not at the point.\n\n`FACE` is the background face of the popup. The default value is\n`popup-face`.\n\n`SELECTION-FACE` is the foreground (selection) face of the popup The\ndefault value is `popup-face`.\n\nIf `SCROLL-BAR` is non-nil, the popup will have a scroll bar at the\nright.\n\nIf `MARGIN-LEFT` is non-nil, the popup will have a margin at the left.\n\nIf `MARGIN-RIGHT` is non-nil, the popup will have a margin at the\nright.\n\n`SYMBOL` is a single character which indicates the kind of the item.\n\n`PARENT` is the parent popup instance. If `PARENT` is omitted, the popup\nwill be a root instance.\n\n`PARENT-OFFSET` is a row offset from the parent popup.\n\nHere is an example:\n\n```elisp\n(setq popup (popup-create (point) 10 10))\n(popup-set-list popup '(\"Foo\" \"Bar\" \"Baz\"))\n(popup-draw popup)\n;; do something here\n(popup-delete popup)\n```\n\n### Function: `popup-delete`\n\n```\npopup-delete popup\n```\n\nDelete the `POPUP`.\n\n### Function: `popup-live-p`\n\n```\npopup-live-p popup =\u003e boolean\n```\n\n### Function: `popup-set-list`\n\n```\npopup-set-list popup list\n```\n\nSet the contents of the `POPUP`. `LIST` has to be popup items.\n\n### Function: `popup-draw`\n\n```\npopup-draw popup\n```\n\nDraw the contents of the `POPUP`.\n\n### Function: `popup-hide`\n\n```\npopup-hide popup\n```\n\nHide the `POPUP`. To show again, call `popup-draw`.\n\n### Function: `popup-hidden-p`\n\n```\npopup-hidden-p popup\n```\n\nReturn non-nil if the `POPUP` is hidden.\n\n### Function: `popup-select`\n\n```\n    popup-select popup index\n```\n\nSelect the item of `INDEX` of the `POPUP`.\n\n### Function: `popup-selected-item`\n\n```\npopup-selected-item popup =\u003e item\n```\n\nReturn the selected item of the `POPUP`.\n\nReturn non-nil if the `POPUP` is still alive.\n\n### Function: `popup-next`\n\n```\npopup-next popup\n```\n\nSelect the next item of the `POPUP`.\n\n### Function: `popup-previous`\n\n```\npopup-previous popup\n```\n\nSelect the next item of the `POPUP`.\n\n### Function: `popup-scroll-down`\n\n```\npopup-scroll-down popup n\n```\n\nScroll down `N` items of the `POPUP`. This won't wrap.\n\n### Function: `popup-scroll-up`\n\n```\npopup-scroll-up popup n\n```\n\nScroll up `N` items of the `POPUP`. This won't wrap.\n\n### Function: `popup-isearch`\n\n```\npopup-isearch popup \u0026key cursor-color keymap callback help-delay\n=\u003e boolean\n```\n\nEnter incremental search event loop of `POPUP`.\n\n## Tooltips\n\nA tooltip is an useful visual UI widget for displaying information\nsomething about what cursor points to.\n\n### Function: `popup-tip`\n\n```\npopup-tip string \u0026key point around width height min-height max-width\ntruncate margin margin-left margin-right scroll-bar parent\nparent-offset nowait nostrip prompt\n```\n\nShow a tooltip with message `STRING` at `POINT`. This function is\nsynchronized unless `NOWAIT` specified. Almost all arguments are same as\n`popup-create` except for `TRUNCATE`, `NOWAIT`, `NOSTRIP` and `PROMPT`.\n\nIf `TRUNCATE` is non-nil, the tooltip can be truncated.\n\nIf `NOWAIT` is non-nil, this function immediately returns the tooltip\ninstance without entering event loop.\n\nIf `NOSTRIP` is non-nil, `STRING` properties are not stripped.\n\n`PROMPT` is a prompt string used when reading events during the event\nloop.\n\nHere is an example:\n\n```elisp\n(popup-tip \"Hello, World!\")\n;; reach here after the tooltip disappeared\n```\n\n## Popup Menus\n\nPopup menu is an useful visual UI widget for prompting users to\nselect an item of a list.\n\n### Function: `popup-menu*`\n\n```elisp\npopup-menu* list \u0026key point around width height margin margin-left\nmargin-right scroll-bar symbol parent parent-offset keymap\nfallback help-delay nowait prompt isearch isearch-filter isearch-cursor-color\nisearch-keymap isearch-callback initial-index =\u003e selected-value\n```\n\nShow a popup menu of `LIST` at `POINT`. This function returns the value\nof the selected item. Almost all arguments are same as `popup-create`\nexcept for `KEYMAP`, `FALLBACK`, `HELP-DELAY`, `PROMPT`, `ISEARCH`,\n`ISEARCH-FILTER`, `ISEARCH-CURSOR-COLOR`, `ISEARCH-KEYMAP`\nand `ISEARCH-CALLBACK`.\n\nIf `KEYMAP` is provided, it is a keymap which is used when processing\nevents during event loop.\n\nIf `FALLBACK` is provided, it is a function taking two arguments; a key\nand a command. `FALLBACK` is called when no special operation is found\non the key. The default value is `popup-menu-fallback`, which does\nnothing.\n\n`HELP-DELAY` is a delay of displaying helps.\n\nIf `NOWAIT` is non-nil, this function immediately returns the menu\ninstance without entering event loop.\n\n`PROMPT` is a prompt string when reading events during event loop.\n\nIf `ISEARCH` is non-nil, do isearch as soon as displaying the popup\nmenu.\n\n`ISEARCH-FILTER` is a filtering function taking two arguments:\nsearch pattern and list of items. Returns a list of matching items.\n\n`ISEARCH-CURSOR-COLOR` is a cursor color during isearch. The default\nvalue is `popup-isearch-cursor-color'.\n\n`ISEARCH-KEYMAP` is a keymap which is used when processing events\nduring event loop. The default value is `popup-isearch-keymap`.\n\n`ISEARCH-CALLBACK` is a function taking one argument.  `popup-menu`\ncalls `ISEARCH-CALLBACK`, if specified, after isearch finished or\nisearch canceled. The arguments is whole filtered list of items.\n\nIf `INITIAL-INDEX` is non-nil, this is an initial index value for\n`popup-select`. Only positive integer is valid.\n\nHere is an example:\n\n```elisp\n(popup-menu* '(\"Foo\" \"Bar\" \"Baz\"))\n;; =\u003e \"Baz\" if you select Baz\n(popup-menu* (list (popup-make-item \"Yes\" :value t)\n                   (popup-make-item \"No\" :value nil)))\n;; =\u003e t if you select Yes\n```\n\n### Function: `popup-cascade-menu`\n\nSame as `popup-menu` except that an element of `LIST` can be also a\nsub-menu if the element is a cons cell formed `(ITEM . SUBLIST)` where\n`ITEM` is an usual item and `SUBLIST` is a list of the sub menu.\n\nHere is an example:\n\n```elisp\n(popup-cascade-menu '((\"Top1\" \"Sub1\" \"Sub2\") \"Top2\"))\n```\n\n### Customize Variables\n\n#### `popup-isearch-regexp-builder-function`\n\nFunction used to construct a regexp from a pattern. You may for instance\nprovide a function that replaces spaces by '.+' if you like helm or ivy style\nof completion. Default value is `#'regexp-quote`.\n\n----\n\nCopyright (C) 2011-2015  Tomohiro Matsuyama \u003c\u003cm2ym.pub@gmail.com\u003e\u003e\u003cbr/\u003e\nCopyright (C) 2020-2022  Jen-Chieh Shen \u003c\u003cjcs090218@gmail.com\u003e\u003e\n\n[melpa-link]: https://melpa.org/#/popup\n[melpa-stable-link]: https://stable.melpa.org/#/popup\n[melpa-badge]: https://melpa.org/packages/popup-badge.svg\n[melpa-stable-badge]: https://stable.melpa.org/packages/popup-badge.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauto-complete%2Fpopup-el","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauto-complete%2Fpopup-el","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauto-complete%2Fpopup-el/lists"}