QColorOutput Class

Outputs colored messages to stderr. \internal. More...

Header: #include <QColorOutput>

Public Types

enum ColorCodeComponent { BlackForeground, BlueForeground, GreenForeground, CyanForeground, RedForeground, …, DefaultColor }

Public Functions

QColorOutput()
void writeUncolored(const QString &message)

Detailed Description

\nonreentrant

QColorOutput is a convenience class for outputting messages to stderr using color escape codes, as mandated in ECMA-48. QColorOutput will only color output when it is detected to be suitable. For instance, if stderr is detected to be attached to a file instead of a TTY, no coloring will be done.

QColorOutput does its best attempt. but it is generally undefined what coloring or effect the various coloring flags has. It depends strongly on what terminal software that is being used.

When using `echo -e 'my escape sequence'`, \033 works as an initiator but not when printing from a C++ program, despite having escaped the backslash. That's why we below use characters with value 0x1B.

It can be convenient to subclass QColorOutput with a private scope, such that the functions are directly available in the class using it.

Usage

To output messages, call write() or writeUncolored(). write() takes as second argument an integer, which QColorOutput uses as a lookup key to find the color it should color the text in. The mapping from keys to colors is done using insertMapping(). Typically this is used by having enums for the various kinds of messages, which subsequently are registered.

 enum MyMessage
 {
   Error,
   Important
 };

 QColorOutput output;
 output.insertMapping(Error, QColorOutput::RedForeground);
 output.insertMapping(Import, QColorOutput::BlueForeground);

 output.write("This is important", Important);
 output.write("Jack, I'm only the selected official!", Error);

See also Bash Prompt HOWTO, 6.1. Colors, Linux Gazette, Tweaking Eterm, Edward Livingston-Blade, Standard ECMA-48, Control Functions for Coded Character Sets, ECMA International, Wikipedia, ANSI escape code, and Linux Gazette, So You Like Color!, Pradeep Padala.

Member Type Documentation

enum QColorOutput::ColorCodeComponent

\internal

ConstantValueDescription
QColorOutput::BlackForeground1 << ForegroundShift 
QColorOutput::BlueForeground2 << ForegroundShift 
QColorOutput::GreenForeground3 << ForegroundShift 
QColorOutput::CyanForeground4 << ForegroundShift 
QColorOutput::RedForeground5 << ForegroundShift 
QColorOutput::PurpleForeground6 << ForegroundShift 
QColorOutput::BrownForeground7 << ForegroundShift 
QColorOutput::LightGrayForeground8 << ForegroundShift 
QColorOutput::DarkGrayForeground9 << ForegroundShift 
QColorOutput::LightBlueForeground10 << ForegroundShift 
QColorOutput::LightGreenForeground11 << ForegroundShift 
QColorOutput::LightCyanForeground12 << ForegroundShift 
QColorOutput::LightRedForeground13 << ForegroundShift 
QColorOutput::LightPurpleForeground14 << ForegroundShift 
QColorOutput::YellowForeground15 << ForegroundShift 
QColorOutput::WhiteForeground16 << ForegroundShift 
QColorOutput::BlackBackground1 << BackgroundShift 
QColorOutput::BlueBackground2 << BackgroundShift 
QColorOutput::GreenBackground3 << BackgroundShift 
QColorOutput::CyanBackground4 << BackgroundShift 
QColorOutput::RedBackground5 << BackgroundShift 
QColorOutput::PurpleBackground6 << BackgroundShift 
QColorOutput::BrownBackground7 << BackgroundShift 
QColorOutput::DefaultColor1 << SpecialShiftQColorOutput performs no coloring. This typically means black on white or white on black, depending on the settings of the user's terminal.

Member Function Documentation

QColorOutput::QColorOutput()

\internalConstructs a QColorOutput instance, ready for use.

void QColorOutput::writeUncolored(const QString &message)

\internalWrites message to stderr as if for instance QTextStream would have been used, and adds a line ending at the end.

This function can be practical to use such that one can use QColorOutput for all forms of writing.