diff --git a/src/intf.c b/src/intf.c index 450ff8c..5b2b9a7 100644 --- a/src/intf.c +++ b/src/intf.c @@ -32,7 +32,7 @@ /************************************************************************ -* Module constants and type declarations * +* Module-specific constants and type declarations * ************************************************************************/ typedef struct txwin { @@ -51,7 +51,7 @@ bool use_color = false; // True to use colour in Star Traders /************************************************************************ -* Module variables * +* Module-specific variables * ************************************************************************/ txwin_t *topwin = NULL; // Top-most txwin structure @@ -62,29 +62,24 @@ txwin_t *firstwin = NULL; // First (bottom-most) txwin structure * Basic text input/output function definitions * ************************************************************************/ -/*----------------------------------------------------------------------- - Function: init_screen - Initialise the screen (terminal) - Arguments: (none) - Returns: (nothing) +// These functions are documented in the file "intf.h" - This function initialises the input (keyboard) and output (screen) - using the Curses library. -*/ + +/***********************************************************************/ +// init_screen: Initialise the screen (terminal display) void init_screen (void) { - int i; - - initscr(); - if ((COLS < MIN_COLS) || (LINES < MIN_LINES)) { + if (COLS < MIN_COLS || LINES < MIN_LINES) { err_exit("terminal size is too small (%d x %d required)", MIN_COLS, MIN_LINES); } use_color = ! option_no_color && has_colors(); + // Initialise variables controlling the stack of windows curwin = stdscr; topwin = NULL; firstwin = NULL; @@ -93,6 +88,7 @@ void init_screen (void) curs_set(CURS_OFF); raw(); + // Initialise all colour pairs used; see intf.h for more comments if (use_color) { start_color(); @@ -113,9 +109,11 @@ void init_screen (void) clear(); - for (i = 0; i < COLS; i++) { - mvwaddch(stdscr, 0, i, ATTR_GAME_TITLE | ' '); + move(0, 0); + for (int i = 0; i < COLS; i++) { + addch(ATTR_GAME_TITLE | ' '); } + center(stdscr, 0, ATTR_GAME_TITLE, PACKAGE_NAME); attrset(ATTR_ROOT_WINDOW); @@ -123,14 +121,8 @@ void init_screen (void) } -/*----------------------------------------------------------------------- - Function: end_screen - End using the screen (terminal) - Arguments: (none) - Returns: (nothing) - - This function closes the input (keyboard) and output (screen) using the - Curses library. It makes sure the screen is cleared before doing so. -*/ +/***********************************************************************/ +// end_screen: Deinitialise the screen (terminal display) void end_screen (void) { @@ -141,48 +133,35 @@ void end_screen (void) endwin(); curwin = NULL; + topwin = NULL; + firstwin = NULL; } -/************************************************************************ -* Simplified panel-like window functions * -************************************************************************/ - -/*----------------------------------------------------------------------- - Function: newtxwin - Create a new window, inserted into window stack - Arguments: nlines - Number of lines in new window - ncols - Number of columns in new window - begin_y - Starting line number (global coordinates) - begin_x - Starting column number (global coordinates) - draw_bkgd_box - True to draw background and box frame - bkgd_attr - Background attribute - Returns: WINDOW * - Pointer to new window structure - - This function creates a window (using the Curses newwin() function) and - places it top-most in the stack of windows managed by this module. A - pointer to the new window is returned; the global variable "curwin" - also points to this new window. Please note that wrefresh() is NOT - called on the new window. -*/ +/***********************************************************************/ +// newtxwin: Create a new window, inserted into window stack WINDOW *newtxwin (int nlines, int ncols, int begin_y, int begin_x, - bool draw_bkgd_box, chtype bkgd_attr) + bool dofill, chtype bkgd_attr) { WINDOW *win; txwin_t *nw; + // Create the new window + win = newwin(nlines, ncols, begin_y, begin_x); if (win == NULL) { - return NULL; + err_exit_nomem(); } nw = malloc(sizeof(txwin_t)); if (nw == NULL) { - delwin(win); - return NULL; + err_exit_nomem(); } + // Insert the new window into the txwin stack + nw->win = win; nw->next = NULL; nw->prev = topwin; @@ -198,7 +177,9 @@ WINDOW *newtxwin (int nlines, int ncols, int begin_y, int begin_x, firstwin = nw; } - if (draw_bkgd_box) { + // Paint the background and border, if required + + if (dofill) { wbkgd(win, bkgd_attr); box(win, 0, 0); } @@ -207,17 +188,8 @@ WINDOW *newtxwin (int nlines, int ncols, int begin_y, int begin_x, } -/*----------------------------------------------------------------------- - Function: deltxwin - Delete the top-most window in window stack - Arguments: (none) - Returns: int - OK if all well, ERR if not - - This function deletes the top-most window in the stack of windows - managed by this module. ERR is returned if there is no such window, or - if delwin() fails. Please note that the actual screen is NOT - refreshed: a call to txrefresh() should follow this one. This allows - multiple windows to be deleted without screen flashing. -*/ +/***********************************************************************/ +// deltxwin: Delete the top-most window in the window stack int deltxwin (void) { @@ -229,6 +201,8 @@ int deltxwin (void) return ERR; } + // Remove window from the txwin stack + cur = topwin; prev = topwin->prev; topwin = prev; @@ -248,17 +222,8 @@ int deltxwin (void) } -/*----------------------------------------------------------------------- - Function: delalltxwin - Delete all windows in the window stack - Arguments: (none) - Returns: int - OK is always returned - - This function deletes all windows in the stack of windows managed by - this module. After calling this function, the global variable "curwin" - points to "stdscr", the only window for which output is now permitted. - Please note that the screen is NOT refreshed; a call to txrefresh() - should follow this one if appropriate. -*/ +/***********************************************************************/ +// delalltxwin: Delete all windows in the window stack int delalltxwin (void) { @@ -270,25 +235,15 @@ int delalltxwin (void) } -/*----------------------------------------------------------------------- - Function: txrefresh - Redraw all windows in the window stack - Arguments: (none) - Returns: int - OK if all well, ERR if not - - This function redraws (refreshes) all windows in the stack of windows - managed by this module. Windows are refreshed from bottom (first) to - top (last). The result of doupdate() is returned. -*/ +/***********************************************************************/ +// txrefresh: Redraw all windows in the window stack int txrefresh (void) { - txwin_t *p; - - touchwin(stdscr); wnoutrefresh(stdscr); - for (p = firstwin; p != NULL; p = p->next) { + for (txwin_t *p = firstwin; p != NULL; p = p->next) { touchwin(p->win); wnoutrefresh(p->win); } diff --git a/src/intf.h b/src/intf.h index c927f48..2659963 100644 --- a/src/intf.h +++ b/src/intf.h @@ -183,17 +183,109 @@ extern bool use_color; // True to use colour in Star Traders * Basic text input/output function prototypes * ************************************************************************/ +/* + The functions in this interface create and manage a "stack of windows" + that can overlap. It is similar in spirit to the panels library, but + does not allow windows to be raised or lowered. In spite of this + limitation, these functions are ample for the needs of this program. +*/ + +/* + Function: init_screen - Initialise the screen (terminal display) + Parameters: (none) + Returns: (nothing) + + This function initialises the input keyboard and output terminal + display using the Curses library. It also draws an overall title at + the top with the name of the game. This function must be called before + calling any other functions in this header file. +*/ extern void init_screen (void); + + +/* + Function: end_screen - Deinitialise the screen (terminal display) + Parameters: (none) + Returns: (nothing) + + This function closes the input keyboard and output terminal display. + It makes sure the screen is cleared before doing so. +*/ extern void end_screen (void); -// Simplified panel-like window functions +/* + Function: newtxwin - Create a new window, inserted into window stack + Parameters: nlines - Number of lines in new window + ncols - Number of columns in new window + begin_y - Starting line number (0 to LINES-1) + begin_x - Starting column number (0 to COLS-1) + dofill - True to draw background and box frame + bkgd_attr - Background attribute + Returns: WINDOW * - Pointer to new window + + This function creates a window using the Curses newwin() function and + places it top-most in the stack of windows managed by this module. A + pointer to this new window is returned; the global variable curwin also + points to this new window. Note that begin_y and begin_x are zero- + based global coordinates. If dofill is true, bkgd_attr is used to fill + the background and box(curwin, 0, 0) is called. Note that wrefresh() + is NOT called on the new window. + + If newtxwin() fails to create a new window due to insufficient memory, + this function does NOT return: it terminates the program with an "out + of memory" error message. +*/ extern WINDOW *newtxwin (int nlines, int ncols, int begin_y, int begin_x, - bool draw_bkgd_box, chtype bkgd_attr); + bool dofill, chtype bkgd_attr); + + +/* + Function: deltxwin - Delete the top-most window in the window stack + Parameters: (none) + Returns: int - ERR on failure, OK otherwise + + This function removes the top-most window from the Curses screen and + from the stack managed by this module. ERR is returned if there is no + such window or if the Curses delwin() function fails. + + Note that the actual terminal screen is NOT refreshed: a call to + txrefresh() should follow this one. This allows multiple windows to be + deleted without any annoying screen flashes. +*/ extern int deltxwin (void); + + +/* + Function: delalltxwin - Delete all windows in the window stack + Parameters: (none) + Returns: int - OK is always returned + + This function deletes all windows in the stack of windows managed by + this module. After calling this function, the global variable curwin + will point to stdscr. Note that the actual terminal screen is NOT + refreshed: a call to txrefresh() should follow this one if appropriate. +*/ extern int delalltxwin (void); + + +/* + Function: txrefresh - Redraw all windows in the window stack + Parameters: (none) + Returns: int - Return code from doupdate(): either OK or ERR + + This function redraws (refreshes) all windows in the stack of windows + managed by this module. Windows are refreshed from bottom (first) to + top (last). The result of doupdate() is returned. + + Normal window output does not require calling txrefresh(): a call to + wrefresh(curwin) is sufficient. However, once a window has been + deleted with deltxwin() (or all windows with delalltxwin()), windows + under that one will need refreshing by calling txrefresh(). +*/ extern int txrefresh (void); + // Output routines extern int center (WINDOW *win, int y, int attr, const char *format, ...)