Glk 075 draft spec changes

Zero-size windows

(Added to the chapter on windows:)

A note about zero-size windows: a window may wind up with a height or width of zero. (Because of a fixed height of zero, or a percentage allocation of zero, or simply because the application display area does not have enough space.) The library should support this by hiding the window and its contents entirely. Any border between the window and its sibling should also disappear.

When a window has zero size, it is reasonable for the library to stop passing input events to it. The input request is not cancelled, but the UI may not be able to give keyboard focus or mouse events to a zero-size region of the screen. Therefore, a program which sets a window to zero size should not rely on input from it.

Char input in graphics windows

(Added text:)

Graphics windows do not support text output, nor line input. They may support character input. Character input for graphics windows was added in Glk spec 0.7.5. Older interpreters may not support this feature.

res = glk_gestalt(gestalt_GraphicsCharInput, 0);

This returns 1 if graphics windows can accept character input requests. If it returns zero, do not call glk_request_char_event() or glk_request_char_event_uni() on a graphics window.

gestalt_GraphicsCharInput has numeric value 23.

Encoding of external files

strid_t glk_stream_open_file(frefid_t fileref, glui32 fmode, glui32 rock);

...When writing in binary mode, byte values are written directly to the file. (Writing calls such as glk_put_char_stream() are defined in terms of Latin-1 characters, so the binary file can be presumed to use Latin-1. Newlines will remain as 0x0A bytes.) Unicode values (characters greater than 255) cannot be written to the file. If you try, they will be stored as 0x3F ("?") characters.

When writing in text mode, character data is written in an encoding appropriate to the platform; this may be Latin-1 or some other format. Newlines may be converted to other line break sequences. Unicode values may be stored exactly, approximated, or abbreviated, depending on what the platform's text files support.

strid_t glk_stream_open_file_uni(frefid_t fileref, glui32 fmode, glui32 rock);

This works just like glk_stream_open_file(), except that in binary mode, characters are written and read as four-byte (big-endian) values. This allows you to write and read any Unicode character.

In text mode, the file is written and read using the UTF-8 Unicode encoding. Files should be written without a byte-ordering mark. This ensures that text-mode files created by glk_stream_open_file() and glk_stream_open_file_uni() will be identical if only ASCII characters (32-127) are written.

Previous versions of this spec said, of glk_stream_open_file_uni(): "In text mode, the file is written and read in a platform-dependent way, which may or may not handle all Unicode characters." This left open the possibility of other native text-file formats, as well as richer formats such as RTF or HTML. Richer formats do not seem to have ever been used; and at this point, UTF-8 is widespread enough for us to mandate it.

To summarize:

• glk_stream_open_file (byte stream), text mode: platform native text
• glk_stream_open_file (byte stream), binary mode: Latin-1
• glk_stream_open_file_uni (word stream), text mode: UTF-8
• glk_stream_open_file_uni (word stream), binary mode: four-byte (big-endian) integers

However, if the fileref was created via a prompt (glk_fileref_create_by_prompt), the player may have selected format options that override these rules.

---

See also the following notes about filerefs.

• fileusage_BinaryMode: The file contents will be stored exactly as they are written, and read back in the same way. The resulting file may not be viewable on platform-native text file viewers.
• fileusage_TextMode: The file contents will be transformed to a platform-native text file as they are written out. Newlines may be converted to linefeeds or linefeed-plus-carriage-return combinations; Latin-1 characters may be converted to native character codes. When reading a file in text mode, native line breaks will be converted back to newline (0x0A) characters, and native character codes may be converted to Latin-1 or UTF-8. Line breaks will always be converted; other conversions are more questionable. If you write out a file in text mode, and then read it back in text mode, high-bit characters (128 to 255) may be transformed or lost.

In general, you should use text mode if the player expects to read the file with a platform-native text editor; you should use binary mode if the file is to be read back by your program, or if the data must be stored exactly. Text mode is appropriate for fileusage_Transcript; binary mode is appropriate for fileusage_SavedGame and probably for fileusage_InputRecord. fileusage_Data files may be text or binary, depending on what you use them for.

When a fileref is created via a user prompt (glk_fileref_create_by_prompt), it may include extra file type information. For example, a prompt to write a transcript file might include a choice of text encodings, or even alternate formats such as RTF or HTML. This player-selected information will override the default encoding rules noted above. When a fileref is created non-interactively (glk_fileref_create_by_name, glk_fileref_create_temp) the default rules always apply.