21.12 Scroll Bars

On graphical displays, there is a vertical scroll bar on the side of each Emacs window. Clicking mouse-1 on the scroll bar’s up and down buttons scrolls the window by one line at a time (but some toolkits allow you to customize the scroll bars to not have those buttons). Clicking mouse-1 above or below the scroll bar’s inner box scrolls the window by nearly the entire height of the window, like M-v and C-v respectively (see Changing the Location of Point). (This, too, can behave differently with some toolkits.) Dragging the inner box scrolls continuously.

If Emacs is compiled on the X Window System without X toolkit support, the scroll bar behaves differently. Clicking mouse-1 anywhere on the scroll bar scrolls forward like C-v, while mouse-3 scrolls backward like M-v. Clicking mouse-2 in the scroll bar lets you drag the inner box up and down.

To toggle the use of vertical scroll bars, type M-x scroll-bar-mode. This command applies to all frames, including frames yet to be created. To toggle vertical scroll bars for just the selected frame, use the command M-x toggle-scroll-bar.

To control the use of vertical scroll bars at startup, customize the variable scroll-bar-mode (see Customization). Its value should be either right (put scroll bars on the right side of windows), left (put them on the left), or nil (disable vertical scroll bars). By default, Emacs puts scroll bars on the right if it was compiled with GTK+ support on the X Window System, and on MS-Windows or macOS; Emacs puts scroll bars on the left if compiled on the X Window System without GTK+ support (following the old convention for X applications).

You can also use the X resource ‘ verticalScrollBars’ to enable or disable the scroll bars (see X Resources). To control the scroll bar width, change the scroll-bar-width frame parameter (see Frame Parameters in The Emacs Lisp Reference Manual).

If you’re using Emacs on X (with GTK+ or Motif), you can customize the variable scroll-bar-adjust-thumb-portion to control overscrolling of the scroll bar, i.e., dragging the thumb down even when the end of the buffer is visible. If its value is non- nil, the scroll bar can be dragged downwards even if the end of the buffer is shown; if nil, the thumb will be at the bottom when the end of the buffer is shown. You cannot over-scroll when the entire buffer is visible.

The visual appearance of the scroll bars is controlled by the scroll-bar face. (Some toolkits, such as GTK+ and MS-Windows, ignore this face; the scroll-bar appearance there can only be customized system-wide, for GTK+ see GTK+ resources).

On graphical frames, vertical scroll bars implicitly serve to separate side-by-side windows visually. When vertical scroll bars are disabled, Emacs by default separates such windows with the help of a one-pixel wide vertical border. That border occupies the first pixel column of the window on the right and may thus overdraw the leftmost pixels of any glyph displayed there. If these pixels convey important information, you can make them visible by enabling window dividers, see Window Dividers. To replicate the look of vertical borders, set the right-divider-width parameter of frames to one and have the window-divider face inherit from that of vertical-border, Window Dividers in The Emacs Lisp Reference Manual.

On graphical displays with toolkit support, Emacs may also supply a horizontal scroll bar on the bottom of each window. Clicking mouse-1 on that scroll bar’s left and right buttons scrolls the window horizontally by one column at a time. (Note that some toolkits allow customizations of the scroll bar that cause these buttons not to be shown.) Clicking mouse-1 on the left or right of the scroll bar’s inner box scrolls the window by four columns. Dragging the inner box scrolls the window continuously.

Note that such horizontal scrolling can make the window’s position of point disappear on the left or the right. Typing a character to insert text or moving point with a keyboard command will usually bring it back into view.

To toggle the use of horizontal scroll bars, type M-x horizontal-scroll-bar-mode. This command applies to all frames, including frames yet to be created. To toggle horizontal scroll bars for just the selected frame, use the command M-x toggle-horizontal-scroll-bar.

To control the use of horizontal scroll bars at startup, customize the variable horizontal-scroll-bar-mode.

You can also use the X resource ‘ horizontalScrollBars’ to enable or disable horizontal scroll bars (see X Resources). To control the scroll bar height, change the scroll-bar-height frame parameter (see Frame Parameters in The Emacs Lisp Reference Manual).