English | 简体中文
Emacs Application Framework (EAF)
EAF is a GUI application framework that revolutionizes Emacs graphical capabilities to ultimately Live in Emacs.
EAF Application Overview
EAF is an extensible framework, one can develop any Qt5 application and integrate it into Emacs.
|Image Viewer||Video Player|
|File Sender||File Receiver|
|Air Share||Org Previewer|
|Terminal Emulator||RSS Reader|
|Aria2 Download Manager||Mind Map|
- Install EAF dependencies:
sudo pacman -S python-pyqt5 python-pyqt5-sip python-pyqtwebengine python-qrcode python-feedparser python-dbus python-pyinotify python-markdown nodejs aria2 libreoffice yay -S python-pymupdf python-grip filebrowser-bin
- Clone this repository.
git clone https://github.com/manateelazycat/emacs-application-framework.git --depth=1
- Add the full path to the EAF installation directory to your Emacs
load-path, then add the following to
If you use use-package, a sample configuration has been provided.
(use-package eaf :load-path "~/.emacs.d/site-lisp/emacs-application-framework" ; Set to "/usr/share/emacs/site-lisp/eaf" if installed from AUR :custom (eaf-find-alternate-file-in-dired t) :config (eaf-bind-key scroll_up "C-n" eaf-pdf-viewer-keybinding) (eaf-bind-key scroll_down "C-p" eaf-pdf-viewer-keybinding) (eaf-bind-key take_photo "p" eaf-camera-keybinding))
If you use Chemacs, a sample
init.el is provided as follows:
;; An example of init.el (defun add-subdirs-to-load-path (dir) "Recursive add directories to `load-path'." (let ((default-directory (file-name-as-directory dir))) (add-to-list 'load-path dir) (normal-top-level-add-subdirs-to-load-path))) (add-subdirs-to-load-path "~/.emacs.d/") (require 'eaf)
During EAF installation, you only need to modify the parameter value when calling function
add-subdirs-to-load-path, change it into your full path to the EAF installation directory. The sample gives a situation when you install EAF at
After EAF installation, let's assume your EAF installation directory is
~/eaf, you only have Emacs configurations at
~/.emacs.d and EAF installed on your computer, and you have installed Chemacs, then the
.emacs-profiles.el should look like this:
(("default" . ((user-emacs-directory . "~/.emacs.d"))) ("EAF" . ((user-emacs-directory . "~/eaf"))))
When you want to use EAF by chemacs, you can excute
emacs --with-profile EAF in the terminal.
Packages listed as Core are mandatory for EAF to work, whereas other packages are optional - install if you want to use corresponding EAF Application.
|python-pyqt5, python-pyqt5-sip||Core||Essential GUI library|
|python-dbus||Core||DBus IPC to connect Python with Elisp|
|python-pyqtwebengine||Core||Chromium based web rendering engine|
|python-pymupdf||PDF Viewer||PDF rendering engine|
|python-grip||Markdown Previewer||Markdown rendering server|
|python-qrcode||File Sender, File Receiver, Airshare||Render QR code pointing to local files|
|python-feedparser||RSS Reader||Parse RSS feeds|
|python-pyinotify||Mermaid||Monitor *.mmd file change status|
|python-markdown||Mermaid||Covert markdown format to mermaid html format|
|nodejs||Terminal||Communicate between browser and local TTY|
|aria2||Browser||Download files from the web|
|libreoffice||Doc Viewer||Convert doc file to pdf|
|filebrowser-bin||File Browser||Share files between computer and smartphone|
Launch EAF Applications
|HTML Email Renderer||
- To open the file under the cursor in
diredusing appropriate EAF Application, use
NOTE: EAF use DBus' session bus, it must run by a general user. Please don't use EAF when Emacs is started with sudo or root user, a root user can only access DBus's system bus.
It is highly suggested to read the Wiki first before using EAF.
Wiki consists of documentations on Keybinding, Customization, Design and TODOLIST. There also are some helpful tips to make EAF work with Docker, Helm, etc.
How does EAF work?
EAF implements three major functionalities:
- Integrate PyQt program window into Emacs frame using QWindow Reparent technology.
- Listen to EAF buffer's keyboard event flow and control the keyboard input of PyQt program via DBus IPC.
- Create a window compositer to make a PyQt program window adapt Emacs's Window/Buffer design.
EAF vs EXWM?
- EAF and EXWM share a common goal: enhance collaboration between the standard GNU Emacs with other GUI tools.
- EXWM is an X11 Window Manager, it manages and controls other software using a keyboard, but it cannot modify, customize and extend the behavior of other software. For example, it cannot modify the behavior when you press a key in Chrome or a PDF viewer.
- EAF is not a Window Manager, it utilizes the windows managing capabilities of Emacs to display its applications.
- The intention of EAF is to provide a framework to write PyQt5 applications that extends the multimedia experience of Emacs. From the perspective of Emacs' buffer/mode design, EAF is not different from any other package, with the former uses Qt for drawing contents while the latter uses Emacs' built-in text libraries instead.
Both projects are similar in terms of interface, but they are two completely different projects with different goals in mind. Sometimes one may find EAF is more suitable than EXWM, sometimes it's the other way around. Please do not meaninglessly compare them.
EAF is (currently) Linux only. Why?
- DBus is Linux-specific technology, it's difficult to support DBus in other operating systems.
- Qt5's QGraphicsScene technology does not work on MacOS.
If you've figure them out, PRs are always welcome!
[EAF] *eaf* aborted (core dumped) error
Please check the
*eaf* buffer, something is wrong on the Python side. Usually due to Python dependencies are not installed correctly.
If you're sure Python dependences are installed correctly, please create an issue with the
*eaf* buffer content, it contains many clues that can help us locate the problem faster.
What is Github Personal Access Tokens?
If you use EAF Markdown Previewer, to get consistent previewing, you need to access Github Personal access token site, fill something in "Token description" and click button "Generate token" to get your personal token. Then set the token:
(setq eaf-grip-token "yourtokencode")
Although Markdown Previewer works for the first few times by entering empty string when prompted, eventually it stops working and gives "GitHub Rate Limit Reached" error.
If you need to use proxy to access internet, one can configure the proxy settings.
(setq eaf-proxy-type "http") (setq eaf-proxy-host "127.0.0.1") (setq eaf-proxy-port "1080")
If you use Socks5 as local proxy, one can set proxy type with:
(setq eaf-proxy-type "socks5")
EAF in the community
A list of other community packages that use EAF to enhance their graphical experiences!
If we missed your package, please make a PR to add it to the list.
For any installation and configuration assistance, please read the Wiki first!
If you encounter any problem with EAF, please use command
emacs -q with a minimal setup that only contains EAF and verify the bug is reproducible. If
emacs -q works fine, probably something is wrong with your Emacs config.
If the problem persists, please report bug here.
If you got segfault error, please use the following way to collect crash information:
- Install gdb and turn on option
- Use command
eaf-stop-processstop current process
- Restart eaf, send issue with
*eaf*buffer content when next crash
Do you want to make Emacs a real "operating system"?
Do you want to live in Emacs more comfortably?
Do you want to revolutionize the capabilities of Emacs?
如果我的作品让你的生活充满快乐, 欢迎请我喝瓶啤酒, 哈哈哈哈