Basic Screen Effects: @set_colour vs. VM_SetWindowColours

(Posting this here because built-in extensions don’t seem to have threads in the I7 Extensions forum.)

I was reading Basic Screen Effects by Emily Short and I noticed that it uses the @set_colour z-machine opcode directly.

Having recently investigated color support in the I6 library, I’m curious why it doesn’t use VM_SetWindowColours (the I7 equivalent of I6’s SetColour routine).

To quote the Inform 6 release notes: “The advantage [of SetColour] over @set_colour is that when the player restores a saved game or types UNDO, the colours will be correct for that state of the game.”

I wrote the following test program to demonstrate the differences. Note that this program should be compiled to zcode, not the default glulx target.

Include Basic Screen Effects by Emily Short.

Test Chamber is a room.

[true: use colored text rules from Basic Screen Effects (@set_colour)]
[false: use colored text rules below (VM_SetWindowColours)]
Use extension is initially true.

Before jumping:
	if use extension is true, say blue letters;
	otherwise say blue letters vm;
	say run paragraph on;
	clear the screen.
Before waving hands:
	if use extension is true, say green letters;
	otherwise say green letters vm;
	say run paragraph on;
	clear the screen.
When play begins:
	if use extension is true, say red letters;
		enable colours;
		say red letters vm;
	say run paragraph on;
	clear the screen.
[I7's VM_SetWindowColours and lib 6/11's SetColour both reject fg and bg args of 0 (CLR_CURRENT), while lib 6/12's SetColour and the @set_colour opcode itself both allow it. So, we set the bg to 1 (CLR_DEFAULT) instead.]
[See for more on this.]

To say red letters vm:
	(- VM_SetWindowColours(3, 1); -)
To say green letters vm:
	(- VM_SetWindowColours(4, 1); -)
To say blue letters vm:
	(- VM_SetWindowColours(6, 1); -)
To enable colours:
	(- clr_on = 1; -)
[Test me with "jump / wave / undo / undo".]

Test it once, set use extension to false, then test again and note how the correct color is set and the screen cleared after restore or undo. The desirability of the screen clear performed by RestoreColours (I7: VM_RestoreWindowColours) after restore or undo is under discussion in the I6 color thread that I linked above.

The difference in status line text color is due to a workaround for issue 1377, which has not been fixed in I7. Specifically, VM_SetWindowColours should accept f and b == 0.