glk_request_line_event ()

void
glk_request_line_event (winid_t win,
                        char *buf,
                        glui32 maxlen,
                        glui32 initlen);

Requests input of a line of Latin-1 characters. A window cannot have requests for both character and line input at the same time. Nor can it have requests for line input of both types (Latin-1 and Unicode). It is illegal to call glk_request_line_event() if the window already has a pending request for either character or line input.

The buf argument is a pointer to space where the line input will be stored. (This may not be NULL.) maxlen is the length of this space, in bytes; the library will not accept more characters than this. If initlen is nonzero, then the first initlen bytes of buf will be entered as pre-existing input — just as if the player had typed them himself. (The player can continue composing after this pre-entered input, or delete it or edit as usual.)

The contents of the buffer are undefined until the input is completed (either by a line input event, or glk_cancel_line_event(). The library may or may not fill in the buffer as the player composes, while the input is still pending; it is illegal to change the contents of the buffer yourself.

glk_request_line_event_uni ()

void
glk_request_line_event_uni (winid_t win,
                            glui32 *buf,
                            glui32 maxlen,
                            glui32 initlen);

Request input of a line of Unicode characters. This works the same as glk_request_line_event(), except the result is stored in an array of glui32 values instead of an array of characters, and the values may be any valid Unicode code points.

If possible, the library should return fully composed Unicode characters, rather than strings of base and composition characters.

glk_cancel_line_event ()

void
glk_cancel_line_event (winid_t win,
                       event_t *event);

This cancels a pending request for line input. (Either Latin-1 or Unicode.)

The event pointed to by the event argument will be filled in as if the player had hit enter, and the input composed so far will be stored in the buffer; see below. If you do not care about this information, pass NULL as the event argument. (The buffer will still be filled.)

For convenience, it is legal to call glk_cancel_line_event() even if there is no line input request on that window. The event type will be set to evtype_None in this case.

glk_set_echo_line_event ()

void
glk_set_echo_line_event (winid_t win,
                         glui32 val);

Normally, after line input is completed or cancelled in a buffer window, the library ensures that the complete input line (or its latest state, after cancelling) is displayed at the end of the buffer, followed by a newline. This call allows you to suppress this behavior. If the val argument is zero, all subsequent line input requests in the given window will leave the buffer unchanged after the input is completed or cancelled; the player's input will not be printed. If val is nonzero, subsequent input requests will have the normal printing behavior.

If you turn off line input echoing, you can reproduce the standard input behavior by following each line input event (or line input cancellation) by printing the input line, in the Input style, followed by a newline in the original style.

The glk_set_echo_line_event() does not affect a pending line input request. It also has no effect in non-buffer windows.

Not all libraries support this feature. You can test for it with gestalt_LineInputEcho.

glk_set_terminators_line_event ()

void
glk_set_terminators_line_event (winid_t win,
                                glui32 *keycodes,
                                glui32 count);

It is possible to request that other keystrokes complete line input as well. (This allows a game to intercept function keys or other special keys during line input.) To do this, call glk_set_terminators_line_event(), and pass an array of count keycodes. These must all be special keycodes (see Character Input). Do not include regular printable characters in the array, nor keycode_Return (which represents the default enter key and will always be recognized). To return to the default behavior, pass a NULL or empty array.

The glk_set_terminators_line_event() affects subsequent line input requests in the given window. It does not affect a pending line input request.

A library may not support this feature; if it does, it may not support all special keys as terminators. (Some keystrokes are reserved for OS or interpreter control.) You can test for this with gestalt_LineTerminators and gestalt_LineTerminatorKey.