File: README.org

package info (click to toggle)
emacs-posframe 1.4.4-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 204 kB
  • sloc: lisp: 1,226; makefile: 2
file content (105 lines) | stat: -rw-r--r-- 2,958 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
# Created 2021-06-01 Tue 10:41
#+TITLE: Pop a posframe (just a frame) at point
#+AUTHOR: Feng Shu

#+html: <a href="http://elpa.gnu.org/packages/posframe.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/posframe.svg"/></a>
#+html: <a href="http://elpa.gnu.org/devel/posframe.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/posframe.svg"/></a>
#+html: <a href="https://melpa.org/#/posframe"><img alt="MELPA" src="https://melpa.org/packages/posframe-badge.svg"/></a>

* What is posframe?
Posframe can pop up a frame at point, this *posframe* is a
child-frame connected to its root window's buffer.

The main advantages are:
1. It is fast enough for daily usage :-)
2. It works well with CJK languages.

NOTE:
1. For MacOS users, posframe needs Emacs version >= 26.0.91
2. GNOME users with GTK3 builds need Emacs 27 or later.
   See variable `posframe-gtk-resize-child-frames'
   which auto-detects this configuration.

   More details:
   1. [[https://git.savannah.gnu.org/cgit/emacs.git/commit/?h=emacs-27&id=c49d379f17bcb0ce82604def2eaa04bda00bd5ec][Fix some problems with moving and resizing child frames]]
   2. [[https://lists.gnu.org/archive/html/emacs-devel/2020-01/msg00343.html][Emacs's set-frame-size can not work well with gnome-shell?]]

[[file:./snapshots/posframe-1.png]]

* Installation

#+begin_example
(require 'posframe)
#+end_example

* Usage

** Create a posframe

*** Simple way
#+begin_example
(when (posframe-workable-p)
  (posframe-show " *my-posframe-buffer*"
                 :string "This is a test"
                 :position (point)))
#+end_example

*** Advanced way
#+begin_example
(defvar my-posframe-buffer " *my-posframe-buffer*")

(with-current-buffer (get-buffer-create my-posframe-buffer)
  (erase-buffer)
  (insert "Hello world"))

(when (posframe-workable-p)
  (posframe-show my-posframe-buffer
                 :position (point)))
#+end_example

*** Arguments

#+begin_example
C-h f posframe-show
#+end_example

** Hide a posframe
#+begin_example
(posframe-hide " *my-posframe-buffer*")
#+end_example

** Hide all posframes
#+begin_example
M-x posframe-hide-all
#+end_example

** Delete a posframe
1. Delete posframe and its buffer
   #+begin_example
   (posframe-delete " *my-posframe-buffer*")
   #+end_example
2. Only delete the frame
   #+begin_example
   (posframe-delete-frame " *my-posframe-buffer*")
   #+end_example
** Delete all posframes
#+begin_example
M-x posframe-delete-all
#+end_example

Note: this command will delete all posframe buffers.
You probably shouldn't use it if you are sharing a buffer
between posframe and other packages.

** posframe-arghandler

posframe-arghandler feature has been removed from posframe-1.1, 
user can use advice feature instead.

** Mouse banish
Default setting will work well in most case, but for EXWM user,
suggest use the below config.

#+begin_src emacs-lisp
(setq posframe-mouse-banish-function #'posframe-mouse-banish-simple)
#+end_src