Version 3 of Basic Screen Effects by Emily Short begins here.

"Waiting for a keypress; clearing the screen. Also provides facilities for 
changing the foreground and background colors of text, when using the z-machine.
These abilities will not function under Glulx."

Section 1 - Spacing and Pausing

Include (-

[ KeyPause i; 
	i = KeyCharPrimitive(); 
	rfalse;
];

[ SPACEPause i;
	while (i ~= 13 or 31 or 32)
	{
		i = KeyCharPrimitive();	
	}
];

[ GetKey i;
	i = KeyCharPrimitive(); 
	return i;
];

-)

To clear the screen:
	(- ClearScreen(0); -)

To clear only the main screen:
	(- ClearScreen(2); -)

To clear only the status line:
	(- ClearScreen(1); -).

To wait for any key:
	(- KeyPause(); -)

To wait for the SPACE key:
	(- SPACEPause(); -)

To decide what number is the chosen letter:
	(- GetKey() -)

To pause the game: 
	say "[paragraph break]Please press SPACE to continue.";
	wait for the SPACE key;
	clear the screen.

To center (quote - text-routine):
	(- CenterPrintComplex({quote}); -);

To center (quote - text):
	(- CenterPrintComplex({quote}); -);
 
To center (quote - text-routine) at row (depth - a number):
	(- CenterPrint({quote}, {depth}); -);

To center (quote - text) at row (depth - a number):
	(- CenterPrint({quote}, {depth}); -);
	
To stop game abruptly:
	(- quit; -)

Include (-

#ifndef printed_text;
Array printed_text --> 64;
#endif;

[ CenterPrint str depth i j;
	font off;
	i = ScreenWidth();
            PrintToBuffer(printed_text, 63, str);
	j = (i-(printed_text-->0))/2; 
	j = j-1;
	MoveCursor(depth, j);
	print (I7_string) str; 
	font on;
];

[ CenterPrintComplex str i j;
	font off;
	print "^"; 
	i = ScreenWidth();
            PrintToBuffer(printed_text, 63, str);
	j = (i-(printed_text-->0))/2; 
	spaces j-1;
	print (I7_string) str; 
	font on;
];

-)

To decide what number is screen width:
	(- ScreenWidth-);

To decide what number is screen height:
	(- I7ScreenHeight() -);

Include (-

[ I7ScreenHeight i screen_height;
	i = 0->32;
          if (screen_height == 0 or 255) screen_height = 18;
          screen_height = screen_height - 7;
	return screen_height;
];

[ ClearBoxedText i;
  if (I7_box) {
      for (i=0: I7_boxes_appeared-->i: i++)
          if (I7_boxes_appeared-->i == I7_box) {
              I7_box = 0;
              return;
          }
      I7_boxes_appeared-->i = I7_box;
      I7_box();
      I7_box = 0;
  }
];

-)

To deepen status line to (depth - a number) rows:
	(- DeepStatus({depth}); -);

To move cursor to (depth - a number):
	(- I7MoveCursor({depth}); -)

To right align cursor to (depth - a number):
	(- RightAlign({depth}); -)

Include (- 

[ DeepStatus depth i screen_width;
	StatusLineHeight(depth);
	screen_width = ScreenWidth(); style reverse;
            #ifdef TARGET_GLULX;
              ClearScreen(1);
            #ifnot;
	  for (i=1:i<depth+1:i++)
              {
	 	@set_cursor i 1;
	 	spaces(screen_width);
	  } 
           #endif;
];

[ I7MoveCursor depth;
	MoveCursor(depth, 1);
];

[ RightAlign depth screen_width o n;
	screen_width = ScreenWidth(); 
	n = (+ right alignment depth +);
	o = screen_width - n;
	MoveCursor(depth, o);
];

-)

Table of Ordinary Status
left	central	right
"[location]"	""	"[score]/[turn count]" 

Status bar table is a table-name that varies. Status bar table is the Table of Ordinary Status.

To fill status bar with (selected table - a table-name):
	let __n be the number of rows in the selected table;
	deepen status line to __n rows;
	let __index be 1;
	repeat through selected table
	begin;
		move cursor to __index; 
		say "[left entry]";
		center central entry at row __index;
		right align cursor to __index;
		say "[right entry]";
		change __index to __index + 1;
	end repeat.

Right alignment depth is a number that varies. Right alignment depth is 14.

Section 2 - Colors (for Z-machine only)

To say default letters:
	(- @set_colour 1 1; -)

To say red letters:
	(- @set_colour 3 0; -)

To say green letters:
	(- @set_colour 4 0; -)

To say yellow letters:
	(- @set_colour 5 0; -)

To say blue letters:
	(- @set_colour 6 0; -)

To say magenta letters:
	(- @set_colour 7 0; -)

To say cyan letters:
	(- @set_colour 8 0; -)

To say white letters:
	(- @set_colour 9 0; -)

To say black letters:
	(- @set_colour 2 0; -)

To turn the background black:
	(- @set_colour 0 2; -);

To turn the background red:
	(- @set_colour 0 3; -);

To turn the background green:
	(- @set_colour 0 4; -);

To turn the background yellow:
	(- @set_colour 0 5; -);

To turn the background blue:
	(- @set_colour 0 6; -);

To turn the background magenta:
	(- @set_colour 0 7; -);

To turn the background cyan:
	(- @set_colour 0 8; -);

To turn the background white:
	(- @set_colour 0 9; -);

To show the current quotation:
	(- ClearBoxedText(); -);


Basic Screen Effects ends here.

---- DOCUMENTATION ----

Basic Screen Effects implements the following effects: pauses to wait for a keypress from the player; clearing the screen; changing the color of the foreground font; and changing the color of the background. Color changes function only on the Z-machine.

(1) Pauses and spacing

The following phrases are defined:

To clear the entire screen of everything it contains, including the status line,

	clear the screen.

To clear only one section of the screen, we also have:

	clear only the main screen.
	clear only the status line.

To produce a pause until the player types any key:

	wait for any key.

To produce a pause until the player types SPACE, ignoring all other keys:

	wait for the SPACE key.

To give the player a message saying to press SPACE to continue, wait for a keypress, and then clear the screen before continuing the action:

	pause the game.

In extreme cases, we may want to end the game without allowing the player an opportunity to RESTART, RESTORE, or QUIT; to this end:

	stop game abruptly.

Show the current quotation displays whatever the author has selected with "display the boxed quotation...". Ordinarily boxed quotations appear when the prompt is printed, but this allows the author to show a boxed quote at another time. To achieve a splash-screen before the game proper begins, we could do something like this:

	When play begins:
		display the boxed quotation 
		"What's this room? I've forgotten my compass.
		Well, this'll be south-south-west parlour by living room.
		-- Philadelphia Story";
		show the current quotation;
		pause the game.

Similarly, we can display a phrase centered in the middle of the screen but without the background-coloration of the boxed quotation, like this:

	center "The Merchant of Venice";

Centering text puts the text on its own new line, since it would not make much sense otherwise. Note that centered text will always be set to fixed-width; font stylings such as bold and italic will not work. (If they did, they would throw off the centering; the screen model is insufficiently sophisticated to deal with centering non-fixed-width letters.)

If we want to make our own calculations using this information, the width of the screen can be checked at any time, like so:

	if the screen width is less than 75, say "The map will not display properly until you widen your screen." instead.

We can also use a variation of the center command to position text in the status line. To produce a Trinity-style status line with the location, centered:

	Rule for constructing the status line:
		center "[location]" at row 1;
		rule succeeds.

For status lines of more than one row, we can create a table representing the overall appearance of the desired status line and then set that table as our status bar table. The following would build a two-line status bar with all sorts of information in it. (For a more practical demonstration involving a three-line compass rose, see the example below.)
 
	Table of Fancy Status
	left	central	right 
	" [location]"	"[time of day]"	"[score]"
	" [hair color of the suspect]"	"[eye color of the suspect]"	"[cash]"

Rule for constructing the status line:
		fill status bar with Table of Fancy Status;
		rule succeeds.
 
A status bar table must always have left, central, and right columns, and we must provide the rule for constructing the status line. Otherwise, Inform will use the default status line behavior. The position of the right hand side is set to 14 spaces from the end by default (matching Inform's default status line), but it is possible to change this by altering the value of the variable called right alignment depth; so we might for instance say

	When play begins: change right alignment depth to 30.

for the purpose of moving what is printed on the right side inward. Note that right alignment depth will only affect the behavior of status bar tables of the kind described here; it will have no effect on Inform's default handling of the right hand status line variable.

(2) Color effects (available on the Z-machine only). 

To turn the background black (or red, green, yellow, blue, white, magenta, or cyan):

	turn the background black. 
	turn the background red. 

...and so on. This only applies to what is typed from that point in the game onward. If we wish to turn the entire background a new color at once (and this is usually desirable), we should set the background and then clear the screen, so:

	turn the background black;
	clear the screen.

Finally, font colors can be changed with say (color) letters, where the same range of colors may be used as for the background. So for instance

	say "There is a [red letters]piping hot[default letters] pie on the table."

We should be careful with color effects. Some older interpreters do not deal well with color, and part of the audience plays interactive fiction on black and white devices or via a screenreader. The phrase "say default letters" restores whatever background and foreground are normal on this system. It is not safe to assume that the player is necessarily using one particular color scheme; black-on-white, white-on-black, and white-on-blue are all relatively common.

Thanks to Eric Eve for the biplatform patches to this extension.

Example: ** Pillaged Village - A status bar showing unvisited rooms in a colored compass rose.

Note that attempting to compile this example for Glulx will fail, because it uses color effects available only on the Z-machine.

	"Pillaged Village" by Lars Thurgoodson.
	
	Include Basic Screen Effects by Emily Short.

	The story headline is "An interactive looting".

	The Viking Longship is west of the Seashore. The Seashore is west of the Burning Village. The Shrine of the Green Man is northwest of the Burning Village. The Shattered Fort is southwest of the Burning Village. The Treetop is above the Shrine.

	When play begins:
	     center "[story title]";
	     center "[story headline]";
	     center "by [story author]";
	     leave space;
	     center "Press SPACE to begin.";
	     wait for the SPACE key;
	     clear the screen;
	     leave space.

	To turn screen black:
		say white letters;
		turn the background black;
		clear the screen;
		leave space;
	
	To turn screen white:
		turn the background white;
		say black letters;
		clear the screen;
		leave space.

	To leave space:
		say paragraph break;
		say paragraph break;
		say paragraph break;
		say paragraph break. 
	
	Table of Fancy Status
	left	central	right 
	" [if in darkness]Darkness[otherwise][location][end if]"	""	"[top rose]"
	" "	""	"[middle rose]"
	" Rooms searched: [number of rooms which are visited]/[number of rooms]"	""	"[bottom rose]"
 	
	To say red reverse:
		turn the background red.
		
	To say black reverse:
		turn the background black.
	
	To say white reverse:
		turn the background white. 

	To say top rose:
		let place be the room up from the location;
		if the place is a room, say "[if the place is unvisited][red reverse][end if]U   [default letters]"; otherwise say "    "; 
		let place be the room northwest from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if]NW[default letters]"; otherwise say "  ";
		let place be the room north from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if] N [default letters]"; otherwise say "   ";
		let place be the room northeast from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if]NE[default letters]"; otherwise say "  ".
	
	To say middle rose:
		say "    ";
		let place be the room west from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if]W [default letters]"; otherwise say "  ";
		say " . ";
		let place be the room east from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if] E[default letters]"; otherwise say "  ".
	
	To say bottom rose:
		let place be the room down from the location;
		if the place is a room, say "[if the place is unvisited][red reverse][end if]D   [default letters]"; otherwise say "    ";
		let place be the room southwest from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if]SW[default letters]"; otherwise say "  ";
		let place be the room south from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if] S [default letters]"; otherwise say "   ";
		let place be the room southeast from the location;
		if place is a room, say "[if the place is unvisited][red reverse][end if]SE[default letters]"; otherwise say "  ".
	 	
	Rule for constructing the status line:
		fill status bar with Table of Fancy Status;
		say default letters;
		rule succeeds.

	Rule for constructing the status line:
   	  fill status bar with Table of Fancy Status;
   	  rule succeeds.