Ceylan::System::Console Class Reference

Provides a console abstraction for basic output of text in a terminal. More...

#include <CeylanConsole.h>

Inheritance diagram for Ceylan::System::Console:

Inheritance graph
[legend]
Collaboration diagram for Ceylan::System::Console:

Collaboration graph
[legend]

List of all members.

Classes

struct  BackgroundColor
 Escape sequences for color backgrounds in terminal. More...
class  ConsoleException
 Exception thrown when an operation on a Console failed. More...
struct  ForegroundColor
 Escape sequences for color foregrounds in terminal. More...

Public Types

enum  TextOutputFormat { rawText, html }
 Defines what text output formats for TextDisplayable instances are available. More...

Public Member Functions

 Console (bool startInForeground=true)
 Constructor for a basic console, mostly suitable for debugging.
 Console (TextBuffer::CharAbscissa startingX, TextBuffer::CharOrdinate startingY, TextBuffer::CharAbscissa width, TextBuffer::CharOrdinate height, TextBuffer::TextLayout layout, bool useBottomScreen=true, bool useSubCore=true, bool startInForeground=true)
 Constructor for a basic console, mostly suitable for debugging.
virtual ~Console () throw ()
 Virtual destructor.
virtual void goInteractive ()
 Sets the console to foreground if needed, render its text and enter its event loop so that the user can use the keys to browse its content.
virtual TextBuffer::TextLayout getTextLayout () const
 Returns the text layout being currently used.
virtual void setTextLayout (TextBuffer::TextLayout newLayout)
 Sets a new text layout.
virtual bool jumpNextText ()
 Makes the console display next text on top.
virtual bool jumpPreviousText ()
 Makes the console display previous text on top.
virtual bool jumpNextLine ()
 Offsets the console display text of one line to the bottom.
virtual bool jumpPreviousLine ()
 Offsets the console display text of one line to the bottom.
virtual void addInBuffer (const std::string &text)
 Adds specified text in the character buffer of this console.
virtual void blankBuffer ()
 Blanks the character buffer of this console.
virtual void setToForeground (bool toForeground=true)
 Sets the console either in the foreground (hence using the screen and the keys), or in the background (not using them).
virtual void render ()
 Renders in console output the current text of its character buffer.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns an user-friendly description of the state of this object.

Static Public Member Functions

static void SetKeyRepeat (Millisecond durationBeforeFirstRepeat=300, Millisecond durationBetweenRepeats=100)
 Sets for the console the key repeat settings.
static void Initialize (bool useBottomScreen=true, bool useSubCore=true, bool force=false)
 Initializes the console for text output, with as little side-effects as possible.
static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
 Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat GetOutputFormat ()
 Returns the current overall text format to be used by TextDisplayable instances.
static void SetOutputFormat (TextOutputFormat newOutputFormat)
 Sets the current overall text format to be used by TextDisplayable instances.

Static Public Attributes

static const
TextBuffer::CharAbscissa 
UnlimitedWidth = 0
 Use this constant when terminal supports unlimited width (i.e.
static const
TextBuffer::CharOrdinate 
UnlimitedHeight = 0
 Use this constant when terminal supports unlimited height (i.e.
static const char *const DefaultColors = "\033[0m"
static const char *const Bold = "\033[1m"
static const char *const Faint = "\033[2m"
static const char *const BoldAndFaintOff = "\033[22m"
static const char *const Underline = "\033[4m"
static const char *const UnderlineOff = "\033[24m"
static const char *const Blinking = "\033[5m"
static const char *const BlinkingOff = "\033[25m"
static const char *const NegativeImage = "\033[7m"
static const char *const NegativeImageOff = "\033[27m"
static const char *const InvisibleImage = "\033[8m"
static const char *const InvisibleImageOff = "\033[28m"

Protected Member Functions

virtual void initConsole (TextBuffer::CharAbscissa startingX, TextBuffer::CharOrdinate startingY, TextBuffer::CharAbscissa width, TextBuffer::CharOrdinate height, TextBuffer::TextLayout layout, bool useBottomScreen=true, bool useSubCore=true)
 Initializes a console, used by constructors.

Protected Attributes

TextBuffer::CharAbscissa _xstart
TextBuffer::CharOrdinate _ystart
TextBuffer_buffer
 Buffer storing all the texts.
bool _inForeground
 Tells whether the console is in interactive mode or hidden from the user.
bool _useBottomScreen
 Tells whether any bottom screen should be used.
bool _useSubCore
 Tells whether any sub rendering core should be used.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText
 The text format to be used currently by TextDisplayable instances.

Private Member Functions

 Console (const Console &source)
 Copy constructor made private to ensure that it will be never called.
Consoleoperator= (const Console &source)
 Assignment operator made private to ensure that it will be never called.


Detailed Description

Provides a console abstraction for basic output of text in a terminal.

Uses a character buffer.

Definition at line 58 of file CeylanConsole.h.


Member Enumeration Documentation

Defines what text output formats for TextDisplayable instances are available.

Enumerator:
rawText 
html 

Definition at line 124 of file CeylanTextDisplayable.h.


Constructor & Destructor Documentation

Console::Console ( bool  startInForeground = true  )  [explicit]

Constructor for a basic console, mostly suitable for debugging.

The console will use all available terminal space.

On classical terminals (ex: xterm-like), it implies that terminal-provided line-wrapping and scrolling will be used.

This console will start with a raw layout.

On Nintendo DS, it implies it will take the full extent of the bottom LCD screen and will provide a text area of 32x24 characters. As a side-effect, the sub 2D core will be powered on, the console will use the second (sub) core, here located at the bottom actual screen, and using the VRAM bank C, the background #0 and the default font. Only available for the ARM9.

Parameters:
startInForeground tells whether the console is to start in foreground (thus directly taking control of the its display and input devices, i.e. keys) or if it should be on the background, storing text non-interactively until it is set to foreground.
Exceptions:
ConsoleException if the operation failed or is not supported.

Definition at line 112 of file CeylanConsole.cc.

References initConsole(), Ceylan::TextBuffer::Raw, and setToForeground().

Console::Console ( TextBuffer::CharAbscissa  startingX,
TextBuffer::CharOrdinate  startingY,
TextBuffer::CharAbscissa  width,
TextBuffer::CharOrdinate  height,
TextBuffer::TextLayout  layout,
bool  useBottomScreen = true,
bool  useSubCore = true,
bool  startInForeground = true 
)

Constructor for a basic console, mostly suitable for debugging.

It

Parameters:
startingX the abscissa of the top-left corner of the rectangle used for text output.
startingY the ordinate of the top-left corner of the rectangle used for text output.
width the width allowed for text output, starting from startingX.
height the height allowed for text output, starting from startingY.
layout the desired text layout for this buffer.
useBottomScreen tells whether the bottom or the top physical screen should be used (default: bottom screen).
useSubCore tells whether the main or the sub 2D engine should be used (default: sub core).
See also:
TextBuffer::TextLayout
Exceptions:
ConsoleException if the operation failed or is not supported.

Definition at line 150 of file CeylanConsole.cc.

References initConsole(), and setToForeground().

Console::~Console (  )  throw () [virtual]

Virtual destructor.

Definition at line 169 of file CeylanConsole.cc.

References _buffer.

Ceylan::System::Console::Console ( const Console source  )  [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.


Member Function Documentation

void Console::addInBuffer ( const std::string &  text  )  [virtual]

Adds specified text in the character buffer of this console.

Note:
Does not render anything, just stores the text.
Parameters:
text the text to add.
Exceptions:
ConsoleException if the operation failed.

Definition at line 390 of file CeylanConsole.cc.

References _buffer, Ceylan::TextBuffer::add(), and render().

Referenced by goInteractive(), Ceylan::Log::LogAggregatorConsole::write(), and Ceylan::Log::LogAggregatorConsole::~LogAggregatorConsole().

void Console::blankBuffer (  )  [virtual]

Blanks the character buffer of this console.

Exceptions:
ConsoleException if the operation failed.

Definition at line 402 of file CeylanConsole.cc.

References _buffer, and Ceylan::TextBuffer::blank().

Referenced by Ceylan::Log::LogAggregatorConsole::~LogAggregatorConsole().

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat (  )  [static, inherited]

Ceylan::TextBuffer::TextLayout Console::getTextLayout (  )  const [virtual]

Returns the text layout being currently used.

Definition at line 281 of file CeylanConsole.cc.

References _buffer, and Ceylan::TextBuffer::getTextLayout().

Referenced by goInteractive().

void Console::goInteractive (  )  [virtual]

Sets the console to foreground if needed, render its text and enter its event loop so that the user can use the keys to browse its content.

Key controls are:

  • button X: go to previous paragraph
  • button B: go to next paragraph
  • button up: go to previous line
  • button down: go to next line
  • button Y: toggle text layout (raw/justified/word-wrapped)
  • button A: quit

Exceptions:
ConsoleException if the operation failed.

Definition at line 196 of file CeylanConsole.cc.

References addInBuffer(), generalUtils::false, Ceylan::getChar(), getTextLayout(), jumpNextLine(), jumpNextText(), jumpPreviousLine(), jumpPreviousText(), Ceylan::TextBuffer::Justified, Ceylan::TextBuffer::Raw, setTextLayout(), setToForeground(), generalUtils::true, and Ceylan::TextBuffer::WordWrapped.

Referenced by Ceylan::Log::LogAggregatorConsole::~LogAggregatorConsole().

void Console::initConsole ( TextBuffer::CharAbscissa  startingX,
TextBuffer::CharOrdinate  startingY,
TextBuffer::CharAbscissa  width,
TextBuffer::CharOrdinate  height,
TextBuffer::TextLayout  layout,
bool  useBottomScreen = true,
bool  useSubCore = true 
) [protected, virtual]

Initializes a console, used by constructors.

Exceptions:
ConsoleException if the operation failed or is not supported.
Parameters:
useBottomScreen tells whether the bottom or the top physical screen should be used (default: bottom screen).
useSubCore tells whether the main or the sub 2D engine should be used (default: sub core).
Exceptions:
ConsoleException if the operation failed.

Definition at line 665 of file CeylanConsole.cc.

References _buffer, _useBottomScreen, _useSubCore, _xstart, _ystart, CEYLAN_CONSOLE_LOG, and SetKeyRepeat().

Referenced by Console().

void Console::Initialize ( bool  useBottomScreen = true,
bool  useSubCore = true,
bool  force = false 
) [static]

Initializes the console for text output, with as little side-effects as possible.

After that call, Ceylan::display can be used.

This method performs action only on the ARM9 of the Nintendo DS.

Parameters:
useBottomScreen tells whether the bottom or the top physical screen should be used (default: bottom screen).
useSubCore tells whether the main or the sub 2D engine should be used (default: sub core).
force tells whether the initialization is to be performed unconditionally (if true) or if we should rely on the memory of this method (if false; rendering settings may have been modified outside of this method, thus without it knowing about them). Default is to rely on the method memory.
Exceptions:
ConsoleException if the operation failed.

Definition at line 566 of file CeylanConsole.cc.

References generalUtils::false, and generalUtils::true.

Referenced by setToForeground().

bool Console::jumpNextLine (  )  [virtual]

Offsets the console display text of one line to the bottom.

Does nothing if there is no line left.

Returns:
true iff there was a line left indeed.

Definition at line 352 of file CeylanConsole.cc.

References _buffer, generalUtils::false, Ceylan::TextBuffer::jumpNextLine(), render(), and generalUtils::true.

Referenced by goInteractive().

bool Console::jumpNextText (  )  [virtual]

Makes the console display next text on top.

Does nothing if there is no text left.

Returns:
true iff there was a text left indeed.

Definition at line 314 of file CeylanConsole.cc.

References _buffer, generalUtils::false, Ceylan::TextBuffer::jumpNextText(), render(), and generalUtils::true.

Referenced by goInteractive().

bool Console::jumpPreviousLine (  )  [virtual]

Offsets the console display text of one line to the bottom.

Does nothing if there is no line left.

Returns:
true iff there was a line left indeed.

Definition at line 371 of file CeylanConsole.cc.

References _buffer, generalUtils::false, Ceylan::TextBuffer::jumpPreviousLine(), render(), and generalUtils::true.

Referenced by goInteractive().

bool Console::jumpPreviousText (  )  [virtual]

Makes the console display previous text on top.

Does nothing if there is no text left.

Returns:
true iff there was a prior text indeed.

Definition at line 333 of file CeylanConsole.cc.

References _buffer, generalUtils::false, Ceylan::TextBuffer::jumpPreviousText(), render(), and generalUtils::true.

Referenced by goInteractive().

Console& Ceylan::System::Console::operator= ( const Console source  )  [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void Console::render (  )  [virtual]

Renders in console output the current text of its character buffer.

Exceptions:
ConsoleException if the operation failed.

Definition at line 442 of file CeylanConsole.cc.

References _buffer, _inForeground, Ceylan::TextBuffer::getScreenLines(), and Ceylan::TextBuffer::getWidth().

Referenced by addInBuffer(), jumpNextLine(), jumpNextText(), jumpPreviousLine(), jumpPreviousText(), and setTextLayout().

void Console::SetKeyRepeat ( Millisecond  durationBeforeFirstRepeat = 300,
Millisecond  durationBetweenRepeats = 100 
) [static]

Sets for the console the key repeat settings.

Parameters:
durationBeforeFirstRepeat duration in milliseconds before, once a key is help, it starts repeating.
durationBetweenRepeats duration in milliseconds before two key repeats are triggered, once they are repeating.
Exceptions:
ConsoleException if the key repeat could not be set.

Definition at line 522 of file CeylanConsole.cc.

Referenced by initConsole().

void TextDisplayable::SetOutputFormat ( TextOutputFormat  newOutputFormat  )  [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:
newOutputFormat the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

void Console::setTextLayout ( TextBuffer::TextLayout  newLayout  )  [virtual]

Sets a new text layout.

Triggers an update of the preformatted text.

Parameters:
newLayout the new layout to be used from now on.
Exceptions:
ConsoleException if the operation failed.

Definition at line 290 of file CeylanConsole.cc.

References _buffer, dataUtils::e, render(), Ceylan::TextBuffer::setTextLayout(), and Ceylan::Exception::toString().

Referenced by goInteractive().

void Console::setToForeground ( bool  toForeground = true  )  [virtual]

Sets the console either in the foreground (hence using the screen and the keys), or in the background (not using them).

Parameters:
toForeground sets the console to foreground iff true.
Note:
On transition from foreground to background, do not change the video or input settings, the caller is expected to set them as wished after the call.
Exceptions:
ConsoleException if the operation failed.

Definition at line 413 of file CeylanConsole.cc.

References _inForeground, _useBottomScreen, _useSubCore, generalUtils::false, Initialize(), and generalUtils::true.

Referenced by Console(), goInteractive(), and Ceylan::Log::LogAggregatorConsole::LogAggregatorConsole().

const std::string TextDisplayable::ToString ( std::list< TextDisplayable * >  displayables,
Ceylan::VerbosityLevels  level = Ceylan::high 
) [static, inherited]

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:
displayables a list of pointers to TextDisplayable instances/
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const std::string Console::toString ( Ceylan::VerbosityLevels  level = Ceylan::high  )  const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
TextDisplayable

Implements Ceylan::TextDisplayable.

Definition at line 504 of file CeylanConsole.cc.

References _buffer, _xstart, _ystart, Ceylan::toNumericalString(), and Ceylan::TextBuffer::toString().


Member Data Documentation

Tells whether the console is in interactive mode or hidden from the user.

Definition at line 521 of file CeylanConsole.h.

Referenced by render(), and setToForeground().

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:
Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

Tells whether any bottom screen should be used.

Definition at line 525 of file CeylanConsole.h.

Referenced by initConsole(), and setToForeground().

Tells whether any sub rendering core should be used.

Definition at line 529 of file CeylanConsole.h.

Referenced by initConsole(), and setToForeground().

Definition at line 505 of file CeylanConsole.h.

Referenced by initConsole(), and toString().

Definition at line 507 of file CeylanConsole.h.

Referenced by initConsole(), and toString().

const char *const Console::Blinking = "\033[5m" [static]

Definition at line 465 of file CeylanConsole.h.

const char *const Console::BlinkingOff = "\033[25m" [static]

Definition at line 466 of file CeylanConsole.h.

const char *const Console::Bold = "\033[1m" [static]

Definition at line 458 of file CeylanConsole.h.

const char *const Console::BoldAndFaintOff = "\033[22m" [static]

Definition at line 460 of file CeylanConsole.h.

const char *const Console::DefaultColors = "\033[0m" [static]

Definition at line 456 of file CeylanConsole.h.

const char *const Console::Faint = "\033[2m" [static]

Definition at line 459 of file CeylanConsole.h.

const char *const Console::InvisibleImage = "\033[8m" [static]

Definition at line 471 of file CeylanConsole.h.

const char *const Console::InvisibleImageOff = "\033[28m" [static]

Definition at line 472 of file CeylanConsole.h.

const char *const Console::NegativeImage = "\033[7m" [static]

Definition at line 468 of file CeylanConsole.h.

const char *const Console::NegativeImageOff = "\033[27m" [static]

Definition at line 469 of file CeylanConsole.h.

const char *const Console::Underline = "\033[4m" [static]

Definition at line 462 of file CeylanConsole.h.

const char *const Console::UnderlineOff = "\033[24m" [static]

Definition at line 463 of file CeylanConsole.h.

Use this constant when terminal supports unlimited height (i.e.

performs line-scrolling).

Definition at line 80 of file CeylanConsole.h.

Use this constant when terminal supports unlimited width (i.e.

performs line-wrapping).

Definition at line 71 of file CeylanConsole.h.


The documentation for this class was generated from the following files:

Generated on Thu Jun 4 20:40:46 2009 for Ceylan by  doxygen 1.5.8