23.3.2.37 Python representation of styles

A style object contains the foreground and background colors (see Colors In Python), along with an intensity, and can be used to apply this styling to output produced from Python.

GDB has many styles builtin (see Output Styling), and style objects can be created that apply these builtin styles to Python output. It is also possible to create new styles which can be used to style Python output (see Creating Style Parameters).

The style class is called gdb.Style, and has the following methods and attributes:

Function: Style.__init__ (style_name)

Create a gdb.Style that represents a builtin named style. The style_name must be a non-empty string that names a style that exists as a setting in GDB within ‘set style …’. For example, the string ‘"filename"’ can be used to create a gdb.Style object representing the ‘set style filename’ style.

If style_name names an unknown style then a RuntimeError exception is raised.

Function: Style.__init__ (foreground=None, background=None, intensity=gdb.INTENSITY_NORMAL)

Create a custom gdb.Style, manually specifying the three individual components. All of the arguments are optional. By default, if no arguments are given, then the default style will be created, this will produce output with the default terminal foreground and background colors, along with the normal level of intensity (i.e. neither bold, nor dim).

The foreground and background arguments should either be None, in which case the terminal default colors are used, or a gdb.Color object (see Colors In Python). Any other object type will result in a TypeError exception being raised.

The intensity argument should be one of the intensity constants defined below (see Style Intensities). Passing a none integer value results in a TypeError exception, and passing an invalid constant results in a ValueError exception.

Function: Style.escape_sequence ()

If styling is enabled (see Output Styling, then this method returns the string which is the terminal escape sequence necessary to apply this gdb.Style.

If styling is disabled then this method returns the empty string.

If this is a named style, which for some reason can no longer be read, then a RuntimeError exception is raised.

Function: Style.apply (string)

This method returns string, which must be a str object, with an escape sequence at both the start, and at the end. The escape sequence at the start applies this style, while the escape sequence at the end applies the terminal’s default style.

The effect of this is that, printing the result of this method, will print string with this style applied. Future output will be printed with the terminal’s default style.

If styling is currently disabled (see Output Styling), then Style.apply just returns a copy of string with no escape sequences added.

If this is a named style, which for some reason can no longer be read, then a RuntimeError exception is raised.

Variable: Style.foreground

This read/write attribute contains the gdb.Color object representing this style’s foreground color. Writing to this attribute updates the style’s foreground color.

If the gdb.Style object was created using a named style (i.e. using the single argument style_name __init__ method), then the underlying setting will be updated.

For unnamed styles, only the gdb.Style object will change.

Variable: Style.background

This read/write attribute contains the gdb.Color object representing this style’s background color. Writing to this attribute updates the style’s background color.

If the gdb.Style object was created using a named style (i.e. using the single argument style_name __init__ method), then the underlying setting will be updated.

For unnamed styles, only the gdb.Style object will change.

Variable: Style.intensity

This read/write attribute contains the intensity for this style, and will be one of the constants defined below (see Style Intensities). Writing to this attribute updates the style’s intensity.

It is also possible to write None to this attribute, this is equivalent of writing gdb.INTENSITY_NORMAL. This attribute will never read as None.

If the gdb.Style object was created using a named style (i.e. using the single argument style_name __init__ method), then the underlying setting will be updated.

For unnamed styles, only the gdb.Style object will change.

The following constants are defined to represent the different style intensities:

gdb.INTENSITY_NORMAL

This is the terminal’s default intensity.

gdb.INTENSITY_BOLD

This is for bold text.

gdb.INTENSITY_DIM

This is for dim text.