Merge pull request #168 from curiousdannii/cumulative

Cumulative Glk changes, part 2

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

@@ -1642,7 +1642,7 @@ To fill/redraw the/-- status bar/line/window with (new status table - a table-na
 	if once only:
 		now the status window table is the old status window table;
 
-To move the status bar/line/window cursor to row (row - number) column (col - number):
+To move the status bar/line/window cursor to row (row - number) and/-- column/col (col - number):
 	(- VM_MoveCursorInStatusLine({row}, {col}); -).
 
 To set the status bar/line/window to (rows - number) row/rows:
@@ -1724,7 +1724,7 @@ To decide what version number is the interpreter version number/--:
 
 Chapter - Glk windows
 
-A glk window is a kind of abstract object.
+A Glk window is a kind of abstract object.
 The glk window kind is accessible to Inter as "K_Glk_Window".
 The specification of a glk window is "Models the Glk window system."
 
@@ -1737,6 +1737,8 @@ The rock number property translates into Inter as "glk_rock".
 A glk window has a number called the glk window handle.
 The glk window handle property translates into Inter as "glk_ref".
 
+Definition: a glk window is on-screen rather than off-screen if the glk window handle of it is not 0.
+
 A graphics window is a kind of glk window.
 The window type of a graphics window is graphics window type.
 A text buffer window is a kind of glk window.
@@ -1753,9 +1755,6 @@ The status window object is accessible to Inter as "Status_Window".
 The quote window is a text buffer window.
 The quote window object is accessible to Inter as "Quote_Window".
 
-The unknown window is a glk window.
-The unknown window object is accessible to Inter as "Unknown_Glk_Window".
-
 Section - Glk windows
 
 To clear (win - a glk window)
@@ -1774,46 +1773,74 @@ To decide what number is the width of (win - a glk window)
 	(documented at ph_glkwindowwidth):
 	(- WindowGetSize({win}, 0) -).
 
-To set (win - a glk window) cursor to row (row - a number) and/-- column (col - a number)
+To set (win - a glk window) cursor to row (row - a number) and/-- column/col (col - a number)
 	(documented at ph_glksetcursor):
 	(- WindowMoveCursor({win}, {col}, {row}); -).
 
 Chapter - Glk events
 
-The glk event handling rules is a glk event based rulebook.
+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):
+	(- 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):
+	(- 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):
+	(- 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):
+	(- 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/--:
+	(- GLK_EVENT_TY_New({-new: glk event}, evtype_MouseInput, 0, {x}, {y}) -).
+To decide what glk event is a/-- mouse event for/of/with x (x - number) and/-- y (y - a number) coordinates/-- in (win - glk window):
+	(- GLK_EVENT_TY_New({-new: glk event}, evtype_MouseInput, {win}, {x}, {y}) -).
+To decide what glk event is a/-- mouse event for/of/with row (y - number) and/-- column/col (x - a number):
+	(- GLK_EVENT_TY_New({-new: glk event}, evtype_MouseInput, 0, {x}, {y}) -).
+To decide what glk event is a/-- mouse event for/of/with row (y - number) and/-- column/col (x - a number) in (win - glk window):
+	(- GLK_EVENT_TY_New({-new: glk event}, evtype_MouseInput, {win}, {x}, {y}) -).
+
+To decide what glk event is a/-- hyperlink event for/of/with (val - number):
+	(- GLK_EVENT_TY_New({-new: glk event}, evtype_Hyperlink, 0, {val}) -).
+To decide what glk event is a/-- hyperlink event for/of/with (val - number) in (win - glk window):
+	(- GLK_EVENT_TY_New({-new: glk event}, evtype_Hyperlink, {win}, {val}) -).
+
+To decide what glk event type is type of (ev - glk event):
+	(- GLK_EVENT_TY_Type({ev}) -).
+
+To decide what glk window is window of (ev - glk event):
+	(- GLK_EVENT_TY_Window({ev}) -).
+
+To decide what unicode character is the character value of (ev - glk event):
+	(- GLK_EVENT_TY_Value1({ev}) -).
+
+To decide what number is the x coordinate of (ev - glk event):
+	(- GLK_EVENT_TY_Value1({ev}) -).
+To decide what number is the y coordinate of (ev - glk event):
+	(- GLK_EVENT_TY_Value2({ev}) -).
+To decide what number is the row of (ev - glk event):
+	(- GLK_EVENT_TY_Value2({ev}) -).
+To decide what number is the column of (ev - glk event):
+	(- GLK_EVENT_TY_Value1({ev}) -).
+
+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):
+	(- GLK_EVENT_TY_Text({ev}, {-new: text}) -).
+
+The glk event handling rules is a glk event type based rulebook.
 The glk event handling rules is accessible to Inter as "GLK_EVENT_HANDLING_RB".
 
-The glk event window is a glk window variable.
-The glk event window variable translates into Inter as "Glk_Event_Struct_win".
-The glk event value 1 is a number variable.
-The glk event value 1 variable translates into Inter as "Glk_Event_Struct_val1".
-The glk event value 2 is a number variable.
-The glk event value 2 variable translates into Inter as "Glk_Event_Struct_val2".
-
-Definition: a glk event is dependent on the player rather than independent of the player if
-	it is character event or
-	it is line event or
-	it is mouse event or
-	it is hyperlink event.
+The current glk event is a glk event variable.
+The current glk event variable is defined by Inter as "current_glk_event".
 
-To set the/-- glk event type to (t - glk event):
-	(- SetGlkEventType({t}); -).
+To process (ev - glk event):
+	(- GLK_EVENT_TY_Process({ev}); rtrue; -).
 
-To say current line input of (w - glk window):
-	(- WindowBufferPrint({w}); -).
-
-To decide what text is the current line input of (w - glk window):
-	(- WindowBufferCopyToText({w}, {-new:text}) -).
-
-To set the current line input of (w - glk window) to (t - text):
-	(- WindowBufferSet({w}, {-by-reference:t}); -).
-
-First glk event handling rule for a glk event (called the event) (this is the update input requests rule):
-	[ It was too risky to set the text input status here, in case the author also sets a first glk event handling rule, so that property is reset within glk_select. ]
-	if the event is hyperlink event:
-		now the glk event window is not requesting hyperlink input;
-	if the event is mouse event:
-		now the glk event window is not requesting mouse input;
+Glk event handling rule for a screen resize event (this is the redraw the status line rule):
+	redraw the status window;
 
 Chapter - Suspending and resuming input
 
@@ -1830,6 +1857,12 @@ To suspend text input in (win - a glk window), without input echoing:
 To resume text input in (win - a glk window):
 	(- ResumeTextInput({win}); -).
 
+To decide what text is the current line input of (w - glk window):
+	(- WindowBufferCopyToText({w}, {-new:text}) -).
+
+To set the current line input of (w - glk window) to (t - text):
+	(- WindowBufferSet({w}, {-by-reference:t}); -).
+
 Chapter - Glk object recovery
 
 The current glk object rock number is a number that varies.

inform7/Internal/Inter/Architecture32Kit/Contents.w

@@ -9,7 +9,6 @@ Sections
 	Capabilities
 	InfGlk
 	Glk
-	Glk Events
 	Startup
 	State
 	Mathematics

inform7/Internal/Inter/Architecture32Kit/RTPs/EventUnknownWindow.md

@@ -0,0 +1,3 @@
+# Event is on unknown Glk window
+
+A Glk event has occurred which references a window we don't know about. This could be caused by old extensions which created their own windows in Inform 6. Inform now requires such extensions to also create a `glk window` object and keep it updated, so that the events system can track all windows.

inform7/Internal/Inter/Architecture32Kit/RTPs/EventWrongType.md

@@ -0,0 +1,3 @@
+# Glk event phrase called for wrong event type
+
+A Glk event phrase was used for the wrong event type, for example `x coordinate` was used with a hyperlink event.

inform7/Internal/Inter/Architecture32Kit/RTPs/EventWrongWindowType.md

@@ -0,0 +1,3 @@
+# Glk event created for window of wrong type
+
+Glk events can only be created for the appropriate window type. For example, line events can't be created for graphics window, mouse events can't be created for buffer windows. In particular, note that if you create an event without explicitly specifying the window, the main window will be used, which is usually a buffer window.

inform7/Internal/Inter/Architecture32Kit/RTPs/WindowBadGridCursor.md

@@ -0,0 +1,3 @@
+# Grid window cursor row must be >= 1
+
+While the Glk API specifies that coordinates in grid windows are 0-based (meaning the top left is (0, 0)), we use 1-based coordinates, so that the top left is (1, 1).

inform7/Internal/Inter/Architecture32Kit/RTPs/WindowHasActiveLineInput.md

@@ -0,0 +1,3 @@
+# Cannot set current line input of a window with active line input
+
+The `set the current line input` phrase cannot be used for a window which currently has active line input; there'd be no point as the text you set would be overwritten once the player submitted their input. You should only use `set the current line input` while handling a line event, or after using `suspend text input`.