---

GNE::Console Namespace Reference
[Console API]

Compounds
class	ConsoleManipulator
class	ConsoleMutex
class	ginbuf
class	GOut
	The class for GNE::Console::gout. More...
class	goutbuf
class	moveTo
class	TextConsole
Functions
GOut	gout (&outbuf)
std::istream	gin (&inbuf)
bool	initConsole (bool clearOnExit)
	Initalizes the console part of GNE.
bool	initConsole (int(*)(void(*)(void)))
void	shutdownConsole ()
	Shuts down the console part of GNE.
void	mclearConsole ()
	Clears the console screen.
int	kbhit ()
	Returns non-zero if a key is waiting in the buffer to be received by getch.
int	getch ()
	Returns the next character in the input, blocking if no character is ready to be returned.
int	mprintf (const char *format,...)
	Function to sync on printf.
int	mlprintf (int x, int y, const char *format,...)
	Function to sync on printf, and print to a certain location.
void	mputchar (int ch)
	A syncronized version of the ANSI function putchar.
void	mlputchar (int x, int y, int ch)
	Like mputchar(), but with a specified location.
int	lgetString (int x, int y, char *str, int maxlen)
	Gets input from the console.
int	getString (char *str, int maxlen)
	Same as lgetString(int, int, char*, int), but uses the current cursor position as obtained from mgetpos for the positions.
void	setTitle (const char *title)
	Sets the title of the console window to the given parameter, where GNE can, and where it makes sense (like Windows).
void	mgetConsoleSize (int *width, int *height)
	Gets the size of the console, in character columns and character rows.
void	mgetPos (int *x, int *y)
	Returns the current position of the cursor.
bool	initConsole (int(*atexit_ptr)(void(*func)(void)))
	Initalizes the console part of GNE.
Variables
ConsoleMutex	acquire (true)
	A manipulator for gout to lock the gout output.
ConsoleMutex	release (false)
	A manipulator to release the gout output.
int	ENTER
	The keycode the enter key gives from getch().
int	BACKSPACE
	The keycode the backspace key gives from getch().
const int	IBUF_LEN = 128
const int	OBUF_LEN = 256
GOut	gout
	An ostream that works after the console part of GNE has been initialized.
std::istream	gin
	Similar thing with gout, but unlike gout, gin does not work in a multithreaded context.

---

Detailed Description

Functions for providing very basic console support, meant for use in the example and test programs, and in console-only servers using GNE. These functions's behavior is undefined when running in a Win32 application (not a Win32 console) project, or in any non-console environment.

Functions that have m prefixed on them mean "multithreaded," because they are thread safe. Functions with l prefixed on them mean "location," because they perform their operations starting at the given coordinates rather than the current cursor location. When one of these functions are called, the cursor is not returned to its original location (so you can't mix mprintf and mlprintf calls well).

The upper-left coordinate of the screen is (0,0). The lower-right coordinate of the window is (width-1,height-1). Use the function getConsoleSize(int*, int*) to find the width and height if possible. Note that the input functions are not thread-safe since there's only one keyboard to be used ;). It is okay, however, to be using the console output functions at the same time you are using the locatable input functions. If you are using the inputfunctions that do not take locations (like getString and gin), you cannot be doing output at the same time, since they will move the cursor's location.

---

Function Documentation

int GNE::Console::getch (   )

Returns the next character in the input, blocking if no character is ready to be returned. You cannot use this call while an lgetstring is being processed, but you can use this while output is being written (getch does not echo to the screen). None of the input routines are thread safe. If you access them from more than one thread at a time then results are undefined. Returns: the next character See also: kbhit lgetString

int GNE::Console::getString (  char *  str, int  maxlen )

Same as lgetString(int, int, char*, int), but uses the current cursor position as obtained from mgetpos for the positions. None of the input routines are thread safe. If you access them from more than one thread at a time then results are undefined. See also: lgetString mgetpos

bool initConsole (  int(*  atexit_ptr)(void(*func)(void))  )

Initalizes the console part of GNE. This may be called multiple times. Returns: true if the console could not be initialized. Deprecated: the atexit pointer is no longer needed or used. This method has the same effect as initConsole( true )

bool GNE::Console::initConsole (  bool  clearOnExit = true  )

Initalizes the console part of GNE. This may be called multiple times. Set the clearOnExit variable to true if after the program is finished the console should clear the screen and move the cursor back to the top. Set to false to preserve the screen contents and cursor position after Console close if possible. Returns: true if the console could not be initialized.

int GNE::Console::kbhit (   )

Returns non-zero if a key is waiting in the buffer to be received by getch. You cannot use this call while an lgetstring is being processed. You can use this function while output is being displayed. None of the input routines are thread safe. If you access them from more than one thread at a time then results are undefined. See also: getch lgetString

int GNE::Console::lgetString (  int  x, int  y, char *  str, int  maxlen )

Gets input from the console. This is a blocking call, because you cannot have multiple inputs at the same time, since there is no way for the user to choose which input to go to. Also when you use this call, no other threads can be using kbhit or getch. It is recommended that only one thread be in charge of input from the console. It is okay, however, to be using the console output functions at the same time you are using this function. When the user presses enter the input is complete. None of the input routines are thread safe. If you access them from more than one thread at a time then results are undefined. Parameters: str  a char* with size maxlen+1 where input will be stored. maxlen  the maximum number of characters the user can input. Returns: the length of the string returned, from 0 <= x <= maxlen See also: kbhit getch

void GNE::Console::mclearConsole (   )

Clears the console screen. The cursor's position remains unchanged after the clear.

void GNE::Console::mgetConsoleSize (  int *  width, int *  height )

Gets the size of the console, in character columns and character rows. If x or y are -1, then the width and height are unable to be determined. The return values for this function may or may not change if the console window is resized. Parameters: width  integer where the number of columns is stored. height  integer where the number of rows is stored.

void GNE::Console::mgetPos (  int *  x, int *  y )

Returns the current position of the cursor. As an "m" prefixed function, this is safe to call from multiple threads, but note that if you are using functions that relocate the cursor at the same time this function is called, the "current position" probably will not be very helpful. It is best used when a single thread is doing console I/O.

int GNE::Console::mlprintf (  int  x, int  y, const char *  format, ...  )

Function to sync on printf, and print to a certain location. Returns: number of characters written. See also: mprintf

int GNE::Console::mprintf (  const char *  format, ...  )

Function to sync on printf. Returns: number of characters written.

void GNE::Console::setTitle (  const char *  title  )

Sets the title of the console window to the given parameter, where GNE can, and where it makes sense (like Windows). If the title cannot be set, this function does nothing. Parameters: title  the new window title

void GNE::Console::shutdownConsole (   )

Shuts down the console part of GNE. This may be called multiple times.

---

Variable Documentation

ConsoleMutex GNE::Console::acquire

A manipulator for gout to lock the gout output. This does not lock other threads from writing with other Console class functions, only for writing with gout. acquire is provided mostly for backwards compatibility, but it is not deprecated. Creating a LockObject object is the prefered method as it is safer. See also: release gout

int GNE::Console::BACKSPACE

The keycode the backspace key gives from getch(). See also: getch

int GNE::Console::ENTER

The keycode the enter key gives from getch(). See also: getch

std::istream GNE::Console::gin

Similar thing with gout, but unlike gout, gin does not work in a multithreaded context. You should use lgetString if you are doing output and input at the same time. See also: gout

GOut GNE::Console::gout

An ostream that works after the console part of GNE has been initialized. Normally cout doesn't work after the console has been initalized. Note if you have redirected stdin or stdout then cout and cin will still work -- just not if they are writing or reading to the screen/keyboard. This is why I opted to create a separate stream from cout and cin. Also, gout is not "quite" thread safe. There is no way to know when you ended, plus the basic_ostream that uses the streambuf may not be thread safe so, use acquire and release like a mutex if you will be using gout from multiple threads. These are not needed if using gout from a single threaded context: gout << acquire << "Hello World!" << x << y << endl << release;

ConsoleMutex GNE::Console::release

A manipulator to release the gout output. release is provided mostly for backwards compatibility, but it is not deprecated. Creating a LockObject object is the prefered method as it is safer. See also: acquire gout

---