==================================================== OrgAsm by T-SOFT ©1994 D.Cameron All Rights Reserved ==================================================== =============== What is OrgAsm? =============== OrgAsm is a utility which enables you to get multi-window, multi-gadget intuition graphic user interfaces (GUI's) up and running in Amos in a very short time, typically in under 10 minutes!!! ================= How does it work? ================= In practice, OrgAsm 'sits' between two other programs, namely GadToolsBox and A68k. GadToolsBox is the well known 'point and click' GUI creation utility, and A68k is a 68000 macro assembler. You 'paint' your desired GUI within GadToolsBox, then save it as assembler source code. However, this source code is completely unsuitable for use within Amos. This is where OrgAsm comes into play. OrgAsm completely alters the assembler source code output file from GadToolsBox into a format which is suitable for use in Amos. OrgAsm, then assembles the new code via the assembler A68k until finally you are in reciept of two new files, namely, Ram:GUI.BIN and Ram:GUI.ASC. OrgAsm itself is extremely simple to use, it requires only two pieces of information from you:- (1) the path to the GadToolsBox source code file (default filename=unnamed.s) and (2) the path to the assembler, A68k. ========================================================= Tell me about these two files Ram:GUI.BIN and Ram:GUI.ASC ========================================================= Well, GUI.BIN is a binary file containing the information for your GUI. It can simply be loaded into an Amos Bank. In practice this should be Bank 8, otherwise you will have to make some alterations to the GUI.ASC file. It can be loaded permanently like this:- Reserve as Data 8,1540 Bload "Ram:GUI.BIN",Start(8) End (Note there is no need to use the Amos command Pload since headers and footers have already been stripped away.) The GUI.ASC file contains some Amos source code relating to your GUI and so should be 'merged' onto your Amos Editor. Typically, this .ASC file will look something like this:- '------------------------------------------------- Rem Your Gadget ID's:- GD_BUTT1=0 GD_BUTT2=1 GD_CHCKBOX1=2 GD_CHCKBOX2=3 GD_CHCKBOX3=4 GD_STRINGAD=5 ' Procedure _OPENGUI Shared _GAD,_INT,_GFX,_UTIL,_FONT Call Start(8)+$16A,_GAD,_INT,_GFX,_UTIL,_FONT _SUCCESS=Dreg(0) End Proc[_SUCCESS] ' Procedure _CLOSEGUI Call Start(8)+$212 End Proc ' Procedure _OPENWINDOW0 Shared _GLIST0,_MENUSTRIP0 Call Start(8)+$25A WIN0=Leek(Start(8)+$16) _GLIST0=Leek(Start(8)+$1A) _MENUSTRIP0=Leek(Start(8)+$26) End Proc[WIN0] ' Procedure _CLOSEWINDOW0 Call Start(8)+$38C End Proc ' Procedure _RENDER0 Call Start(8)+4E8 End Proc '------------------------------------------- Please do not touch any of these variables or procedures. They are ready to use and require nothing to be added. You will see how to constuct a fully working program, from thes code fragments in the next section. ======================================== How do I put together a working program? ======================================== Read the following, and make sure to take a look at the worked example programs which will be useful tutorial material. '------------ 'A simple GUI '------------ Rem We won't need the following lines since you will already have Rem loaded GUI.BIN into Bank 8. Remember the .BIN file will vary in Rem size depending on the GUI which you have built. ' 'Reserve as Data 8,1108 'Bload "Ram:GUI.BIN",Start(8) 'End Rem Now open up the required libraries, namely, intuition & gadtools Rem making sure to take into account of the fact that libraries only Rem open successfully 99.9% of the time! ' _INT=F(0) If _INT=0 : Edit : Endif _GAD=F(0) If _GAD=0 : VOID=F : Edit : Endif Rem These are some constants from the GUI.ASC file. 'Your gadget ID's are:- GD_BUTT1=0 GD_BUTT2=1 GD_CHCKBOX1=2 GD_CHCKBOX2=3 GD_CHCKBOX3=4 GD_STR=5 Rem Now we can open our GUI which will initialise Bank 8 it may Rem also open up a screen depending on whether or not you are Rem using the WB Screen or not. We do this by calling the _OPENGUI Rem procedure. This procedure returns back to you a value which Rem is 'picked up' using the Amos command Param. If this value is Rem zero then everything went OK. However a non-zero value means Rem that a failure has occurred (eg low memory situation, etc...) Rem Should this occur you should exit the program 'gracefully' Rem Take note also that even if the _OPENGUI procedure fails Rem you must still call the _CLOSEGUI procedure even if this Rem sounds silly its not so remember to do it. So... ' Proc _OPENGUI If Param<>0 Proc _CLOSEGUI VOID=F VOID=F Edit Endif Rem Ok, now we are in a position to open our window. To do this Rem we call the pre-written procedure that comes in the GUI.ASC Rem file. This procedure returns the window address if successful, Rem otherwise a zero (fail) will be returned. We pick up this Rem address using the Amos command Param. Note that if the window Rem fails to open, we still call the Procedure _CLOSEWINDOW0. ' Proc _OPENWINDOW0 WIN=Param If WIN=0 Proc _CLOSEWINDOW0 Proc _CLOSEGUI VOID=F VOID=F Edit Endif Rem Our window is now open, so we are ready to start monitoring Rem for input by the user. So this is where you put your IDCMP Rem message handling loop. If you have to monitor more than one Rem window simultaneously, then you will have to put your program Rem to sleep using F instead of F which is suitable Rem for a single window. ' USERPORT=Leek(WIN+86) : Rem This is our message port Repeat VOID=F(USERPORT) : Rem Sleep until a message arrives Repeat MSG=F(USERPORT) : Rem Fetch the message Exit if MSG=0 : Rem Loop exit condition _CLASS=Leek(MSG+20) : Rem It's up to you how _CODE=Deek(MSG+24) : Rem much information you _QUAL=Deek(MSG+26) : Rem extract from the _GADGET=Leek(MSG+28) : Rem intui-message. _GADGETID=Deek(GADGET+38) : Rem <-ID's were given above VOID=F(MSG) : Rem Reply as soon as possible ' If _CLASS=$200 : Rem IDCMP_CLOSEWINDOW _EXIT=True : Rem He wants to quit ;-( Endif ' If _CLASS=$40 : Rem IDCMP_GADGETUP ' ' Which button was pressed If _GADGETID=BUTT1 'Do something Else If _GADGETID=BUTT2 'Do something else Endif ' Endif ' If _CLASS=$100 : Rem IDCMP_MENUPICK ' Do something again Endif ' If _CLASS=$4 : Rem IDCMP_REFRESH 'Intuition is telling us to 'do a redraw of any text and 'bevel boxes etc So... VOID=F(WIN) Proc _RENDER0 VOID=F(WIN,True) Endif ' Etc ' Etc ' Until DUMMY : Rem Exit If (above) handles loop exit Until _EXIT=True Rem Ok now its time to cleanup and quit. Remember and do it in Rem the correct order. ' Proc _CLOSEWINDOW0 Proc _CLOSEGUI VOID=F VOID=F Edit ' Rem These are the procedures that come pre-written in the GUI.ASC file. Procedure _OPENGUI Shared _GAD,_INT,_GFX,_UTIL,_FONT Call Start(8)+$16A,_GAD,_INT,_GFX,_UTIL,_FONT _SUCCESS=Dreg(0) End Proc[_SUCCESS] ' Procedure _CLOSEGUI Call Start(8)+$212 End Proc ' Procedure _OPENWINDOW0 Shared _GLIST0,_MENUSTRIP0 Call Start(8)+$25A WIN0=Leek(Start(8)+$16) _GLIST0=Leek(Start(8)+$1A) _MENUSTRIP0=Leek(Start(8)+$26) End Proc[WIN0] ' Procedure _CLOSEWINDOW0 Call Start(8)+$38C End Proc ' Procedure _RENDER0 Call Start(8)+4E8 End Proc ' This is not an exhaustive example nevertheless I hope you have got an impression of what is required. Essentially, all that needs to be done by the Amos programmer is to monitor for incoming messages from the user and respond to them accordingly. The dreadful drudgery of coding the GUI from the keyboard has been completely circumvented. ===================== Anything to remember? ===================== When saving the assembler source code file from GadToolsBox, you must save the code as 'Raw Asm'. Raw Asm is not a default mode in GadToolsBox, therfore before saving your file you must select the menuitem 'Preferences' and set 'Raw Asm' as a preference, by clicking on its checkbox. When setting your gadget labels in GadToolsBox try to make them as meaningful as possible so as you can recognise them easily when you ccome to read them in the GUI.ASC file. ie use things like BUTT1, CBOX3, STR2 etc By default GadToolsBox names each window of your GUI as Project0 Project1 etc. Please do not change these default names, there is no need to do so anyway! If you use the text strings and bevel-boxes in GadToolsBox you will get some extra code in your GUI.ASC file. For each 'project' ie window, in your GUI you will now get an additional procedure, for rendering (re-drawing) your strings and boxes when a refresh of the window is required ie when you get a refresh message at the message port. The BOOPSI getfile gadget in Gadtoolsbox is NOT supported by OrgAsm, so don't use one! Everything else is supported. The BOOPSI getfile gadget is the one that everyone knows best from the Commodore 'Fountain' program. If you intend to use a disk font instead of the user's screenfont or topaz 8, then you will also have to open diskfont.library and graphics.library as well as intuition and gadtools.library. Please use the variables _FONT and _GFX to pass the library addresses to the _OPENGUI procedure. (see above example). Also, enable the GadToolsBox preference checkbox 'Generate Openfont' as this will add the required code to the assembler source code file. (For the curious the variable _UTIL is never used currently. It's for future use when the getfile gadget mentioned above becomes available.) The _OPENGUI Procedure will be different for AmosPro users, but this doesn't matter since you should not touch these procedures at any time. The reason for the difference surprisingly enough, is that the AmosPro 'Call' command is bugged, more precisely, the 'Call' command is bugged with respect to passing parameters to 'Call'. Where your parameters disappear to is unclear, but they sure don't appear on the a3 stack like they're supposed to. (We're not guessing here, we've had AmosPro running under MonAm with an appropriate example and seen the 'trash' that appears at a3). ========= What now? ========= Get comfortable with using GadToolsBox, look at the examples, start off simply, and work to more complex GUI's, and above all, enjoy yourself, because thats the most important thing. ============= A Brief Recap ============= 1. Familiarise yourself with the use of GadToolsBox 2. 'Paint' your desired GUI, set GadToolsBox to RawAsm mode. Save your GUI as assembler source code. 3. Run OrgAsm, fill the Amos filerequesters with the path to the aforementioned assembler source file and the path to the program A68k. You will now have the two new files which you need GUI.BIN and GUI.ASC. 4. Run Amos and load GUI.BIN into Bank 8, then merge GUI.ASC onto the Amos Editor. 5. Write a message handling loop suitable for your particular GUI. 6. Go have a coffee, you've just saved two days work!! ======== Purchase ======== Take a look at the demonstration examples, to see them in operation you will need to add the enclosed file Tiny.lib as an Amos Extension It should be added as extension number 20. If you want to purchase Orgasm then of course you can. It costs £22 (or 25 sterling Eurocheque). Make cheques payable to D.Cameron. and send to T-SOFT,PO Box 598, Ayr KA6 6PJ, U.K. In addition to Orgasm you will also recieve the full Liberator extension for Amos, at no extra cost. This has been reviewed in magazines. Aug '94 Amiga Computing: "Hang on a minute I feel a bit faint!" (ME Could only be Phil South that wrote this eh! Aug '94 Computer Shopper: "Adds some pretty wild things to the old code engine" (ME Why did this get into a PC magazine?) Oct '94 82% Amiga User International: "the most exciting Amos release since the compiler" Nov '94 80% Amiga Computing "Liberator is one of the most exciting releases that Amos has seen in a long time" ******************************************************************** ORGASM AND LIBERATOR FOR £22 IS THE BARGAIN OF THE YEAR GET IT NOW *********************************************************************