-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path09-02-interface-language.html
625 lines (469 loc) · 27.8 KB
/
09-02-interface-language.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
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
<!doctype html>
<html lang="en">
<head>
<!--
This Amos Professional Manual is written by asymetrix for the Amiga community and should stay completely FREE FOREVER.
Created 2008. :)
It was created from the original AMOS Professional Manual by Europress Software Ltd.
It has been updated by Fredrik Rambris.
-->
<title>Interface Language - AMOS Professional Manual</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<meta name="keywords" content="Amos Professional, Amiga, Programming, Basic, Francois Lionet, Europress Software Ltd, Amos, computing, code, AmigaDOS">
<meta name="author" content="asymetrix,Fredrik Rambris">
<link rel="GitHub" href="https://github.com/fredrik-rambris/amospromanual">
<meta property="og:site_name" content="AMOS Professional Manual">
<meta property="og:image" content="https://amospromanual.dev/images/cover.jpg">
<link rel="stylesheet" type="text/css" href="styles.css">
<link rel="canonical" href="https://amospromanual.dev/09-02-interface-language.html">
</head>
<body>
<section>
<h1>Interface Language</h1>
<p>
This Chapter deals with all of the AMOS Professional Interface general purpose programming
commands.</p>
<p>
The Interface is a complete language, and includes a full set of general instructions that can be
used to great effect in dialogue boxes. There is an extensive range of graphics commands, a
testing facility and a pair of important program control instructions for making jumps. The
Interface even provides fully-operative procedures and user-defined functions!</p>
<section id="01-the-graphics-functions">
<h2>The graphics functions</h2>
<p>
When defining a number of buttons, it is important to be able to arrange them neatly as part of
the display. The AMOS Professional Interface provides a number of simple functions to
shoulder the burden of these problems.</p>
<p>
As usual, these functions read their values directly from the number stack, so the numbers go
before the operations.</p>
<h3 class="command" id="intf-bx">B<span>ase</span>X</h3>
<h3 class="command" id="intf-by">B<span>ase</span>Y</h3>
<p><i>Interface functions: get the coordinate base location</i><br>
x=<b>BX</b><br>
y=<b>BY</b></p>
<p>
These functions are used to return the screen coordinates that are to be used as the starting
point for all future calculations. These values are assumed to have been previously set with the
BAse instruction.</p>
<p>
<h3 class="command" id="intf-sx">S<span>ize</span>X</h3>
<h3 class="command" id="intf-sy">S<span>ize</span>Y</h3>
<p><i>Interface functions: get the size of the dialogue box</i><br>
width=<b>SX</b><br>
height=<b>SY</b></p>
<p>
Use these functions to provide the precise dimensions of the current dialogue box, as set with
the SIze command.</p>
<h3 class="command" id="intf-sw">S<span>creen</span>W<span>idth</span></h3>
<h3 class="command" id="intf-sh">S<span>creen</span>H<span>eight</span></h3>
<p><i>Interface functions: read dimensions of the current screen</i><br>
width=<b>SW</b><br>
height=<b>SH</b></p>
<p>
The SW and SH functions find the height and width of the current AMOS Professional screen.
They can be used in conjunction with the SX and SY functions to position a dialogue box neatly
in the centre of the display. For example:</p>
<code class="prefix ex">Size 240.100;
BAse SW SX 2/-,SH SY 2/-;
</code>
<p>
The next pair of functions keep track of the graphics cursor. This is automatically positioned at
the location of the last drawing operation on the screen.</p>
<h3 class="command" id="intf-xa">XA</h3>
<h3 class="command" id="intf-ya">YA</h3>
<p><i>Interface functions: get previous coordinates of graphics cursor</i><br>
x=<b>XA</b><br>
y=<b>YA</b></p>
<p>
XA and YA retain a copy of the graphic coordinates, at their position <b>before</b> the most recent
graphics operation was performed. This pair of values can be very useful when objects need to
be defined relative to one another, as you will only have to set the coordinates of the first object,
and all of the others will be relative to it. For example:</p>
<code class="prefix ex">GraphicSquare 10,10,30,30; draw a box at 10,10
GraphicSquare XA,40,XA 20+,30; draw a box immediately below at 10,40
</code>
<h3 class="command" id="intf-xb">XB</h3>
<h3 class="command" id="intf-yb">YB</h3>
<p><i>Interface functions: get current coordinates of graphics cursor</i><br>
x=<b>XB</b><br>
y=<b>YB</b></p>
<p>
These two functions complement the previous pair, and they return the position of the graphics
cursor after the execution of the most recent instruction. Here are some schematic examples:</p>
<code class="prefix ex">BUtton 1,160,100,...;[][]
BUtton 2,XB,YA,...;[][]
</code>
<code class="prefix ex">PRint 0,8,"Hello, first line",2;
PRint XA,YB,"This line will be directly under!",2;
</code>
</section>
<section id="02-the-graphics-commands">
<h2>The Graphics Commands</h2>
<p>
Here are all of the AMOS Professional Interface graphics commands. They fall into the following
main groups: boxes and bars, lines and outlines, and the text commands. Most of these Interface
instructions are very similar to their normal AMOS Professional equivalents.</p>
</section>
<section id="03-boxes-and-bars">
<h2>Boxes and Bars</h2>
<h3 class="command" id="inti-gb">G<span>raphic</span>B<span>ox</span></h3>
<p><i>Interface instruction: draw a filled box</i><br>
<b>GB</b> x1,y1,x2,y2;</p>
<p>
To draw a box that is filled with the current colour, the GraphicBox command is followed by
familiar top left-hand corner coordinates, and then the coordinates of the diagonally opposite
corner.</p>
<p>
All coordinates are measured from the start location of the dialogue box, which can be set by the
Interface instruction BAse, or the AMOS Professional command DIALOG BOX. The default
position is the top left-hand corner of the screen.</p>
<h3 class="command" id="inti-in">IN<span>k</span></h3>
<p><i>Interface instruction: set current drawing colours</i><br>
<b>IN</b> pen,background,outline;</p>
<p>
The colours for boxes and bars and all future drawing operations are set by the INk command.
The three parameters are as follows:</p>
<p>The pen parameter is set by the colour index number to be used for drawing all future items.</p>
<p>
The background colour is then chosen for filling bars and for the paper colour on which text is to
be printed. This option is usually ignored, because the background is completely transparent,
but it may be activated using a SetWriting mode, which is explained later.</p>
<p>
The third parameter to be set is for the outline colour of a bar. This is only relevant if the outline
mode has been switched on, using a previous SetPattern instruction, also explained later.</p>
<p>
If one of these settings is to be left unchanged, simply enter a negative value for the relevant
colour number. As you may expect, a wide range of fill patterns can also be used.</p>
<h3 class="command" id="inti-sp">S<span>et</span>P<span>attern</span></h3>
<p><i>Interface instruction: set the fill pattern for dialogue box</i><br>
<b>SP</b> pattern number,outline mode;</p>
<p>
The Interface SetPattern command is a combination of the normal SET PATTERN and SET
PAINT instructions, and it is used to set the fill pattern and toggle the outline mode of all
subsequent GraphicBox commands.</p>
<p>
The pattern for all future drawing operations is an index number from zero to 34. The outline
mode can be set to zero to turn it off completely, or to 1 to activate the feature. If the setting is
activated, bars will be automatically enclosed by a hollow box in the current outline colour.</p>
<p>To generate a hollow box in its own right, the next command is used.</p>
<h3 class="command" id="inti-gs">G<span>raphic</span>S<span>quare</span></h3>
<p><i>Interface instruction: draw a hollow rectangle</i><br>
<b>GS</b> x1 ,y1 ,x2,y2;</p>
<p>
This is the equivalent to the normal BOX command, and it is used to draw a hollow rectangle,
determined by the coordinates of the top left and bottom right-hand corners.</p>
</section>
<section id="04-lines-and-outlines">
<h2>Lines and Outlines</h2>
<h3 class="command" id="inti-sl">S<span>et</span>L<span>ine</span></h3>
<p><i>Interface instruction: set the style of a line</i><br>
<b>SL</b> pattern;</p>
<p>
This is identical to the SET LINE command, and is used to design the style of all future line
drawing. The pattern for the line style is set by the combination of "dots and dashes" in binary
format. For example, this example would set a line style of equal solid and blank components:</p>
<code class="prefix ex">SLine %1111000011110000;</code>
<p>
<b>G</b>raphic<b>L</b>ine<br>
<i>Interface instruction: draw a line on the screen</i><br>
<b>GL</b> x1,y1,x2,y2;</p>
<p>
This command draws a graphical line from coordinates x1,y1 to x2,y2, like the normal DRAW
command. As usual with Interface commands, the starting coordinates are measured from the
BAse position. For example:</p>
<code class="prefix ex">GLine 0,0,100,100</code>
<h3 class="command" id="inti-ge">G<span>raphic</span>E<span>llipse</span></h3>
<p><i>Interface instruction: draw an ellipse or circle</i><br>
<b>GE</b> x,y,radius1,radius2;</p>
<p>
This simple Interface command is used to draw hollow ellipses or circles. The centre of the
figure is set by coordinates x,y relative to the BAse location, and then the height and width of
the figure are set by specifying the length of the appropriate radii in pixels. To draw a circle,
simply specify the same value for both radii.</p>
</section>
<section id="05-displaying-text">
<h2>Displaying text</h2>
<p>
Once the surroundings of the requester have been generated, the following commands will be
needed to display text in these dialogue boxes. The PRint command is examined in <a href="09-01-amos-interface.html">Chapter 9.1</a>,
here are some more instructions to affect the way text is displayed.</p>
<h3 class="command" id="inti-po">P<span>rint</span>O<span>utline</span></h3>
<p><i>Interface instruction: print hollow text with outline</i><br>
<b>PO</b> x,y,'text',outline colour,text colour;</p>
<p>
The PrintOutine command is used 'to call up outlined or stencilled text. This is achieved by
pasting the same text at slightly different positions, and is most effective with larger typefaces.
The parameters are self-explanatory, and consist of the starting coordinates for the text on
screen, the string of text enclosed in single quotation marks and the index numbers of the
outline and text colours.</p>
<p>
One side effect of the PrintOutline command is that the drawing mode is automatically re-set to
transparent, and so a previous opaque setting may need to be changed. This is explained next.</p>
<h3 class="command" id="inti-sw">S<span>et</span>W<span>riting</span></h3>
<p><i>Interface instruction: set the writing mode for text and graphics</i><br>
<b>SW</b> mode;</p>
<p>
Normally, all text and graphics are drawn over a transparent background, allowing them to
merge neatly into the existing display. If you need to set the background colour using an INk
command, you must change the mode to "opaque". The mode parameter that affects this
command uses a value from zero to 7, and is fully explained under the GR WRITING command
in <a href="06-04-graphics.html">Chapter 6.4</a>. A parameter value of zero will set an opaque mode, and a value of 1 re-sets it to
transparent. Use of the PrintOutline command automatically re-sets the mode to transparent.</p>
<h3 class="command" id="inti-sf">S<span>et</span>F<span>ont</span></h3>
<p><i>Interface instruction: select font to be assigned to text</i><br>
<b>SF</b> number,style;</p>
<p>
To change the type font used by a previous PRint or PrintOutline command, use SetFont
followed by the number of the new font to be assigned to the text, and the style to be adopted
by that font. A full explanation of the available styles can be found under the SET TEXT
command in <a href="05-06-text.html">Chapter 5.6</a>.</p>
<p>
If only the style is to be changed, the font remains unaffected when a dummy parameter value,
such as zero, is used for the font number.</p>
<p>
There are four more simple Interface functions that can be used to manipulate text, which are
self-explanatory.</p>
<h3 class="command" id="intf-tw">T<span>ext</span>W<span>idth</span></h3>
<p><i>Interface function: return the width of current font text in pixels</i><br>
width="text" <b>TW</b></p>
<h3 class="command" id="intf-th">T<span>ext</span>H<span>eight</span></h3>
<p><i>Interface function: return the height of current font in pixels</i><br>
height=<b>TH</b></p>
<h3 class="command" id="intf-tl">T<span>ext</span>L<span>ength</span></h3>
<p><i>Interface function: return the number of characters in a string of text</i><br>
number="text" <b>TL</b></p>
<h3 class="command" id="intf-cx">C<span>entre</span>X</h3>
<p><i>Interface function: centre text in the display</i><br>
position="text" <b>CX</b></p>
<p>
The CentreX function is used to find the correct centring location by comparing the width of the
given text with the value returned by an SX function, like this:</p>
<code>SetVar 0,"Hello, this is the text"
PRint 0VA CentreX,0,0 VA,2;
</code>
<h3 class="command" id="inti-vt">V<span>ert</span>T<span>ext</span></h3>
<p><i>Interface instruction: display vertical text</i><br>
<b>VT</b> x,y,'text',colour</p>
<p>
The VertText command is used to display a column of vertical text using the specified colour
index number, starting at your chosen coordinates.</p>
</section>
<section id="06-labels-and-tests">
<h2>Labels and Tests</h2>
<p>
The AMOS Professional Interface also supports a number of program control instructions,
allowing simple tests to be performed and jumps to be made to various routines. These controls
make it easy to create complex multi-level user interfaces.</p>
<h3 class="command" id="inti-la">LA<span>bel</span></h3>
<p><i>Interface instruction: create a simple label</i><br>
<b>LA</b> label;</p>
<p>
The LAbel command is used to define a marker label in an Interface program. This can them be
employed as the target destination for a JumP or JumpSub command, which are the Interface's
equivalents to the familiar GOTO and GOSUB operations in normal AMOS Professional
programs. It can also be used as an entry point for the DIALOG RUN instruction.</p>
<p>Several complete dialogue boxes can be installed into the same definition string, if required.</p>
<p>
Unlike conventional AMOS Professional programs which recognise any characters for labels,
Interface labels are referred to by <b>numbers</b> only, ranging from zero up to 65535. If a newly
defined label already exists, an error message will be generated. Interface labels are defined in
the following manner:</p>
<code class="prefix ex">LA 10; <comment>set up label number 10</comment></code>
<h3 class="command" id="inti-jp">J<span>m</span>P</h3>
<p><i>Interface instruction: jump to an Interface program label</i><br>
<b>JP</b> label;</p>
<p>
The JumP command transfers control to the Interface instructions that commence with the
selected label number. This label must be defined elsewhere in the Interface program. The JumP
instruction <b>cannot</b> be used inside any of the routines held in square brackets of a BUtton
command. It is used with the single parameter of the target label, like this:</p>
<code class="prefix ex">JumP 10;</code>
<p>
Interface labels are also used to mark the start of various subroutines, which are entered and left
as explained next.</p>
<h3 class="command" id="inti-js">J<span>ump</span>S<span>ubroutine</span></h3>
<p><i>Interface instruction: call an Interface sub-routine</i><br>
<b>JS</b> label;</p>
<p>
The JumpSubroutine command calls up the sub-routine whose beginning is marked by the
specified label number from zero to 65535. Sub-routines may be nested inside one another, with
a maximum of 128 calls that can be made from each routine.</p>
<h3 class="command" id="inti-rt">R<span>e</span>T<span>urn</span></h3>
<p><i>Interface instruction: return from an Interface sub-routine</i><br>
<b>RT</b>;</p>
<p>
An Interface sub-routine must be terminated by a ReTurn command. The Interface program will
now re-commence from the command immediately after the initial JumpSubroutine call. If a
ReTurn call is encountered out of sequence, an error will be generated.</p>
</section>
<section id="07-interface-conditional-tests">
<h2>Interface conditional tests</h2>
<p>
<p>Constructing a test facility inside the AMOS Professional Interface is relatively simple.</p>
<h3 class="command" id="ints-if">IF</h3>
<p><i>Interface structure: Mark start of conditional test</i><br>
<b>IF</b> expression;[routine]</p>
<p>
The familiar IF structure is followed by an Interface expression. When the expression results in a
value of zero (False), any routine held inside the square brackets will be completely ignored, but
if the expression is not zero (True) the bracketed routine will be executed immediately.</p>
<p>
The expression is a normal Interface expression, and all values are taken from the stack in
reverse order! The routine within the square brackets contains a list of normal Interface
commands to be performed if the expression is true.</p>
<p>
There is no limit to the size or the number of these commands, and JUmp as well as
JumpSubroutine calls can be included. User-defined instructions may be accessed, and these are
explained below. It is even possible to include another IF within the square brackets, and
providing the number of opening brackets equals the number of closing brackets, all should be
well. Here is a very simple example of a conditional test:</p>
<code class="prefix ex">IF 0VA 1=; <comment>if the contents of variable zero is equal to one</comment>
[PRint 0,0,'Variable 0 equals 1',5; <comment>then print a message</comment>]
</code>
<p>Here is a table of the available testing operators that can be used for Interface conditional tests:</p>
<table>
<thead>
<tr><th>Operator</th><th>Meaning</th><th>Notes</th></tr>
</thead>
<tbody>
<tr><td>=</td><td>equals</td><td>Gives -1 if two values are equal, otherwise gives zero</td></tr>
<tr><td>\</td><td>not equals</td><td>Gives -1 if two values are unequal. Do not confuse with /</td></tr>
<tr><td><</td><td>less than</td><td>Gives -1 if the first value is less than the second value</td></tr>
<tr><td>></td><td>greater than</td><td>Gives -1 if the first value is greater than the second value</td></tr>
<tr><td>&</td><td>logical AND</td><td></td></tr>
<tr><td>|</td><td>logical OR</td><td></td></tr>
</tbody>
</table>
</section>
<section id="08-user-defined-functions">
<h2>User-defined functions</h2>
<p>User-defined Interface commands are treated in exactly the same way as any of the existing
instructions, and they can be used to create whole libraries of box definitions, button types and
selectors.</p>
<h3 class="command" id="inti-ui">U<span>ser</span>I<span>nstruction</span></h3>
<p><i>Interface instruction: create a user-defined Interface command</i><br>
<b>UI</b> XX,number of parameters;[instruction definition]</p>
<p>
To create a new Interface instruction, use the UI command and then specify the pair of capital
letters that are to represent the name of the new instruction from now on. For example, SB could
be specified to refer to a new command for drawing a ShadowedBox. The new name must not
already be used for an existing Interface command.</p>
<p>
The pair of identification letters is followed by a list of parameter values. Each user-defined
instruction can read up to <b>nine</b> parameter values from the Interface program, these parameters
must be separated by commas, and can be entered directly in the command line. They can now
be read from the new definition routine using the parameter functions P1 to P9.</p>
<p>
Finally, the definition of the user-defined command is specified inside a pair of square brackets.
This definition enters an Interface program to be assigned to the new instruction, and it can
include anything you wish.</p>
<p>
Here is a complete working example of a user-defined instruction that draws a shadowed
dialogue box:</p>
<code class="prefix edit">A$=A$+"BA 50,50;"
A$=A$+"SI 160,60; SA 1;"
A$=A$+"SB 0,0,150,50,5,0,5;"
AS=A$+"PO 10,10,'AMOS Professional',2,4; PR 48,20,'Basic',4;"
A$=A$+"BU 1,90,38,50,10,0,0,6;"
A$=A$+"[ShadowBox 0,0,50,10,1,0,4 BPos+; PR 1,2,'Button',6;][]"
A$=A$+"RU 0,7;EXit;"
A$=A$+"UserInstruction ShadowBox,7; <comment>create shadowed box with seven parameters</comment>"
A$=A$+"[IN P6,0,0; GB P1 P5+,P2 P5+,P3 P5+,P4 P5+; <comment>draw the shadow effect</comment>"
A$=A$+"1N P7,0,0; GB P1,P2,P3,P4, <comment>draw the box at the top</comment>]"
D=Dialog Box(A$)
</code>
<p>
The Interface provides a method of arranging your user-defined instructions so that they
behave exactly like the built-in graphics operations.</p>
<h3 class="command" id="inti-xy">XY</h3>
<p><i>Interface instruction: set graphics variables</i><br>
<b>XY</b> xa,ya,xb,yb</p>
<p>
The XY instruction loads the internal variables XA, YA, XB and YB with the position of the
graphics cursor before and after the new operation.</p>
<p>
The xa,ya parameters hold the values to be loaded into XA and YA, and these store the
coordinates of the graphics cursor before the current operation is performed. Similarly, the xb,yb
parameters enter values to be stored in XB and YB, and they are used to set the position of the
cursor after the new instruction as been executed. So after the new command has done its
work, the internal variables can b set up accordingly. For example:</p>
<code class="prefix ex">'An instruction that draws a box and then prints some text in it.
'XB YB will be at the end of the box, and not at the printed text!
'The syntax for this is TextBox x1 ,y1,x2,y2,text
Userinstruction TextBox,5;
[BOx P1,P2,1,P3,P4; PRint P1 ,P2,P5,1; XY P1 ,P2,P3,P4;]
</code>
<p>
User instructions have a few limitations, which should be remembered. Each command is
restricted to a maximum of nine parameters, identified as P1 to P9, and any user-defined
instruction can call up to a maximum of ten additional UserInstruction commands from the
definition routine.</p>
<p>
One additional problem can occur if you want to create a new button type with a
UserInstruction. You need to save the parameters somewhere safe before you leave your
routine, so that they will be readily available when the new button is selected on the screen. This
problem only occurs if you are defining a zone <b>inside</b> a UserInstruction, and the problem can be
solved by the following instruction.</p>
<h3 class="command" id="inti-sz">S<span>et</span>Z<span>onevariable</span></h3>
<p><i>Interface instruction: save a parameter for the next zone definition</i><br>
<b>SZ</b> value;</p>
<p>
This command is used to set the internal zone variable for the next active zone to be defined.
The value can be a number or a string that you want to save, and the Interface stores it in an
internal buffer, ready for the new Zone definition. You can now use the ZoneVariable function
to poke this value directly into the new zone, so that a "change" routine, held inside the second
pair of square brackets, will work as normal. This function is explained lastly..</p>
<h3 class="command" id="intf-zv">Z<span>one</span>V<span>ariable</span></h3>
<p><i>Interface function: read a zone variable from the internal buffer area</i><br>
value=<b>ZV</b></p>
<p>
This function can only be used inside a change or a draw routine held inside square brackets. It
returns the contents of the internal zone variable, and pokes it into your definition for safe-
keeping. For example:</p>
<code class="prefix ex"><comment>'This user instruction defines a button made of text only
'MyButton zone,x,y,text</comment>
Userinstruction MyButton,4;
[SetZone P4; <comment>save parameter four in the internal buffer zone</comment>
BUtton P1,P2,P3,P4 TextWidth 16+,TextHeight 4+,0,0,1;
[PRint 0,0,ZoneVariable,1][] <comment>zvar permanently installs text into the new button</comment>
</code>
</section>
<section id="09-machine-code-extensions">
<h2>Machine code extensions</h2>
<p>
The final part of this Chapter explains how to add your own machine code extensions directly
into the AMOS Professional Interface.</p>
<h3 class="command" id="inti-ca">CA<span>ll</span></h3>
<p><i>Interface instruction: call a machine code extension</i><br>
<b>CA</b> address;</p>
<p>
The address parameter refers to the address of a machine code program in memory, and the
easiest way to load it is to place it into an Interface variable from the main program. For
example:</p>
<code class="prefix ex">Vdialog(1,0)=Start(6) : <comment>Rem Load 0VA of channel 1 with the address of bank 6.</comment></code>
<p>You can now run your CAll routine using a line like this:</p>
<code class="prefix ex">Vdialog(1,0)=Start(6) : <comment>Rem Load 0VA of channel 1 with the address of bank 6.</comment></code>
<p>
Machine code can be used to modify all registers, and should return with an RTS. All aspects of
using machine code for your AMOS Professional programs are examined in detail in Appendix
A of this User Guide. If you are familiar with assembly language, the following brief information
will be of use:</p>
<p>On entry to your routine, data will be placed in the address registers like this:</p>
<pre>
A6= Program pointer
A5= AMOS datazone
A4= Base of this Dialog Structure
A3= Parameter stack. Use this to grab values from the Interface stack.
</pre>
</section>
<footer>
<a href="09-01-amos-interface.html" rel="prev">AMOS Interface</a>
<a href="./">Contents</a>
<a href="14-appendix-g-command-index.html">Index</a>
<a href="09-03-advanced-control-panels.html" rel="next">Advanced Control Panels</a>
</footer>
</body>
</html>