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 style
  • buffer: The buffer to apply the style for
  • start_pos: The starting position of the style
  • length: 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.
generated by LDoc 1.1