AMOS Interface

Section 9 of this User Manual is devoted to the AMOS Professional Interface. You should be warned that this is a very advanced feature of the system, and will take a while to fully understand, even for experts! Unfortunately there can be no short-cuts with such a technical subject, so please persevere.

Introducing the Interface

Imagine the possibilities of including all of the features of the AMOS Professional Editor inside your own programs, and that they can be controlled directly from the screen via icons, buttons and selectors!

How about a state-of-the-art graphics adventure, with selection boxes for the commands and an interactive inventory on the screen. Or a set of direction keys that display all of the available movements from the current location. Simple simulations could be transformed into complex fantasy worlds, arcade games could have interactive hi-score tables, and animations could be conjured up by the actions and reactions of the player.

Perhaps you are interested in more serious applications. Then imagine an animated data base, complete with intelligent dialogue boxes, or powerful calculators that appear above your program listings on demand. Even the humble File Selector could be transformed beyond recognition!

You can stop imagining now, because all this and more is already available. The control panels used by the AMOS Professional Editor were not written in assembly language or C, they were produced with the help of a built-in dialogue creator which we call the AMOS Professional Interface, and it is waiting to serve you!

The Interface is directly available from your AMOS Professional programs, so anything the Editor can achieve, you can do too! What's more, you have instant access to all of the original Editor messages and graphics, allowing an effortless matching of your own programs to the existing AMOS Professional style. Since the Editor messages are saved as part of the configuration file, it is simple to generate multi-lingual programs, with prompts and buttons available in a variety of languages.

There is no need to rely on the default settings, and graphics can be designed from scratch, using 16, 32 or even 64 colours. A powerful Resource Creator is provided on the Accessory Disc, allowing images to be grabbed from any IFF picture, and immediately assigned to your icons, buttons and requesters.

And if that hasn't whetted your appetite, see all of this theory in practice now, by running the following ready-made example program:

The need for the AMOS Professional Interface

Experienced AMOS programmers will know that the features demonstrated in the above example program could also be created using standard AMOS screen zones, so why is a separate Interface language required?

In fact, the traditional system may well be useful, but it has many limitations. The SET ZONE command creates a rectangular testing zone around any area of the screen, and this area can be identified if it comes under the mouse pointer, via the MOUSE ZONE function. This is a powerful system, as demonstrated by the Disc Manager and Object editor, but these are massive programs involving huge amounts of work, even for the most experienced of programmers. If you need to generate similar features in your own programs, much time and effort would have to be expended.

Up to now, most AMOS programmers have restricted themselves to simple, two-dimensional displays, using basic graphics. The results compared favorably to Workbench 1.3, but are not acceptable to the AMOS Professional programmer.

With the AMOS Professional Interface, the situation has been completely transformed ! Interactive three-dimensional buttons can be created anywhere on the screen, and made to perform in the most startling way! Control panels are ridiculously easy to create, and they can be handled automatically by AMOS Professional using a powerful interrupt system. Your program only needs to read these buttons and panels at regular intervals and the AMOS Professional Interface takes care of everything else.

Scroll bars are as smooth as silk, and can be dragged directly by the mouse. The improvement over the original VSLIDER and HSLIDER commands is astounding. Selectors can now be generated by a few lines of code, and they can be tailored to any programming need.

The only problem created by the AMOS Professional Interface is the fact that there is so much to absorb! With over one hundred powerful instructions on board, embarking on the Interface can seem a daunting prospect, but fear not, once the fundamental principles have been mastered, everything will fall into place. You will be creating amazing dialogue boxes worthy of a true AMOS Professional!

Introducing the AMOS Professional Interface

The Interface is a complete language in its own right, dedicated to the single task of generating attractive dialogue boxes, buttons and control panels. It works in a similar manner to the AMOS Professional AMAL and MENU languages. Here are the rules of use:

• All Interface programs are entered into strings.
• These strings are brought to life with the standard AMOS Professional functions DIALOG BOX or DIALOG OPEN.
• Each Interface instruction consists of a pair of capital letters. Similarly to AMAL, anything in lower case letters is completely ignored, allowing commands to be expanded and customised for readability and recognition. REM comments can be freely included in Interface listings, as long as no capital letters are used.
• Each command is terminated by a semi-colon character. A colon can also be used for this purpose. Each command must be isolated from its neighbours in this way. Spaces are not enough.

Here is a simple example of an Interface command:

EXit

The EXit command must always be the last instruction in an Interface program. It is used to return to the more familiar environment of AMOS Professional Basic programs, by informing I lie system that the last line of an Interface program has been reached. If the EXit command is omitted, a syntax error will be generated when the routine is tested or run.

Variables and numbers

The AMOS Professional Interface provides a standard way of performing calculations, and saving the results into variables.

All Interface programs have their own list of variables, stored in an internal array. These variables have exactly the same format as ordinary AMOS Professional numbers.

Each variable is referred to by an index number, from zero upwards. However, instead of reading an array in the conventional way, like this:

Interface variables must have the item number placed first, like this:

VAriable

Interface function: return value held by an index
value=index number VA;

VA will return the value associated with the item number index, making it available for your Interface program. As a default, up to 17 variables can be used at one time, but this number can be increased via the DIALOG OPEN command, which is explained later.

Setting a variable

Set Variable

Interface instruction: set an Interface variable
SV index number,value;

Setting a variable for the AMOS Professional Interface is very easy. Simply give the command, followed by the number of the variable to be changed and the value to be entered. Interface variables are not limited to numbers, and complete strings of characters may be assigned as necessary. For example:

The use of quotation' marks in Interface programs is very important. You are recommended to use single quotation marks as above, instead of the conventional double quotes. This will avoid any confusion when Interface commands are typed into an ordinary AMOS Professional string.

Numbers may also be entered in Hexadecimal or Binary notation, if preferred. For example:

PRint

Interface instruction: print contents of a variable to screen
PR x,y,number,ink;
PR x,y,'text',ink;

The PRint command is used to print the contents of a variable. After the command, the target coordinates should be specified, followed by the variable number or the string of characters to be printed. The final parameter is a colour index number, which determines the ink colour to be used. The following example prints a message at coordinates 10,10 using colour 2. Note the use of single quotation marks, which is explained above.

The next example would print the contents of 1 VA at the coordinates 0,100 in ink colour 2:

The hash character # can be used as a special function, which converts a number into a string. It is similar to the normal AMOS Professional STR$ function. When using this, the following syntax must be observed:

Expressions

AMOS Professional Interface expressions have been carefully optimised for speed, which is why they appear very different from the standard system.

All calculations are performed in reverse, with operations and functions after the numbers. So a normal expression like 1+2 is entered as 12+ for an Interface program. Similarly:

To perform more complex calculation's some theoretical understanding is needed. Every time a value is entered into an expression, it is laced on the top of a list of numbers known as a stack. Supposing a stack is represented by this:

3
2
1
0

The stack grows from the bottom upwards, so 3 sits on the top and the zero is sitting at the bottom. Whenever the Interface encounters a number or a string, it is pushed straight to the top of the current stack. But operators are treated differently. When an operator or a function is spotted, the Interface will execute it immediately, grabbing the required values directly from the stack. After the calculation has been performed, the result is replaced back onto the current stack. This process continues until the Interface reaches the end of the expression.

Here is a theoretical calculation of one of these expressions, in this case how the result of 21 is evaluated from the expression 23+ 4*1+

23+4*1+=54*1+
54*1+=20 1+
20 1+=21

That expression is evaluated strictly from left to right. The 2 and the 3 are first placed onto the stack and are then added together by the plus sign, giving a result of 5. The 4 is now loaded onto the stack to be multiplied by the item immediately below it, which is the 5 that resulted from the last operation. This gives a value of 20, and this new value is loaded onto the stack to be added to the item below, generating a final value of 21.

It is important to realise that the stack is only retained during the current calculation. It has no permanent existence whatsoever! This means that after the expression has been calculated, exactly one value must be left in the stack, otherwise a syntax error will be generated.

Here is a table of the available arithmetic operators:

A separate set of logical operators that can be used to perform tests is explained in Chapter 9.2.

Resources

Each Interface program has access to a number of objects, known as resources. These resources contain a set of images to be used for background effects, as well as a list of messages for titles or interactive buttons. There is a Resource Editor program on the Accessory Disc, which can be installed into a permanent memory bank ready for instant use. As a default, the Interface grabs the internal resources assigned to the Editor, allowing a complete range of useful images to be employed in your own programs. Resources are examined in detail in Chapter 9.4.

Calling an AMOS Professional Interface program

DIALOG BOX

function: display dialogue box on screen
button=Dialog Box(Interface$)
button=Dialog Box(Interface$,value,parameter$,x,y)

To display a requester or dialogue box, the DIALOG BOX function is used to handle your Interface commands from the specified Interface string. This dialogue now waits for either an appropriate button to be selected, or until a specific period of time has elapsed. The system then returns to the AMOS Professional main program, returning the value of the button. The dialogue box can be quit at any time by pressing Ctrl + C. If this is done, a value of zero will be returned.

The Interface$ parameter is a normal AMOS Professional string, containing the Interface program. This may be followed by various optional parameters:

The optional value parameter contains a value that is loaded straight into the internal variable array. It can then be accessed using the VA function, from the dialogue box, or requester.

Parameter$ holds an optional string parameter which will be forwarded to the Interface program. It will be saved as item 1 of the variable array (1 VA).

Finally, the optional coordinates x,y are given, to position the dialogue box on screen. These coordinates may be overridden by a BAse command inside the Interface program, and this is explained later. Here are some examples:

Please note that if the Interface program is to wait for user input, a RunUntil command must be included before the final EXit, otherwise the dialogue box will jump directly to the main AMOS Professional program after the last Interface program instruction. RunUntil is explained in detail below.

The DIALOG BOX facility is only intended for simple requesters. To control the dialogue directly from an AMOS Professional program, the DIALOG OPEN and DIALOG RUN commands must be used instead. These are fully explained at the beginning of Chapter 9.3, which is devoted to advanced control panels.

Creating a simple requester

If a large requester with a lot of graphics is to be generated, it can be very difficult to keep track of all the coordinates. You can simplify things enormously by entering all the coordinates relative to the top left-hand corner of the requester box.

BAse

Interface instruction: set coordinate base for dialogue box
BA x,y;

The BAse command sets the reference point for all future coordinate calculations, and is used by simply setting the screen coordinates of the new origin. The default coordinate values are 0,0.

If this command is called more than once, the new BAse setting will replace the previous one. This coordinate reference point can also be set using the x,y parameters with the DIALOG BOX command, as explained earlier. Here is a working example:

Saving the background graphics

The simple drawing operations used in these examples would destroy any existing graphics on the screen. But AMOS Professional dialogue boxes should wink into place over an existing display, and then return the screen to its original state after use. The Interface includes commands that do exactly that!

SIze

Interface instruction: define the size of graphics to be saved
SI width,height;

The SIze command sets the size of the dialogue box on the screen, and prepares the Interface system to save the background graphics. The location of this screen area is set by giving the number of pixels for the width of the zone, followed by the number of pixels for its height, measured relative to the reference point already set by the BAse command.

SAve

Interface instruction: save background under the dialogue box
SA block number;

This is used to save the graphics defined by the previous BAse and SIze commands. The area that is saved into memory will be restored to the screen after the Interface program reaches its final EXit instruction. Give the SAve command, followed by the number of a memory block to be used for the graphics. If this has already been defined, it will be replaced by the new definition.

Note that each new control panel can save its own background area independently. Blocks will be re-drawn in reverse order when the dialogue panel is removed. If there is insufficient memory, an error will be generated when the program is initialised.

Supposing a dialogue box is to be positioned from coordinates 50,50 to 210,110. The following sequence of instructions could be used:

Unfortunately, when that example is run, the graphics will be removed from the screen immediately after they have been drawn! This is because DIALOG BOX executes the entire Interface program in a single burst, and jumps back to the main AMOS Professional program as soon as it is completed. In order to use a dialogue box, the Interface must be instructed to wait for an event of some sort. To make that example work properly, read on!

Waiting for an event

RunUntil

Interface instruction: run until conditions are satisfied
RU delay,flags;

This command runs an Interface program from the first command, and activates all buttons and sliders that have been defined in the dialogue box. The box now waits on screen, until a specific set of conditions have been satisfied.

These conditions can be anything from pressing Ctrl + C, selecting a [Quit] icon, or simply hitting a key. The requester may also be displayed for a specific amount of time. If the original screen contents have been saved using the SAve command, they will be restored to normal as soon as the program returns to AMOS Professional Basic.

The RunUntil command is ideal for use with dialogue boxes that do not need to interact with the main AMOS Professional program.

The delay parameter holds the interval time for the dialogue to remain on screen, specified in 50th of a second. If this value is greater than zero, the box will automatically exit after the chosen period has elapsed, with no n ed for any user input. On the other hand, a value of zero will wait patiently for a user response, or until the conditions specified in the flag values have been met.

The flag parameter is a simple bitmap, with a value of 1 in the relevant position activating the feature, and a zero disabling it. Here are the settings:

You can now display a crude requester on the screen, by changing the last working example as follows:

Requesters serve a useful purpose, but real control panels need to employ buttons, icons and slider bars. The AMOS Professional Interface makes this very easy, and offers a large selection of options.

The last part of this Chapter deals with simple button commands Advanced control panels will be explained in Chapter 9.3. All these commands are used to display an object on the screen which is automatically assigned its own zone, and can then be manipulated in a variety of ways.

Interface buttons

BUtton

Interface instruction: define an Interface button
BU number,x,y,width,height,setting,minimum,maximum;[ ][ ]

The BUtton command defines a simple Interface button, which can then be selected directly using the mouse. This button system is very flexible, and can be used to generate dozens of different button types in a few simple lines of code.

These buttons can be read in several ways. If the RUn command has been used in the program the button value that has been selected will be returned immediately by a DIALOG BOX or DIALOG RUN command. Alternatively, a background dialogue box can have its buttons read directly from an AMOS Professional main program, which is explained later.

Here are the BUtton command parameters, in order:

After the BUtton instruction, the number of the button is specified, from 1 upwards. If several buttons are to be linked together, they can be assigned the same number without causing any problems at all. Each button can be individually tested by the RDIALOG function in an AMOS Professional main program.

The x,y coordinates hold the position of the button, relative to the BAse setting of the dialogue box.

The width and height parameters determine the size of the rectangular test zone that is to enclose the new button, and are given in pixels as usual.

Setting refers to an initial value setting for the new button, starting from zero. This indicates the actual appearance of the position of the button on screen. In the case of a simple ON/OFF button, a value of zero could indicate OFF, while 1 would indicate an ON setting. Normally, the value of this setting will increase by one every time the button is "clicked", but this may be changed directly, within your new button definition.

The minimum and maximum parameters are used to set the range of the allowable button settings. If the button exceeds the maximum limit, it is automatically set back to the minimum setting.

After these parameters have been specified, you are ready to draw the button on the screen. This is defined using a simple list of Interface commands enclosed in square brackets. These instructions can feature anything, including any of the Interface graphics operations. The semi- colon in front of the first square bracket is essential!

The drawing routine is first called when the button is initialised, and it is performed again every time the button is activated by the user.

At the beginning of the routine, the coordinate base is moved to the specified x,y position, and the Size is set to the specified width and height. So all drawing operations are relative to the start position of the current button. This means that there is no need to know the final location of the button on the screen, so the button may be moved around by simply changing the original coordinate values in x,y. The same drawing routines can also be used for several different buttons.

There is a second set of square brackets, which can remain empty, or contain optional commands. These are used to define any "change" routine, to be called every time the button is released.

Note that there is no semi-colon after this final set of brackets. if one is included a syntax error will be generated when the program is run. Beware of making this very easy mistake!

Whenever a button is selected by the user, the AMOS Professional Interface performs the following sequence of actions:

• The button setting is incremented by one, and this new setting is compared to the values held in the minimum and maximum parameters.
• The commands held in the button drawing routine are now executed on screen.
• The system waits for the mouse key to be released
• If it has been defined, the "change" routine is now performed. This can change the setting value of any button on the screen, allowing you to link several buttons together. If the "change" commands move one or more buttons to a new setting, they will be updated with an appropriate call to the relevant drawing routine.

Here are some examples of button definitions:

ButtonQuit

Interface instruction: trigger an exit button
BQ;

There are special buttons featured in the Editor requesters, such as [Ok] and [Cancel], which are used to leave the dialogue box the moment that they are selected by the user. These "Exit" buttons are created using the Button Quit instruction. This command can be placed inside the "change" brackets in order to trigger a forced exit from the dialogue box after the button has been selected. For example:

Drawing a button

Buttons can be drawn in a variety of styles, using any of the Interface graphics commands. A full list of all these commands is fully explained in Chapter 9.2. Here are some typical options:

Text buttons can be created by enclosing the required text with a box or a filled bar, as follows:

Vertical buttons can be drawn using the Vertical Text command, like this:

Graphical Icons can be generated using a packed image held in the Resource bank. They can be displayed with a simple call to the UNpack command, as follows:

Complex buttons may be produced using a packed picture as the background, along with any combination of the Interface text and graphics commands. The background can also be generated from a whole line of images, using the powerful LIne command. Here is a ready- made example to examine:

Changing a button

The ability to call an Interface routine whenever the status of a button is changed allows a range of useful effects to be generated. The key to these effects is held by three Interface button functions, BPosition, BReturn and BChange.

BPosition

Interface function: return the setting inside a button definition
setting=BP

After a normal button is created with a BUtton definition, the position of the current setting can be read straight from the drawing routine, using a simple call to the BPosition function. BPosition returns a value from the minimum to maximum, depending on the current setting of the button. It can be used to flick the image of the button ON or OFF as part of the drawing routine, so that there is one image for the selected button, and a different appearance for the original version.

This can be used in a number of ways. Here are some examples for changing the colour of text or background, using the INk command:

As mentioned earlier, another possibility is to display a packed image from the resource bank.

The value of BPosition can be use4 to choose between two pictures representing ON and OFF in the following way:

The same technique can be used to generate buttons with a number of different positions. All that is required is to specify the appropriate values of the setting, minimum and maximum parameters in your button definitions, then test BPosition as part of the main drawing routine. Here is a ready-made example using this system:

BReturn

Interface instruction: change the setting of a button
BR new setting;

This instruction can only be used inside a dialogue change routine, which is held in the second pair of square brackets, as explained earlier. BReturn moves the button to the specified new setting, and changes the value of BPosition. It then calls up the original drawing routine to update the display. If this includes the BPosition function, the effect can be seen immediately.

This feature can be used to return the button to its original state, after the mouse key is released. If it is omitted, the button will stay in its current setting until it is chosen once more. Here is a schematic example:

BChange

Interface instruction: change the setting of any active button
BC number,new setting

An alternative way to change the setting of a button is to make it behave like a radio button. Here, only one of a group of buttons may be switched on at any time, and as soon as it is "on" the other related buttons automatically appear to be switched "off".

The BChange command is used to alter the setting of any active button on the screen, simply by specifying the number of the button or buttons that are to be changed, followed by the new setting required.

If many buttons are to be affected by this technique, the process can be simplified by assigning them all to the same identification number. Note that BChange has no effect on the current button, even if it is specifically given in the instruction. To change the setting of the current button, the BReturn command should be used instead.

Here is an instant working example of every button type:

Keyboard short-cuts

Any of your buttons can be optionally assigned to an equivalent control-key combination from the keyboard.

KY

Interface instruction: set keyboard short-cut
KY ascii,shift

The KY command requires two parameters. The first is the Ascii code of the chosen key (scan codes can be entered by simply adding 128 to their value). The shift parameter is a bitmap which allows a test to be made for one or more control keys, and the default value is zero. The full list of possibilities is explained under the KEY SHIFT function in Chapter 10.1.

Once the keyboard short-cut has been defined, the button may be activated by pressing the appropriate key. This will click the button on screen and release it immediately. Here are some example settings:

NoWait

Interface instruction: specify a quick release button
NW;

It is often necessary for buttons to take effect immediately, without waiting for the mouse key to be released. The NoWait command is provided for this purpose, and it is normally used with a BQuit instruction, or with routines that need to interact directly with an existing AMOS Professional program. It is used like this: