*************************** TUTORIAL ******************************** This Tutorial is not intended as a substitute for careful reading of the detailed program documentation, and merely talks you through a few first steps. Here the aim is simply to accustom you to the HeliOS programming environment and mention a few important and useful points which will help you to get started. It is quite impossible to satisfy all requirements in an introduction such as this, because HeliOS is aimed at programmers with a wide range of expertise: some may be expert programmers and others may never have tried programming before. If you are in either of these categories, or if you are coming to HeliOS from another very different language like "C" or "Basic", please have patience and give this and the other introductory tutorials a chance to explain some of the very unusual features which make HeliOS possibly the most interesting and powerful programming language for the Amiga. ------------------------------- Before you start reading....... ------------------------------- Before you commit yourself to reading this tutorial, you would probably like to see HeliOS in action, so we have included a range of short demo programs. These programs are very elementary in scope, but will give you some useful source code upon which to build your first HeliOS programming projects. The idea is that these programs should provide you with a few simple building blocks to help you get started. The demo source code files are in the HeliOS:Source directory, and the file names all have a ".src" suffix for easy identification. These source code files are easy to run by proceeding as follows: If you press the "Intpt" button to get into the Interpreter, you will find an Interpreter menu item "Compile file" in the "Compiling" menu. If you use this "Compile file" menu option, you will be presented with a file requester using which you can select a source code file to run. Your selected file will be instantly interpreted, compiled and run. These source code files can also, of course, be loaded into one of the HeliOS editors for inspection and modification, and can also be run directly from the editor. Having seen these demos, please do read this and the other introductory documentation before starting to do any HeliOS programming. ----------------------------------------- IMPORTANT: Setting your Amiga preferences ----------------------------------------- The HeliOS editor in which you are reading this text relies on certain Amiga preferences settings. Even before going on to read this introductory tutorial it is a good idea to ensure that your Amiga preferences are correctly adjusted. Failure to do this will probably mean that you will not get the best performance from the ultra-fast HeliOS editor, and incorrectly set Amiga preference settings can also be responsible for slowing down any other text editors and word processors used on your system. There are two Amiga preferences settings which make a really dramatic difference to the performance of the text editor: these are the mouse button "double-click" timing interval and the keyboard repeat rate. It is a surprising fact that most people never trouble to change these from the original Amiga default settings, and unfortunately the default settings are far too slow. Programming involves much time spent editing text, and in general it is important to be able to operate quickly and efficiently within your editing environment. The HeliOS editor is fast, and has many features designed for quick operation via the mouse or keyboard: it is important to make good use of this potential speed by choosing appropriate Amiga preference settings. ------------------------------ The mouse double-click setting ------------------------------ If you tend to use the mouse frequently in your editing you soon become fairly quick at mouse operations, and you do not really want two fast but distinct mouse operations to be mistaken for a double-click. The left mouse double-click is used in the HeliOS editor to select text block highlight mode, and obviously you do not want to enter this mode by mistake when you are using the mouse to scroll or place the cursor. The standard Amiga double-click setting is so slow that if you do not change it you will frequently select "highlight" mode by mistake in the HeliOS editor: this is a frustrating and annoying experience! It is sensible to set the Amiga preferences double-click interval as fast as is convenient, such that only quite fast double-clicks register as such. Please try this until you are happy with the double click sensing within the HeliOS editor: if you get frequent occurrence of unwanted text highlighting you will need to reduce the double-click sensing interval. ------------------- The key repeat rate ------------------- The keyboard repeat speed has a tremendous influence on the speed and responsiveness of any editor. The HeliOS editor is one of the very fastest on the Amiga, so what is the point of having all this speed if your Amiga preferences are introducing a ridiculous delay between each key operation? Again, the Amiga default keyboard repeat rate is terribly slow, and it is vital to change this if you want to get full performance from the fast HeliOS editors. Try holding down the left and right cursor keys and observe how fast the cursor moves: adjust the key repeat rate until the cursor speed is as fast as you can manage. You will probably find that setting the key repeat to maximum speed results in the best editor responsiveness. ---------------- HeliOS and Forth ---------------- First we should explain that HeliOS is a Forth-like language with many functions similar to that language. Forth may be used as a model to get started with HeliOS, but beware of carrying the analogy too far, since HeliOS is radically different and more advanced in many respects. And it is actually easier, too......! Forth is sometimes (unjustly) thought to be difficult because it uses a stack and "reverse polish notation", as does HeliOS, but you will soon see that this system is very easy to learn and to use. In general fig-FORTH has been used as the model for most of the HeliOS Forth-like functions, because this version of Forth has become the most widely distributed and is more familiar to many people than the later versions of the Forth standard. However, the fact is that there are more HeliOS functions which differ from Forth than those which are similar, and the internal organisation of HeliOS is totally different from Forth. If you want to study fig-Forth in one of the readily available texts, by all means do so, but with care not to assume too much concurrence between the two languages. You will find a good deal of the general program structure of Forth similar to HeliOS, and in particular you will find the use of the stack in Forth very similar to HeliOS. ------------------------------ The Editor and the Interpreter ------------------------------ You are reading this in the HeliOS text editor, which is where you spend most of the time when writing software. When you want to test and run the source code you have written, you pass the code over to the Interpreter. The Interpreter has its own screen, where it handles all matters relating to interpretation, debugging, and compiling. You will have seen already the Interpreter screen, and you can go there any time to experiment with typing code at the command lines: to do this just press the "Intpt" button. Note that you can cut and paste between the Interpreter command lines and the editors, which can often be useful in testing short sections of code. You can also cut and paste freely between any of the HeliOS editors, including the Out editor which "captures" all program output. To copy code from the editor to the command lines use the editor "Copy" function, then move into the Interpreter and use the function "Paste command lines" in the Interpreter "Copy/Paste" menu. To copy code from the Interpreter command lines to the editor use the "Copy command lines" in the Interpreter "Copy/Paste" menu, then enter the Editor and use "Paste". You can run code directly from within the editors, as you will see later, but when you do so the HeliOS system will automatically move you into the Interpreter. Have a look at the menu options and command buttons in the Editor and Interpreter to see the sort of options available and the way functional tasks are divided between the two environments. ------------------ The HeliOS Editors ------------------ Before giving you a short guided tour around the editors, let's look at the easy method of getting started with HeliOS so that in future you will be able to begin editing with the minimum of effort. --------------------- Setting Startup Paths --------------------- Very often you will be working on the same set of files from session to session, or even the same file, so HeliOS allows you to preset the paths in each of the editors to any particular files. Having done so you can start HeliOS and get to the file you require with just three mouse clicks: To set the path for any editor, just load the file whose path you wish to set, then use the "Save All Paths" option in the "Editing" menu. HeliOS will remember the path settings for the file requester in each editor separately, as well as all other important path settings. Let us assume that you have this file in Editor1, and you now use the "Save All Paths" menu option. Next time you start Helios, you will be presented initially with the Interpreter screen as usual. To get back to this file: 1. Press the "Ed 1" button to enter "Editor 1". 2. Press the "Load File" button. This is the red and white downward pointing triangle button to the right of the filename string. This will bring up the file requester with the path and name of your preset file already set. 3. Press the "Ok!" button in the file requester. Your preset file will be loaded without you typing anything and with only three mouse clicks required. If you set each of the editors in this way it can save much time compared with the usual method of using the file requester to navigate to the same place at the start of every session. --------------------- Using the Help System --------------------- Rather than boring you by explaining the obvious here, you can use the built in HeliOS "Help" function to familiarise yourself with the general operation of all the buttons and menus. To enter "Help" mode, either press the "Help" key, press the "Help" button, or use the "Help on user interface" menu option. Now, when you select any button or menu item, you will be presented with a short explanatory text. To get "Help" on normally hidden control panels such as the colour requester, the debugger, or the find/replace panel, you merely need to activate the required panel before entering "Help" mode. Use the "Help" mode now to browse through the buttons and menus of the HeliOS Editor (and the Interpreter too if you wish). Notice that some buttons do more than you might initially suppose, and some have multi-functions, so look at all the options carefully. ------------------------------------- Special use of the Right Mouse Button ------------------------------------- In HeliOS the right mouse button is used for many purposes (such as screen scrolling), and only acts in the usual Amiga "menu-selection" mode when the mouse pointer is positioned over the title bar. If you have used the "Help" system to look around, you will perhaps have noticed that the right mouse button can be used in many places to gain quick access to commonly used commands as a "modifier" to the left mouse button. Here are two very useful examples: 1. Holding down the right mouse button and double clicking the left mouse button will put you instantly into columnar block mode. This is a very useful feature which enables you to cut and past columns of text. 2. Holding down the right mouse button and clicking the left over one of the "Ed x" buttons will compile the file in that editor. You can usually use the SHIFT or CTRL keys instead of the right mouse button, but the right mouse method is quicker once you are used to it. It is worth looking several times through the "Help" system to pick up operational details such as this concerning the main controls and operations you intend to use often. ------------ HeliOS Menus ------------ The HeliOS menus all display command key sequences on the right of the menu text. Notice that HeliOS menus allow unrestriced use of ANY command key sequences, and also that all menu "Hot-keys" are user configurable, along with the menu texts themselves. It is worth noting and learning the command key sequences for those menu commands which you use often. ------------------------------------ Reconfiguring menus and command keys ------------------------------------ Because the HeliOS editor is easy to reconfigure, you may as well learn how to do this as soon as possible so that you can set up the software to suit your own preferences. All editing and menu command keys may be "rebound" in HeliOS, to allow you to set up the HeliOS text editor to emulate any other editor to which you are already accustomed. You can rebind single keys using the "Shortcut options" menu, but you may prefer to edit the master ASCII key definition file. This latter option allows you to view and change ALL the key commands by editing a simple text file. See the "InitialSetup.doc" file and other main documentation for full instructions on how to do this. In addition you can create and save "Macros" which you can use to make your own editing commands. Again, see the main documentation for details on Macros, but the basic idea is that you record a series of commands and attach them to a single keystroke. This is a simple linear recording process very similar to that used in many other word processors and text editors. Because the HeliOS system already uses a very large number of command keys, it is important that you take care not to cause conflicting allocations. The process of rebinding keys and setting up macros is easy in itself, but you do need to study existing allocations and plan your new commands carefully. ------------------ Editing menu texts ------------------ Once you have changed any command keys you will notice that the menus no longer describe the correct command sequences. This is easy to put right because all HeliOS menu texts can be changed by editing an ASCII menu text definition file. In particular, you might wish to edit the "Key Index" menu page to reflect any Macros which you have created and to display the commands which you personally use most often. The "MenuText" configuration file is a simple ASCII file which can be edited in any text editor and which contains its own instructions. See the "InitialSetup.doc" file for instructions on how to set up an initial startup default "MenuText" file. Remember that the default startup file must be called "HeliOS_MenuText" and must be in the same path as the KeyTable file. The most difficult time using any new software is at the beginning, and the sooner you configure everything to suit your own taste, the sooner you will be working productively. ---------------- The Options Menu ---------------- The "Options" menu is a place where you will find many useful settings which you will probably want to experiment with early in your use of the HeliOS editor. Here you can do things like setting the scroll speed to suit your own Amiga system and choosing colours which you find pleasant. In particular we recommend that you experiment with the "Return" menu options, since these can cause the editor to behave in a manner which may be unfamiliar and confusing. In fact most beginners initially dislike the default "AutoIndent Return" setting, which is designed to make life easier for programmers writing indented source code. This option behaves by default quite unlike the majority of word processors, but can be reset to a more standard mode of operation if required. Try it both ways now and see what you think, but remember to try the AutoIndent setting once you are writing source code since you will then find it most useful. Most experienced programmers will find the default setting excellent for editing indented source code but since no other Amiga editor provides this facility you may need time to become accustomed to it. ------------------------ Saving the "Environment" ------------------------ Once you have set everything up to your requirements, do not forget to use the "Save Environment" menu option in the "Editing" menu to preserve your selected settings. ---------------------------------------- The "Status Display" and control buttons ---------------------------------------- Most of the status display at the top of the screen is fairly self explanatory, but as mentioned above several of the control buttons have dual functions. It is worth examining carefully the "Help" text on all these buttons because they control all the most commonly used functions. In particular, do NOT use the "Editorx" button on the left of the file name string gadget until you are very familar with the debugger, since this will instantly enter "debug" mode with the current file. Using the debugger without expertise can be either very confusing or downright disastrous, so please take care! The red and white triangle "Quick Load" button to the right of the file name string gadget is very useful and worth remembering. The red and yellow triangle "Quick Save" button at the far right of the editor status bar is very useful because it "lights up" to warn you when any text has been changed in the editor. Pressing the "Quick Save" button when it is highlighted causes the text in the editor to be saved with the current file name, and then the "Quick Save" button reverts to its neutral colours. It is very useful to remember that pressing one of the "Ed x" buttons with the left mouse button while simultaneously holding down SHIFT or CTRL or R-MOUSE will cause the code in that editor to be instantly compiled and test-run. This is one of the most often used shortcuts, so it is well worth remembering it from the start. --------------------------------------------------------------- A useful little trick for the editor Find/Replace control panel --------------------------------------------------------------- The key can be used to copy strings between the string requesters in the Find/Replace control panel: this is worth remembering because it can save much of the time taken to retype the word in slightly different form. Pressing F1 when using the Search string gadget will copy the current contents of the Search string gadget into the Replace string gadget and then move the cursor down into the Replace string gadget. If the Replace string gadget is switched off (i.e. the Replace function is currently disabled) using F1 in the Search string will fully activate the Replace system before entering the Replace string gadget. Pressing F1 when using the Replace string gadget will copy the current contents of the Replace string gadget into the Search string gadget, while the cursor remains in the Replace string gadget. ----------------------------------- More useful tricks for Find/Replace ----------------------------------- Please read the "Editor_Find&Replace.doc" file to learn about a few more very useful special features of the Find/Replace system...... ------------------------- Compiling HeliOS programs ------------------------- The most common circumstance, certainly while you are learning HeliOS, is that you will be wanting to test and compile a program which you are writing in one of the editors. Another common requirement is to test a small section or subroutine which is just part of the program you are writing in an editor. Look at the small fragment of code below, and imagine that you had just written it and wanted to test it. We are going to test this short routine in a moment, but first here are four important things to check before trying to run ANY program. They may sound simple and even trivial, but casually running code without knowing what you are doing can be a recipe for disaster. 1. Know what the program is meant to do: * You should always know what a program SHOULD do before running it. This little program is intended to allow you to move a small red circle around the screen, overwriting any existing screen graphics. 2. Know how to quit the program: * Always beware of starting up programs which you cannot quit! You will need to press to quit the drawing routine, upon which the program will erase the red circles and rebuild the HeliOS display. 3. Know how the program is going to affect the HeliOS system: * Always be aware of what any program is going to do to the main HeliOS environment - and save your work if there is any risk. When running any source code from an editor, HeliOS always moves first to the interactive Interpreter display, then interprets the source code passed from the editor. Other than this, our little program will not affect the main system. 4. Know what system resources the program is going to change: * Always be aware of what any program is going to do to any part of the Amiga's memory and operating sytem. Since the small "red circle" program uses the HeliOS default graphic output, the program will only write to the HeliOS main display area. After this it will clear the HeliOS display. Now you know what to expect, and you know how to get back to HeliOS by pressing , it is safe to try the program. Because it is just a short routine, you can run it by highlighting the block of text and pressing . Alternatively you could use the "Cut/Paste" menu option named "Compile marked block". Double click the left mouse button with the pointer on the blank line immediately before the line containing the words "Clear the dictionary". This will start the highlighted area. Note that in HeliOS block highlight operations are defined entirely by the reverse video display zone. This means that in HeliOS the highlighted area DOES NOT INCLUDE THE CURSOR, so the single character under the cursor will NOT be included in your highlighted block. Drag the mouse to past the program so that the highlighted area ends on the blank line just after the line containing "Run new program". Hold down the Left Amiga key and press the "e" key. Try out the program, and remember to press the key to quit. Highlight from the NEXT line below this one. FORGET **CORE** \ Clear the dictionary : TUTORIAL1 \ New program name FWINDOW -1 POINTER \ Switch off mouse pointer 1 REPORTMOUSE \ Switch on mouse position reports 1 GFXOUTLINE \ Enable graphic "outline" mode 1 GFXSETOPEN \ Set graphic outline pen to black 6 GFXSETAPEN \ Set foreground drawing pen to red BEGIN \ Start loop GFXWAITTOF \ Wait for new frame MOUSEX MOUSEY 8 4 GFXAREAELLIPSE \ Draw red circle with black outline GFXAREAEND \ Write area drawn to screen ?TERMINAL 27 = \ Wait for UNTIL 0 REPORTMOUSE \ Switch off mouse position reports 0 GFXOUTLINE \ Disable graphic "outline" mode FWINDOW 0 POINTER \ Switch on mouse pointer SCRCLR \ Clear HeliOS text display FSTATUS \ Redraw HeliOS display imagery ; TUTORIAL1 \ Run new program Remember: highlight to the line ABOVE this one, let go of the mouse button, and then hold down the L-Amiga key while pressing the "e" key. Look at the comments in this little program and try changing a few things. For example, try changing the following lines: 6 GFXSETAPEN \ Set foreground drawing pen to red ^ Change this number to alter the colour of the drawing circle. MOUSEX MOUSEY 8 4 GFXAREAELLIPSE \ Draw red circle with black outline ^ ^ Change these numbers to alter the circle/ellipse size. Recompile this small section of code a few times with different values, just to see how things work. Running this little program illustrates how simple it is to test a section of code from within the HeliOS editors. Notice that you are always placed in the interpreter when HeliOS is running any code, and you need to press the "Ed x" button to get back here to the editor. You may be interested at this point to know what happens if there is an error when you are compiling either part or the whole of the source code in any editor. If there is a mistake in your code, the line of text with the mistake is displayed in the interpreter window, and a set of small arrows will point to the error in the code line. Subsequently, when you return to the editor, you will automatically be taken to the error line. Try compiling the line below now, by highlighting it, just as you did the earlier code, and pressing "L-Amiga+e": By the way, make sure that the highlighted area starts BEFORE and goes PAST the ends of the line: if you miss off the last ";" character the compilation will fail. : MISTAKE SCRCLR 2 2 CURPUT ." Hi" 2 4 CURPUUT ." There!" WAITSPACE ; You can see that the mistyping of CURPUUT has been picked up by the HeliOS interpreter, and note that wherever you may have been in the editor you are always be brought back immediately to the error position. Now try highlighting the code line again and this time use the "Copy block" function in the Cut/Paste menu to make a copy of the text. Now go into the interpreter and use the interpreter Cut/Paste menu function to "Past command lines", so that the code line appears in the interpreter command lines. Hit in the interpreter and you will, of course, find that the code fails again. Press the "Cursor up arrow" key to retrieve the previous command line and edit the faulty CURPUUT to the correct version: CURPUT. Now run the code again from the interpreter command lines. This time you should get an OK message. Notice that you keep getting a message telling you that MISTAKE has multiple definitions. This is because MISTAKE does have multiple definitions - you guessed! Each time you try out a new version of a word, the old one remains in the HeliOS dictionary, which can be useful - but we will not try to explain this until you are a little more expert! If you keep recompiling small words like this, you keep consuming tiny amounts of HeliOS dictionary space as each new definition is compiled IN ADDITION TO the old ones. The "Dict" display in the top left corner of the Status Display always shows you how much HeliOS dictionary space is available. Try compiling a few more versions of MISTAKE by pressing the "up arrow" key, followed by , and as you do this observe how the "Dict" display shows a reduced available Dictionary space. It really is a little untidy to keep making multiple copies of every function as you experiment at the command line to improve your code, so you will probably want to know how to remedy this. To clear definitions from the HeliOS dictionary you say FORGET followed by the name of the word you want to forget. For example: FORGET MISTAKE would "forget" the latest copy of MISTAKE. There is one important thing to know about FORGET, and that is that it forgets EVERY word compiled SINCE the target word as well as the target word itself - so take care. Try compiling MISTAKE ten times, watching the dictionary free space display go down. Now use FORGET MISTAKE ten times and watch the dictionary free space go back up again. Usually, in fact, we want to clear all user words to give us a "clean" system, and in this case you use the expression FORGET **CORE**. Try using FORGET **CORE** now to clear the system down to the CORE vocabulary. In general you need not use FORGET after every recompilation from the command lines, and the occasional use of FORGET **CORE** is all that is required to keep the dictionary clear. Never worry about the messages concerning "multiple definitions" since this is only a warning and there are no serious detrimental effects. When you are compiling programs from an editor, it is best to put the line FORGET **CORE** at the start of all your programs. If you do this the system will always be cleared each time you recompile. Notice that the first line of our "Red Circle" program was: FORGET **CORE** \ Clear the dictionary Now, finally, go back to the interpeter and recompile the correct version of MISTAKE. The interpeter said OK, but nothing happened otherwise. You simply compiled the word MISTAKE, which effectively now is a new word within the HeliOS vocabulary. Use the menu option to list the vocabulary and you will see that you have indeed created a new command called MISTAKE. You have not yet, however, run the small program contained in the definition of MISTAKE. To run MISTAKE, you now only need type MISTAKE in the command lines and press . Try it now. All that you have done above will illustrate to you the simple way that HeliOS works by adding new commands to the language. In fact, HeliOS programming consists always in this process of extending the language. As you may imagine, it is not long before you start to build up a new repertoire of commands which YOU have created. The advantage of HeliOS programming is that all these new commands which you create have three absolutely wonderful characteristics: 1. You wrote them yourself to do a job which you required, so you have built a new tool which is very useful to you for ever more. 2. Because you wrote them yourself, you understand them thoroughly. 3. You will have given them NAMES which YOU find appropriate, so you will find them easy to remember and your code will be very readable to you since it uses your own function names. Think about it for a moment, and you will see that programming in HeliOS is like building your very own language, so how could it not be absolutely ideal for your own purposes! After a while you will have built a HeliOS system "in your own image" and you will be able to do far more with it than if you were confined to the straight-jacket of someone else's strict programming system. You can even simply change HeliOS word names which you do not like. Let us suppose that you can never remember a certain word name, for example "WBENCHTOFRONT". Let us suppose that you are really sick of mistyping this stupid long word, and you want to change its name to "WBF". All you need do is use the following line: : WBF WBENCHTOFRONT ; You will now have redefined a new name for WBENCHTOFRONT. Try it, and try typing WBF. Look in the vocabulary and there you have it: WBF! So you can appreciate that once you have moulded HeliOS to fit your own ideas and mode of expression, it will be a powerful and personal tool. -------------------------- Status and debug reporting -------------------------- Notice that when a program finishes the HeliOS system reports the state of the stack etc. into the main window. In fact you normally get full information about program execution time and how long the program took to execute, as well as a stack readout. This information can be switched off, but it is normally quite useful to retain it. How many other languages give you this information automatically? In fact, the reason that the HeliOS display switches to the Interpreter screen while running a program is so that you can view any text messages output while the program is running and when it completes. By default all such text messages go to the main Interpreter screen. One of the most commonly used, and best, debugging methods is to make your program output debug messages while it is running. Simple text messages and stack reports can tell you where your program is going wrong, and often this will be all you need to debug even complex programs. Of course, it can be very annoying if messages output by a program scroll off the screen before you can read them! Everyone has suffered this at one time or another, and if your program is outputting debug messages to the HeliOS screen while running a different display you might never even SEE the messages of course. Some systems get around this problem by using a second computer and a serial port link as a "debug console", but this is hardly convenient for all circumstances. HeliOS has a very nice way of getting around the problem, and it does so by using an editable output review buffer. By default (although this option is switchable) all text output to the main Interpreter window also is output into one of the Editors. This "Output Buffer" editor is called simply the "Out" editor, and is exactly the same as the other three editors except that it receives a full copy of the Output text stream from the Interpreter. You can see the "Out" button at the top of the screen, and you will notice that it has a small red "highlight". This highlight indicates that the option for Interpreter output to be preserved in the "Out" editor is currently "On". You can switch off this feature from the Interpreter menus if you wish, upon which the highlight will be switched off and the "Out" editor can be used as a normal editor. Not only can you switch off this feature and use the "Out" editor as a normal editor; you can also: * Set the size of the output buffer, * Clear the output buffer, * Switch on/off session log markers which identify each output * Switch on/off separator lines between outputs These latter two options allow you to divide up the output text into sections which you can easily relate to individual output sessions. Even program execution times and stack returns are recorded, so that the "Out" editor becomes a full session log and debug report facility. Since you can freely edit, print, save, cut and paste the "Out" editor, you can use it to do many useful things, such as generating programmed text tables etc. This is a another very powerful unique HeliOS feature. Above all though, it is useful to be able to retain debug and error reports, and we recommend that you leave this feature enabled unless you really need to use four editors simultaneously. Look in the "Out" editor now and you will see the full report of your earlier sessions, recorded even complete with the time you did things. ------------------------------ Running complete program files ------------------------------ Running a program which consists of a complete text file is actually even easier than running a highlighted subsection of code. All you need to do is load the program file into an editor, for example "Ed 1", then press the "Ed 1" button at the top of the screen while holding down the right mouse button (or the CTRL or SHIFT key). The HeliOS system will once again switch to the Interpreter screen and run the program. If you look in the Key Index menu you will see that there is a command key for compiling the current editor: this is CTRL+"5". ----------------------------- Experimenting at the keyboard ----------------------------- HeliOS is an easy language to learn at the keyboard and there is no real substitute for creative experimentation. Once you have discovered how simple it is to open screens and windows, and to output graphics and text within an easily comprehensible system, your efforts can soon be directed to really creative programming. The source code files supplied with HeliOS have been included to give you a starting point for your own efforts. All you have to do is load up any of the supplied source code and take from it the sections which interest you. You can very easily elaborate on these simple demonstration programs, and at the same time have all the basic support routines already strung together for you. This saves you the tedium of looking up new words at every turn when you are still learning. HeliOS code can be entered on the lines at the bottom of the Interpreter screen and then, by pressing return, transmitted directly to the HeliOS interpreter. The up and down cursor keys can be used to recover previous input for modification and retrial if required, which makes the system very comfortable for quick keyboard experimentation. For longer and more advanced sections of HeliOS code you can perhaps more easily experiment by entering your code in an editor and compiling it from there, either as a complete file or a marked block. Remember always to save your code to disk before compiling it, just in case the program crashes. The format of your code is quite unrestricted, and it really is a matter of personal taste how you wish to lay things out. Notice that source code comments can be entered in several ways. Long sections of commentary can be entered using the word "(" as follows: ( ................ Commentary ........................................ ................................... Commentary...................... ) The interpreter will skip all material between the two round brackets. Remember that the first round bracket must, like all HeliOS words, have a space before it and a space after it. The second round bracket still needs a preceding and succeeding space, even though it is merely a delimiter. There is also provision for skipping commentary material up to the end of each line by using the word "\" as follows: HELIOSWORD ..... HELIOSWORD \ This is a comment and will be skipped. The interpreter will skip the material after "\", up to the end of the line, and then restart interpretation at the beginning of the next line. ---------------------------- Controlling editor scrolling ---------------------------- If you use the cursor "Up" and "Down" arrow keys to scroll the editor text display, scrolling speed is deliberately quite slow for ease of reading text "on the fly". It is worth noting that you can momentarily increase the scrolling speed at any time by pressing one of the shift keys while still pressing the arrow key. You can speed up and slow down scrolling at will by simply holding down the cursor arrow key and pressing and releasing a shift key. Try it! ---------------- PAUSE convention ---------------- In HeliOS a convention has been adopted when dealing with continous scrolling displays which it may be useful to know from the start. It is very frustrating when scrolling displays go scrolling off the screen before you can read them. If you try to examine the HeliOS CORE vocabulary for example, you will find that it rapidly scrolls through many screens of text. Any operation which may require to be paused, such as listing the vocabulary to the screen, or DUMPing memory contents, will always in HeliOS include a standard PAUSE function. This PAUSE function works as follows : = Pauses operation. = Restarts after Pause. = Quits operation, and can be used while paused or not. ----------------------------- Requester response convention ----------------------------- Another convention is that when a HeliOS requester appears at the top of the display requiring a "positive" or "negative" response, such as a "Proceed/Cancel" request, it may be answered from the keyboard using the "y" and "n" keys. "y" = Positive respose (Yes) "n" = Negative respose (No) ------------------------- Text, Windows and Streams ------------------------- HeliOS uses an interesting and powerful text stream system which can save you a great deal of programming effort. It is worth mentioning this here to introduce you to what is a quite unfamiliar concept on the Amiga. All normal output passes via the standard HeliOS text output routines which use an enhanced application of the Amiga console device and transmit screen output via a system of ten HeliOS text streams. You can set up a comprehensive HeliOS console text output system for any window by simply using the one word MAKEOUTWINDOW, and in a similar way you can set up a sophisticated user input gathering system by using MAKEINWINDOW. These two single word functions are equivalent to many pages of rather complex code in many other languages. If you are a "C" programmer, try considering how much code you would need to write to achieve the full functionality of the HeliOS STREAM system we are about to describe. HeliOS is full of such labour saving devices, which is why it can be considered an ideal beginner's language as well as being probably the most powerful language on the Amiga. You CAN have the best of both worlds, and power is not always synonymous with tedious complexity. HeliOS console text output is always associated with one of the ten streams, and the current stream can be set by using the single word STREAM, preceded by a number from 0 to 9. Before we even start to explain streams, try the little program below which outputs the HeliOS vocabulary list to a small text window: if you do not wish to wait for the whole listing to scroll by just press to quit. 6 STREAM 20 10 40 10 SCRWIN 1 BPENSET 6 FPENSET VLIST 2 STREAM SCRCLR or, with better layout and comments: 6 STREAM \ Enter stream 6 20 10 40 10 SCRWIN \ Set stream 6 text window \ Top corner = Column 20 Row 10 \ Width = 40 Columns \ Height = 10 Rows 1 BPENSET \ Set background pen to 1 (=Black) 6 FPENSET \ Set foreground pen to 6 (=Red) VLIST \ Output any demo text (list the vocabulary) 2 STREAM \ Return to interpreter output window stream SCRCLR \ Clear the mess we have made! This creates a new text window as STREAM 6, outputs text to it, then returns to STREAM 2 and clears the interpeter (STREAM 2) display. You now have STREAM 6 set up in terms of colours, window size, and position, so you can try something like: 6 STREAM SCRCLR ." Hello!" WAITSPACE 2 STREAM SCRCLR Try it. It really is that easy to set up text streams! No other language has anything like this facility, so once again HeliOS gives you a labour saving edge over other Amiga languages. Try highlighting and running the short program below, from the line after this one to the line after the word STREAMTEST. : STREAMTEST 2 STREAM SCRCLR 6 STREAM 20 8 20 10 SCRWIN 1 BPENSET 6 FPENSET 7 STREAM 45 12 20 10 SCRWIN 7 BPENSET 1 FPENSET 8 STREAM 70 16 5 10 SCRWIN 3 BPENSET 4 FPENSET 100 0 DO 6 STREAM ." Hello There!" 7 STREAM ." Hello There!" 8 STREAM ." Hello There!" LOOP 2 STREAM 4 20 CURPUT ." Press or to continue." WAITSPACE ; STREAMTEST Highlight to the line above this one. As you can see, text output via HeliOS streams is simple to program and very powerful. Here is a very brief overview of streams: Having set a stream, you can set up a text window, with unique text styles and colours, and that stream will retain these settings. You can set up several streams and move between them using the STREAM command, instantly recalling the preset stream characteristics of each stream. These text windows are actually subsections of a console text display and are not in any way related conceptually to Intuition windows. An Intuition window is the background entity to which a console text output display may be connected, but the HeliOS stream window is merely a further subdivision of the console text display area. Any text formatting carried out while using any particular stream is automatically remembered when the stream is left, and restored when that stream is re-entered. Output in any stream can be formatted using a word called SCRWIN to set up a restricted independent "scrolling text window" area of the screen into which output is channelled. You can use SCRCLR to clear any stream window. Setting a new stream text window causes the cursor position to be forced to the top left corner of the window. All output is then confined within the text window limits and automatic scrolling takes place. There is also a word SETCONORIGIN which allows precise pixel-placement of text stream window boundaries. You can have several stream windows within a single "console device" window, each with a different pixel alignment with respect to each other and the main "parent" window. A wide range of text styles and colours can be set by the user and will be automatically associated with the current STREAM and remembered. In general, the idea of STREAMS is that many features of a text window are associated with the current stream, and are automatically preserved as you move from one stream to another. This enables you to completely define many different output formats and change between them instantly merely by use of the single word STREAM. ------------------------------------------ A few interesting features of text streams ------------------------------------------ The HeliOS display uses some streams itself, and in cases where your program uses streams it is best to call a function named INITFSTREAMS when your program finishes, to reinitialise the HeliOS stream system. Rows and columns within text windows in HeliOS are numbered from 1 upwards i.e. the top left corner is 1,1. Text stream output can be simultaneously directed, using PRTON/PRTOFF, to a printer via the AmigaDOS PRT: device. Text stream output can also be sent to any "capture" file if the file handle is placed in the variable ALTOUT. See the definitions of FILEON, FILEOFF, OPENALT, CLOSEALT, and ALTERNATE in the "Dictionary.doc" file. There are many commands related to HeliOS text output, and in particular things like cursor control and automatic collection of user input are well worth investigating early in your HeliOS programming efforts. Please do take the time to read the dictionary file to get more details about console output/input and general text handling. You will find that HeliOS has no rival on the Amiga in terms of its text handling ability, and also has the most comprehensive array of text string handling words. We hope that you are already happy that HeliOS has been an excellent investment for you, in terms of the care and attention which has gone into making this a truly excellent Amiga programming system. If you like the small things you have seen so far, just think that you have over 1000 special HeliOS functions at your disposal, and probably the most advanced arcade game programming subsystem available on any home computer. While we are on this short guided tour, let us look at some more unique HeliOS features which distinguish it from other programming languages. ----------------- Resource tracking ----------------- On a flexible and multi-tasking computer such as the Amiga, many of your programming tasks relate to the requesting of available resources from the operating system, and the restoring of these resources when you have finished with them. If you are just learning to program the Amiga, you may find that good intentions in this direction sometimes fail, and you will not always succeed in closing down a faulty program, for example, with all its resources restored to the Amiga operating system. You may end up with memory allocated by a program and not restored correctly, windows not closed, and all manner of other discrepancies. HeliOS can help you if this happens, because unlike any other Amiga language it has a comprehensive built in resource management system. HeliOS maintains internal lists detailing everything that has been allocated and opened using HeliOS commands. If you close down HeliOS the HeliOS system will automatically do a comprehensive clean up of any allocations which you may have missed, restoring the Amiga operating system to what it was when HeliOS started up. If you find that your early efforts have messed things up a little, all you need do is close down HeliOS and then start again. HeliOS will clear everything up for you (unless you did serious damage!) and you can start again without rebooting. You could actually use this comprehensive resource tracking system to be totally lazy, allowing HeliOS to do all your clearing up for you, but this is, needless to say, not a good idea. Nevertheless, if you are writing some experimental code which you want to test quickly, and you haven't time to write all the close down routines properly, you can at least use the HeliOS resource manager as a temporary aid. ---------------------- Command line "History" ---------------------- The Intepreter command lines have a "History" feature which allows you to recall previous input for modification. The good news is that actually this is a feature of the HeliOS built-in line editor, and so it is available for use in all your own programs. The command line editor will not duplicate remembered input sessions, so if you make the same input five times, only one will be remembered. This "History" feature is very useful indeed when you are, for example, learning to use the stack by entering small sections of code at the interpreter command line. ------------- Stack Display ------------- Which brings us to the stack display at the top of the interpeter window. This is a permanent feature of the interpeter display unless you are using the debugger, and it has been provided entirely for the benefit of anyone who is learning to use a stack oriented language like HeliOS for the first time. No other language goes to the trouble of providing such a useful feature just to help beginners, and we hope you will find it useful in getting used to the sometimes initially confusing concept of the HeliOS stack. The idea here is that you can play with stack operators at the command line while observing the program output on the main screen display and with a full display of the current state of the stack always present in the stack display area. Use the stack display to get a thorough understanding of how the stack is affected by various commands. This is a unique feature of HeliOS, and is really worth exploiting while you are still learning to become familiar with parameter passing via the stack. You will find more about the stack in the tutorials...... ------------- Documentation ------------- There are many documentation files with HeliOS, and it is important to be able to access this information and have a knowledge of where to find particular topics. Here is a quick overview. The most important document of all is the "Dictionary.doc", which is a comprehensive reference file for all the words in the HeliOS language. Next in initial importance are the tutorial files, which will lead you through many aspects of HeliOS programming. Much important information has been included in these tutorial files rather than being packed away in obscure reference documents. The tutorial files present many vital topics in a sequential easy to follow manner, with many examples. It is absolutely essential for a full understanding of HeliOS that you read ALL the tutorials, because much of the information contained in them is not only very important, but is not given elsewhere. While you are still unfamiliar with HeliOS you will probably find the documents in the UserInterface document directory useful, since they explain details of the general HeliOS operating environment which the on-line help does not cover. The rest of the documentation contains descriptive files, with examples, of all other aspects of the HeliOS language, such as the special HeliOS function libraries, and the game operating system. In the documentation on the HeliOS game operating system you will find much useful information on important general Amiga computing topics such as generating Amiga displays and using hardware sprites. ------------------------------------------- The further note on the Dictionary.doc file ------------------------------------------- As you will have seen, HeliOS has many individual documentation files covering different aspects of the HeliOS system, but the majority of the main documentation on all the command words is contained in the one large "master" dictionary file. The "Dictionary.doc" is the essential main reference source for all the fundamental HeliOS language functions, and you may find it useful to keep this file in one of the editors for constant easy access. If you are running short of memory you may find that the dictionary file is too large for convenient use, and in extreme cases may even be unable to load it at all. In these cases you may need to divide the dictionary file into shorter more manageable sections, and it is easy to do this in the HeliOS editor using the "Load part" menu option. This option allows you to load a short section of any file, and if necessary you can save files back out in short sections. As you write, and gradually expand, your first short HeliOS programs we recommend that you spend a little time each day reading the dictionary to learn more about how the commands you are using work. If you read the dictionary carefully, and learn new commands one at a time while simultaneously trying them out in interesting small programs, you will, in no time at all, have a confident command of the all most important HeliOS functions. The dictionary is a vital source of important information on how HeliOS works, and since the dictionary file is ordered in sections relating to functionally connected words you may find it useful to read more about command words related to the ones you already know. For example, you will soon know the words CURPUT and CURGET, but having gained confidence using these you should make a point of looking at all the other cursor functions too, in order to expand your repertoire of commands. When you are learning a new set of command words it is a good idea to experiment at the keyboard using the interpreter and to write example programs to get a "hands on" feel for how everything works. ----------------------------------------------------------- A useful thing to learn early - the HeliOS macro key system ----------------------------------------------------------- Making full use of the powerful features of the HeliOS user interface will help speed up your initial learning, and one of the most useful of these features is the HeliOS command macro system. Rather than go into full detail here we refer you to the file: HeliOS:Docs/UserInterface/HeliOS_Macro_Commands.Doc Please read this file once you get down to programming, because by using the command macros you can set up HeliOS to do many useful things, especially setting up your own custom help system. ------------------- Where to go now.... ------------------- HeliOS is a very large and flexible system, and the way you use it is down to your own personal preference. Please do not omit to look at the documentation on the user interface and general program functions, because otherwise you may well miss many powerful features of the software which are not immediately obvious. When it comes to learning HeliOS programming, do not try to learn too much "theoretically" by reading documentation on all the hundreds of HeliOS commands BEFORE you start programming. You will never learn everything this way and HeliOS has too many program commands to learn by simply reading about them in advance. Having advised you not to read TOO much programming documentation to start with, you will nevertheless find it useful to gradually work through all the HeliOS Language Tutorials. The tutorials will give you some insight into the basic concepts of HeliOS programming, and offer a good gradual introduction to much essential HeliOS "technical" knowledge. HeliOS has been designed to be "interactive" and to allow creative and direct experimentation. In spite of the advice given in many books on programming (whose authors have evidently never used or seen a good interactive computer language) do not be afraid to experiment "at the keyboard" and follow up your own ideas. Above all, try doing things which interest you, and try doing things you own way. HeliOS provides an extremely "rich" set of commands in order to allow a wide choice of programming techniques. There is no "right and wrong" way to do things (although you will find certain techniques more efficent than others), and you will always find that examining your own programs will reveal ways of improving them. If you learn to do the simple things really well the large scale programs will come easily. You can best approach your first programming efforts by working with the example programs provided, and as you do so you can look up words which you do not understand in the HeliOS dictionary documentation. Use the example programs provided as a starting point for your own experiments and get used to how things work by changing the programs a little at a time to see what happens. As you start to write your own programs you will learn new commands and find which techniques suit you best: then you will gradually make use of more of the advanced features of HeliOS as you progress. Each time you look up a function in the dictionary documentation it is a good idea to read a little more about associated functions. This will gradually increase your knowledge of useful new HeliOS words, and you will often be surprised to discover powerful functions which help you to produce more effective programs. ------------------------------ A useful philosophical outlook ------------------------------ The way you approach the large task of learning to program the Amiga will determine your success or failure. Most beginners quite rightly, and admirably, have a good idea of what they want to be able to do, and naturally they want to know "how to do it" quickly, assuming there is a relatively simple "know how" involved. The basic assumption is that the experts know something which enables them to program the Amiga, like some kind of magic technique which will surely be found by reading some book or other........ This is not how it is when you are programming the Amiga, and to avoid instant disillusionment here are a few things you might consider. Do not try to go to fast and do not become disillusioned when you realise that programming the Amiga is not going to be easy..... The Amiga is a complex computer and many apparantly easy things take quite a lot of background programming: there simply are not too many instant tricks to do clever things, and the reality is that hard work and time are required before you write masterpieces. All the wonderful fluent and exciting software you see and wish to emulate has been created by very experienced programmers who have had to learn the basics first just like everyone else. There are no real shortcuts, although HeliOS does try to give you as many fine automated tools as possible, and to make programming as enjoyable as possible. Do not start by trying to realise your "dream projects": before you try to do creative things it is best (necessary!) to concentrate on becoming fluent in the techniques and tools which will underpin all your future efforts. Like climbing a hill, it is better to keep your head down and take each small step carefully. In fact, if you think about it, it is obvious that your dream program will never get written unless and until you personally have taken all the basic apparantly dull and insignificant steps which will be required to write it. You will not find your future masterpiece in any book written by someone else, and no amount of reading other people's ideas and reading other people's code will ever teach you as much as hands on experience down in the "engine room", learning by experience. Do not waste too much time searching for that illusive book or file which will answer all your questions: it probably does not exist. Most beginner's spend more time trying fruitlessly to find "instant solutions" from other sources than they do actually learning to program. It may not be obvious, and it may not be too exciting, but the reality is that the most useful way to learn to program is to do-it-yourself: write your own small programs and learn fundamentals "at the keyboard". Do not expect to be told, or to read, "how to write an arcade game", as if there were only one way: you might indeed get hints and ideas from other people's code, but you will always do best to work things out for yourself when it comes to creating your final code. Above all, experiment and play with the computer: enjoy yourself trying out new ideas and doing things in new ways. If you do not enjoy your programming you will have a long struggle.....and HeliOS is designed for creative programming and enjoyment. ---------------------------------------- A starting point for your first programs ---------------------------------------- The file "Tutorial.src" will give you a simple starting point and provides a useful start-up and close-down framework for launching your own first programs. Once you are bored with reading tutorials you might like to try loading this short program into one of the editors and experimenting. To run the Tutorial.src program once you have loaded it into an editor simply hold down SHIFT or CTRL or R-MOUSE while pressing the "Ed x" button of the editor containing the program - or use the menu option. Try experimenting with this program until you really feel confident that you understand it: this simple code can be a good basis for all your early HeliOS programs. ------------- Configuration ------------- Having become familiar with HeliOS please do not forget to read the "InitialSetup.doc" file, which will give you an insight into useful ways of reconfiguring the software to suit your own needs. ------------------- Helios User Support ------------------- We hope that you like using HeliOS and that you communicate your ideas to other HeliOS programmers by joining the HeliOS user group. Helios Software are also willing to help you directly with any problems you are experiencing, and for this reason we operate an advisory scheme whereby for a small charge we offer you help with any general HeliOS programming difficulty. ------------ A final word ------------ Thank you for purchasing HeliOS, and we hope that you will support our continued development of this excellent language by persuading your friends to pay the very reasonable purchase price rather than using a copied version. HeliOS is constantly evolving, and legitimate registered users will have the advantage of gaining a constant and regular stream of exciting new functions to use. It really is worthwhile for any HeliOS programmer to be a registered user, even if only to get the latest software updates, so please do support our efforts by discouraging piracy. We would be pleased to hear your views on new features you would like to see in HeliOS, as well as improvements you think would benefit other programmers. We hope that you enjoy using this quality Helios product. Thank you. Helios Software