Correct behavior for glk_cancel_line_event()?

Technical Development Specifications
,
1

(EDITED to add new information)

The Glk spec 0.7.5 Section 4.2 Line Input Events says:

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.

The section also says:

In the event structure, win tells what window the event came from. val1 tells how many characters were entered. val2 will be 0 unless input was ended by a special terminator key, in which case val2 will be the keycode (one of the values passed to glk_set_terminators_line_event()).

and (regarding setting terminators):

Do not include regular printable characters in the array, nor keycode_Return (which represents the default enter key and will always be recognized).

For the “event argument” parameter, I understand this to mean the address of a four-field event array/struct of the type described at the start of Section 4. Is that correct?

If yes, what values should be populated to that array by this call? From reading the spec, my interpretation was that these should be filled out as follows:

  • -->0 = evtype_None (if no request was live) or evtype_LineInput (if request was live)
  • -->1 = window supplied as first argument
  • -->2 = 0 (if no request was live) or number of characters entered prior to cancellation (if request was live)
  • -->3 = 0 (only possible value)

Is this interpretation correct? Is there a standard definition here?

1 Like
2

Yea that’s correct.

1 Like