Add support for overlay popup boxes to show text or output temporarily

above the normal layout. These work similarly to menus and are created
with the display-popup command.

1 files changed, 90 insertions, 1 deletions

diff --git a/tmux.1 b/tmux.1
index 8cd4841f..263bedc1 100644
--- a/tmux.1
+++ b/tmux.1
@@ -4382,7 +4382,10 @@ The following variables are available, where appropriate:
 .It Li "pane_top" Ta "" Ta "Top of pane"
 .It Li "pane_tty" Ta "" Ta "Pseudo terminal of pane"
 .It Li "pane_width" Ta "" Ta "Width of pane"
-.It Li "pid" Ta ""  Ta "Server PID"
+.It Li "pid" Ta "" Ta "Server PID"
+.It Li "popup_key" Ta "" Ta "Key pressed in popup"
+.It Li "popup_mouse_x" Ta "" Ta "Mouse X position in popup"
+.It Li "popup_mouse_y" Ta "" Ta "Mouse Y position in popup"
 .It Li "rectangle_toggle" Ta "" Ta "1 if rectangle selection is activated"
 .It Li "scroll_position" Ta "" Ta "Scroll position in copy mode"
 .It Li "scroll_region_lower" Ta "" Ta "Bottom of scroll region in pane"
@@ -4972,6 +4975,92 @@ lists the format variables and their values.
 .Fl I
 forwards any input read from stdin to the empty pane given by
 .Ar target-pane .
+.It Xo Ic display-popup
+.Op Fl CEK
+.Op Fl c Ar target-client
+.Op Fl d Ar start-directory
+.Op Fl h Ar height
+.Op Fl R Ar shell-command
+.Op Fl t Ar target-pane
+.Op Fl w Ar width
+.Op Fl x Ar position
+.Op Fl y Ar position
+.Op Ar command Ar line Ar ...
+.Xc
+.D1 (alias: Ic popup )
+Display a popup on
+.Ar target-client .
+A popup is a rectangular box drawn over the top of any panes.
+Panes are not updated while a popup is present.
+The popup content may be given in two ways:
+.Bl -enum -offset Ds
+.It
+A set of lines as arguments.
+Each line is a format which is expanded using
+.Ar target-pane
+as the target.
+If a line contains newlines it is split into multiple lines.
+Lines may use styles, see the
+.Sx STYLES
+section.
+.It
+A shell command given by
+.Fl R
+which is run and any output shown in the pane.
+.El
+.Pp
+The first argument,
+.Ar command ,
+is a
+.Nm
+command which is run when a key is pressed.
+The key is available in the
+.Ql popup_key
+format.
+After
+.Ar command
+is run, the popup is closed.
+It may be empty to discard any key presses.
+If
+.Fl K
+is given together with
+.Fl R,
+key presses are instead passed to the
+.Fl R
+shell command.
+.Fl E
+closes the popup automatically when
+.Ar shell-command
+exits.
+With
+.Fl K ,
+.Ql Escape
+and
+.Ql C-c
+close the popup unless
+.Fl E
+is also given.
+.Pp
+.Fl x
+and
+.Fl y
+give the position of the popup, they have the same meaning as for the
+.Ic display-menu
+command.
+.Fl w
+and
+.Fl h
+give the width and height - both may be a percentage (followed by
+.Ql % ) .
+If omitted, without
+.Fl R
+they are calculated from the given lines and with
+.Fl R
+they use half the terminal size.
+.Pp
+The
+.Fl C
+flag closes any popup on the client.
 .El
 .Sh BUFFERS
 .Nm