Module _M.textui.style
The style module lets you define and use custom, non-lexer-based styles.
The default styles
TextUI piggybacks on the default lexer styles defined by a user's theme, and makes them available for your TextUI interface. The big benefit of this is that by using those styles, or by basing your custom styles on them, your interface stands a much higher chance of blending in well with the color scheme used. As an example, your custom style with cyan foreground text might look great with your own dark theme, but may be pretty near invisible for some user with a light blue background.
You can read more about the default lexer styles
here.
You access a default style (or any style for that matter), by indexing the
style module, like so: style.<name>
. For reference, the default styles
available are these:
- style.nothing
- style.whitespace
- style.comment
- style.string
- style.number
- style.keyword
- style.identifier
- style.operator
- style.error
- style.preproc
- style.constant
- style.variable
- style.function
- style.class
- style.type
- style.default
- style.line_number
- style.bracelight
- style.bracebad
- style.controlchar
- style.indentguide
- style.calltip
What's a style?
TextUI styling has been made to resemble the lexer based style creation.
A style is thus just a table with certain properties, almost exactly the same as
for style created for a lexer or theme. Please see the documentation for
lexer.style
for information about the fields. The one exception compared to lexer styles
is that colors are specified using the standard '#rrggbb'
notation instead of
the lexer styles' bgr
notation. This is what you use to create custom styles
(see below), and also what you get when accessing any already existing styles.
Defining styles
You define a new style by assigning the style to the style module, like so:
style.foo_header = { italic = true, fore = '#680000' }
As has been previously said, it's often a good idea to base your custom styles on an existing default style. Similarily to defining a lexer style in Textadept you can achieve this by concatenating styles:
style.foo_header = style.string .. { underline = true }
NB: Watch out for the mistake of not assigning the style to the style module:
local header = style.string .. { underline = true }
This will not work, as the style is not correctly defined with the style module.
In order to avoid name clashes, it's suggested that you name any custom styles
by prefixing their name with the name of your module. E.g. if your module is named
awesome
, then name your style something like style.awesome_style
.
Using styles
You typically use a style by inserting text through _M.textui.buffer's text insertion methods, specifying the style. Please see the examples in buffer_styling.lua for examples on this.
Functions
apply (style, buffer, start_pos, length) | Applies the specified style for the given text range and buffer. |
define_styles () | Defines the currently used custom styles for the current buffer. |
Functions
- apply (style, buffer, start_pos, length)
-
Applies the specified style for the given text range and buffer.
While you could use this directly, you'd typically use the text insertion
methods in _M.textui.buffer to style content.
Parameters:
style
: The defined stylebuffer
: The buffer to apply the style forstart_pos
: The starting position of the stylelength
: The number of positions to style
- define_styles ()
- Defines the currently used custom styles for the current buffer. This must be called whenever a buffer with custom styles is switched to. This is automatically done by the _M.textui.buffer class, and thus not something you typically have to worry about.