editor-pane-set-line-numbers-appearance

editor-pane-set-line-numbers-appearance Function

Summary

Sets the appearance of line numbers when they are displayed in an editor-pane.

Package

capi

Signature

editor-pane-set-line-numbers-appearance editor-pane &key on-p background foreground font wrapped-string width-string separator-thickness separator-color separator-dash right-gap highlight-background highlight-foreground

Arguments

`editor-pane`⇩	An editor-pane.
`on-p`⇩	A boolean.
`background`⇩, `foreground`⇩
	Color specifiers.
`font`⇩	A font specifier.
`wrapped-string`⇩	A string or `nil`.
`width-string`⇩	A string.
`separator-thickness`⇩	A real number or `nil`.
`separator-color`⇩	A color specifier.
`separator-dash`⇩	A dash specifier (list of 2 or more integers) or `nil`.
`right-gap`⇩	A real.
`highlight-background`⇩, `highlight-foreground`⇩
	A color specifier or `nil`.

Description

The function editor-pane-set-line-numbers-appearance sets various values for the appearance of line numbers in editor-pane.

on-p sets whether the lines numbers are displayed. If on-p is nil, the line numbers are not displayed, which is the initial default state. Otherwise line numbers are displayed. on-p defaults to t.

For all arguments except on-p, the underlying value in editor-pane is changed only if the argument is supplied. The first time editor-pane-set-line-numbers-appearance is called for editor-pane, or if any of the :line-numbers-… initargs were supplied when making editor-pane, all of the unsupplied values are set to an initial value as described below. Otherwise, the existing underlying values are unchanged.

background and foreground specify the colors of the background and foreground of the line numbers, using 15 The Color System. If either is nil, it means using the background or foreground of editor-pane. In addition, background and foreground can also be one the keywords :tweak or :tweak-light, :background, :foreground, :tweak_background and :tweak_foreground.

:tweak means using a "tweak" of the background or the foreground of editor-pane, where "tweak" means a color that is close the background/foreground color in the RGB space, but is quite clearly different.
:tweak-light is like :tweak, but with less "tweaking", that is the "tweaked" color is closer to the background/foreground.
:background and :foreground mean using the background or the foreground of editor-pane. These are useful if you want to reverse the colors for line numbers, by supplying :background :foreground :foreground :background.
:tweak_background and :tweak_foreground mean using a "tweak" of the background or foreground of editor-pane.
:highlight means using the background or the foreground of the region highlight face.

The initial value of background is the value of the variable *editor-pane-default-line-numbers-background*, which defaults to :tweak. The initial value of foreground is the value of the variable *editor-pane-default-line-numbers-foreground*, which defaults to nil.

font specifies the font to use for the line numbers, as for simple-pane. In addition, it can be one of the symbols nil, :italic, :bold, :bold-italic, which means using the default, italic, bold or bold-italic fonts of editor-pane.

In addition, font can also be a list. The list may contain these elements:

A string specifying the family. If there is no string in the list, the family of the font in editor-pane is used.
The symbols :bold and :italic, specifying bold and italic fonts. By default, the font has normal weight and roman slant.
A real, specifying the size. If the real is positive, it explicitly specifies the size. If the real is negative, it is added to the size of the font in editor-pane. If there is no real in the list, the font size from editor-pane is used.

The main purpose of the list form for font is to allow you to specify a font that is the same as the font in editor-pane but of different size.

The initial value of font is the value of the variable *editor-pane-default-line-numbers-font*, which defaults to :italic.

wrapped-string specifies what to show for a wrapped line, that is a text line that takes more than one line on the screen. The first screen line of the text line shows the line number and the rest of the screen lines for a wrapped line show wrapped-string instead. The initial value of wrapped-string is the value of the variable *editor-pane-default-line-numbers-wrapped-string*, which defaults to "---".

width-string is used to control the width of the area that shows the line numbers. The width in pixels of width-string is assumed to be the widest string that it will need to show. The initial value of width-string is the value of the variable *editor-pane-default-line-numbers-width-string*, which defaults to "88888".

The line numbers are separated from the main text by a vertical line. separator-color, separator-thickness and separator-dash specify how to draw this line, as if they specify the foreground, thickness and dash in a call to gp:draw-line (with dashed being t when dash is non-nil). When separator-dash is 0, the line not drawn at all.

The initial value of separator-color is the value of the variable *editor-pane-default-line-numbers-separator-color*, which defaults to :gray80. The initial value of separator-thickness is the value of the variable *editor-pane-default-line-numbers-separator-thickness*, which defaults to 0.5. The initial value of separator-dash is the value of the variable *editor-pane-default-line-numbers-separator-dash*, which default to nil.

right-gap specifies an extra gap between the line numbers and the separator. The initial value of right-gap is the value of the variable *editor-pane-default-line-numbers-right-gap*, which defaults to 2.

When highlight-background or highlight-foreground are non-nil, they specify that the line numbers corresponding to the highlighted region should be drawn with highlight-background or highlight-foreground as background or foreground respectively, rather than background or foreground. If there is no highlighted region, then the line number corresponding to the cursor is drawn with this background. The initial value of highlight-background and highlight-foreground are the values of the variables *editor-pane-default-line-numbers-highlight-background* and *editor-pane-default-line-numbers-highlight-foreground*, which default to nil.

Notes

You typically set the appearance of the line numbers using the line-numbers-p, line-numbers-background, line-numbers-foreground and line-numbers-font initargs when making editor-pane. editor-pane-set-line-numbers-appearance is useful when you want to dynamically change the appearance.

The "tweaking" is particularly useful when you commonly switch colors for editor-pane, for example from light mode to dark mode.

The CAPI assumes that the font has the correct size. In particular, a font that is too high does not affect the layout of the text in the editor and will cause overlap between the line numbers of different lines.