8 Star 11 Fork 2

KiteAB / emacs-application-framework

Create your Gitee Account
Explore and code with more than 6 million developers,Free private repositories !:)
Sign up
Clone or download
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README.md

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.

Browser Markdown Previewer
Image Viewer Video Player
PDF Viewer Camera
File Sender File Receiver
Air Share Org Previewer
Terminal Emulator RSS Reader (Integrated with Elfeed)
Aria2 Download Manager Mind Map
Mermaid EAF Interleave
Jupyter

EmacsConf2020 - Extend Emacs to Modern GUI Applications with EAF

EmacsConf2020 - Extend Emacs to Modern GUI Applications with EAF

Install

  1. Download EAF
git clone --depth=1 -b master https://github.com/manateelazycat/emacs-application-framework.git ~/.emacs.d/site-lisp/emacs-application-framework/

Note: change master to master-full if you cannot properly use npm install.

Alternatively, you can use a Quelpa recipe

(quelpa '(eaf (:fetcher github
               :repo  "manateelazycat/emacs-application-framework"
               :files ("*"))))
  1. Install EAF dependencies. An explanation of each dependency can be found in Dependency List.
  • M-x install-eaf-dependencies
  • or run install-eaf.sh:
cd emacs-application-framework
chmod +x ./install-eaf.sh
./install-eaf.sh
  1. Install Elisp packages:
  1. From here on, you can either add the full path to the EAF installation directory to your Emacs load-path, then add the following to init.el:
(add-to-list 'load-path "~/.emacs.d/site-lisp/emacs-application-framework/")
(require 'eaf)

or, if you use use-package, you can use the following sample configuration for your convenience.

(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-browser-continue-where-left-off t)
  :config
  (eaf-setq eaf-browser-enable-adblocker "true")
  (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)
  (eaf-bind-key nil "M-q" eaf-browser-keybinding)) ;; unbind, see more in the Wiki

Dependency List

Packages listed as Core are mandatory for EAF to work, whereas other packages are optional - install if you want to use corresponding EAF Application.

Package Dependent Description
python-pyqt5, python-pyqt5-sip Core Essential GUI library
python-pyqtwebengine Core Chromium based web rendering engine
wmctrl Core Activate Emacs window input focus
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-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
qtconsole Jupyter Provide RichJupyterWidget

Launch EAF Applications

Application Name Launch
Browser M-x eaf-open-browser Search or Goto URL
M-x eaf-open-browser-with-history Search or Goto URL or Goto History
HTML Email Renderer M-x eaf-open-mail-as-html in gnus, mu4e, notmuch HTMl Mail
PDF Viewer M-x eaf-open PDF File
Video Player M-x eaf-open Video File
Image Viewer M-x eaf-open Image File
Markdown Previewer M-x eaf-open Markdown File
Org Previewer M-x eaf-open Org File
Camera M-x eaf-open-camera
Terminal M-x eaf-open-terminal
File Sender M-x eaf-file-sender-qrcode or eaf-file-sender-qrcode-in-dired
File Browser M-x eaf-file-browser-qrcode
Airshare M-x eaf-open-airshare
Mindmap M-x eaf-create-mindmap or M-x eaf-open-mindmap
MS Office Viewer M-x eaf-open-office
Mermaid M-x eaf-open Mermaid file (*.mmd)
Jupyter M-x eaf-open-jupyter
Demo M-x eaf-open-demo to verify basic functionality
  • EAF Browser and PDF Viewer support Emacs built-in bookmark operation, with M-x bookmark-set (defaulted to C-x r m) and M-x bookmark-bmenu-list (defaulted to C-x r l).

Wiki

It is highly suggested to read the Wiki first before using EAF.

Wiki consists of documentations on:

  • Keybindings
  • Customization
  • Design
  • TODOLIST

There also are some helpful tips to make EAF work with Docker, Helm, etc.

FAQ

How does EAF work?

EAF implements three major functionalities:

  1. Integrate PyQt program window into Emacs frame using QWindow Reparent technology.
  2. Listen to EAF buffer's keyboard event flow and control the keyboard input of PyQt program via Python EPC.
  3. Create a window compositer to make a PyQt program window adapt Emacs's Window/Buffer design.

Learn more from the Wiki!

EAF vs EXWM?

  1. EAF and EXWM share a common goal: enhance collaboration between the standard GNU Emacs with other GUI tools.
  2. 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.
  3. EAF is not a Window Manager, it utilizes the windows managing capabilities of Emacs to display its applications.
  4. 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.
  5. Through EAF's design, one can use Elisp to control Python and vice versa, and even able to use Elisp to control JavaScript in EAF Browser. EAF enables Emacs to the world of multi-language scripting.

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 can't works on MacOS. Why?

  1. Qt5's QGraphicsScene technology does not work on MacOS.
  2. QWindow Reparent technology need use the original API of Mac platform for replacement.

If you've figure them out, PRs are always welcome!

Why doesn't EAF receive input events on WM?

EAF confirms that the desktop environment or window manager you can work includes: KDE, GNOME2, GNOME3, Mate, Xfce, LXDE, I3, QTILE, Xpra.

We suspect there are some issues with how all the Window Managers implement their x11 protocols.

One workaround is to name of command wmctrl -m to the elisp list eaf-wm-focus-fix-wms. Fill an issue if it still doesn't work.

[EAF] *epc:server* aborted (core dumped) error

Please check the *epc:server* buffer (it is invisible, find it using C-b SPC), 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 *epc:server* 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.

Proxy

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.

Report bug

For any installation and configuration assistance, please read the Wiki first!

If you encounter a problem with EAF, and it occured after pulling the latest commit, please check the Discussions page first.

For any other problems, please use emacs -q and load a minimal setup with only EAF to verify that the bug is reproducible. If emacs -q works fine, probably something is wrong with your Emacs config.

If the problem persists, please report it here.

Join Us

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?

Let's hack together!

打赏

如果我的作品让你的生活充满快乐, 欢迎请我喝瓶啤酒, 哈哈哈哈

ManateeLazyCat

Comments ( 0 )

Sign in for post a comment

About

EAF 是一个全新的图形应用框架,通过扩展Emacs的多媒体能力,最终达到 Live in Emacs 的终极目标。 spread retract
GPL-3.0
Cancel

Releases

No release

Gitee Metrics

Contributors

All

Activities

load more
can not load any more
Python
1
https://git.oschina.net/KiteAB/emacs-application-framework.git
git@git.oschina.net:KiteAB/emacs-application-framework.git
KiteAB
emacs-application-framework
emacs-application-framework
master

Search

103611 48b8ff67 1899542 103622 4d02230c 1899542