---

GNE::ConsoleBuffer Class Reference
[Console API]

#include <ConsoleBuffer.h>

Inheritance diagram for GNE::ConsoleBuffer:

List of all members.

Public Types
typedef std::ostream &(*	CBFType )(std::ostream &)
Public Member Functions
void	setContIndent (const std::string &indent)
	Sets the continuation indent for the TextConsole.
void	setAutoRender (bool autoRender)
	Sets auto rendering mode on or off.
int	getXOffset ()
	Returns the x offset.
int	getYOffset ()
	Returns the y offset.
int	getWidth () const
	Returns the current buffer width.
int	getHeight () const
	Returns the current buffer height.
virtual void	erase ()=0
	Tells the renderer for this ConsoleBuffer to completely erase the display.
void	clear ()
	Clears all the text from the console, leaving an empty buffer.
void	redraw ()
	Redraws the console by rerendering all of it.
void	update ()
	Updates the view of this console by having the renderer update the destination device.
template<class T> ConsoleBuffer &	operator<< (const T &rhs)
ConsoleBuffer &	operator<< (const Console::ConsoleMutex &rhs)
ConsoleBuffer &	operator<< (CBFType f)
Protected Member Functions
	ConsoleBuffer (int xoffset, int yoffset, int width, int height, int textHeight)
	Readies a new TextConsole in the inclusive rectangle from (xoffset, yoffset) to (xoffset+width, yoffset+height).
virtual void	render (int x, int y, std::string text, int renderHints)=0
	Asks the renderer to render the data at the specified location.
virtual bool	scroll (int height)
	Tells the renderer that the console is scrolling by the specified height in units.
virtual int	stringWidth (const std::string &str)
	Returns the width of the text in width units.
void	setRequiredDelimiters (const std::string &delims)
	Sets a string of the set of required delimiter characters.
void	addRequiredDelimiters (const std::string &delims)
	Adds the delimiters in the string to the set of required delimiters.
std::string	getRequiredDelimiters ()
	Returns the current set of required delimiter characters.
Static Protected Attributes
const int	REDRAW_HINT = 1

---

Detailed Description

An abstracted Console. A console is defined as a rectangle in units. What a unit is is entirely arbitrary -- it could be characters or pixels or something else.

Essentially, this class abstracts a character (or mostly character) based console that does word-wrapping. A renderer for this buffer would extend this class.

The buffer operates on a single pass -- thus once it writes data, it won't rewrite that data again (assuming the scroll method is supported). The important thing to note about this fact is that the console is therefore "word buffered" meaning you must output a full word before it is shown -- specifically, all text is displayed until the last delimiter element or a newline element.

You won't instantiate a ConsoleBuffer directly, but instead will create a instance of a child class of ConsoleBuffer, like TextConsole.

ConsoleBuffer provides thread-safety in a similar way used for Console::gout. You may use the acquirecb and releasecb objects to acquire or release the buffer when using the insertion operators: cb << acquirecb << "Testing " << 123 << endl << releasecb;

Calling the ConsoleBuffer functions implicitly lock it, so you need not acquire or release the object when calling the functions.

---

Constructor & Destructor Documentation

GNE::ConsoleBuffer::ConsoleBuffer (  int  xoffset, int  yoffset, int  width, int  height, int  textHeight )  [protected]

Readies a new TextConsole in the inclusive rectangle from (xoffset, yoffset) to (xoffset+width, yoffset+height). The TextConsole will not write to the lower right character as not to trigger accidental hardware scrolling on some platforms. The textHeight parameter denotes the height of the text (and therefore the line height).

---

Member Function Documentation

void GNE::ConsoleBuffer::addRequiredDelimiters (  const std::string &  delims  )  [protected]

Adds the delimiters in the string to the set of required delimiters. See also: setRequiredDelimiters

void GNE::ConsoleBuffer::clear (   )

Clears all the text from the console, leaving an empty buffer. Whether auto render is enabled or disabled, erase is called immedately.

virtual void GNE::ConsoleBuffer::erase (   )  [pure virtual]

Tells the renderer for this ConsoleBuffer to completely erase the display. This is different from clear in the fact that erase will "hide" the console. The behavior of calling update, or adding text during auto render mode, before calling redraw or clear is defined by the renderer, but in general if you want to use the console again, you should call either clear or redraw before inserting text. Implemented in GNE::Console::TextConsole.

void GNE::ConsoleBuffer::redraw (   )

Redraws the console by rerendering all of it. This method most useful after a call to erase (but not by one to clear).

virtual void GNE::ConsoleBuffer::render (  int  x, int  y, std::string  text, int  renderHints )  [protected, pure virtual]

Asks the renderer to render the data at the specified location. There will not be newline characters in the text string. The renderHints parameter contains hints for the renderer. At this time the only hint is ConsoleBuffer::REDRAW_HINT, which is set when redrawing to a location. The renderHints field is a bitmask, so use the bitwise and operator to check for hints. Implemented in GNE::Console::TextConsole.

bool GNE::ConsoleBuffer::scroll (  int  height  )  [protected, virtual]

Tells the renderer that the console is scrolling by the specified height in units. If the renderer supports some sort of scrolling scheme, it should invove it. If it can do so, the renderer shall return true, and then only the changed and new lines will be sent to render. If the renderer does not support scrolling, it shall return false. In this case, all lines are resent to the render function, and it will act as a total redraw. The default behaviour is to return false.

void GNE::ConsoleBuffer::setAutoRender (  bool  autoRender  )

Sets auto rendering mode on or off. When auto render mode is enabled, the screen is refreshed immediately whenever an action on the console would change its view on the screen. The default is true.

void GNE::ConsoleBuffer::setContIndent (  const std::string &  indent  )

Sets the continuation indent for the TextConsole. The default value is 2 spaces. When the word wrap wraps a line, the next line will be indented with the given string.

void GNE::ConsoleBuffer::setRequiredDelimiters (  const std::string &  delims  )  [protected]

Sets a string of the set of required delimiter characters. A delimiter character is required if it should always be displayed, and never left out during a word wrap. For example a dash character would be a required delimiter whereas a space is not. The default required delimiter set is a dash. Depending on your preference, you may wish to add characters such as ";." or other puncutation marks. Required delimiters are considered to the be the last part of a word, whereas optional delimiters are considered to be the beginning of the next word (and thus are sent to the renderer as such). The exception to this rule is the newline character. The newline character is always considered a delimiter. It is processed differently and is a required delimiter but treated more like an optional one in the fact that it belongs to the start of the next word, meaning the line is not actually advanced until the next word appears. This is so that there is not always a blank line at the bottom of the console if you use a newline character to end your additions to the console.

int GNE::ConsoleBuffer::stringWidth (  const std::string &  str  )  [protected, virtual]

Returns the width of the text in width units. The default implementation returns simply str.length(), so if the renderer uses a proportional font, or more specifically if any letter has a length greater than 1, the renderer should override this method. The given string may contain any character you insert into the buffer, excluding newline characters.

void GNE::ConsoleBuffer::update (   )

Updates the view of this console by having the renderer update the destination device. If auto render is enabled, calling this method will be a redundant operation.

---

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

• ConsoleBuffer.h
• ConsoleBuffer.cpp

---