Cursor Position (CUP) - Ghostty Org

The parameters y and x must be integers greater than or equal to 1. If either is less than or equal to 0, adjust that parameter to be 1.

The values y and x are both one-based. For example, the top row is row 1 and the leftmost column on the screen is column 1.

This sequence always unsets the pending wrap state.

If origin mode is NOT set, the cursor is moved exactly to the row and column specified by y and x. The maximum value for y is the bottom row of the screen and the maximum value for x is the rightmost column of the screen.

If origin mode is set, the cursor position is set relative to the top-left corner of the scroll region. y = 1 corresponds to the top margin and x = 1 corresponds to the left margin. The maximum value for y is the bottom margin and the maximum value for x is the right margin.

When origin mode is set, it is impossible set a cursor position using this sequence outside the boundaries of the scroll region.

Validation

CUP V-1: Normal Usage

bash

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[2;3H"
printf "A"

|__________|
|__Ac______|

CUP V-2: Off the Screen

bash

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[500;500H"
printf "A"

|__________|
|__________|
|_________Ac

CUP V-3: Relative to Origin

bash

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[2;3r" # scroll region top/bottom
printf "\033[?6h" # origin mode
printf "\033[1;1H" # move to top-left
printf "X"

|__________|
|X_________|

CUP V-4: Relative to Origin with Left/Right Margins

bash

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[?69h" # enable left/right margins
printf "\033[3;5s" # scroll region left/right
printf "\033[2;3r" # scroll region top/bottom
printf "\033[?6h" # origin mode
printf "\033[1;1H" # move to top-left
printf "X"

|__________|
|__X_______|

CUP V-5: Limits with Scroll Region and Origin Mode

bash

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[?69h" # enable left/right margins
printf "\033[3;5s" # scroll region left/right
printf "\033[2;3r" # scroll region top/bottom
printf "\033[?6h" # origin mode
printf "\033[500;500H" # move to top-left
printf "X"

|__________|
|__________|
|____X_____|

CUP V-6: Pending Wrap is Unset

bash

cols=$(tput cols)
printf "\033[${cols}G" # move to last column
printf "A" # set pending wrap state
printf "\033[1;1H"
printf "X"

|Xc_______X|