[netwatch.git] / include / console.h

/** @file console.h
 *  @brief Function prototypes for the console driver.
 *
 *  This contains the prototypes and global variables for the console
 *  driver
 *
 *  @author Michael Berman (mberman)
 *  @bug No known bugs.
 */

#ifndef _CONSOLE_H
#define _CONSOLE_H

#include <video_defines.h>

/** @brief Prints character ch at the current location
 *         of the cursor.
 *
 *  If the character is a newline ('\n'), the cursor is
 *  be moved to the beginning of the next line (scrolling if necessary).  If
 *  the character is a carriage return ('\r'), the cursor
 *  is immediately reset to the beginning of the current
 *  line, causing any future output to overwrite any existing
 *  output on the line.  If backsapce ('\b') is encountered,
 *  the previous character is erased.  See the main console.c description
 *  for more backspace behavior.
 *
 *  @param ch the character to print
 *  @return The input character
 */
int putbyte( char ch );

/** @brief Prints the string s, starting at the current
 *         location of the cursor.
 *
 *  If the string is longer than the current line, the
 *  string fills up the current line and then
 *  continues on the next line. If the string exceeds
 *  available space on the entire console, the screen
 *  scrolls up one line, and then the string
 *  continues on the new line.  If '\n', '\r', and '\b' are
 *  encountered within the string, they are handled
 *  as per putbyte. If len is not a positive integer or s
 *  is null, the function has no effect.
 *
 *  @param s The string to be printed.
 *  @param len The length of the string s.
 *  @return Void.
 */
void putbytes(const char* s, int len);

/** @brief Changes the foreground and background color
 *         of future characters printed on the console.
 *
 *  If the color code is invalid, the function has no effect.
 *
 *  @param color The new color code.
 *  @return 0 on success or integer error code less than 0 if
 *          color code is invalid.
 */
int set_term_color(int color);

/** @brief Writes the current foreground and background
 *         color of characters printed on the console
 *         into the argument color.
 *  @param color The address to which the current color
 *         information will be written.
 *  @return Void.
 */
void get_term_color(int* color);

/** @brief Sets the position of the cursor to the
 *         position (row, col).
 *
 *  Subsequent calls to putbytes should cause the console
 *  output to begin at the new position. If the cursor is
 *  currently hidden, a call to set_cursor() does not show
 *  the cursor.
 *
 *  @param row The new row for the cursor.
 *  @param col The new column for the cursor.
 *  @return 0 on success or integer error code less than 0 if
 *          cursor location is invalid.
 */
int set_cursor(int row, int col);

/** @brief Writes the current position of the cursor
 *         into the arguments row and col.
 *  @param row The address to which the current cursor
 *         row will be written.
 *  @param col The address to which the current cursor
 *         column will be written.
 *  @return Void.
 */
void get_cursor(int* row, int* col);

/** @brief Hides the cursor.
 *
 *  Subsequent calls to putbytes do not cause the
 *  cursor to show again.
 *
 *  @return Void.
 */
void hide_cursor();

/** @brief Shows the cursor.
 *  
 *  If the cursor is already shown, the function has no effect.
 *
 *  @return Void.
 */
void show_cursor();

/** @brief Clears the entire console.
 *
 * The cursor is reset to the first row and column
 *
 *  @return Void.
 */
void clear_console();

/** @brief Prints character ch with the specified color
 *         at position (row, col).
 *
 *  If any argument is invalid, the function has no effect.
 *
 *  @param row The row in which to display the character.
 *  @param col The column in which to display the character.
 *  @param ch The character to display.
 *  @param color The color to use to display the character.
 *  @return Void.
 */
void draw_char(int row, int col, int ch, int color);

/** @brief Returns the character displayed at position (row, col).
 *  @param row Row of the character.
 *  @param col Column of the character.
 *  @return The character at (row, col).
 */
char get_char(int row, int col);

#endif /* _CONSOLE_H */
Commit	Line	Data
f16f4f1e JW	1	/** @file console.h
	2	* @brief Function prototypes for the console driver.
	3	*
	4	* This contains the prototypes and global variables for the console
	5	* driver
	6	*
	7	* @author Michael Berman (mberman)
	8	* @bug No known bugs.
	9	*/
	10
	11	#ifndef _CONSOLE_H
	12	#define _CONSOLE_H
	13
	14	#include <video_defines.h>
	15
	16	/** @brief Prints character ch at the current location
	17	* of the cursor.
	18	*
	19	* If the character is a newline ('\n'), the cursor is
	20	* be moved to the beginning of the next line (scrolling if necessary). If
	21	* the character is a carriage return ('\r'), the cursor
	22	* is immediately reset to the beginning of the current
	23	* line, causing any future output to overwrite any existing
	24	* output on the line. If backsapce ('\b') is encountered,
	25	* the previous character is erased. See the main console.c description
	26	* for more backspace behavior.
	27	*
	28	* @param ch the character to print
	29	* @return The input character
	30	*/
	31	int putbyte( char ch );
	32
	33	/** @brief Prints the string s, starting at the current
	34	* location of the cursor.
	35	*
	36	* If the string is longer than the current line, the
	37	* string fills up the current line and then
	38	* continues on the next line. If the string exceeds
	39	* available space on the entire console, the screen
	40	* scrolls up one line, and then the string
	41	* continues on the new line. If '\n', '\r', and '\b' are
	42	* encountered within the string, they are handled
	43	* as per putbyte. If len is not a positive integer or s
	44	* is null, the function has no effect.
	45	*
	46	* @param s The string to be printed.
	47	* @param len The length of the string s.
	48	* @return Void.
	49	*/
	50	void putbytes(const char* s, int len);
	51
	52	/** @brief Changes the foreground and background color
	53	* of future characters printed on the console.
	54	*
	55	* If the color code is invalid, the function has no effect.
	56	*
	57	* @param color The new color code.
	58	* @return 0 on success or integer error code less than 0 if
	59	* color code is invalid.
	60	*/
	61	int set_term_color(int color);
	62
	63	/** @brief Writes the current foreground and background
	64	* color of characters printed on the console
65	* into the argument color.
66	* @param color The address to which the current color
67	* information will be written.
68	* @return Void.
69	*/
70	void get_term_color(int* color);
71
72	/** @brief Sets the position of the cursor to the
73	* position (row, col).
74	*
75	* Subsequent calls to putbytes should cause the console
76	* output to begin at the new position. If the cursor is
77	* currently hidden, a call to set_cursor() does not show
78	* the cursor.
79	*
80	* @param row The new row for the cursor.
81	* @param col The new column for the cursor.
82	* @return 0 on success or integer error code less than 0 if
83	* cursor location is invalid.
84	*/
85	int set_cursor(int row, int col);
86
87	/** @brief Writes the current position of the cursor
88	* into the arguments row and col.
89	* @param row The address to which the current cursor
90	* row will be written.
91	* @param col The address to which the current cursor
92	* column will be written.
93	* @return Void.
94	*/
95	void get_cursor(int* row, int* col);
96
97	/** @brief Hides the cursor.
98	*
99	* Subsequent calls to putbytes do not cause the
100	* cursor to show again.
101	*
102	* @return Void.
103	*/
104	void hide_cursor();
105
106	/** @brief Shows the cursor.
107	*
108	* If the cursor is already shown, the function has no effect.
109	*
110	* @return Void.
111	*/
112	void show_cursor();
113
114	/** @brief Clears the entire console.
115	*
116	* The cursor is reset to the first row and column
117	*
118	* @return Void.
119	*/
120	void clear_console();
121
122	/** @brief Prints character ch with the specified color
123	* at position (row, col).
124	*
125	* If any argument is invalid, the function has no effect.
126	*
127	* @param row The row in which to display the character.
128	* @param col The column in which to display the character.
129	* @param ch The character to display.
130	* @param color The color to use to display the character.
131	* @return Void.
132	*/
133	void draw_char(int row, int col, int ch, int color);
134
135	/** @brief Returns the character displayed at position (row, col).
136	* @param row Row of the character.
137	* @param col Column of the character.
138	* @return The character at (row, col).
139	*/
140	char get_char(int row, int col);
141
142	#endif /* _CONSOLE_H */