-
Notifications
You must be signed in to change notification settings - Fork 4
/
sect10.html
262 lines (216 loc) · 9.12 KB
/
sect10.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
<!DOCTYPE html>
<html>
<head>
<title>The Z-Machine Standards Document</title>
<link rel="stylesheet" type="text/css" href="zspec.css">
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
</head>
<body>
<img class="icon" src="images/icon10.gif" alt="">
<h1>10. Input streams and devices</h1>
<hr>
<p>10.1 <a href="#10.1">Keyboard only in V1</a> /
10.2 <a href="#10.2">Input streams</a> /
10.3 <a href="#10.3">Mouse support</a> /
10.4 <a href="#10.4">Menu support</a> /
10.5 <a href="#10.5">Terminating characters and timed input</a> /
10.6 <a href="#10.6">Single keypresses</a> /
10.7 <a href="#10.7">Reading ZSCII from the keyboard</a>
</p>
<hr>
<h2 id="10.1">10.1</h2>
<p>In Versions 1 and 2, the player's commands can only be
drawn from the keyboard.
</p>
<h2 id="10.2">10.2</h2>
<p>In Versions 3 and later, the player's keypresses are drawn
from the current "input stream". There are two input streams:
numbered 0 (the keyboard) and 1 (a file containing commands).
Other inputs (mouse clicks or menu selections), if available,
are also implemented as keypresses (see below).
</p>
<h2 id="10.2.1">10.2.1</h2>
<p>The format of a file containing commands must be the same as
that written in output stream 4.
</p>
<h2 id="10.2.2">10.2.2</h2>
<p>The game can change the current input stream itself, using
the opcode <strong>input_stream</strong>. It has no way of finding out which input
stream is currently in use. An interpreter is free to change the
input stream whenever it likes (e.g. at the player's request) or,
indeed, to run the entire game under input stream 1 (for testing
purposes).
</p>
<h2 id="10.2.3">10.2.3</h2>
<p>When input stream 1 is first selected, the interpreter may
use any method of choosing a file name for the file of commands. (Good
practice is to use the same conventions as when choosing a filename
for output to stream 4.)
</p>
<h2 id="10.2.4">10.2.4</h2>
<p>When the the current stream is stream 1, the interpreter
should not hold up long passages of text (by printing "[MORE]"
and waiting for a keypress, for instance).
</p>
<h2 id="10.3">10.3</h2>
<p>Mouse support is optional but can be provided in Versions 5 and
later.
</p>
<h2 id="10.3.1">10.3.1</h2>
<p>In a game which wishes to use the mouse, bit 5 of 'Flags 2'
in the header should be set in the story file. If it wishes to read
the mouse position after clicks, it must provide at least the first
two words of a header extension table. (Note that Inform 6.12 and
later always provide a header extension table at least this large,
but Inform 6.11 and earlier never provide an extension table at all.)
</p>
<h2 id="10.3.1.1">10.3.1.1</h2>
<p>If the interpreter cannot offer mouse support, then it
should clear bit 5 of 'Flags 2' to signal this to the game.
</p>
<h2 id="10.3.2">10.3.2</h2>
<p>Whenever a mouse click takes place (and provided the header
extension table exists and contains at least 2 words) the interpreter
should update the coordinates as follows:
</p>
<pre>
Word 1: x coordinate where click took place
Word 2: y coordinate where click took place
</pre>
<h2 id="10.3.3">10.3.3</h2>
<p>The mouse is presumed to have between 0 and 16 buttons.
The state of these buttons can be read by the <strong>read_mouse</strong> opcode
in Version 6. Otherwise, mouse clicks are treated as keyboard
input codes (see below).
</p>
<h2 id="10.3.4">10.3.4</h2>
<p>In Version 6, the mouse can either be free or constrained
to one of the 8 windows: if so, clicks outside the 'mouse window'
must be ignored, and the interpreter is at liberty to confine the
mouse's movement to the boundary of its window.
</p>
<h2 id="10.4">10.4</h2>
<p>Menu support can optionally be provided in Version 6.</p>
<h2 id="10.4.1">10.4.1</h2>
<p>In a game which wishes to use menus, bit 8 of 'Flags 2'
in the header should be set in the story file.
</p>
<h2 id="10.4.1.1">10.4.1.1</h2>
<p>If the interpreter cannot offer menu support, then it
should clear bit 8 of 'Flags 2' to signal this to the game.
</p>
<h2 id="10.4.2">10.4.2</h2>
<p>Menus are numbered from 0 upwards. 0, 1 and 2 are reserved for
the interpreter to manage (this system has only been implemented on
the Macintosh, wherein 0 is the Apple menu, 1 the File menu and 2 the
Edit menu). Menus numbered 3 and upwards can be created or removed with
the <strong>make_menu</strong> opcode.
</p>
<h2 id="10.4.3">10.4.3</h2>
<p>Menu selection is reported to the game as a keypress
(see below). Details of what selection has been made are read with
<strong>read_mouse</strong>.
</p>
<h2 id="10.5">10.5</h2>
<p>Whole commands are read from the input stream using the <strong>read</strong>
opcode. (Note that this has two different internal names in Inform,
<strong>sread</strong> for Versions 1 to 4 and <strong>aread</strong> subsequently.)
</p>
<h2 id="10.5.1">10.5.1</h2>
<p>In Versions 1 to 3, the interpreter must redisplay the status
line before it begins accepting input.
</p>
<h2 id="10.5.2">10.5.2</h2>
<p>Commands are normally terminated by a new-line (a carriage
return or a line feed as appropriate for the machine's keyboard or
file format).
</p>
<h2 id="10.5.2.1">10.5.2.1</h2>
<p>In Versions 5 and later, the game may provide a
"terminating characters table" by giving its byte address in
the word at <strong>$2e</strong> in the header. This table is a zero-terminated
list of input character codes which cause <strong>aread</strong> to finish the
command (in addition to new-line). Only function key codes are
permitted: these are defined as those between 129 and 154
inclusive, together with 252, 253 and 254. The special value
255 means "any function key code is terminating".
</p>
<h2 id="10.5.3">10.5.3</h2>
<p><strong>***</strong>
In Versions 4 and later, an interpreter should ideally
be able to time input and to call a (game) routine at periodic
intervals: see the <strong>read</strong> opcode. If it is able to do this, it
should set bit 7 of 'Flags 1' in the header.
</p>
<h2 id="10.6">10.6</h2>
<p>In Versions 4 and later, individual characters can be read
from the current input stream, using <strong>read_char</strong>. Again, the interpreter
should ideally be able to time input and to call a (game) routine at
periodic intervals. If it is able to do this, it should set bit 7 of 'Flags
1' in the header.
</p>
<h2 id="10.7">10.7</h2>
<p>The only characters which can be read from the keyboard
are ZSCII characters defined for input (see <strong>§</strong> 3).
</p>
<h2 id="10.7.1">10.7.1</h2>
<p>Every ZSCII character defined for input can be returned
by <strong>read_char</strong>.
</p>
<h2 id="10.7.2">10.7.2</h2>
<p>Only ZSCII characters defined for both input and output can
be stored in the text buffer supplied to the <strong>read</strong> opcode.
</p>
<h2 id="10.7.3">10.7.3</h2>
<p>The "escape" code is optional: that is, an interpreter
need not provide an escape key. (The Inform library clears and
quits menus if this code is returned to <strong>read_char</strong>.)
</p>
<hr>
<h2 id="remarks">Remarks</h2>
<p>Menus in 'Beyond Zork' define cursor up and cursor down as terminating
characters, and make use of <strong>read</strong> in the upper window.
</p>
<p>Mouse co-ordinates, whether returned by <strong>read_mouse</strong> or written
into the header during input, are always relative to the top of the display
at (1,1), regardless of the position of the current mouse window.
</p>
<p><strong>read_mouse</strong> is realtime. When called it must read the current mouse
location, whether or not the mouse is inside the current mouse window. Interpreters
are allowed to show positions and button states outside the
Z-machine screen if the pointer is outside the interpreter's own user
interface (using negative values if needed).
</p>
<p>Programs must be prepared to cope with this. For example in a painting
program you might want to ignore all buttons down outside the screen. When
dragging something you might want to keep trying to follow the pointer, even
outside the screen, until the buttons are released.
</p>
<p>Interpreters may constrain the pointer to the screen as long as buttons are
held down - this might aid dragging operations - although this is not
required.
</p>
<hr>
<p>
<a href="index.html">Contents</a> /
<a href="preface.html">Preface</a> /
<a href="overview.html">Overview</a>
</p>
<p>Section
<a href="sect01.html">1</a> / <a href="sect02.html">2</a> /
<a href="sect03.html">3</a> / <a href="sect04.html">4</a> /
<a href="sect05.html">5</a> / <a href="sect06.html">6</a> /
<a href="sect07.html">7</a> / <a href="sect08.html">8</a> /
<a href="sect09.html">9</a> / <a href="sect10.html">10</a> /
<a href="sect11.html">11</a> / <a href="sect12.html">12</a> /
<a href="sect13.html">13</a> / <a href="sect14.html">14</a> /
<a href="sect15.html">15</a> / <a href="sect16.html">16</a>
</p>
<p>Appendix
<a href="appa.html">A</a> / <a href="appb.html">B</a> /
<a href="appc.html">C</a> / <a href="appd.html">D</a> /
<a href="appe.html">E</a> / <a href="appf.html">F</a>
</p>
<hr>
</body>
</html>