rlutil.h

Summary

rlutil.h
Description	This file provides some useful utilities for console mode roguelike game development with C and C++.
Copyright	© 2010 Tapio Vierros
Licensing	See License
Macros
RLUTIL_USE_ANSI	Define this to use ANSI escape sequences also on Windows (defaults to using WinAPI instead).
RLUTIL_STRING_T	Define/typedef this to your preference to override rlutil’s string type.
Functions
getch	Get character without waiting for Return to be pressed.
kbhit	Determines if keyboard has been hit.
gotoxy	Same as rlutil.locate.
rlutil	In C++ all functions except getch, kbhit and gotoxy are arranged under namespace rlutil.
Macros
Internal typedefs and macros
Enumerations and Constants
Color codes
ANSI escape strings
Key codes for keyhit()
Functions
getkey	Reads a key press (blocking) and returns a key code.
nb_getch	Non-blocking getch().
getANSIColor	Return ANSI color escape sequence for specified number 0-15.
getANSIBackgroundColor	Return ANSI background color escape sequence for specified number 0-15.
setColor	Change color specified by number (Windows / QBasic colors).
setBackgroundColor	Change background color specified by number (Windows / QBasic colors).
saveDefaultColor	Call once to preserve colors for use in resetColor() on Windows without ANSI, no-op otherwise
resetColor	Reset color to default Requires a call to saveDefaultColor() to set the defaults
cls	Clears screen, resets all attributes and moves cursor home.
locate	Sets the cursor position to 1-based x,y.
setChar	Sets the character at the cursor without advancing the cursor
hidecursor	Hides the cursor.
showcursor	Shows the cursor.
msleep	Waits given number of milliseconds before continuing.
trows	Get the number of rows in the terminal window or -1 on error.
tcols	Get the number of columns in the terminal window or -1 on error.
anykey	Waits until a key is pressed.
min	Returns the lesser of the two arguments.
max	Returns the greater of the two arguments.
CursorHider	RAII OOP wrapper for rlutil.hidecursor.

Description

This file provides some useful utilities for console mode roguelike game development with C and C++. It is aimed to be cross-platform (at least Windows and Linux).

Copyright

Licensing

See License

Macros

RLUTIL_USE_ANSI

Define this to use ANSI escape sequences also on Windows (defaults to using WinAPI instead).

RLUTIL_STRING_T

Define/typedef this to your preference to override rlutil’s string type.

Defaults to std::string with C++ and char* with C.

Functions

getch

RLUTIL_INLINE int getch( void )

Get character without waiting for Return to be pressed. Windows has this in conio.h

kbhit

RLUTIL_INLINE int kbhit( void )

Determines if keyboard has been hit. Windows has this in conio.h

gotoxy

RLUTIL_INLINE void gotoxy( int x,
int y )

Same as rlutil.locate.

rlutil

namespace rlutil

In C++ all functions except getch, kbhit and gotoxy are arranged under namespace rlutil. That is because some platforms have them defined outside of rlutil.

Summary

Macros
Internal typedefs and macros
Enumerations and Constants
Color codes
ANSI escape strings
Key codes for keyhit()
Functions
getkey	Reads a key press (blocking) and returns a key code.
nb_getch	Non-blocking getch().
getANSIColor	Return ANSI color escape sequence for specified number 0-15.
getANSIBackgroundColor	Return ANSI background color escape sequence for specified number 0-15.
setColor	Change color specified by number (Windows / QBasic colors).
setBackgroundColor	Change background color specified by number (Windows / QBasic colors).
saveDefaultColor	Call once to preserve colors for use in resetColor() on Windows without ANSI, no-op otherwise
resetColor	Reset color to default Requires a call to saveDefaultColor() to set the defaults
cls	Clears screen, resets all attributes and moves cursor home.
locate	Sets the cursor position to 1-based x,y.
setChar	Sets the character at the cursor without advancing the cursor
hidecursor	Hides the cursor.
showcursor	Shows the cursor.
msleep	Waits given number of milliseconds before continuing.
trows	Get the number of rows in the terminal window or -1 on error.
tcols	Get the number of columns in the terminal window or -1 on error.
anykey	Waits until a key is pressed.
min	Returns the lesser of the two arguments.
max	Returns the greater of the two arguments.

Macros

Internal typedefs and macros

RLUTIL_STRING_T	String type depending on which one of C or C++ is used
RLUTIL_PRINT(str)	Printing macro independent of C/C++

Enumerations and Constants

Color codes

BLACK	Black
BLUE	Blue
GREEN	Green
CYAN	Cyan
RED	Red
MAGENTA	Magenta / purple
BROWN	Brown / dark yellow
GREY	Grey / dark white
DARKGREY	Dark grey / light black
LIGHTBLUE	Light blue
LIGHTGREEN	Light green
LIGHTCYAN	Light cyan
LIGHTRED	Light red
LIGHTMAGENTA	Light magenta / light purple
YELLOW	Yellow (bright)
WHITE	White (bright)

ANSI escape strings

ANSI_CLS	Clears screen
ANSI_ATTRIBUTE_RESET	Resets all attributes
ANSI_CURSOR_HIDE	Hides the cursor
ANSI_CURSOR_SHOW	Shows the cursor
ANSI_CURSOR_HOME	Moves the cursor home (0,0)
ANSI_BLACK	Black
ANSI_RED	Red
ANSI_GREEN	Green
ANSI_BROWN	Brown / dark yellow
ANSI_BLUE	Blue
ANSI_MAGENTA	Magenta / purple
ANSI_CYAN	Cyan
ANSI_GREY	Grey / dark white
ANSI_DARKGREY	Dark grey / light black
ANSI_LIGHTRED	Light red
ANSI_LIGHTGREEN	Light green
ANSI_YELLOW	Yellow (bright)
ANSI_LIGHTBLUE	Light blue
ANSI_LIGHTMAGENTA	Light magenta / light purple
ANSI_LIGHTCYAN	Light cyan
ANSI_WHITE	White (bright)
ANSI_BACKGROUND_BLACK	Black background
ANSI_BACKGROUND_RED	Red background
ANSI_BACKGROUND_GREEN	Green background
ANSI_BACKGROUND_YELLOW	Yellow background
ANSI_BACKGROUND_BLUE	Blue background
ANSI_BACKGROUND_MAGENTA	Magenta / purple background
ANSI_BACKGROUND_CYAN	Cyan background
ANSI_BACKGROUND_WHITE	White background

Key codes for keyhit()

KEY_ESCAPE	Escape
KEY_ENTER	Enter
KEY_SPACE	Space
KEY_INSERT	Insert
KEY_HOME	Home
KEY_END	End
KEY_DELETE	Delete
KEY_PGUP	PageUp
KEY_PGDOWN	PageDown
KEY_UP	Up arrow
KEY_DOWN	Down arrow
KEY_LEFT	Left arrow
KEY_RIGHT	Right arrow
KEY_F1	F1
KEY_F2	F2
KEY_F3	F3
KEY_F4	F4
KEY_F5	F5
KEY_F6	F6
KEY_F7	F7
KEY_F8	F8
KEY_F9	F9
KEY_F10	F10
KEY_F11	F11
KEY_F12	F12
KEY_NUMDEL	Numpad del
KEY_NUMPAD0	Numpad 0
KEY_NUMPAD1	Numpad 1
KEY_NUMPAD2	Numpad 2
KEY_NUMPAD3	Numpad 3
KEY_NUMPAD4	Numpad 4
KEY_NUMPAD5	Numpad 5
KEY_NUMPAD6	Numpad 6
KEY_NUMPAD7	Numpad 7
KEY_NUMPAD8	Numpad 8
KEY_NUMPAD9	Numpad 9

Functions

getkey

RLUTIL_INLINE int getkey( void )

Reads a key press (blocking) and returns a key code.

See Key codes for keyhit()

Note

Only Arrows, Esc, Enter and Space are currently working properly.

nb_getch

RLUTIL_INLINE int nb_getch( void )

Non-blocking getch(). Returns 0 if no key was pressed.

getANSIColor

RLUTIL_INLINE RLUTIL_STRING_T getANSIColor( const int c )

Return ANSI color escape sequence for specified number 0-15.

See Color Codes

getANSIBackgroundColor

RLUTIL_INLINE RLUTIL_STRING_T getANSIBackgroundColor( const int c )

Return ANSI background color escape sequence for specified number 0-15.

See Color Codes

setColor

RLUTIL_INLINE void setColor( int c )

Change color specified by number (Windows / QBasic colors). Don’t change the background color

See Color Codes

setBackgroundColor

RLUTIL_INLINE void setBackgroundColor( int c )

Change background color specified by number (Windows / QBasic colors). Don’t change the foreground color

See Color Codes

saveDefaultColor

RLUTIL_INLINE int saveDefaultColor()

Call once to preserve colors for use in resetColor() on Windows without ANSI, no-op otherwise

See Color Codes See resetColor

resetColor

RLUTIL_INLINE void resetColor()

Reset color to default Requires a call to saveDefaultColor() to set the defaults

See Color Codes See setColor See saveDefaultColor

cls

RLUTIL_INLINE void cls( void )

Clears screen, resets all attributes and moves cursor home.

locate

RLUTIL_INLINE void locate( int x,
int y )

Sets the cursor position to 1-based x,y.

setChar

RLUTIL_INLINE void setChar( char ch )

Sets the character at the cursor without advancing the cursor

hidecursor

RLUTIL_INLINE void hidecursor( void )

Hides the cursor.

showcursor

RLUTIL_INLINE void showcursor( void )

Shows the cursor.

msleep

RLUTIL_INLINE void msleep( unsigned int ms )

Waits given number of milliseconds before continuing.

trows

RLUTIL_INLINE int trows( void )

Get the number of rows in the terminal window or -1 on error.

tcols

RLUTIL_INLINE int tcols( void )

Get the number of columns in the terminal window or -1 on error.

anykey

#ifdef __cplusplus RLUTIL_INLINE void anykey()

Waits until a key is pressed. In C++, it either takes no arguments or a template-type-argument-deduced argument. In C, it takes a const char* representing the message to be displayed, or NULL for no message.

min

#ifdef __cplusplus template <class T> const T& min ( const T & a,
const T & b )

Returns the lesser of the two arguments.

max

#ifdef __cplusplus template <class T> const T& max ( const T & a,
const T & b )

Returns the greater of the two arguments.

CursorHider

struct CursorHider

RAII OOP wrapper for rlutil.hidecursor. Hides the cursor and shows it again when the object goes out of scope.