A little more on line and character events

inform7/Internal/Extensions/Graham Nelson/Basic Inform.i7x

@@ -1782,14 +1782,16 @@ Chapter - Glk events
 To decide what glk event is (evtype - glk event type) glk event:
 	(- GLK_EVENT_TY_New({-new: glk event}, {evtype}) -).
 
-To decide what glk event is a/-- character event for/of/with (C - unicode character):
+To decide what glk event is a/-- character event with (C - unicode character):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_CharInput, 0, MapUnicodeToGlkKeyCode({C})) -).
-To decide what glk event is a/-- character event for/of/with (C - unicode character) in (win - glk window):
+To decide what glk event is a/-- character event with (C - unicode character) in (win - glk window)
+	(documented at ph_glkcharacterevent):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_CharInput, {win}, MapUnicodeToGlkKeyCode({C})) -).
 
-To decide what glk event is a/-- line event for/of/with (T - text):
+To decide what glk event is a/-- line event with (T - text):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_LineInput, 0, 0, 0, {-by-reference:T}) -).
-To decide what glk event is a/-- line event for/of/with (T - text) in (win - glk window):
+To decide what glk event is a/-- line event with (T - text) in (win - glk window)
+	(documented at ph_glklineevent):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_LineInput, {win}, 0, 0, {-by-reference:T}) -).
 
 To decide what glk event is a/-- mouse event for/of/with x (x - number) and/-- y (y - a number) coordinates/--:
@@ -1814,7 +1816,8 @@ To decide what glk window is window of (ev - glk event)
 	(documented at ph_glkeventwindow):
 	(- GLK_EVENT_TY_Window({ev}) -).
 
-To decide what unicode character is the character value of (ev - glk event):
+To decide what unicode character is the character value of (ev - glk event)
+	(documented at ph_glkeventcharactervalue):
 	(- GLK_EVENT_TY_Value1({ev}) -).
 
 To decide what number is the x coordinate of (ev - glk event):
@@ -1829,7 +1832,8 @@ To decide what number is the column of (ev - glk event):
 To decide what number is the hyperlink value of (ev - glk event):
 	(- GLK_EVENT_TY_Value1({ev}) -).
 
-To decide what text is the text of (ev - glk event):
+To decide what text is the text of (ev - glk event)
+	(documented at ph_glkeventtextvalue):
 	(- GLK_EVENT_TY_Text({ev}, {-new: text}) -).
 
 The glk event handling rules is a glk event type based rulebook.

inform7/Internal/HTML/xrefs.txt

@@ -259,6 +259,7 @@ ph_fileready ph_markfileready ph_markfilenotready _ WI_25_15 "25.15" "25.15. Exc
 ph_glksupported ph_glkversion _ WI_26_1 "26.1" "26.1. Glk"
 ph_glkwindowheight ph_glkwindowwidth ph_glkwindowclear ph_glkwindowfocus ph_glksetcursor _ WI_26_2 "26.2" "26.2. Dividing the screen into windows"
 ph_glkeventtype ph_glkeventwindow _ WI_26_3 "26.3" "26.3. Glk events"
+ph_glkeventcharactervalue ph_glkeventtextvalue ph_glkcharacterevent ph_glklineevent _ WI_26_4 "26.4" "26.4. Character and line events"
 PM_BadEpisode _ WI_28_2 "28.2" "28.2. Bibliographic data"
 LCARDS _ WI_28_4 "28.4" "28.4. The Library Card"
 IFIDS _ WI_28_5 "28.5" "28.5. The Treaty of Babel and the IFID"

inform7/Tests/Test Internals/Index-Values--I.txt

@@ -35,7 +35,7 @@ up key - <i>unicode character</i><br>
 status window table - <i>table name</i><br>
 </p>
 <p><b>Glk events</b><br>
-current glk event - <i>glk event</i><br>
+current glk event initialiser - <i>glk event</i><br>
 </p>
 <p><b>Glk object recovery</b><br>
 current glk object rock number - <i>number</i><br>

inform7/extensions/basic_inform/Sections/Glulx and Glk.w

@@ -120,14 +120,16 @@ Chapter - Glk events
 To decide what glk event is (evtype - glk event type) glk event:
 	(- GLK_EVENT_TY_New({-new: glk event}, {evtype}) -).
 
-To decide what glk event is a/-- character event for/of/with (C - unicode character):
+To decide what glk event is a/-- character event with (C - unicode character):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_CharInput, 0, MapUnicodeToGlkKeyCode({C})) -).
-To decide what glk event is a/-- character event for/of/with (C - unicode character) in (win - glk window):
+To decide what glk event is a/-- character event with (C - unicode character) in (win - glk window)
+	(documented at ph_glkcharacterevent):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_CharInput, {win}, MapUnicodeToGlkKeyCode({C})) -).
 
-To decide what glk event is a/-- line event for/of/with (T - text):
+To decide what glk event is a/-- line event with (T - text):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_LineInput, 0, 0, 0, {-by-reference:T}) -).
-To decide what glk event is a/-- line event for/of/with (T - text) in (win - glk window):
+To decide what glk event is a/-- line event with (T - text) in (win - glk window)
+	(documented at ph_glklineevent):
 	(- GLK_EVENT_TY_New({-new: glk event}, evtype_LineInput, {win}, 0, 0, {-by-reference:T}) -).
 
 To decide what glk event is a/-- mouse event for/of/with x (x - number) and/-- y (y - a number) coordinates/--:
@@ -152,7 +154,8 @@ To decide what glk window is window of (ev - glk event)
 	(documented at ph_glkeventwindow):
 	(- GLK_EVENT_TY_Window({ev}) -).
 
-To decide what unicode character is the character value of (ev - glk event):
+To decide what unicode character is the character value of (ev - glk event)
+	(documented at ph_glkeventcharactervalue):
 	(- GLK_EVENT_TY_Value1({ev}) -).
 
 To decide what number is the x coordinate of (ev - glk event):
@@ -167,7 +170,8 @@ To decide what number is the column of (ev - glk event):
 To decide what number is the hyperlink value of (ev - glk event):
 	(- GLK_EVENT_TY_Value1({ev}) -).
 
-To decide what text is the text of (ev - glk event):
+To decide what text is the text of (ev - glk event)
+	(documented at ph_glkeventtextvalue):
 	(- GLK_EVENT_TY_Text({ev}, {-new: text}) -).
 
 @ And now the glk event handling rules themselves.

resources/Documentation/Writing with Inform.md

@@ -18380,15 +18380,55 @@ The different event types, and how to handle them, will be covered in subsequent
 
 > phrase: {ph_glkeventwindow} window of (glk event) ... glk window
 >
-> Some events take place in or on a given window: for example, commands are typed into windows, so line events have a window, and a mouse event indicates a click or tap on a window. For those events, this returns the window in question; for events not tied to any specific window, such as a screen resize event (affecting every window) or a timer event (nothing to do with the screen), this returns `nothing`.
+> Some events take place in or on a given window: for example, commands are typed into windows, so line events have a window, and a mouse event indicates a click or tap on a window. For those events, this returns the window in question; for events not tied to any specific window, such as a timer event, this returns `nothing`.
 
-## Keyboard input
+## Character and line events
 
-As has already been hinted (see [Dividing the screen into windows]), windows channel text input as well as text output.
+As has already been hinted (see [Dividing the screen into windows]), windows channel text input as well as text output. There are times when individual key-presses matter — for example, if the user presses a cursor key to navigate a menu, and we have to react immediately — and then there are times when we don't care what is being typed until an entire command has been entered. That's why there are two different keyboard events: `character event` and `line event`.
 
-There are times when individual key-presses matter — for example, if the user presses a cursor key to navigate a menu, and we have to react immediately — and then there are times when we don't care what is being typed until an entire command has been entered. That's why there are two different keyboard events: `character event` and `line event`.
+* A `character event` is the pressing of a key, or strictly speaking, the input of a character from the keyboard. If the user presses and releases the shift key, for example, that won't generate a character event. Typing the 7 key will do, however, as will typing shift-7, which on most keyboards will lead to a character event with the ``&`` symbol.
 
-Which ones are sent to the story depends on what the story has asked to receive. In a standard command-parser story, for example, we don't care about the individual keypresses. If the player is typing ``EAT CAKE``, we don't want to receive a stream of character events (E, A, Y, delete, T, space, ...): we just want a line event to say that a complete command has now been typed.
+* A `line event` marks when a complete line has been fully typed in, and the user has indicated that it's finished by pressing the RETURN or ENTER key. (That end-marker does not become part of the text of the command.)
+
+### How to request these events
+
+Glk sends us events only if we have requested them. By default, an Inform story never requests character events. Traditionally turn-by-turn command parser stories only care about entire commands, not individual keypresses. If the player is typing ``EAT CAKE``, we don't want to receive a stream of character events (E, A, Y, delete, T, space, ...).
+
+An Inform story requests a line event only when it has, in effect, halted waiting for a command to be typed in. But since Inform stories usually print quickly and spend most of the time waiting for player input, this means they are almost always requesting line events.
+
+### Details for these events
+
+Both character and line events are tied to windows, so `window of (glk event)` can be used to find which.
+
+> phrase: {ph_glkeventcharactervalue} character value of (glk event) ... unicode character
+>
+> For a character event, this returns the character in question: for any other event, it returns `U+003F`, that is, the Unicode value for a question mark.
+
+> phrase: {ph_glkeventtextvalue} text value of (glk event) ... text
+>
+> For a line event, this returns the text of the line. For any other event, it throws a run-time problem.
+
+### Fictitious character and line events
+
+Some types of event can be created even though they haven't happened yet, and the two keyboard types are a case in point. It may seem peculiar to create fictitious Glk events, but it turns out be very useful in order to, say, treat mouse clicks as if they were keypresses or commands, as we shall see. Here are the phrases to create such events:
+
+> phrase: {ph_glkcharacterevent} character event with (unicode character) in (glk window) ... glk event
+>
+> This produces an event value exactly like that which would have been generated by glk if a key with the given character had been typed in the given window.
+> 
+> The `in (glk window)` can be omitted, in which case the event is in the `main window`.
+
+> phrase: {ph_glklineevent} line event with (text) in (glk window) ... glk event
+>
+> This produces an event value exactly like that which would have been generated by glk if the given whole command had been typed in the given window. There's no necessity for the text to be in upper case, or for that matter in lower case. These all produce different events:
+>
+>     line event with "GATHER YE ROSEBUDS" in main window
+>     line event with "GATHER   YE   ROSEBUDS" in main window
+>     line event with "gather ye rosebuds" in main window
+>
+> Though the Inform command parser would treat all three commands just the same, that all happens much higher up than in this input-output layer. The texts are different, so the events are different.
+> 
+> The `in (glk window)` can be omitted, in which case the event is in the `main window`.
 
 ## Basic IO