Document the nmstermio modules

modified:   src/nmstermio.c
	modified:   src/nmstermio_ncurses.c
This commit is contained in:
Brian Barto 2017-01-20 14:35:00 -05:00
parent 08957b766c
commit 4b79262cf2
2 changed files with 127 additions and 36 deletions

View File

@ -5,6 +5,12 @@
* under the terms of the MIT License. See LICENSE for more details.
*/
/*
* The nmstermio modules implements the terminal interface used by the
* nmseffect module. All terminal IO functionality is defined and
* implemented here.
*/
#include <stdio.h>
#include <string.h>
#include <time.h>
@ -37,14 +43,19 @@
#define COLOR_CYAN 6
#define COLOR_WHITE 7
// Static settings
// Terminal IO settings
static int clearScr = 0; // clearScr flag
static int foregroundColor = COLOR_BLUE; // Foreground color setting
// Function prototypes
static void nmstermio_set_terminal(int);
// Initialize terminal window
/*
* Initialize and configure the terminal for output. This usually means
* just turning off terminal echo and line buffering. If the clearScr
* flag is set, it will also save the state of the cursor and screen (so
* it can be restored) and then clear it.
*/
void nmstermio_init_terminal(void) {
// Turn off line buffering and echo
@ -60,6 +71,12 @@ void nmstermio_init_terminal(void) {
}
}
/*
* Restore the state of the terminal to the state prior to executing
* nmstermio_init_terminal(). This usually means turning on line buffering
* and echo. If the clearScr flag is set, it will also restore the
* terminal content and cursor position.
*/
void nmstermio_restore_terminal(void) {
// Restore screen and cursor is clearSrc is set
@ -74,8 +91,7 @@ void nmstermio_restore_terminal(void) {
}
/*
* Gets and returns the number of rows in the current
* terminal window.
* Get and return the number of rows in the current terminal window.
*/
int nmstermio_get_rows(void) {
struct winsize w;
@ -85,8 +101,7 @@ int nmstermio_get_rows(void) {
}
/*
* Gets and returns the number of cols in the current
* terminal window.
* Get and return the number of cols in the current terminal window.
*/
int nmstermio_get_cols(void) {
struct winsize w;
@ -95,18 +110,32 @@ int nmstermio_get_cols(void) {
return w.ws_col;
}
/*
* Move terminal cursor to the given x/y coordinates.
*/
void nmstermio_move_cursor(int y, int x) {
CURSOR_MOVE(y, x);
}
/*
* Print the given character string to the terminal output.
*/
void nmstermio_print_string(char *s) {
printf("%s", s);
}
/*
* Refresh the screen. Display all pending output that has not been
* displayed yet.
*/
void nmstermio_refresh(void) {
fflush(stdout);
}
/*
* Clear all input pending in STDIN. This is used prior to getting user
* input to clear the input queue in case of any prior errant keystrokes.
*/
void nmstermio_clear_input(void) {
int i;
@ -117,6 +146,11 @@ void nmstermio_clear_input(void) {
}
}
/*
* Get a single character of input from the user. Given that line buffering
* is turned off, we must constantly loop until we get a character other
* than EOF.
*/
char nmstermio_get_char(void) {
struct timespec ts;
int t = 50;
@ -132,6 +166,11 @@ char nmstermio_get_char(void) {
return c;
}
/*
* Print the character string that represents the decrypted data. We
* apply the bold and color attributes (if colorOn flag is set) to this
* string.
*/
void nmstermio_print_reveal_string(char *s, int colorOn) {
// Set bold and foreground color
@ -147,21 +186,31 @@ void nmstermio_print_reveal_string(char *s, int colorOn) {
CLEAR_ATTR();
}
/*
* Display the cursor that have been turned off by nmstermio_init_terminal().
*/
void nmstermio_show_cursor(void) {
CURSOR_SHOW();
}
/*
* Make the terminal beep. Used when the returnOpts setting is set in the
* nmseffect module.
*/
void nmstermio_beep(void) {
BEEP();
}
/*
* Return the status of the clearScr flag. This is used by the nmseffect
* module to make certain decisions based on its value.
*/
int nmstermio_get_clearscr(void) {
return clearScr;
}
/*
* Sets the clearScr flag according to the
* true/false value of the 's' argument.
* Sets the clearScr flag according to the true/false value of the 's' argument.
*/
void nmstermio_set_clearscr(int s) {
if (s)
@ -171,11 +220,9 @@ void nmstermio_set_clearscr(int s) {
}
/*
* Sets the foreground color of the unencrypted
* characters as they are revealed to the color indicated by the 'color'
* argument. Valid arguments are "white", "yellow", "magenta", "blue",
* "green", "red", and "cyan". This function will default to blue if
* passed an invalid color. No value is returned.
* Set the desired foreground color of the unencrypted characters as they
* are revealed by nmstermio_print_reveal_string(). Valid arguments are
* "white", "yellow", "magenta", "blue", "green", "red", and "cyan".
*/
void nmstermio_set_foregroundcolor(char *c) {
@ -200,8 +247,9 @@ void nmstermio_set_foregroundcolor(char *c) {
}
/*
* Returns the row position of the cursor as reported
* by the terminal program via the ANSI escape code
* Get and returns the current row position of the cursor. This involves
* sending the appropriate ANSI escape code to the terminal and
* reading/parsing its response.
*/
int nmstermio_get_cursor_row(void) {
int i, r = 0;
@ -233,10 +281,9 @@ int nmstermio_get_cursor_row(void) {
}
/*
* Turns off terminal echo and line buffering when
* passed an integer value that evaluates to true. It restores the
* original terminal values when passed an integer value that evaluates
* to false.
* Turn off terminal echo and line buffering when passed an integer value
* that evaluates to true. Restore the original terminal values when passed
* an integer value that evaluates to false.
*/
static void nmstermio_set_terminal(int s) {
struct termios tp;

View File

@ -5,6 +5,12 @@
* under the terms of the MIT License. See LICENSE for more details.
*/
/*
* The nmstermio_ncurses modules implements the terminal interface, with
* ncurses support, used by the nmseffect module. All terminal IO
* functionality is defined and implemented here.
*/
#include <string.h>
#include <ncurses.h>
@ -12,7 +18,12 @@
static int clearScr = 1; // clearScr flag
static int foregroundColor = COLOR_BLUE; // Foreground color setting
// Initialize terminal window
/*
* Initialize and configure the terminal for output. This usually means
* just turning off terminal echo, line buffering, and clearing the screen.
* Note that ncurses always clears the screen, so there is no option to do
* otherwise.
*/
void nmstermio_init_terminal(void) {
initscr();
cbreak();
@ -25,53 +36,71 @@ void nmstermio_init_terminal(void) {
}
}
/*
* Restore the state of the terminal to the state prior to executing
* nmstermio_init_terminal(). This usually means turning on line buffering,
* echo, and terminal contents.
*/
void nmstermio_restore_terminal(void) {
endwin();
}
/*
* Gets and returns the number of rows in the current
* terminal window.
* Get and return the number of rows in the current terminal window.
*/
int nmstermio_get_rows(void) {
return getmaxy(stdscr);
}
/*
* Gets and returns the number of cols in the current
* terminal window.
* Get and return the number of cols in the current terminal window.
*/
int nmstermio_get_cols(void) {
return getmaxx(stdscr);
}
/*
* Returns the row position of the cursor
* Move terminal cursor to the given x/y coordinates.
*/
int nmstermio_get_cursor_row(void) {
return getcury(stdscr);
}
void nmstermio_move_cursor(int y, int x) {
move(y, x);
}
/*
* Print the given character string to the terminal output.
*/
void nmstermio_print_string(char *s) {
addstr(s);
}
/*
* Refresh the screen. Display all pending output that has not been
* displayed yet.
*/
void nmstermio_refresh(void) {
refresh();
}
/*
* Clear all input pending in STDIN. This is used prior to getting user
* input to clear the input queue in case of any prior errant keystrokes.
*/
void nmstermio_clear_input(void) {
flushinp();
}
/*
* Get a single character of input from the user.
*/
void nmstermio_get_char(void) {
getch();
}
/*
* Print the character string that represents the decrypted data. We
* apply the bold and color attributes (if the terminal supports color)
* to this string.
*/
void nmstermio_print_reveal_string(char *s, int colorOn) {
(void) colorOn;
(void) foregroundColor;
@ -90,22 +119,32 @@ void nmstermio_print_reveal_string(char *s, int colorOn) {
attroff(A_BOLD);
}
/*
* Display the cursor that have been turned off by nmstermio_init_terminal().
*/
void nmstermio_show_cursor(void) {
curs_set(1);
refresh();
}
/*
* Make the terminal beep. Used when the returnOpts setting is set in the
* nmseffect module.
*/
void nmstermio_beep(void) {
beep();
}
/*
* Return the status of the clearScr flag. This is used by the nmseffect
* module to make certain decisions based on its value.
*/
int nmstermio_get_clearscr(void) {
return clearScr;
}
/*
* Sets the clearScr flag according to the
* true/false value of the 's' argument.
* Sets the clearScr flag according to the true/false value of the 's' argument.
*/
void nmstermio_set_clearscr(int s) {
if (s)
@ -115,11 +154,9 @@ void nmstermio_set_clearscr(int s) {
}
/*
* Sets the foreground color of the unencrypted
* characters as they are revealed to the color indicated by the 'color'
* argument. Valid arguments are "white", "yellow", "magenta", "blue",
* "green", "red", and "cyan". This function will default to blue if
* passed an invalid color. No value is returned.
* Set the desired foreground color of the unencrypted characters as they
* are revealed by nmstermio_print_reveal_string(). Valid arguments are
* "white", "yellow", "magenta", "blue", "green", "red", and "cyan".
*/
void nmstermio_set_foregroundcolor(char *c) {
@ -142,3 +179,10 @@ void nmstermio_set_foregroundcolor(char *c) {
else
foregroundColor = COLOR_BLUE;
}
/*
* Get and returns the current row position of the cursor.
*/
int nmstermio_get_cursor_row(void) {
return getcury(stdscr);
}