Function: posframe-show
posframe-show is an autoloaded and byte-compiled function defined in
posframe.el.
Signature
(posframe-show BUFFER-OR-NAME &key STRING POSITION POSHANDLER POSHANDLER-EXTRA-INFO WIDTH HEIGHT MAX-WIDTH MAX-HEIGHT MIN-WIDTH MIN-HEIGHT X-PIXEL-OFFSET Y-PIXEL-OFFSET LEFT-FRINGE RIGHT-FRINGE BORDER-WIDTH BORDER-COLOR INTERNAL-BORDER-WIDTH INTERNAL-BORDER-COLOR FONT CURSOR TTY-NON-SELECTED-CURSOR WINDOW-POINT FOREGROUND-COLOR BACKGROUND-COLOR RESPECT-HEADER-LINE RESPECT-MODE-LINE INITIALIZE NO-PROPERTIES KEEP-RATIO LINES-TRUNCATE OVERRIDE-PARAMETERS TIMEOUT REFRESH ACCEPT-FOCUS HIDEHANDLER REFPOSHANDLER &allow-other-keys)
Documentation
Pop up a posframe to show STRING at POSITION.
(1) POSITION
POSITION can be:
1. An integer, meaning point position.
2. A cons of two integers, meaning absolute X and Y coordinates.
3. Other type, in which case the corresponding POSHANDLER should be
provided.
(2) POSHANDLER
POSHANDLER is a function of one argument returning an actual position. Its argument is a plist of the following form:
(:position xxx
:poshandler xxx
:font-height xxx
:font-width xxx
:posframe xxx
:posframe-width xxx
:posframe-height xxx
:posframe-buffer xxx
:parent-frame xxx
:parent-window-start xxx
:parent-window-end xxx
:parent-window-left xxx
:parent-window-top xxx
:parent-frame-width xxx
:parent-frame-height xxx
:parent-window xxx
:parent-window-width xxx
:parent-window-height xxx
:mouse-x xxx
:mouse-y xxx
:minibuffer-height xxx
:mode-line-height xxx
:header-line-height xxx
:tab-line-height xxx
:x-pixel-offset xxx
:y-pixel-offset xxx
:parent-text-scale-mode-amount xxx)
By default, poshandler is auto-selected based on the type of POSITION, but the selection can be overridden using the POSHANDLER argument.
The builtin poshandler functions are listed below:
1. posframe-poshandler-frame-center
2. posframe-poshandler-frame-top-center
3. posframe-poshandler-frame-top-left-corner
4. posframe-poshandler-frame-top-right-corner
5. posframe-poshandler-frame-top-left-or-right-other-corner
6. posframe-poshandler-frame-bottom-center
7. posframe-poshandler-frame-bottom-left-corner
8. posframe-poshandler-frame-bottom-right-corner
9. posframe-poshandler-window-center
10. posframe-poshandler-window-top-center
11. posframe-poshandler-window-top-left-corner
12. posframe-poshandler-window-top-right-corner
13. posframe-poshandler-window-bottom-center
14. posframe-poshandler-window-bottom-left-corner
15. posframe-poshandler-window-bottom-right-corner
16. posframe-poshandler-point-top-left-corner
17. posframe-poshandler-point-bottom-left-corner
18. posframe-poshandler-point-bottom-left-corner-upward
19. posframe-poshandler-point-window-center
20. posframe-poshandler-point-frame-center
(3) POSHANDLER-EXTRA-INFO
POSHANDLER-EXTRA-INFO is a plist, which will prepend to the
argument of poshandler function: info, it will *OVERRIDE* the
exist key in info.
(4) BUFFER-OR-NAME
This posframe's buffer is BUFFER-OR-NAME, which can be a buffer or a name of a (possibly nonexistent) buffer.
buffer name can prefix with space, for example " *mybuffer*", so
the buffer name will hide for ibuffer and list-buffers.
(5) NO-PROPERTIES
If NO-PROPERTIES is non-nil, The STRING's properties will be removed before being shown in posframe.
(6) HEIGHT, MAX-HEIGHT, MIN-HEIGHT, WIDTH, MAX-WIDTH and MIN-WIDTH
These arguments are specified in the canonical character width
and height of posframe, more details can be found in docstring of
function fit-frame-to-buffer(var)/fit-frame-to-buffer(fun),
(7) LEFT-FRINGE and RIGHT-FRINGE
If LEFT-FRINGE or RIGHT-FRINGE is a number, left fringe or right fringe with be shown with the specified width.
(8) BORDER-WIDTH, BORDER-COLOR, INTERNAL-BORDER-WIDTH and INTERNAL-BORDER-COLOR
By default, posframe shows no borders, but users can specify borders by setting BORDER-WIDTH to a positive number. Border color can be specified by BORDER-COLOR.
INTERNAL-BORDER-WIDTH and INTERNAL-BORDER-COLOR are same as BORDER-WIDTH and BORDER-COLOR, but do not suggest to use for the reason:
Add distinct controls for child frames' borders (Bug#45620)
http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=ff7b1a133bfa7f2614650f8551824ffaef13fadc
(9) FONT, FOREGROUND-COLOR and BACKGROUND-COLOR
Posframe's font as well as foreground and background colors are derived from the current frame by default, but can be overridden using the FONT, FOREGROUND-COLOR and BACKGROUND-COLOR arguments, respectively.
(10) CURSOR, TTY-NON-SELECTED-CURSOR and WINDOW-POINT
By default, cursor is not showed in posframe, user can let cursor
showed with this argument help by set its value to a cursor-type.
TTY-NON-SELECTED-CURSOR will let redisplay put the terminal cursor in a non-selected frame, which is useful when use vertico-posframe like package in tty.
When cursor need to be showed in posframe, user may need to set WINDOW-POINT to the point of BUFFER, which can let cursor showed at this point.
(11) RESPECT-HEADER-LINE and RESPECT-MODE-LINE
By default, posframe will display no header-line, mode-line and tab-line. In case a header-line, mode-line or tab-line is desired, users can set RESPECT-HEADER-LINE and RESPECT-MODE-LINE to t.
(12) INITIALIZE
INITIALIZE is a function with no argument. It will run when
posframe buffer is first selected with with-current-buffer
in posframe-show, and only run once (for performance reasons).
(13) LINES-TRUNCATE
If LINES-TRUNCATE is non-nil, then lines will truncate in the posframe instead of wrap.
(14) OVERRIDE-PARAMETERS
OVERRIDE-PARAMETERS is very powful, *all* the valid frame parameters used by posframe's frame can be overridden by it.
NOTE: some posframe-show arguments are not frame parameters, so they
can not be overrided by this argument.
(15) TIMEOUT
TIMEOUT can specify the number of seconds after which the posframe will auto-hide.
(15) REFRESH
If REFRESH is a number, posframe's frame-size will be re-adjusted every REFRESH seconds.
(17) ACCEPT-FOCUS
When ACCEPT-FOCUS is non-nil, posframe will accept focus. be careful, you may face some bugs when set it to non-nil.
(18) HIDEHANDLER
HIDEHANDLER is a function, when it return t, posframe will be hide, this function has a plist argument:
(:posframe-buffer xxx
:posframe-parent-buffer xxx)
The builtin hidehandler functions are listed below:
1. posframe-hidehandler-when-buffer-switch
(19) REFPOSHANDLER
REFPOSHANDLER is a function, a reference position (most is top-left of current frame) will be returned when call this function.
when it is nil or it return nil, child-frame feature will be used and reference position will be deal with in Emacs.
The user case I know at the moment is let ivy-posframe work well in EXWM environment (let posframe show on the other application window).
DO NOT USE UNLESS NECESSARY!!!
An example parent frame poshandler function is:
1. posframe-refposhandler-xwininfo
(19) Others
You can use posframe-delete-all to delete all posframes.
Source Code
;; Defined in ~/.emacs.d/elpa/posframe-20260415.14/posframe.el
;;;###autoload
(cl-defun posframe-show (buffer-or-name
&key
string
position
poshandler
poshandler-extra-info
width
height
max-width
max-height
min-width
min-height
x-pixel-offset
y-pixel-offset
left-fringe
right-fringe
border-width
border-color
internal-border-width
internal-border-color
font
cursor
tty-non-selected-cursor
window-point
foreground-color
background-color
respect-header-line
respect-mode-line
initialize
no-properties
keep-ratio
lines-truncate
override-parameters
timeout
refresh
accept-focus
hidehandler
refposhandler
&allow-other-keys)
"Pop up a posframe to show STRING at POSITION.
(1) POSITION
POSITION can be:
1. An integer, meaning point position.
2. A cons of two integers, meaning absolute X and Y coordinates.
3. Other type, in which case the corresponding POSHANDLER should be
provided.
(2) POSHANDLER
POSHANDLER is a function of one argument returning an actual
position. Its argument is a plist of the following form:
(:position xxx
:poshandler xxx
:font-height xxx
:font-width xxx
:posframe xxx
:posframe-width xxx
:posframe-height xxx
:posframe-buffer xxx
:parent-frame xxx
:parent-window-start xxx
:parent-window-end xxx
:parent-window-left xxx
:parent-window-top xxx
:parent-frame-width xxx
:parent-frame-height xxx
:parent-window xxx
:parent-window-width xxx
:parent-window-height xxx
:mouse-x xxx
:mouse-y xxx
:minibuffer-height xxx
:mode-line-height xxx
:header-line-height xxx
:tab-line-height xxx
:x-pixel-offset xxx
:y-pixel-offset xxx
:parent-text-scale-mode-amount xxx)
By default, poshandler is auto-selected based on the type of POSITION,
but the selection can be overridden using the POSHANDLER argument.
The builtin poshandler functions are listed below:
1. `posframe-poshandler-frame-center'
2. `posframe-poshandler-frame-top-center'
3. `posframe-poshandler-frame-top-left-corner'
4. `posframe-poshandler-frame-top-right-corner'
5. `posframe-poshandler-frame-top-left-or-right-other-corner'
6. `posframe-poshandler-frame-bottom-center'
7. `posframe-poshandler-frame-bottom-left-corner'
8. `posframe-poshandler-frame-bottom-right-corner'
9. `posframe-poshandler-window-center'
10. `posframe-poshandler-window-top-center'
11. `posframe-poshandler-window-top-left-corner'
12. `posframe-poshandler-window-top-right-corner'
13. `posframe-poshandler-window-bottom-center'
14. `posframe-poshandler-window-bottom-left-corner'
15. `posframe-poshandler-window-bottom-right-corner'
16. `posframe-poshandler-point-top-left-corner'
17. `posframe-poshandler-point-bottom-left-corner'
18. `posframe-poshandler-point-bottom-left-corner-upward'
19. `posframe-poshandler-point-window-center'
20. `posframe-poshandler-point-frame-center'
(3) POSHANDLER-EXTRA-INFO
POSHANDLER-EXTRA-INFO is a plist, which will prepend to the
argument of poshandler function: `info', it will *OVERRIDE* the
exist key in `info'.
(4) BUFFER-OR-NAME
This posframe's buffer is BUFFER-OR-NAME, which can be a buffer
or a name of a (possibly nonexistent) buffer.
buffer name can prefix with space, for example \" *mybuffer*\", so
the buffer name will hide for ibuffer and `list-buffers'.
(5) NO-PROPERTIES
If NO-PROPERTIES is non-nil, The STRING's properties will
be removed before being shown in posframe.
(6) HEIGHT, MAX-HEIGHT, MIN-HEIGHT, WIDTH, MAX-WIDTH and MIN-WIDTH
These arguments are specified in the canonical character width
and height of posframe, more details can be found in docstring of
function `fit-frame-to-buffer',
(7) LEFT-FRINGE and RIGHT-FRINGE
If LEFT-FRINGE or RIGHT-FRINGE is a number, left fringe or
right fringe with be shown with the specified width.
(8) BORDER-WIDTH, BORDER-COLOR, INTERNAL-BORDER-WIDTH and INTERNAL-BORDER-COLOR
By default, posframe shows no borders, but users can specify
borders by setting BORDER-WIDTH to a positive number. Border
color can be specified by BORDER-COLOR.
INTERNAL-BORDER-WIDTH and INTERNAL-BORDER-COLOR are same as
BORDER-WIDTH and BORDER-COLOR, but do not suggest to use for the
reason:
Add distinct controls for child frames' borders (Bug#45620)
http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=ff7b1a133bfa7f2614650f8551824ffaef13fadc
(9) FONT, FOREGROUND-COLOR and BACKGROUND-COLOR
Posframe's font as well as foreground and background colors are
derived from the current frame by default, but can be overridden
using the FONT, FOREGROUND-COLOR and BACKGROUND-COLOR arguments,
respectively.
(10) CURSOR, TTY-NON-SELECTED-CURSOR and WINDOW-POINT
By default, cursor is not showed in posframe, user can let cursor
showed with this argument help by set its value to a `cursor-type'.
TTY-NON-SELECTED-CURSOR will let redisplay put the terminal
cursor in a non-selected frame, which is useful when use
vertico-posframe like package in tty.
When cursor need to be showed in posframe, user may need to set
WINDOW-POINT to the point of BUFFER, which can let cursor showed
at this point.
(11) RESPECT-HEADER-LINE and RESPECT-MODE-LINE
By default, posframe will display no header-line, mode-line and
tab-line. In case a header-line, mode-line or tab-line is
desired, users can set RESPECT-HEADER-LINE and RESPECT-MODE-LINE
to t.
(12) INITIALIZE
INITIALIZE is a function with no argument. It will run when
posframe buffer is first selected with `with-current-buffer'
in `posframe-show', and only run once (for performance reasons).
(13) LINES-TRUNCATE
If LINES-TRUNCATE is non-nil, then lines will truncate in the
posframe instead of wrap.
(14) OVERRIDE-PARAMETERS
OVERRIDE-PARAMETERS is very powful, *all* the valid frame parameters
used by posframe's frame can be overridden by it.
NOTE: some `posframe-show' arguments are not frame parameters, so they
can not be overrided by this argument.
(15) TIMEOUT
TIMEOUT can specify the number of seconds after which the posframe
will auto-hide.
(15) REFRESH
If REFRESH is a number, posframe's frame-size will be re-adjusted
every REFRESH seconds.
(17) ACCEPT-FOCUS
When ACCEPT-FOCUS is non-nil, posframe will accept focus.
be careful, you may face some bugs when set it to non-nil.
(18) HIDEHANDLER
HIDEHANDLER is a function, when it return t, posframe will be
hide, this function has a plist argument:
(:posframe-buffer xxx
:posframe-parent-buffer xxx)
The builtin hidehandler functions are listed below:
1. `posframe-hidehandler-when-buffer-switch'
(19) REFPOSHANDLER
REFPOSHANDLER is a function, a reference position (most is
top-left of current frame) will be returned when call this
function.
when it is nil or it return nil, child-frame feature will be used
and reference position will be deal with in Emacs.
The user case I know at the moment is let ivy-posframe work well
in EXWM environment (let posframe show on the other application
window).
DO NOT USE UNLESS NECESSARY!!!
An example parent frame poshandler function is:
1. `posframe-refposhandler-xwininfo'
(19) Others
You can use `posframe-delete-all' to delete all posframes."
(let* ((position (or position (point)))
(max-width (if (numberp max-width)
(min max-width (frame-width))
(frame-width)))
(max-height (if (numberp max-height)
(min max-height (frame-height))
(frame-height)))
(min-width (min (or min-width 1) max-width))
(min-height (min (or min-height 1) max-height))
(width (when width
(min (max width min-width) max-width)))
(height (when height
(min (max height min-height) max-height)))
(x-pixel-offset (or x-pixel-offset 0))
(y-pixel-offset (or y-pixel-offset 0))
(window-point (or window-point 0))
;;-----------------------------------------------------
(buffer (get-buffer-create buffer-or-name))
(parent-window (selected-window))
(parent-window-start (window-start parent-window))
(parent-window-end (window-end parent-window))
(parent-window-top (window-pixel-top parent-window))
(parent-window-left (window-pixel-left parent-window))
(parent-window-width (window-pixel-width parent-window))
(parent-window-height (window-pixel-height parent-window))
(parent-frame (window-frame parent-window))
(parent-frame-width (frame-pixel-width parent-frame))
(parent-frame-height (frame-pixel-height parent-frame))
(ref-position
(when (functionp refposhandler)
(ignore-errors
(funcall refposhandler parent-frame))))
(font-width (default-font-width))
(font-height (with-current-buffer (window-buffer parent-window)
(posframe--get-font-height position)))
(parent-text-scale-mode-amount (with-current-buffer (window-buffer parent-window)
(and (bound-and-true-p text-scale-mode) text-scale-mode-amount)))
(mode-line-height (window-mode-line-height
(and (window-minibuffer-p)
(ignore-errors (window-in-direction 'above)))))
(minibuffer-height (window-pixel-height (minibuffer-window)))
(header-line-height (window-header-line-height parent-window))
(tab-line-height (if (functionp 'window-tab-line-height)
(window-tab-line-height)
0))
(mouse-position (cdr (mouse-pixel-position)))
(frame-resize-pixelwise t)
pixel-position
posframe)
(with-current-buffer buffer
;; Initialize
(unless posframe--initialized-p
(let ((func initialize))
(when (functionp func)
(funcall func)
(setq posframe--initialized-p t))))
;; Create posframe
(setq posframe
(posframe--create-posframe
buffer
:position position
:font font
:cursor cursor
:tty-non-selected-cursor tty-non-selected-cursor
:parent-frame
(unless ref-position
parent-frame)
:left-fringe left-fringe
:right-fringe right-fringe
:border-width border-width
:border-color border-color
:internal-border-width internal-border-width
:internal-border-color internal-border-color
:foreground-color foreground-color
:background-color background-color
:keep-ratio keep-ratio
:lines-truncate lines-truncate
:respect-header-line respect-header-line
:respect-mode-line respect-mode-line
:override-parameters override-parameters
:accept-focus accept-focus
:parent-text-scale-mode-amount parent-text-scale-mode-amount))
;; Insert string into the posframe buffer
(posframe--insert-string string no-properties)
(let* ((size-info
(list :posframe posframe
:width width
:height height
:max-width max-width
:max-height max-height
:min-width min-width
:min-height min-height))
(position-info
(list :position position
:poshandler poshandler
:font-height font-height
:font-width font-width
:posframe posframe
:posframe-buffer buffer
:parent-frame parent-frame
:parent-frame-width parent-frame-width
:parent-frame-height parent-frame-height
:ref-position ref-position
:parent-window parent-window
:parent-window-start parent-window-start
:parent-window-end parent-window-end
:parent-window-top parent-window-top
:parent-window-left parent-window-left
:parent-window-width parent-window-width
:parent-window-height parent-window-height
:mouse-x (car mouse-position)
:mouse-y (cdr mouse-position)
:mode-line-height mode-line-height
:minibuffer-height minibuffer-height
:header-line-height header-line-height
:tab-line-height tab-line-height
:x-pixel-offset x-pixel-offset
:y-pixel-offset y-pixel-offset
:parent-text-scale-mode-amount parent-text-scale-mode-amount)))
(setq pixel-position (and
width
height
(posframe-run-poshandler
`(,@poshandler-extra-info
,@position-info
:posframe-width ,(* (default-font-width) width)
:posframe-height ,(* (default-line-height) height)))))
(if (and width height
(fboundp 'set-frame-size-and-position-pixelwise)
(frame-visible-p posframe)
(not (equal
pixel-position
posframe--last-posframe-pixel-position)))
(posframe--set-frame-size-and-position
size-info
pixel-position
parent-frame-width parent-frame-height)
;; Set posframe's size
(posframe--set-frame-size size-info)
;; Get new position of posframe.
(unless pixel-position
(setq pixel-position
(posframe-run-poshandler
;; All poshandlers will get info from this plist.
`(,@poshandler-extra-info
,@position-info
:posframe-width ,(frame-pixel-width posframe)
:posframe-height ,(frame-pixel-height posframe)))))
;; Move posframe
(posframe--set-frame-position
posframe pixel-position parent-frame-width parent-frame-height))
;; Re-adjust posframe's size when buffer's content has changed.
(posframe--run-refresh-timer refresh size-info))
;; Delay hide posframe when timeout is a number.
(posframe--run-timeout-timer posframe timeout)
;; Make sure not hide buffer's content for scroll down.
(let ((window (frame-root-window posframe--frame)))
(when (window-live-p window)
(set-window-point window window-point)))
;; Hide posframe when switch buffer
(let* ((parent-buffer (window-buffer parent-window))
(parent-buffer-name (buffer-name parent-buffer)))
(set-frame-parameter posframe--frame 'posframe-hidehandler hidehandler)
(set-frame-parameter posframe--frame 'posframe-parent-buffer
(cons parent-buffer-name parent-buffer)))
;; Mouse banish
(funcall
posframe-mouse-banish-function
(list :parent-frame parent-frame
:mouse-x (when (car mouse-position)
(+ (or (car ref-position) 0)
(car mouse-position)))
:mouse-y (when (cdr mouse-position)
(+ (or (cdr ref-position) 0)
(cdr mouse-position)))
:posframe-x
(if (>= (car pixel-position) 0)
(car pixel-position)
(- (frame-pixel-width parent-frame)
(frame-pixel-width posframe)))
:posframe-y
(if (>= (cdr pixel-position) 0)
(cdr pixel-position)
(- (frame-pixel-height parent-frame)
(frame-pixel-height posframe)))
:posframe-width (frame-pixel-width posframe)
:posframe-height (frame-pixel-height posframe)
:parent-frame-width parent-frame-width
:parent-frame-height parent-frame-height))
;; Return posframe
posframe)))