moar/MOUSE.md

Mouse Scrolling vs Selecting and Copying

moar supports two mouse modes (using the --mousemode parameter):

• scroll makes moar process mouse events from your terminal, thus enabling mouse scrolling work, but disabling the ability to select text with mouse in the usual way. Selecting text will require using your terminal's capability to bypass mouse protocol. Most terminals support this capability, see Selection workarounds for scroll mode for details.
• select makes moar not process mouse events. This makes selecting and copying text work, but scrolling might not be possible, depending on your terminal and its configuration.
• auto uses select on terminals where we know it won't break scrolling, and scroll on all others. The white list lives in the mouseTrackingRecommended() function in screen.go.

The reason these tradeoffs exist is that if moar requests mouse events from the terminal, it should process all mouse events, including attempts to select text. This is the case with every console application.

However, some terminals can send "fake" arrow key presses to applications which do not request processing mouse events. This means that on those terminals, you will be better off using --mousemode select option, given that you also have this feature enabled (it's usually on by default). With this setup, both scrolling and text selecting in the usual way will work. To check whether this could work, simply run moar with option --mousemode select and see if scrolling still works.

Mouse Selection Workarounds for scroll Mode

Most terminals implement a way to suppress mouse events capturing by applications, thus allowing you to select text even in those applications which make use of the mouse. Usually this involves selecting with Shift being held. Often the modifier key is configurable. Some other terminals allow setting options for specific types of mouse events to be reported. While the table below attempts to list the default behaviours of some common terminals, you should consult documentation of the one you're using to get detailed up-to-date information.

If your favorite terminal is missing, feel free to add it.

⚠️ With some of these, if you made incorrect selection you can cancel it either with an Escape key press or with a mouse click on text area. You will probably need to still hold the modifier key for this, as hitting Escape without it will likely exit moar.

Terminal	Solution
Alacritty	Use Shift when selecting with mouse. Cred to @chrisgrieser for this tip.
Contour	Use Shift when selecting with mouse. Cred to @postsolar for this tip.
Foot	Use Shift when selecting with mouse. Cred to @postsolar for this tip.
Hyper	On macOS: Set macOptionSelectionMode: 'force' in your config file, then hold the Option Key ⌥ when selecting with mouse.
iTerm	Go to Preferences / Profiles / Default / Terminal / and uncheck "Report mouse clicks & drags".
Terminal on macOS	On a laptop: Hold down the fn key when selecting with mouse.
kitty	Use Shift or Fn when selecting with mouse. Cred to @PrayagS for this tip.
Konsole	Use Shift when selecting with mouse. Cred to @cig0 for this tip.
Terminator	Use Shift key when selecting with mouse. Cred to @felix-seifert for this tip.
Tilix	Use Shift key when selecting with mouse. Cred to @Macr0Nerd for this tip.
Warp	Go to Preferences / Settings / Features / Terminal / and uncheck "Enable Mouse Reporting".
Windows	Use Shift key when selecting with mouse. Cred to @89z for this tip.

less' screen initialization sequence

Recorded using iTerm's Automatically log session input to files feature.

less is version 487 that comes with macOS 11.3 Big Sur.

All linebreaks are mine, added for readability. The ^Ms are not.

less /etc/passwd
^G<ESC>[30m<ESC>(B<ESC>[m^M
<ESC>[?1049h
<ESC>[?1h
<ESC>=^M
##

moar's screen initialization sequence

moar /etc/passwd /Users/johan/src/moar
^G<ESC>[30m<ESC>(B<ESC>[m^M
<ESC>[?1049h
<ESC>[?1006;1000h
<ESC>[?25l
<ESC>[1;1H
<ESC>[m<ESC>[2m  1 <ESC>[22m##

Analysis of less

The line starting with ^G is probably from from fish since it's the same for both less and moar.

<ESC>[?1049h switches to the Alternate Screen Buffer, search here for 1 0 4 9 for info.

Then less does [?1h, which apparently is DECCKM Cursor Keys Mode, send ESC O A for cursor up, followed by =, meaning DECKPAM - Set keypad to applications mode (ESCape instead of digits).

NOTE that this means that less version 487 that comes with macOS 11.3 Big Sur doesn't even try to enable any mouse reporting, but relies on the terminal to convert scroll wheel events into arrow keypresses.

Analysis of moar

Same as less up until the Alternate Screen Buffer is enabled.

<ESC>[?1006;1000h enables SGR Mouse Mode and the X11 xterm mouse protocol (search for 1 0 0 0).

<ESC>[?25l hides the cursor. NOTE Maybe we don't need this? It might be implicit when we enable the Alternate Screen Buffer.

<ESC>[1;1H moves the cursor to the top left corner.

Then it's the first line with its line number in faint type.