gnusto 
| resources: | Home Installation Mailing list Source code Bugs Screenshots Nightlies |
|---|---|
| reference: | Roadmap Error messages Code overview Debugger (prototype only) Playthroughs |
Bocardo - upper.js
Read the code
Replaces: Barbara
The Z-machine has a complicated screen model that is better suited to character-based displays than the HTML or XUL representation. Bocardo therefore attempts to produce HTML which allows the rest of the system to treat the screen more like a VT100 than a browser.
Source of the name "upper.js": Bocardo developed from the code to handle the upper window in Barbara. It will be renamed soon.
The identifier prefix for Bocardo is win.
The layout
The screen: The whole screen area is wrapped in one element. This is a <pre> to make spaces significant. (An alternative method would be to replace all spaces with non-breaking spaces.)
There is no physical distinction in the HTML between the upper and lower windows, any more than the operating system can distinguish the windows when running text-mode Frotz.
<div>s represent lines: This <pre> contains a series of <div>s. Because <div>s are block-level elements, they are rendered one below the other.
<spans>s represent sequences of characters: Every <div> contains zero or more <spans>, which are rendered horizontally next to one another. Each span may be CSS-formatted, but not necessarily differently to its neighbours.
The public methods
win_setup(): call this before any writes to the screen, or to clear the screen.
win_resize(width, height): changes the maximum width and height of the screen. It will affect where wrapping and scrolling happen, but it will never make the screen smaller.
win_reset_scroll_count(): The win_chalk() function will stop after printing a certain amount of text, so that the user can read it. If you know that the user has had a chance to catch up with all the text on the screen (for example, when the user has had a chance to wait for input), call this function to reset the internal counter, so that a whole screenful of text must pass again before pausing.
win_chalk(window, style, text) writes text onto window number window using the CSS style style. The function may stop printing when a whole screenful has been written, in which case it will return the unwritten part of the string; it returns an empty string if the whole string was written.
Most of win_chalk() is written in terms of a private function, win__subchalk() [which should probably be a subfunction of win_chalk()]: win_chalk() divides the text into linefuls, and handles pausing for more, and win__subchalk() handles manipulating the HTML.
win_gotoxy(win,x,y) moves the cursor on window win to co-ordinate x,y. Note the order of the co-ordinates, which is that commonly used in graphics libraries but opposite to that used in Z-code. Note also that this function is never called on the lower window in practice.
win_set_top_window_size(lines) sets the size of the upper window. This will not affect the current screen. For example, it's quite valid to extend the upper window to cover the entire lower window, draw a box on top, and then reset the upper window to cover only a small part of the screen; many Inform games do just that.
win_clear(win) clears a window.
win_print_table(window, style, lines) writes a series of lines lines onto window number window using the CSS style style, one below the other. The cursor is not moved. This is an attempt to implement @print_table, which is rather under-specified in the documentation.
The future
Improvements: The system works far better than the old Barbara system. However:
- It's slow. Drawing up a fairly simple screen can take over a second. Even the simplest update takes around twice as many DOM operations as in Barbara.
- There's no scrollback.
- Monospace looks frumpy, it has to be said.
I have some ideas on how to improve this; I'll add them here in a while.
Sharing work: It's possible that some of the work we've done here will be useful to other projects (e.g. MudZilla), or that their work can be used here; we should contact them and talk about it.