elisp: Scroll Bars
37.14 Scroll Bars
=================
Normally the frame parameter ‘vertical-scroll-bars’ controls whether the
windows in the frame have vertical scroll bars, and whether they are on
the left or right. The frame parameter ‘scroll-bar-width’ specifies how
wide they are (‘nil’ meaning the default).
The frame parameter ‘horizontal-scroll-bars’ controls whether the
windows in the frame have horizontal scroll bars. The frame parameter
‘scroll-bar-height’ specifies how high they are (‘nil’ meaning the
default). Layout Parameters.
Horizontal scroll bars are not available on all platforms. The
function ‘horizontal-scroll-bars-available-p’ which takes no argument
returns non-‘nil’ if they are available on your system.
The following three functions take as argument a live frame which
defaults to the selected one.
-- Function: frame-current-scroll-bars &optional frame
This function reports the scroll bar types for frame FRAME. The
value is a cons cell ‘(VERTICAL-TYPE . HORIZONTAL-TYPE)’, where
VERTICAL-TYPE is either ‘left’, ‘right’, or ‘nil’ (which means no
vertical scroll bar.) HORIZONTAL-TYPE is either ‘bottom’ or ‘nil’
(which means no horizontal scroll bar).
-- Function: frame-scroll-bar-width &optional frame
This function returns the width of vertical scroll bars of FRAME in
pixels.
-- Function: frame-scroll-bar-height &optional frame
This function returns the height of horizontal scroll bars of FRAME
in pixels.
You can override the frame specific settings for individual windows
by using the following function:
-- Function: set-window-scroll-bars window &optional width
vertical-type height horizontal-type
This function sets the width and/or height and the types of scroll
bars for window WINDOW.
WIDTH specifies the width of the vertical scroll bar in pixels
(‘nil’ means use the width specified for the frame). VERTICAL-TYPE
specifies whether to have a vertical scroll bar and, if so, where.
The possible values are ‘left’, ‘right’, ‘t’, which means to use
the frame’s default, and ‘nil’ for no vertical scroll bar.
HEIGHT specifies the height of the horizontal scroll bar in pixels
(‘nil’ means use the height specified for the frame).
HORIZONTAL-TYPE specifies whether to have a horizontal scroll bar.
The possible values are ‘bottom’, ‘t’, which means to use the
frame’s default, and ‘nil’ for no horizontal scroll bar.
If WINDOW is ‘nil’, the selected window is used.
The following four functions take as argument a live window which
defaults to the selected one.
-- Function: window-scroll-bars &optional window
This function returns a list of the form ‘(WIDTH COLUMNS
VERTICAL-TYPE HEIGHT LINES HORIZONTAL-TYPE)’.
The value WIDTH is the value that was specified for the width of
the vertical scroll bar (which may be ‘nil’); COLUMNS is the
(possibly rounded) number of columns that the vertical scroll bar
actually occupies.
The value HEIGHT is the value that was specified for the height of
the horizontal scroll bar (which may be ‘nil’); LINES is the
(possibly rounded) number of lines that the horizontally scroll bar
actually occupies.
-- Function: window-current-scroll-bars &optional window
This function reports the scroll bar type for window WINDOW. The
value is a cons cell ‘(VERTICAL-TYPE . HORIZONTAL-TYPE)’. Unlike
‘window-scroll-bars’, this reports the scroll bar type actually
used, once frame defaults and ‘scroll-bar-mode’ are taken into
account.
-- Function: window-scroll-bar-width &optional window
This function returns the width in pixels of WINDOW’s vertical
scrollbar.
-- Function: window-scroll-bar-height &optional window
This function returns the height in pixels of WINDOW’s horizontal
scrollbar.
If you don’t specify these values for a window with
‘set-window-scroll-bars’, the buffer-local variables
‘vertical-scroll-bar’, ‘horizontal-scroll-bar’, ‘scroll-bar-width’ and
‘scroll-bar-height’ in the buffer being displayed control the window’s
scroll bars. The function ‘set-window-buffer’ examines these variables.
If you change them in a buffer that is already visible in a window, you
can make the window take note of the new values by calling
‘set-window-buffer’ specifying the same buffer that is already
displayed.
You can control the appearance of scroll bars for a particular buffer
by setting the following variables which automatically become
buffer-local when set.
-- Variable: vertical-scroll-bar
This variable specifies the location of the vertical scroll bar.
The possible values are ‘left’, ‘right’, ‘t’, which means to use
the frame’s default, and ‘nil’ for no scroll bar.
-- Variable: horizontal-scroll-bar
This variable specifies the location of the horizontal scroll bar.
The possible values are ‘bottom’, ‘t’, which means to use the
frame’s default, and ‘nil’ for no scroll bar.
-- Variable: scroll-bar-width
This variable specifies the width of the buffer’s vertical scroll
bars, measured in pixels. A value of ‘nil’ means to use the value
specified by the frame.
-- Variable: scroll-bar-height
This variable specifies the height of the buffer’s horizontal
scroll bar, measured in pixels. A value of ‘nil’ means to use the
value specified by the frame.
Finally you can toggle the display of scroll bars on all frames by
customizing the variables ‘scroll-bar-mode’ and
‘horizontal-scroll-bar-mode’.
-- User Option: scroll-bar-mode
This variable controls whether and where to put vertical scroll
bars in all frames. The possible values are ‘nil’ for no scroll
bars, ‘left’ to put scroll bars on the left and ‘right’ to put
scroll bars on the right.
-- User Option: horizontal-scroll-bar-mode
This variable controls whether to display horizontal scroll bars on
all frames.