53438: support for changing terminal cursor shape and colour

2 files changed, 79 insertions, 0 deletions

diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 6cb9167d5..76185efca 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -1749,6 +1749,12 @@ inserted instead of invoking editor commands. Furthermore, pasted text forms a
 single undo event and if the region is active, pasted text will replace the
 region.
 )
+item(tt(cursor-color) <E>)(
+Support for changing the color of the cursor.
+)
+item(tt(cursor-shape) <E>)(
+Support for changing the shape of the cursor.
+)
 item(tt(integration-output) <E>)(
 This provides the terminal with semantic information regarding where the output
 from commands start and finish. Some terminals use this information to make it
@@ -1769,6 +1775,11 @@ item(tt(query-bg) <E>)(
 Query the terminal background color which is used for tt(.term.bg) and
 tt(.term.mode).
 )
+item(tt(query-cursor) <E>)(
+Query the cursor color. This facilitates restoring the cursor to its original
+color if it has been configured via tt(zle_cursorform). The color is also
+assigned to tt(.term.cursor).
+)
 item(tt(query-fg) <E>)(
 Query the terminal foreground color which is used for tt(.term.fg).
 )
@@ -1900,6 +1911,13 @@ parameter has the effect of ensuring that bracketed paste remains disabled.
 However, see also the tt(.term.extensions) parameter which provides a single
 place to enable or disable terminal features.
 )
+vindex(zle_cursorform)
+item(tt(zle_cursorform))(
+An array describing contexts in which ZLE should change the shape and color
+of the cursor.
+See ifzman(em(Cursor Form) in zmanref(zshzle))\
+ifnzman(noderef(Cursor Form)).
+)
 vindex(zle_highlight)
 item(tt(zle_highlight))(
 An array describing contexts in which ZLE should highlight the input text.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 4c5965c6f..669e6927b 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -2855,3 +2855,64 @@ special array parameter tt(region_highlight); see
 ifnzman(noderef(Zle Widgets))\
 ifzman(above).
 
+texinode(Cursor Form)()()(Character Highlighting)
+subsect(Cursor Form)
+cindex(cursor form)
+
+vindex(zle_cursorform, setting)
+Some terminals support the ability to change the shape and color of the cursor.
+On such terminals, the line editor will use cursor styles appropriate to
+different contexts. This is controlled via the array parameter
+tt(zle_cursorform). To disable all cursor changes, see the tt(.term.extensions)
+parameter.
+
+Each element of the array should consist of a word indicating a context
+followed by a colon, then a comma-separated list of properties describing the
+shape and color to apply to the cursor.
+
+The available contexts follow with the default cursor form shown in
+parentheses. Where no default is given, the terminal's default is applied:
+
+startitem()
+item(tt(command))(
+Used for vi normal mode.
+)
+item(tt(edit))(
+The default form used in the line editor and for editing text in emacs
+mode.
+)
+item(tt(insert) (tt(bar)))(
+Used for vi editing mode.
+)
+item(tt(overwrite) (tt(underline)))(
+Used when editing text in overwrite mode or with the vi replace command.
+)
+item(tt(pending) (tt(underline)))(
+Used where the line editor is waiting for a single key press such as the vi
+operator pending mode widget.
+)
+item(tt(region))(
+Applied for both tt(regionstart) and tt(regionend) contexts.
+)
+item(tt(regionstart))(
+Used when the region is active and the cursor is positioned at the start of the
+region. The region includes the text under the cursor when it is positioned at
+the start so it is best to choose a cursor form that does not obscure this fact.
+)
+item(tt(regionend))(
+Used when the region is active and the cursor is positioned at the end of the
+region. Note that when this is the case, the region does not include the cursor
+position.
+)
+item(tt(visual))(
+Used when vi visual mode is active. The visual selection always includes the
+cursor position so the same advice as for tt(regionstart) applies.
+)
+enditem()
+
+The available cursor forms are tt(none), tt(bar), tt(block), tt(underline) and
+tt(hidden). Additionally, you can specify either tt(blink) or tt(steady) to
+indicate whether the cursor should flash and specify a color as an RGB triplet
+in hexadecimal format with with tt(color=)var(#xxxxxx). The value tt(none)
+applies the terminal's default cursor form. Note that on many terminals, this
+may be different to the initial cursor state from when the shell started.