Display Attributes

Urwid supports a number of common display attributes in monochrome, 16-color, 88-color, 256-color, and 24-bit (true color) modes.

You are encouraged to provide support for as many of these modes as you like, while allowing your interface to degrade gracefully by providing command line arguments or other interfaces to switch modes.

When setting up a palette with MainLoop (or directly on your screen instance), you may specify attributes for 16-color, monochrome and high color modes. You can then switch between these modes with screen.set_terminal_properties(), where screen is your screen instance or MainLoop.screen.

See also

register_palette() reference,

Using Display Attributes

Once you have defined a palette you may use its display attribute names anywhere that expects a display attribute. When no display attribute is defined None is used as a default display attribute.

None will typically be rendered with the terminal’s default foreground and background colors.

You can also specify an exact foreground and background using an AttrSpec instance instead of a display attribute name. Using AttrSpec instances in your code may be trickier than using your screen’s palette because you must know which mode (number of colors) the screen is in.

Text Markup

A Text widget can specify which display attributes each part of the text will use with the format defined in Text class reference. Some examples:

Text(u"a simple string with default attribute")

The string and space around will use the None default display attribute which usually appears in the terminal’s default foreground and background.

Text(('attr1', u"a string in display attribute attr1"))

The string will appear with foreground and backgrounds specified in the display module’s palette for 'attr1', but the space around (before/after) the text will appear with the default display attribute.

Text([u"a simple string ", ('attr1', u"ending with attr1")])

The first three words have the default display attribute and the last three words have display attribute 'attr1'.

Text([('attr1', u"start in attr1 "), ('attr2', u"end in attr2")])

The first three words have display attribute 'attr1' and the last three words have display attribute 'attr2'.

Text(('attr1', [u"nesting example ", ('attr2', u"inside"), u" outside"]))

When markup is nested only the innermost attribute applies. Here "inside" has attribute 'attr2' and all the rest of the text has attribute 'attr1'.

Assigning Display Attributes with AttrMap

If you want a whole widget to be assigned a display attribute, or if you want to change one or more display attributes to other display attributes, you can wrap your widget in an AttrMap widget. Text widgets have no way to specify a display attribute for the whitespace around the text caused by alignment and wrapping so AttrMap may be used. Some examples:

AttrMap(Text(u"hello"), 'attr1')

The whole Text widget will have display attribute 'attr1' including whitespace around the "hello" text.

AttrMap(Text(('attr1', u"hello")), 'attr2')

The u"hello" text will appear with display attribute 'attr1' and all surrounding whitespace will appear with display attribute 'attr2'.

AttrMap(Text([('attr1', u"hello"), u" world"]), {'attr1': 'attr2'})

The AttrMap widget will apply display attribute 'attr2' to all parts of the Text widget that are using 'attr1'. The result is the "hello" text appearing with display attribute 'attr2' and all other text and whitespace appearing in the default display attribute.

AttrMap can also change display attributes differently when they are in focus. This can be used to “highlight” one or more widgets to make your interface more user friendly. To use this feature set the focus_map parameter when creating the AttrMap widget.

Foreground and Background Settings

Supported by Terminal

xterm / gnome-term

rxvt

linux console

others

16 standard foreground colors

YES

YES

YES

very widely supported

8 standard background colors

YES

YES

YES

very widely supported

default foreground/background

YES

YES

YES

widely supported

bold, underline, standout

YES

YES

standout

widely supported

italics

YES

YES

NO

widely supported

blink

YES/NO

NO

NO

some support

strikethrough

YES

NO

NO

some supported

“bright” background colors

YES

urxvt

some support

256-color foreground/background

YES

some support

88-color foreground/background

w/palette setting

urxvt

limited support

RGB palette setting

YES

limited support

16 Standard Foreground Colors

  • 'black'

  • 'dark red'

  • 'dark green'

  • 'brown'

  • 'dark blue'

  • 'dark magenta'

  • 'dark cyan'

  • 'light gray'

  • 'dark gray'

  • 'light red'

  • 'light green'

  • 'yellow'

  • 'light blue'

  • 'light magenta'

  • 'light cyan'

  • 'white'

8 Standard Background Colors

  • 'black'

  • 'dark red'

  • 'dark green'

  • 'brown'

  • 'dark blue'

  • 'dark magenta'

  • 'dark cyan'

  • 'light gray'

Default Foreground and Background

  • 'default' (or simply '')

'default' may be specified as a foreground or background to use a terminal’s default color. For terminals with transparent backgrounds 'default' is the only way to show the transparent background. There is no way to tell what the default colors are, so it is best to use default foregrounds and backgrounds together (not with other colors) to ensure good contrast.

Bold, Underline, Standout

  • 'bold'

  • 'underline'

  • 'standout'

  • 'blink'

  • 'italics'

  • 'strikethrough'

These settings may be tagged on to foreground colors using commas, eg: 'light gray,underline,bold,strikethrough'

For monochrome mode combinations of these are the only values that may be used.

Many terminals will turn foreground colors into their bright versions when you use bold, eg: 'dark blue,bold' might look the same as 'light blue'. Some terminals also will display bright colors in a bold font even if you don’t specify bold. To inhibit this you can try setting bright_is_bold=False with BaseScreen.set_terminal_properties(), but it is not always supported.

'standout' is usually displayed as the foreground and background colors reversed.

“Bright” Background Colors

Warning

Terminal support for bright background colors is spotty, and they generally should be avoided. If you are in a high-color mode you might have better luck using the high-color versions 'h8', 'h9', 'h10', …, 'h15'.

  • 'dark gray'

  • 'light red'

  • 'light green'

  • 'yellow'

  • 'light blue'

  • 'light magenta'

  • 'light cyan'

  • 'white'

24-Bit Foreground and Background Colors

In 24-bit color mode, any hex color code of the form #rrggbb can be used to specify a precise RGB value for foreground and background colors. Support for 24-bit color mode varies widely among terminal programs. Furthermore, terminal multiplexers such as tmux and screen can sometimes interfere with the operation of 24-bit color mode unless properly configured.

See also

The palette_test.py example program

256-Color Foreground and Background Colors

In 256-color mode you have the 16 basic colors, a 6 * 6 * 6 color cube and a gray scale with 24 entries (white and black not included).

The color cube is weighted towards the brighter colors, with RGB points at 0, 0x5f, 0x87, 0xaf, 0xd7 and 0xff. The hex characters '0', '6', '8', 'a', 'd' and 'f' are used as short-forms for these values.

High colors may be specified by their index 'h0', …, 'h255' or with the shortcuts for the color cube '#000', '#006', '#008', …, '#fff' or gray scale entries 'g0' (black from color cube) , 'g3', 'g7', … 'g100' (white from color cube).

See also

The palette_test.py example program

88-Color Foreground and Background Colors

In 88-color mode you have the 16 basic colors, a 4 * 4 * 4 color cube and a gray scale with 8 entries (white and black not included).

The color cube is weighted towards the brighter colors, with RGB points at 0, 0x8b, 0xcd, and 0xff. The hex characters '0', '8', 'c' and 'f' are used as short-forms for these values.

High colors may be specified by their index 'h0', …, 'h87' or with the shortcuts for the color cube '#000', '#008', '#00c', …, '#fff' or gray scale entries 'g0' (black from color cube), 'g19', 'g35', … 'g100' (white from color cube).

See also

The palette_test.py example program

RGB Palette Setting

A few terminals have the ability to customize the terminal palette’s RGB values with raw_display.Screen.modify_terminal_palette(). There is no automatic way to tell if this is supported by a user’s terminal, so this feature shouldn’t be relied on.

raw_display.Screen.reset_default_terminal_palette() is used to reset the palette in the palette_test.py example program when switching modes.