daniel/emacs
1
2
Fork 0
Code Issues 7 Pull Requests Projects Releases Wiki Activity

update eaf package

Browse Source
This commit is contained in:
Daniel Weschke
2021-01-30 14:52:51 +01:00
parent 84eb4929ee
commit 5207af83cb
4981 changed files with 11795 additions and 761570 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
lisp/emacs-application-framework/README.md
View File

@@ -6,7 +6,7 @@ EAF is a GUI application framework that revolutionizes Emacs graphical capabilit
## EAF Application Overview
EAF is an extensible framework, one can develop any Qt5 application and integrate it into Emacs.
| Browser | Markdown Previewer |
| Browser | Markdown Previewer (support Mermaid and PlantUML) |
| :--------: | :----: |
| <img src="./screenshot/browser.gif" width="400"> | <img src="./screenshot/markdown_previewer.gif" width="400"> |
@@ -31,7 +31,7 @@ EAF is an extensible framework, one can develop any Qt5 application and integrat
| <img src="./screenshot/air_share.png" width="400"> | <img src="./screenshot/org_previewer.gif" width="400"> |
| | |
| Terminal Emulator | RSS Reader |
| Terminal Emulator | RSS Reader (Integrated with Elfeed) |
| :--------: | :------: |
| <img src="./screenshot/terminal.gif" width="400"> | <img src="./screenshot/rss_reader.gif" width="400"> |
| | |
@@ -42,92 +42,101 @@ EAF is an extensible framework, one can develop any Qt5 application and integrat
| | |
| Mermaid | EAF Interleave |
| Jupyter | EAF Interleave |
| :--------: | :----------: |
| <img src="./screenshot/mermaid.gif" width="400"> | <img src="./screenshot/eaf-interleave.gif" width="400"> |
| <img src="./screenshot/jupyter.png" width="400"> | <img src="./screenshot/eaf-interleave.gif" width="400"> |
| | |
## EmacsConf2020 - Extend Emacs to Modern GUI Applications with EAF
- EAF talk & demo at EmacsConf2020, presented to you by [MatthewZMD](https://github.com/MatthewZMD)
- Homepage (Q&A included): https://emacsconf.org/2020/talks/34/
- Youtube link:
[![EmacsConf2020 - Extend Emacs to Modern GUI Applications with EAF](https://img.youtube.com/vi/HK_f8KTuR0s/0.jpg)](https://www.youtube.com/watch?v=HK_f8KTuR0s)
## Install
1. Install EAF dependencies, an explaination of each dependency can be found in [Dependency List](#dependency-list).
The following line is for *Archlinux*, same packages should be available to install on your particular distribution:
1. Download EAF
```Bash
yay -S python-pyqt5 python-pyqt5-sip python-pyqtwebengine python-qrcode python-feedparser python-dbus python-pyinotify python-markdown nodejs aria2 libreoffice python-pymupdf python-grip filebrowser-bin
git clone --depth=1 -b master https://github.com/manateelazycat/emacs-application-framework.git ~/.emacs.d/site-lisp/emacs-application-framework/
```
2. Clone this repository.
```Bash
git clone https://github.com/manateelazycat/emacs-application-framework.git --depth=1
Alternatively, you can use a [Quelpa recipe](https://github.com/quelpa/quelpa)
```Emacs-lisp
(quelpa '(eaf (:fetcher github
:repo "manateelazycat/emacs-application-framework"
:files ("*"))))
```
3. Add the full path to the EAF installation directory to your Emacs ```load-path```, then add the following to `init.el`:
2. Install EAF dependencies using `M-x install-eaf-dependencies`.
If you prefer to manually call the installation script in the terminal,
- If you use GNU/Linux,
```Bash
cd emacs-application-framework
chmod +x ./install-eaf.sh
./install-eaf.sh
```
- If you use Windows,
```shell
cd emacs-application-framework
node ./install-eaf-win32.js
```
Feel free to inspect the install script yourself. An explanation of each dependency can be found at [Dependency List](#dependency-list).
3. Install Elisp packages:
- [emacs-ctable](https://github.com/kiwanami/emacs-ctable)
- [emacs-deferred](https://github.com/kiwanami/emacs-deferred)
- [emacs-epc](https://github.com/kiwanami/emacs-epc)
- [s.el](https://github.com/magnars/s.el)
4. 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`:
```Elisp
(add-to-list 'load-path "~/.emacs.d/site-lisp/emacs-application-framework/")
(require 'eaf)
```
If you use [use-package](https://github.com/jwiegley/use-package), a sample configuration has been provided.
or, if you use [use-package](https://github.com/jwiegley/use-package), you can use the following *sample* configuration for your convenience.
```Elisp
(use-package eaf
:load-path "~/.emacs.d/site-lisp/emacs-application-framework" ; Set to "/usr/share/emacs/site-lisp/eaf" if installed from AUR
:init
(use-package epc :defer t)
(use-package ctable :defer t)
(use-package deferred :defer t)
(use-package s :defer t :ensure t)
:custom
(eaf-find-alternate-file-in-dired t)
(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 take_photo "p" eaf-camera-keybinding)
(eaf-bind-key nil "M-q" eaf-browser-keybinding)) ;; unbind, see more in the Wiki
```
---
If you use [Chemacs](https://github.com/plexus/chemacs), a sample `init.el` is provided as follows:
```Elisp
;; 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 `~/.emacs.d/`.
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:
```Elisp
(("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.
### 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-dbus | Core | DBus IPC to connect Python with Elisp |
| 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-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 |
| qtconsole | Jupyter | Provide RichJupyterWidget |
| java-openjdk | Markdown Previewer | Make mume.js can render PlantUML content |
## Launch EAF Applications
| Application Name | Launch |
@@ -145,62 +154,59 @@ Packages listed as **Core** are mandatory for EAF to work, whereas other package
| 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` |
| RSS Reader | `M-x eaf-open-rss-reader` |
| 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 |
- To open the file under the cursor in `dired` using appropriate EAF Application, use `eaf-open-this-from-dired` instead.
- 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`).
```
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.
```
## Wiki
It is **highly** suggested to read the [Wiki](https://github.com/manateelazycat/emacs-application-framework/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.
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 DBus IPC.
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](https://github.com/manateelazycat/emacs-application-framework/wiki/Hacking)!
### 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. For example, it cannot modify the behavior when you press a key in Chrome or a PDF viewer.
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 is (currently) Linux only. Why?
1. DBus is Linux-specific technology, it's difficult to support DBus in other operating systems.
2. Qt5's QGraphicsScene technology does not work on MacOS.
### 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!
### `[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.
### EAF js-video-player can't play some video on Windows. Why?
`js-video-player` requires that qtwebengine built against ffmpeg to support proprietary codecs like `h264/aac`.
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.
### 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.
### 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](https://github.com/settings/tokens/new?scopes=), fill something in "Token description" and click button "Generate token" to get your personal token. Then set the token:
We suspect there are some issues with how all the Window Managers implement their x11 protocols.
```Elisp
(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.
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.
### Proxy
If you need to use proxy to access internet, one can configure the proxy settings.
@@ -227,11 +233,13 @@ 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](https://github.com/manateelazycat/emacs-application-framework/wiki) first!
### For any installation and configuration assistance, please read the [Wiki](https://github.com/manateelazycat/emacs-application-framework/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 you encounter a problem with EAF, and it occured after pulling the latest commit, please check the [Discussions](https://github.com/manateelazycat/emacs-application-framework/discussions/527) page first.
If the problem persists, please [report bug here](https://github.com/manateelazycat/emacs-application-framework/issues/new).
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](https://github.com/manateelazycat/emacs-application-framework/issues/new) with `*eaf*` buffer content, it contains many clues that can help us locate the problem faster.
If you got segfault error, please use the following way to collect crash information:
1. Install gdb and turn on option `eaf-enable-debug`