SI204: Structs and ncurses

Part 1: ncurses basics (name p1.cpp)

The ncurses library views your terminal window as a big 2D table of single-character positions. So think of coordinates as (row,col) rather than (x,y). This means that (0,0) is the upper left corner of the terminal window. We've made it easy on you by writing a header file called easycurses.h which wraps up the ncurses library main functionality into easy-to-call functions. Download it into your directory. All you need to do is

#include "easycurses.h"

in your .cpp files, and you need to compile with the -l ncurses compiler flag, like:

g++ p1.cpp -l ncurses

Create and compile p1.cpp under your account. This source code demonstrates some simple aspects of ncurses. Here's a few comments:

Initializing Ncurses

startCurses();

This line of code should appear at the point in your main() when you're ready to go into "ncurses mode". When this is executed, the screen goes blank and you are ready to write to arbitrary locations in the terminal window.

Draw a character

drawChar('B', 20, 30);

This draws the char 'B' at position 20,30 in the terminal. How about a pause after you draw? The following sleeps your program for 0.8 seconds:

usleep(800000);     // need: #include <unistd.h>

Exiting Ncurses

// Loop forever until user enters 'q'
char c;
while( (c = inputChar()) && c != 'q' ) {
  // do nothing
}

// Close ncurses
endCurses();

Ncurses (at least as we've initialized it) changes the model for how we read data. You fetch the next character with a call to inputChar(). The funny thing is that this is "non-blocking I/O", which means that you don't hang around and wait for input to come. If you call inputChar() and nobody presses a key, inputChar simply returns immediately with an error code. Contrast this with cin >> c or cin.get(). Thus, this loop just spins waiting for inputChar() to report that the user has pressed q. The endwin() function call is required in order for ncurses to clean up after itself and restore the terminal window.

Part 1b: Debugging

What if we need to use cout for debugging information? Of course we do! Well this is slightly problematic because ncurses now controls the screen. Suppose in the Part1 code we wanted to print out a debugging message "Printed a B!" just after writing the "B". We'd just add the line:

cout << "Printed a B!" << endl;

... immediately after the drawChar('B',20,30). Compile and run that. What you will find is that this message pops up in the middle of our ncurses screen and messes things up. The "C" is no longer printed immediately to the right of the "B". It's a real problem when your debugging messages cause new bugs! So how can we write out debugging messages in an ncurses program?

Use the standard error output stream (cerr) instead of standard out (cout) for the debugging message. This doesn't solve the problem immediately, but it helps. To see how ...
Change your error message(s) to use cerr rather than cout, e.g.
```
cerr << "Printed a B!" << endl;
```
... and run your program like this:
```
~/$ ./a.out 2> err
```
What this does is run your program as usual except that any output written to standard error (cerr) gets "redirected" to the file err, which is created or overwritten each time this is run. Let your program run to completion, then give the command cat err to see what is written.
Now, what you'd really like is to see the debugging output as it happens. Here's how you do that: Open a separate terminal window, cd to the lab directory containing your program and the "err" file, and give the command
```
~/$ tail -f err
```
Go back to your original terminal and type something like this:
```
~/$ echo "whoooooooo" > err
```
You should see the whoooooo pop up in the other terminal. Spooky, eh?
Now run p1 in the original terminal like this:
```
~/$ ./a.out 2> err
```
... and watch as your ncurses window is pure and unblighted by debugging messages, but the message does pop up at the appropriate time in the second window.
What's going on here:
- 2> err is telling the shell to redirect standard error (cerr in our program) output to the file err.
- Meanwhile, tail -f is constantly monitoring the file err, printing out any new lines that get written to the file.
You can keep rerunning, compiling and debugging your program without ever having to rerun tail -f, which is nice.

Part 1c: Making Your Life Easier

Download our rundebug script here.

This automates Part 1b above. The script will open a second debugging terminal for you automatically and then run your a.out program. Just download it, and turn its executable bit on: chmod 755 rundebug

Now instead of running ./a.out you just:

./rundebug a.out

Part 2: coming and going (name p2.cpp)

Write a program from scratch that works as follows:

Before going into ncurses mode, read in input from the user like this
```
4
a (10,15)
x (14,29)
k (5,5)
x (18,37)
```
Start up ncurses.
Draw the objects to the screen.
Pause for a moment.
Erase them from the screen. Erasing an object means writing a ' ' in the appropriate position.
If the user has pressed 'q', terminate the program.
Otherwise, pause for a moment, and then go back to step 3.

Important! We fully expect that this will be done with a good design that makes use of structs --- probably more than one --- and functions, and that the solution would work for a wide variety of inputs, not only for the input shown here.

Part 3: You got to move it, move it (name p3.cpp)

Now we will animate things, i.e. each character will move on the screen. To start things off, we want each character to have a direction associated with it — north, south, east or west. Make sure you store that in your struct! Start all your characters from Part 2 moving to the right (i.e., east).

Your program will consist of a loop:

do {
  // Move all characters one step:
  //   1. erase them in the old positions 
  //   2. draw them in the new positions

  usleep(80000); // sleep for 80,000 usecs. This corresponds to flipping the next "frame" in an animation.

  // use inputChar() to see if the user has pressed 'q'

} while('q' has not been pressed);

Important! At some point your characters move off the screen, and ncurses goes crazy --- nothing it draws makes sense anymore. Just kill the program with ctrl-c, and don't worry about it.

You may want to consider a couple functions which takes your struct type and modifies its position and/or direction variable, such as:

Part 4 (going further): Momma should I build a wall? (name p4.cpp)

Though your single animated character makes random turns, eventually it's going to make its way off the screen and strange things will happen. It'd be much cooler if the screen acted like a walled-in space that the character cannot escape. So let's do that. The only real difficulty here is that you need to know the height and width of the terminal window (in characters). Our easycurses function for that:

void getWindowDimensions(int& row, int& col);

So the call getWindowDimensions(h,w) sets h to the number of rows on the screen, and w to the number of columns. Note, then, that the valid positions you can drawChar(ch,row,col) to are when 0 ≤ row < h and 0 ≤ col < w.

Now that you can get the height and width of the terminal window, when you come to a "move" step you must check to see whether the move in question would take you off the screen. If it does, then instead of moving just change direction and leave it at that. Make the character "bounce" by simply reversing direction (north goes to south, east to west, etc). If you do this, your character will be walled in and will never leave the terminal window.

Part 5 (going further): Yes it's that easy (name p5.cpp)

Now, instead of a few moving characters, make it 20 (or 40 or 1000 or whatever you want!). If you've done things right, you should be able to do this trivially. If you haven't made good use of structs and functions, it might be painful!

Important! Every time you call drawChar(), it refreshes the screen. Now that we have so many chars, we don't want to refresh every time. Instead call the function drawCharNoRefresh() with the same parameters. The chars won't immediately show up, though, so you'll later need to call the function refresh(); to have them all appear. Do this once per loop iteration after all characters have been drawn, and do it immediately prior to the call to usleep. This is the way animations work: draw a whole new scene, and only overlay it once when it is all complete.

Lab 10: Structs and Character Animation

Overview

Submission