@DATABASE GUI2.guide @$VER: 2.00 @AUTHOR "Pietro Ghizzoni" @INDEX "index" @node "Main" "GUI Extension" _______ __ __ __ @{FG SHINE}_____ @{FG TEXT} / _____/ / / / / / / @{FG SHINE}/__ /@{FG TEXT} / /____ / / / / / / @{FG SHINE}___/ /@{FG TEXT} / //_ / / / / / / / @{FG SHINE}/ ___/@{FG TEXT} / /__/ / / /_/ / / / @{FG SHINE}/ /__ @{FG TEXT} /______/ /_____/ /_/ @{FG SHINE}/____/@{FG TEXT} Are you ready to take @{I}AMOS Professional@{UI} to the next level? @{" AMOSPro Phoenix Project " link phoenix} - Info about the project... @{" Introduction " link intro} - Important information about GUI @{" Installation " link install} - Installation @{" GUI Commands " link guicmd} - Commands for GUI handling @{" Graphic Commands " link gfxcmd} - Graphic and effect commands @{" Internet Commands " link tcpcmd} - Commands for Internet connections @{" Localization support " link loccmd} - Commands for GUI localization @{" AppWindows/Icons support " link appcmd} - AppIcons and AppWindow support @{" XFA support " link xfacmd} - eXtra Fast Animation support @{" Miscellaneous Commands " link misccmd} - Various commands and functions @{b}@{bg highlight}GUI Extension is Copyright 1995-2000 by Pietro Ghizzoni. All rights reserved.@{ub}@{bg back} @endnode @node "intro" You are to be congratulated. You've just picked up the best extension that has ever been produced in the history of the world! Okay, maybe not, but if you want to be able to access the Amiga system and program your interfaces to use the system properly, this is the extension for you. You'll find GUI control, Public screen control, ASL requesters, Locale control, onscreen help system, AGA and graphics card support, full TCP commands, XFA support and more in this extension. !!! o o +-----------------------------oOO-(_)-OOo----------------------------+ | | | Pietro Ghizzoni - Dairymen Soft __ /// Amiga 12OO | | E-Mail: ghizzo@agonet.it \\\/// PPC 16OMhz | | ICQ 16361472 \/// 32MB CD40x | | | | *Amos Development Group Coordinator* AMIGA RULEZ! | | http://members.xoom.com/AmosFactory/ | | | +--------------------------------------------------------------------+ @endnode @node "install" Here you'll find the informations for installing all the needed stuffs in your AMOSPro system. The first step is.... @{B}Installing the Extension@{UB} @{B}NOTE:@{UB} If you have used a previous version of the extension, it is highly advised that you save your old program as an ASCII listing (Hit CTRL+A CTRL+S then Save ASCII) so you can merge it back in when the new library is installed and running. You will also need to re-convert any GUI banks you use, as the format has changed from that of the old. Its also a good idea to rename the old library so that you can fall back on it if something goes wrong. To install the extension, follow the below instructions: 1) Copy the AMOSPro_GUI.Lib file into the APSystem folder of your AMOSPro. The extension will not work with Classic AMOS. 2) Load your AMOSPro and from the menu, select the "Set Interpreter" function in the Config menu. 3) Select "Loaded Extensions" and fins slot 24 and enter "AMOSPro_GUI.Lib" and hit OK. 4) Save the configuration, and reload AMOSPro. If you did everything correctly, when you reload AMOSPro, your "Number of loaded extensions" should have incremented by 1, and you can check to see if it was loaded using the "View Loaded Extensions" function in the AMOSPro menu. The next step is to install the needed accessories and some extra stuffs: @{" Accessories " link accessories} - Install them in your Usermenu @{" The GUI Compiler " link guicomp} - The OS friendly compiler... @{" XFA " link xfa} - speeeeed up your animations! @endnode @node "accessories" @{B}Accessories@{UB} There are also a couple of small tools which you should really install in your User menu to make things a easier when it comes to working with the extension. These programs are the GUI Bank converter, the HotLinks editor and the RTG Bob converter. To install the programs, follow the below instructions: For example in order to install the GUI Converter: 1) Load AMOSPro and select "Add Option" from the bottom of the User menu. 2) When the request box appears, type in "Gui Convert" and hit OK to continue. 3) Now, the system asks you to select the option from the user menu. Simply choose the option you have just created. 4) Using the file selector, find and click OK on the GUIConvert.AMOS program which came with the extension. Then select the "Okay" function from the requester which pops up. 5) Press a key to cancel the next requester which appears. 8) Repeat the above steps for each programs changing the program names accordingly. 9) Select "Save Configuration" from the Config menu to save your changes @endnode @node "guicomp" @{B}GUI Compiler@{UB} How does the GUI compiler work? What's the difference? The main difference between the GUI and AMOSPro compilers is that the compiled code generated by the GUI compiler hides all the AMOS "system unfriendly" code. If you zap the code you'll see nothing AMOS related. If you zap the code generated by the standard AMOSPro compiler, you'll find tons of AMOS stuff, like the names of all the extensions installed in your system and other preferences. If you trace an AMOS compiled program using SnoopDOS or other programs, you'll notice other activities like search for and freeze any other running AMOS programs, search for the mysterious AMOS_Switcher and other stuff. The GUI Compiler removes these useless operations. If you run a virus checker together with AMOS, it will probably pop up a warning message because some system functions have been modified. For experts: - Graphics.library LoadView() only on AGA machines - Intuition.library EasyRequestArgs() - Intuition.library AutoRequest() ....the GUI Compiler removes them as well. So essentially the GUI compiler: - hides the AMOS rubbish in the code. - makes your AMOS programs able to run in multitasking with the other AMOS programs. As you know you can't run two or more AMOS programs together, because only the last one will run while the others will be freezed. Now you can! - makes your programs more "clean" and virus checkers warnings free. Since so many AMOS tags have been removed from the code, it is not a good idea to use it in AMOS games, for example. The GUI Compiler is specifically designed for @{B}Workbench@{UB} applications. If your program runs in the Workbench environment, it doesn't need the AMOS patches and hacks.. for this reason i've created the GUI Compiler. If you need to open AMOS screens and related stuffs, use the AMOSPro compiler. If you're creating a nice Workbench application, use the GUI compiler. See also the @{" Gui Amiga Os " link guiamigaos} command for extra bonus in your programs! How to use it ------------- The new phoenix version of the GUI Compiler works in a different way respect its older versions. Now the compiler is fully integrated with the editor, and so you can use it like all the other C++/Asm compilers. How? Very simple... now the GUI compiler is able to read the compiling options directly from your source code! Example: ' OPT DEST Ram:Test NOLIB DEBUG You just need to put at the start of your source code a line like the above example... a Rem followed by the OPT keyword and your options for the compiler. The supported options are: DEST - the destination path of the executable created by the compiler INCLIB - includes the gui.library in the executable (DEFAULT) NOLIB - the gui.library is not included in the executable DEBUG - enable the debug output. While your program is runnnig, in the amiga shell will be printed the line number currently executed. LONG - use LONGword Jumps (jsr) in the executable NOLONG - use short jumps (bsr) in the executable (DEFAULT) LINE - save the source code informations in the executable, so when a error occurs, a message like "Illegal function call at line xxx" will appears. @{b}IMPORTANT:@{ub} the GUI compiler will save the currently loaded source code before compile it!! @endnode @node "gadtoolsbox" @{B}GadToolsBox@{UB} @endnode @node "xfa" @{B}XFA - eXtra Fast Animation@{UB} This introduction is taken from the XFA docs... - Another NON-STANDARD animation format, why ? Well, during the development of X-DVE one of the first problems I had to face was to choose an animation format suited for video resolutions (meaning both PAL and NTSC) fast enough to play smooth, even with high resolution and "deep" screens. I started to test the various standard animation formats, like Anim-5, Anim-7 etc. They were all too slow to play and gave other extra features (like multiple palette handling, multi frame rates, complete multitasking) which I could stand without. The only anim format very near to my requirements was SCALA's anim 32I, but: - there was no documentation for it. - it was smooth enough, but trying to swith caches off (68040) display started to flash, making me think of a bad double buffering tecnique. So, I decided to start working on a new compression tecnique (XFA) that now is in your hands. - What kind of tecnique is used in XFA ? The tecnique is the classic "delta frame compression" that is normally used for anim-5, anim-7 formats. XFA animations can be of 4 different kinds: MODE COMPRESSION DISPLAY NOTE XFA_MODE16 16 bit ANY(forced to PAL) ok disk play XFA_MODE32 32 bit ANY(forced to PAL) ok disk play XFA_MODE16I 16 bit PAL/NTSC Lace XFA_MODE32I 32 bit PAL/NTSC Lace While MODE16 and MODE32 can be played from disk and in any screen mode, MODE16I and MODE32I offers a better compression but can only be played in PAL or NTSC interlaced screens (this is what I need for VIDEO applications) The "I" modes are expressely developed to run at 50fps (PAL) and MUST run at 50fps (the only way to see smooth animations) The difference from anim-5/7 is that XFA deltas can be decompressed with a small (can be totally cached), fast and furious asm routine that outperforms any comparable standard decompression routine. Another difference is that, for "16I & 32I" modes, only half information is compressed for each frame, (nearly) doubling the decompression speed and (nearly) halving the size of each delta. Displaying XFA "16I & 32I" mode animations, involves some low-level work with copper lists, in order to achieve a solid double buffering, even when the CPU is not fast enough to decompress deltas in synch with the vertical beam. XFA is really an extra fast animation format and, if you believe in miracles, you will obtain 256 colours super-hires overscan 1472x566 50fps animations with pictures floating on the screen an a basic A1200 ;) This surely is the dream of everyone involved in video production. If XFA could do this, I could surely take the Nobel for Computer Science ! You know that this is impossible to obtain from today's personal computers expecially if they don't have some hot chips inside. Amiga display chips, are really the best for video applications, but they have to be updated, just to follow today's users requirements. If they were light years away from the silly CGA, they now suffer of some bottlenecks (slow clock, cpu stealing, dma saturation). Now figure this: to play an animation at 50fps you have to unpack 1 frame every 1/50s. If the animation is a simple 640x512x4bpl resolution, the maximum thoughput you have to substain is 640/8 * 512 * 4 bytes per 1/50s (163840 bytes) or 8.192.000 bytes/s. If the same animation is a 768x566x8bpl resolution througput is 21.734.400 bytes/s. If you have a 1472x566x8bpl maximum througput is 41.657.600 bytes/s. That's (nearly) all, but you have also to consider: - if the unpack code is in chip mem, it runs much slower than in fast - if the unpack data is in chip mem, it is accessed slower than in fast - the destination bitmaps MUST be in chip mem - the more the resolution displayed, the slower the cpu (video dma steals cycles to cpu, and you cannot figure how much this is true in super-hires). The situation can surely improve if cpu and gfxchips have separate fast clocks and ........ but this is another story. The main point is that HOWEVER Amiga makes full screen animations possible while the others keep on dreaming in front of their waving stamp-size 160x160 (pre)views. @endnode @node "guibnk" In order to create a GUI bank, you've to follow these simple steps: 1- Run the GadToolsBox Editor and create your interface ( GUI from now on ) 2- Save it as GUI file ( NOT POWERPACKED! ) 3- Convert the gui file into a gui bank using the GuiConv Accessory A gui bank can held as many gui as you want. You can load the bank using a normal Load command. If you don't specify the bank number, the gui bank is loaded as bank number 20. @{b}IMPORTANT:@{ub} When you create your GUI, you @{b}MUST@{ub} use the topaz.font 8!! @{b}Creating a IMAGE gadget@{ub} The GadToolsBox Editor don't allows you to create a image gadget, and so i've found another way: You must create a @{b}BUTTON@{ub} gadget, but WITHOUT TEXT! When the Gui Converter will found a BUTTON gadget without text, it setup a image gadget. You can easly assign a image to the gadget specifing the Bob image to be used in the Label field of the button definition window of the GadToolBox editor. When the gui will be opened using the @{" Gui Open " link guiopen} command, the specified Bob image will be used as gadget's image. The specified image will be used as unselected gadget image and the next one will be used as selected gadget image. Example: If you specify the bob image number 4, the image 4 will be the @{i}unselected@{ui} image, and the image 5 will be used as @{i}selected@{ui} image. Obviously it works if there is a bob bank in memory! :) @{b}NOTE:@{ub} If you use the standard Amos Bobs there is the problem of the colours palette. The Bob (...and so your gadget's image) use the colours palette saved inside the bob bank, but probably it's different from the palette used in the screen where are you working (... the WB for example) and so the gadgets will be wrongly displayed. The only solution is to remap the bob images! For this reason i've coded a special Bob format... the RTG Bobs. Using the RTG Bob converter accessory you can easly convert your Bob bank into a RTG Bob bank. This accessory grab the bob bank currenlty loaded, and converter it into chunky data (... a new @{b}RTG Bob bank@{ub} will be created). After using the @{" Gui Remap " link guiremap} command you can easly remap the images thanks to the c2p routine inside the GUI extension. In such way your gadgets will always looks fine! @{b}IMPORTANT:@{ub} The width of a image gadget @{b}MUST BE less or equal@{ub} to the width of the bob image used, otherwise the display will be corrupted!!. @{b}NOTE:@{ub} if you create a RTG Bob bank, you can erase the amos bob bank. Remember that a image gadget IS NOT font sensitive! @{b}Creating a PROGRESS BAR gadget@{ub} The gadtools.library don't allows you to create a progress bar gadget, but this kind of gadget is very usefull, and so i've created this for you! In order to create a progress bar, follow these simple instructions: 1- Run the GadToolsBox Editor 2- Create a TEXT gadget with the Default string set to "PBAR" 3- this is the end.... very easy, no? The Gui Converter Accessory and the GUI extension makes the rest... Using the Gui Set instruction you can change the bar level. Remember that you must indicate the bar level in percentage (0-100)!! @endnode @node "guicmd" @{B} Commands for GUI handling @{UB} The GUI extension offers a reach set of functions for a extremly easy GUI handling. Now you've under control all the gadtools capabilities! @{" General information " link guibnk} - Some info about the GUI banks @{u}General@{uu} @{" Gui Open " link guiopen} - Open a GUI @{" Gui Close " link guiclose} - Close a GUI @{" Gui Exist " link guiexist} - Checks if a GUI Exist @{" Gui Reset " link guireset} - Close all the windows @{" Gui Wait " link guiwait} - Wait a event @{" Gui Event " link guievent} - Wait a event (no block) @{" Gui Code " link guicode} - Return the event code @{" Gui Code$ " link guicodes} - Returns the event code$ @{" Gui Bank " link guibank} - Set the current GUI bank @{" Gui Window " link guiwindow} - Returns the event window @{" Gui Selected " link guiselected} - Returns the currently selected window @{" Gui Actual " link guiactual} - Returns the actual gui # @{" Gui Read " link guiread} - Read the gadget status @{" Gui Read$ " link guireads} - Read the gadget status ($) @{" Gui Set " link guiset} - Update a gadget @{" Gui Set$ " link guisets} - Update a gadget ($) @{" Gui To Front " link guitofront} - Put a window to front @{" Gui To Back " link guitoback} - Put a window to back @{" Gui Move " link guimove} - Move a window @{" Gui Resize " link guiresize} - Resize a window @{" Gui Change " link guichange} - Move and resize a window @{" Gui Sensitive On " link guisensitiveon} - Turn font sensitive on @{" Gui Sensitive Off " link guisensitiveoff} - Turn font sensitive off @{" Gui Center " link guicenter} - Auto center windows @{" Gui On " link guion} - Unlock a GUI @{" Gui Off " link guioff} - Lock a GUI @{" Gui Lock " link guilock} - Lock all the GUI @{" Gui Unlock " link guiunlock} - Unlock all the GUI @{" Gui Remember On " link guirememberon} - Remember window's coords @{" Gui Remember Off " link guirememberoff} - Disable remember @{" Gui Titles " link guititles} - Set window/screen titles @{" Gui Title$ " link guititle$} - Returns the window title @{" Gui Clw " link guiclw} - Clear a window @{" Gui Set Mode " link guisetmode} - Turn on/off iconify gadget @{" Gui Check " link guicheck} - Checks gagdet presence @{" Gui Range " link guirange} - Limit integer gadget values @{" Gui Activate " link guiactivate} - Activate a string gadget @{" Gui Array Read " link guiarrayread} - Read the associated array @{" Gui Array " link guiarray} - Returns the associated array @{" Gui Gadget " link guigadget} - Returns the interactive gadget @{u}Menu@{uu} @{" Gui Menu " link guimenu} - Returns Menu code @{" Gui Menu On " link guimenuon} - Activate a menu @{" Gui Menu Off " link guimenuoff} - Deactivate a menu @{" Gui Menu Check " link guimenucheck} - Checkmark a menu item @{" Gui Menu Uncheck " link guimenuuncheck} - Un-Checkmark a menu item @{u}Window Sizes@{uu} @{" Gui Border " link guiborder} - Returns the gui borders size @{" Gui Width " link guiwidth} - Returns the gui width @{" Gui Height " link guiheight} - Returns the gui height @{" Gui In Width " link guiinwidth} - Returns the inner width @{" Gui In Height " link guiinheight} - Returns the inner height @{" Gui Gad Width " link guigadwidth} - Returns the gadget width @{" Gui Gad Height " link guigadheight} - Returns the gadget height @{" Gui X " link guix} - Returns the window x coord @{" Gui Y " link guiy} - Returns the window y coord @{" Gui X Gad " link guixgad} - Returns the gadget x coord @{" Gui Y Gad " link guiygad} - Returns the gadget y coord @{" Gui Sx " link guisx} - Calc font sensitive x coord @{" Gui Sy " link guisy} - Calc font sensitive y coord @{" Gui Sw " link guisw} - Calc font sensitive width @{" Gui Sh " link guish} - Calc font sensitive height @{u}Requester@{uu} @{" Gui Req " link guireq} - Pop up a requester @{" Gui Asl$ " link guiasls} - Open the asl file requester @{" Gui File$ " link guifiles} - Returns the (ASL) file @{" Gui Dir$ " link guidirs} - Returns the (ASL) dir @{" Gui Asl Font " link guiaslfont} - Open the ASL font requester @{" Gui Font Size " link guifontsize} - Returns the (ASL) font size @{" Gui Asl Screen " link guiaslscreen} - Open the ASL screen requester @{" Gui Asl Id " link guiaslid} - Returns the ASL screen ID @{" Gui Asl Width " link guiaslwidth} - Returns the ASL screen width @{" Gui Asl Height " link guiaslheight} - Returns the ASL screen height @{" Gui Asl Colours " link guiaslcolours} - Returns the ASL screen colours @{" Gui Asl Depth " link guiasldepth} - Returns the ASL screen depth @{" Gui Asl Open " link guiaslopen} - Open a (ASL) screen @endnode @node "loccmd" See the @{" Locale Catalogs " link loccat} for more info @{" Gui Catalog Open " link guicatalogopen} - Open a locale catalog @{" Gui Catalog Close " link guicatalogclose} - Close a catalog @{" Gui Catalog$ " link guicatalogs} - Returns a catalog string @{" Gui User Catalog " link guiusercatalog} - Returns the first user catalog string @endnode @node "loccat" The first thing to learn is how to create a locale catalog :) As you know (??), in order to localize a program, the locale.library needs the specific catalogs for every language. The files needed are automatically created by the GUI Converter. When it save the GUI bank, in the same directory you'll find 2 new files: Example: if the name of your gui bank is Hello.Abk you'll find also: Hello.ct Hello.cd These (ASCII) files are necessary for the translation to different languages, and so for the creation of the different catalogs. The .cd file describe the strings used in your GUI. Don't modify it! The file to modify is the .ct file. Here you have to insert the translation of the strings of your GUI. A example will clarify everything: I've a GUI bank named Hello.Abk and so the locale files: Hello.cd Hello.ct This is the Hello.ct file of this simple Gui with only 2 button gadgets named @{B}Hello@{ub} and @{b}World!@{ub} ## version $VER: hello.catalog 39.0 ## codeset 0 ## language xxx ; ; ;Hello ; MSG0_BUTTON_GAD ; ;World! ; MSG1_BUTTON_GAD ; ;Hello Window ; MSG2_WINDOW_TITLE ; ;Amiga Rulez! ; MSG3_SCREEN_TITLE As you can see there are some blank lines in the above text... If i want create the Italian catalog i must fulfill it as follow: ## version $VER: hello.catalog 39.0 ## codeset 0 ## language italiano ; ; ;Hello ; MSG0_BUTTON_GAD Ciao ; ;World! ; MSG1_BUTTON_GAD Mondo! ; ;AMOS - The BEST! ; MSG2_WINDOW_TITLE AMOS - Il Migliore! ; ;Amiga Rulez! ; MSG3_SCREEN_TITLE Amiga Regna! As you can see, it's very simple! You've just to insert in the blank lines the translation of the @{b}ABOVE@{ub} words i.e In Italian Hello = Ciao and so: ; ; ;Hello ; MSG0_BUTTON_GAD ; In the Italian translation became: ; ; ;Hello ; MSG0_BUTTON_GAD Ciao ; simple eh? When you (or a friend of your) have translated the whole .ct file, you're ready to create the catalog. For this purpose you need a little CLI program (MakeCat.. included in the archive). In order to make the job easy i've created a simple DOS script. The syntax is: CAT your .ct file name (without extensions) In the above example there are the files named Hello.cd and Hello.ct in RAM:, and so you have to type: Cat Ram:Hello and the Hello.catalog will be created. Well done.. now the Hello program can be localized in Italian thanks to the new catalog just created. Briefly: Create a catalog is easy.. the GUI Converter create the necessary translation files automatically. For localize your program in French,Italian,German etc. you just need to translate the .ct file created by the GUI converter in your preferred language. After using the supplied DOS script you can easly create the catalog file. P.S In the archive there are MakeCat and the related DOS script. Put MakeCat in C: and the script in S: @endnode @node "misccmd" @{u} Miscellaneous@{uu} @{" Gui Amiga Os " link guiamigaos} - Disable some Amos hacks @{" Gui Put " link guiput} - Put a string in a file @{" Gui Get$ " link guigets} - Put a file in a string @{" Gui Input$ " link guiinputs} - Read the system input @{" Gui Output " link guioutput} - Write to the system output @{" Gui Array Up " link guiarrayup} - Scroll up a array @{" Gui Array Down " link guiarraydown} - Scroll down a array @{" Gui Help " link guihelp} - Activate help system @{" Gui Guide " link guiguide} - Display a amigaguide doc @{" Gui Pause " link guipause} - Suspend the program @{" Gui Timer " link guitimer} - Send a timer request @{" Gui Key Shift " link guikeyshift} - Checks the ctrl keys @{" Gui Gad Adr " link guigadadr} - Returns the gagdet address @{" Gui Kind " link guikind} - Returns the gadget kind @{" Gui Os " link guios} - Returns the OS version @{u}Clipboard Support@{uu} @{" Gui Clip Read$ " link guiclipreads} - Read the clipboard content @{" Gui Clip Write$ " link guiclipwrites} - Write to the clipboard @{u}DOS Notification@{uu} @{" Gui Notify " link guinotify} - Start DOS Notification @{" Gui Rem Notify " link guiremnotify} - Stop DOS Notification @endnode @node "screencmd" @{" Gui Screen Open " link guiscreenopen} - Open a screen @{" Gui Screen Close " link guiscreenclose} - Close a screen @{" Gui Screen Width " link guiscreenwidth} - Returns the screen width @{" Gui Screen Height " link guiscreenheight} - Returns the screen height @{" Gui Screen Depth " link guiscreendepth} - Returns the screen planes # @{" Gui Screen Colours " link guiscreencolours} - Returns the # of colours @{" Gui Screen Base " link guiscreenbase} - Returns the screen base addr @{" Gui Screen Move " link guiscreenmove} - Move a screen @{" Gui Show Title " link guishowtitle} - Display on/off the title bar @{" Gui Monitor " link guimonitor} - Checks the specified monitor ID @{" Gui Clone " link guiclone} - Promote a Amos screen @{" Gui Pub Screen " link guipubscreen} - Lock a public screen @{" Gui Pub Name$ " link guipubnames} - Returns the public screen name @{" Gui Pub Free " link guipubfree} - Unlock a public screen @{" Gui Pub List " link guipublist} - Lock the public list @{" Gui Pub List Free " link guipublistfree} - Unlock the public list @{" Gui Pub To Front " link guipubtofront} - Put a screen to front @{" Gui Pub To Back " link guipubtoback} - Put a screen to back @{" Gui Pub Mode " link guipubmode} - Set the pub screen mode @{" Gui Pub Check " link guipubcheck} - Returns the number of windows opened @endnode @node "mousecmd" @{b}Miscellaneous mouse support commands:@{ub} @{" Gui Rmb " link guirmb} - Enable the Right mouse button @{" Gui Mouse Mode " link guimousemode} - Set the mouse event mode @{" Gui Mouse Queue " link guimousequeue} - Set the mouse event limit @{" Gui Mouse X " link guimousex} - Returns the x mouse coord @{" Gui Mouse Y " link guimousey} - Returns the y mouse coord @{" Gui Mouse Wx " link guimousewx} - Returns the win-mouse x @{" Gui Mouse Wy " link guimousewy} - Returns the win-mouse y @{" Gui Mouse Ex " link guimouseex} - Returns the event-mouse x @{" Gui Mouse Ey " link guimouseey} - Returns the event-mouse y @{" Gui Mouse Report " link guimousereport} - Activate mouse reports @endnode @node "gfxcmd" @{" Screen Commands " link screencmd} - Commands for screens handling @{" Colour Commands " link colcmd} - Colours commands @{" Zone Commands " link zonecmd} - Zone support @{" Mouse Commands " link mousecmd} - Mouse related functions @{b}Miscellaneous Commands:@{ub} @{" Gui Gfx " link guigfx} - Set the gfx output @{" Gui Beep " link guibeep} - Flash the WB screen @{" Gui Wait Vbl " link guiwaitvbl} - Wait vbl @{" Gui Ink " link guiink} - Change the ink colour @{" Gui Paper " link guipaper} - Set the paper colour @{" Gui Pen " link guipen} - Set the pen colour @{" Gui Text " link guitext} - Print some text @{" Gui Writing " link guiwriting} - Set the gfx writing mode @{" Gui Draw " link guidraw} - Draw a line @{" Gui Draw To " link guidrawto} - Draw a line from the current pos @{" Gui Line 3d " link guiline3d} - Draw a line in the 3d space @{" Gui Eye 3d " link guieye3d} - Set the eye position @{" Gui Ellipse " link guiellipse} - Draw a ellipse @{" Gui Bar " link guibar} - Draw a filled bar @{" Gui Box " link guibox} - Draw a box @{" Gui Bbox " link guibbox} - Draw a bevel box @{" Gui Paint " link guipaint} - Fill a gfx area @{" Gui Cls " link guicls} - Clear the current gfx output @{" Gui Paste Block " link guipasteblock} - Paste a block @{" Gui Paste Icon " link guipasteicon} - Paste a icon @{" Gui Paste Bob " link guipastebob} - Past a bob @{" Gui Scroll " link guiscroll} - Scroll a gfx area @{" Gui Screen Copy " link guiscreencopy} - copy a gfx area @{" Gui Plot " link guiplot} - Plot a pixel @{" Gui Point " link guipoint} - Returns the pixel colour @{" Gui Len " link guilen} - Returns the pixel width of a text @{" Gui Text Base " link guitextbase} - Returns the text font offset @{" Gui X Font " link guixfont} - Returns the font width @{" Gui Y Font " link guiyfont} - Returns the font height @{" Gui Display Iff " link guidisplayiff} - Display a IFF image @{" Gui Save Iff " link guisaveiff} - Save a screen as IFF @endnode @node "colcmd" @{b}The colour handling commands:@{ub} @{" Gui Aga " link guiaga} - Convert 8-bit colour to AGA @{" Gui Rgb " link guirgb} - Change the RGB values @{" Gui Colour " link guicolour} - Returns the colour value @{" Gui Red " link guired} - Returns then red value @{" Gui Green " link guigreen} - Returns the green value @{" Gui Blue " link guiblue} - Returns the blue value @{" Gui Best " link guibest} - Find the best matching colour @{" Gui Remap " link guiremap} - Remap the RTG bob colour map @endnode @node "zonecmd" @{b}The zone handling commands:@{ub} @{" Gui Reserve Zone " link guireservezone} - Reserve memory for zone @{" Gui Free Zone " link guifreezone} - Free memory zone @{" Gui Set Zone " link guisetzone} - Change/Set a zone definition @{" Gui Mouse Zone " link guimousezone} - Returns the mouse zone @{" Gui Zone " link guizone} - Returns the interactive zone @endnode @node "xfacmd" See the @{" Extra Fast Animation chapter " link xfa} for more info. @{b}Commands:@{ub} @{" Xfa Play " link xfaplay} - Play a XFA anim @{" Xfa Rtg Play " link xfartgplay} - Play a XFA anim with GFX Card output @{" Xfa Check " link xfacheck} - Checks the XFA file @{" Xfa Width " link xfawidth} - Returns the anim width @{" Xfa Height " link xfaheight} - Returns the anim height @{" Xfa Mode Id " link xfamodeid} - Returns the anim screen mode @{" Xfa Depth " link xfadepth} - Returns the anim planes depth @{" Xfa Pack " link xfapack} - Returns the anim compression mode @{" Xfa Frames " link xfaframes} - Returns the number of frames @endnode @node "appcmd" See the @{" AppWindows/Icons introduction " link appintro} for more info @{b}Commands:@{ub} @{" Gui App Id " link guiappid} - Returns the AppIcon number @{" Gui App Name$ " link guiappnames} - Returns the dragged file name @{" Gui App Icon " link guiappicon} - Create a Appicon @{" Gui App Remove " link guiappremove} - Remove a Appicon @{" Gui Iconify " link guiiconify} - Iconify a window @{" Gui Uniconify " link guiuniconify} - Uniconify a window @endnode @node "appintro" @{b} AppWindows @{ub} The GUI Extension offers a complete AppWindow support.. by default all the windows are AppWindow, in other words they supports icons drag'n'drop. When the user drag some icon(s) on your window @{" Gui Wait " link guiwait} returns the event -15 and @{" Gui Code " link guicode} the number of icons dragged. In order to know the name of the files you need the @{" Gui App Name$ " link guiappnames} command. Example: W=Gui Wait : NUM=Gui Code : Rem NUM is the number of icons dragged If W=-15 ' Print the name of the files... For I=1 To NUM Print Gui App Name$ Next End If The above example simply display the path of all the files(icons) dragged on your window. @{b} AppIcons @{ub} Using the @{" Gui App Icon " link guiappicon} command you can create as many appicons as you want. The user can interact with your AppIcons in two ways: 1- Double-click your appicons 2- Drag other icons on your appicons When the user use one of your AppIcon, @{" Gui Wait " link guiwait} returns the event -16 and @{" Gui App Id " link guiappid} the number of the AppIcon. The command @{" Gui Code " link guicode} returns the number of dragged icons. @{B}If the user has just double-clicked your AppIcon, Gui Code returns the value 0@{ub} Like the AppWindows, in order to know the name of files dragged on your AppIcon you need the @{" Gui App Name$ " link guiappnames} command. Example: W=Gui Wait : AP=Gui App Id : CD=Gui Code If W=-16 If CD=0 Print "AppIcon "+Str$(AP)+" clicked!" Else Print Str$(CD)+" icons dragged on the AppIcon "+Str$(AP) Print "File Names" For I=1 To CD : Print Gui App Name$ : Next EndIf EndIf @endnode @node "guiopen" @{b}Action:@{ub} Open a GUI window @{b}See Also:@{ub} @{" Gui Close " link guiclose} @{b}Usage:@{ub} Gui Open window,gui Gui Open window,gui,bank Gui Open window,gui,bank,x,y,width,height Gui Open opens a window (number window) using the specified GUI data. You may also include a bank number from which to get the GUI data. This bank will then become the current GUI bank (see @{" Gui Bank " link guibank}). There is a third syntax where you can specify the position and sizes of the window. Otherwise it will default to the position and size as specified in the GadToolsBox editor. As long as there's enough free memory, you can open as many windows as you wish. When you open a window, this window becomes the current, selected window. ( See also the @{" Gui Gfx " link guigfx} command). If the window you specify is already open, it will be selected and pop to front... no error will occur. To close the window, use the @{" Gui Close " link guiclose} command. An error will be reported if no bank number has been specified and Gui Bank has not been called. @endnode @node "guiwait" @{B}@{b}Action:@{ub}@{UB} Wait for events... @{b}Usage:@{ub} A=Gui Wait @{b}See Also:@{ub} @{" Gui Code " link guicode} @{" Gui Event " link guievent} @{" Gui Window " link guiwindow} Gui Wait will wait until the user interacts with your program - your program will be frozen until something happens (you can stop it with Ctrl-C). Thanks to the flexibility of the GUI extension it can handle different kinds of events (see the list below). If the value returned by Gui Wait is is more than or equal to 0 it is the @{B}number of the gadget@{UB} selected by the user. Use the @{" Gui Window " link guiwindow} function in order to find out which window has generated the event. If the gadget selected is one that requires user input (e.g. string gadgets or integer gadgets), then use the commands @{" Gui Code " link guicode} or @{" Gui Code$ " link guicode$} to get the inputted data. For @{B}all@{UB} the other kinds of events it returns a @{B}negative@{UB} value... and exactly one of the following: -1 = Window's close gadget selected -2 = Menu item selected -3 = Not used -4 = Raw key pressed -5 = Key pressed -6 = You must iconify the window! -7 = Nothing selected (see @{" Gui Event " link guievent}). -8 = Window resized -9 = @{" Internet TCP/IP message " link tcpoverview} -10 = ARexx message -11 = Mouse Clicked -12 = Mouse Moved -13 = Timer event -14 = DOS Notification -15 = @{" AppWindow event " link appintro} -16 = @{" AppIcon event " link appintro} -17 = Not used -18 = Window on/off Even for these events Gui Code returns the result code. See the @{" Gui Code " link guicode} command for a complete listing. @ENDNODE @node "guiclose" @{b}Action:@{ub} Close a window previously opened with GUI OPEN @{b}Usage:@{ub} A=Gui Close(window) @{b}See Also:@{ub} @{" Gui Open " link guiopen} @{" Gui Wait " link guiwait} @{" Gui Event " link guievent} @{" Gui Reset " link guireset} Gui Close will close and remove from the screen, the specified window. It will return a special code which will mean one of the following: 0 - Window Closed 1 - First opened Window closed 2 - Last opened window closed 3 - Last window closed Note: Opened windows will not close by themselves when the close gadget is clicked, you have to monitor for it to happen with a command such as GUI WAIT or GUI EVENT. @ENDNODE @node "guicode" @{b}Action:@{ub} Returns the result code associated to the last event occured @{b}Usage:@{ub} A=Gui Code @{b}See Also:@{ub} @{" Gui Code$ " link guicode$} @{" Gui Read$ " link guiread$} @{" Gui Read " link guiread} @{B}Note: After Gui Code has been called, its value is automatically reset to -1 again, until the next call to Gui Wait loads it with a new value.@{UB} Gui Code is used to return the result code of the last event returned by @{" Gui Wait " link guiwait}. Depending on the type of event the values returned are one of: @{B}Gadget Events@{UB} When the user click one the gadgets of your window(s), Gui Wait returns the gadget number and Gui Code its status: BUTTON - No value returned CHECKBOX - Boolean status (on or off -> 0 or -1) INTEGER - Value typed in LISTVIEW - Selected item (in order of list, 0 is first entry) MX - Selected item CYCLE - Currently selected item (in order of list, 0 is first entry) PALETTE - Number of the colour SCROLLER - Position SLIDER - Position STRING - None (see Gui Code$) @{B}Miscellaenous@{UB} There are different events supported by @{" Gui Wait " link guiwait}. Gui Code returns the status of each event: @{B}Event -1 ( Close gadget selected )@{UB} This event is generated when the user click the close gadget of your window. In this case Gui Code returns a NULL value. @{B}Event -2 ( Menu item selected )@{UB} A menu item has been selected. You've to use the @{" Gui Menu " link guimenu} commands in order to handle it. Gui Code returns a NULL value. @{B}Event -4 ( Raw key pressed )@{UB} The user has pressed a key on the keyboard. In this case it's a RAW key such as the shift,alt,ctrl etc. Gui Code returns the keyboard code associated to the key. @{B}Event -5 ( Key pressed )@{UB} The user has pressed a key on the keyboard. Gui Code returns the ASCII value of the key. Example: the key 'A' returns the value 65 @{B}Event -6 ( Iconify Message )@{UB} The user has clicked the iconify(zoom) gadget of your window. Now you MUST! iconify the window using the @{" Gui Iconify " link guiiconify} command. Gui Code returns a NULL value @{B}Event -7 ( No events )@{UB} This event is returned by the @{" Gui Event " link guievent} command only when no more events are present. @{B}Event -8 ( Window resized )@{UB} A window has been resized. As usual in order to discover wich window you've to use the @{" Gui Window " link guiwindow} command. Gui Code returns a NULL value @{B}Event -9 ( Internet Event )@{UB} See the @{" Internet " link tcpoverview} section for a complete overview @{B}Event -10 ( Arexx Message )@{UB} Since the GUI Extension has a built-in Arexx support, you don't need to use the Arexx Wait command in order to detect Arexx messages. When Gui Wait returns the -10 value a Arexx message is available at your Arexx port. Now using the standard AMOSPro Arexx commands you can handle it as usual. Gui Code returns a NULL value @{B}Event -11 ( Mouse Click )@{UB} The user has clicked the mouse. You'll receive @{B}TWO@{UB} -11 events.. The first when the mouse button is hold down, and the second when it's released. In such way you can monitor the mouse press. Gui Code returns the mouse button status: Left button pressed: Right button: @{B}Event -12 ( Mouse pointer moved )@{UB} Using the @{" Gui Mouse Report " link guimousereport} command you can monitor all the mouse movements. In this case Gui Code returns a NULL code... you need the @{" Gui Mouse Ex/Ey " link guimouseex} commands in order to obatin the mouse coordinates related to the event received. @{B}Event -13 ( Timer Event )@{UB} The time period previously specified using the @{" Gui Timer " link guitimer} command is elapsed. Gui Code returns a NULL value @{B}Event -14 ( DOS Notification )@{UB} A file/directory previously monitored using the @{" Gui Notify " link guinotify} command has been modified. Gui Code returns the notifyID code (see @{" Gui Notify " link gui notify}) associated to the file. @{B}Event -15 ( AppWindow message )@{UB} Some icons has been drag-n-dropped in a window. See the @{" AppWindows " link appwindows} section for more info. @{B}Event -16 ( AppIcon message )@{UB} The user has used one of your appicons. See the @{" AppIcons " link appicons} section for more info. @{B}Event -18 ( Window On/Off )@{UB} A window has been activated/deactivated by the user. Gui Code returns the window status. Gui Code = 0 -> Window deactivated Gui Code >< 0 -> Window Activated @endnode @node "guiamigaos" @{b}Action:@{ub} Hide AMOS to a certain degree @{b}Usage:@{ub} Gui Amiga Os Gui Amiga Os will carry out the AMOS instructions Amos to Back and Amos Lock to prevent your programs from using Left Amiga+A to flick back into Amos mode (otherwise the system could become stuck). It has a few extra features inside it. It's also the equivalent of the instructions Comp Test Off and Break Off. It will also remove the AMOS interrupt routine. This makes your program a heck of a lot more OS friendly, speeds up your multitasking (AMOS has a bad habit of being a bad multitasker at times) and stops a lot of the hacking to the OS that AMOS normally does. There are some downsides to this command however, as for the extra speed and OS integration that you gain, you may need to make a few sacrifices. Many of AMOS's internal routines will cease to function properly when under this command. This includes all commands to do with AMAL, Music, Samples and VBL interrupts. If you require music and samples, it is suggested that you use either the AMCAF extension or the DME 2.0 extension (which handles almost every music format around). You should also use @{" Gui Wait Vbl " link guiwaitvbl} instead of the regular Wait Vbl command. Note that all this only takes effect when your program is @{B}compiled!@{UB} If you're creating a WB application, you should really put this command at the start of your source code! @endnode @node "guiset" @{b}Action:@{ub} Update a gadget with a value @{b}Usage:@{ub} Gui Set window,gadget,attribute,value @{b}See Also:@{ub} @{" Gui Set$ " link guisets} @{" Gui Read " link guiread} @{" Gui Read$ " link guireads} Gui Set enables you to update a gadget of your GUI with a new value. Some kinds of gadgets allows you to update up to 3 different attributes (0 to 2) The effect of these attributes varies, depending on the type of the gadget. Here is a table of the possibilities: @{B}Attribute 0:@{UB} CHECKBOX Sets the checkbox status (selected/unselected) INTEGER Enter a new value LISTVIEW Sets the current selected item in the listview MX Sets the selected item NUMBER Enter a new value CYCLE Sets the selected item PALETTE Sets the selected color SCROLLER Sets the position of the scroller bar SLIDER Sets the position of the slider bar STRING Enter a string in the gadget (you MUST use Varptr(String) as value) See the @{" Gui Set$ " link guisets} command TEXT Enter a string in the gadget (you MUST use Varptr(String) as value) See the @{" Gui Set$ " link guisets} command PBAR Sets the bar level (0 to 100) @{B}Attribute 1:@{UB} LISTVIEW Display a new array list (you MUST use Array(your array) as value) See below for more info about listview usage SCROLLER Sets the total slider size SLIDER Sets the minimum value of the slider @{B}Attribute 2:@{UB} LISTVIEW Sets the item at the top of the display SLIDER Sets the max value of the slider SCROLLER Sets the visible size With the Gui Set command, it is possible to make gadgets appear "ghosted" so that they cannot be selected. This can be handy on demo versions of your programs, or simply options which cannot be selected at a particular time on the screen. To ghost out/Reappear any gadgets (except listviews) use the following examples: Gui Set 1,5,-1,1 : Rem Gadget number 5 in win 1 is turned OFF Gui Set 1,5,-1,0 : Rem Gadget number 5 in win 1 is turned ON As you can see you just need to use the attribute -1 and the value 0/1 to turn it On/Off @{B}Using Listviews@{UB} The listview function of the GUI SET can read a regular AMOS string array into its display, and allow the user to select elements from within it, and process them etc. Some things you should know about the way the command works, is if you set your string array with blank strings ("") then the listview will just skip straight past them and carry on going as if they weren't even there. This can prove slightly annoying when using the @{" Gui Read " link guiread}/@{" Gui Read$ " link guireads} commands, as they seriously affect the output they give, and divert you to wrong slots in the array since they returns the current selected item wich may not correspond to the correct array item if there are some empty strings in the array. One of the ways to get around this problem is to look at the @{" Gui Array " link guiarray} and @{"Gui Array Read" link guiarrayread} commands. For using an AMOS array in a listview, it is important the AMOS command Array() is used (@{B}single dimension arrays only@{UB}). Also your array MUST be made GLOBAL! Example: Gui Set 2,3,1,Array(A$(0)) Rem display the array A$() in the listview Note there are highly detailed example programs in the EXAMPLES drawer on using this command effectively with a listview gadget. Please look, and study the code. @endnode @node "guibank" @{b}Action:@{ub} Specify the GUI bank to be used with the GUI OPEN command @{b}Usage:@{ub} Gui Bank bank @{b}See Also:@{ub} @{"Gui Open" link guiopen} Before you can begin opening GUI windows which have been turned into banks, you will need to tell the system which AMOS bank the GUI info is located in. The converter will place it in bank 20 by default, so you could use Gui Bank 20, for example. You don't have to use this command more than once, unless you wish to switch banks in the middle of a program. You can also specify the bank to load the GUI from, in the @{" Gui Open " link guiopen} command itself. @endnode @node "guiwindow" @{b}Action:@{ub} Return the number of the window wich has generated the last event returned by Gui Wait @{b}Usage:@{ub} A=Gui Window Gui Window simply returns the number of the window wich has generated the last GUI event reported by @{" Gui Wait " link guiwait}. Its handy to use to create multitasking windows running completely seperate of each other. The effect can be acheived from a program such as this: Gui Open 1,1 : Gui Open 2,2 : Gui Open 3,3 Repeat SEL=Gui Wait : WIN=Gui Window : Rem Get gadget and window If WIN=1 _SELECTED_WINDOW1[SEL] Else If WIN=2 _SELECTED_WINDOW2[SEL] Else If WIN=3 _SELECTED_WINDOW3[SEL] End If Until SEL=-1 and WIN=1 Gui Reset ' Procedure _SELECTED_WINDOW1[SEL] If SEL=-1 ' Close gadget selected, so close window NULL=Gui Close(1) Else If SEL=0 ' Selected gadget 0 in window 1 Else If SEL=1 ' Selected gadget 1 in window 2 Else If SEL=2 ' etc. End If End Proc ' etc. With this method, you can create a separate procedure to handle input from each window your program has open. @endnode @node "guitofront" @{b}Action:@{ub} Move an opened window to the front @{b}Usage:@{ub} Gui To Front window Gui To Front moves the specified window to the frontmost of the display. @endnode @node "guitoback" @{b}Action:@{ub} Move an opened window to the back of display @{b}Usage:@{ub} Gui To Back window Gui To Back will move to the back of display @endnode @node "guimousex" @{b}Action:@{ub} Grab the x screen-coordinate of the mouse @{b}See Also:@{ub} @{" Gui Mouse Wx " link guimousewx} @{" Gui Mouse Wy " link guimousewy} @{b}Usage:@{ub} A=Gui Mouse X Gui Mouse X will return the screen coordinates of the mouse. If you want them relative to a window on the screen, you will have to use the Gui Mouse Wx commands. @endnode @node "guimousey" @{b}Action:@{ub} Grab the y screen-coordinate of the mouse @{b}See Also:@{ub} @{" Gui Mouse Wx " link guimousewx} @{" Gui Mouse Wy " link guimousewy} @{b}Usage:@{ub} A=Gui Mouse Y Gui Mouse Y will return the screen coordinates of the mouse. If you want them relative to a window on the screen, you will have to use the Gui Mouse Wy commands. @endnode @node "guimove" @{b}Action:@{ub} Move a window to a new coordinates @{b}Usage:@{ub} Gui Move window,x,y @{b}See Also:@{ub} @{" Gui Change " link guichange} Gui Move will simply move the specified window, to the new x and y coordinates specified. @endnode @node "guireset" @{b}Action:@{ub} Close ALL open windows @{b}Usage:@{ub} Gui Reset Gui Reset will simply close all opened windows. It is handy to call from Direct mode if your program fails, as it saves you having to type lots of commands, or when you've to quit from your program. @endnode @node "guiexist" @{b}Action:@{ub} Check to see if a window is opened @{b}Usage:@{ub} A=Gui Exist(window) Gui Exist will check to see if the specified window has been opened or not. If it isn't, then FALSE is returned. If the window is open, it will return with the window's structure address. @{b}Note: Dont fiddle with this structure unless you really know what you're doing to it!!@{ub} @endnode @node "guireq" @{b}Action:@{ub} Open an ASL requester box @{b}Usage:@{ub} A=Gui Req(title$,message$,gadget$) Gui Req will create a simple ASL requester with the absolute minimum of effort. The value loaded into the variable will be the gadget selected by the user. If you wish to have multiple gadgets in the box, then you must seperate each one with a "|" character. If you also wish to have multiple lines of text, you must manually place the Chr$(10) character at the places you wish the line to break. For example: MSG$="Please Click one of"+chr$(10)+"these gadgets below:" GAD$="One|Two|Three|Four" SEL=Gui Req("GUI Extension Requester...",MSG$,GAD$) If the right-most gadget is selected, then 0 will be returned, otherwise 1 and upwards would be returned depending on the gadget you chose. For the previous example, sel could be one of: 1 - One 2 - Two 3 - Three 0 - Four @endnode @node "guiasls" @{b}Action:@{ub} Call the standard ASL File requester @{b}Usage:@{ub} A$=Gui Asl$(Title,directory,file,pattern) @{b}See Also:@{ub} @{" Gui File$ " link guifiles} @{" Gui Dir$ " link guidirs} Gui Asl$ calls the ASL file requester and allows the user to choose a file, starting with the parameters which you have set. The full path and filename are returned in the string. If CANCEL was hit, the string will remain empty. Example: F$=Gui Asl$("Please Select a file...",Dir$,"Pick One...","#?") If F$="" : Rem CANCEL was hit Print "You didn't select a file" : End End If If Not Exist(F$) Print "The file you chose does not exist" : End Endif Open In 1,F$ : L=Lof(1) : Close 1 : Rem Get size of file Print "You selected the file: "+F$ Print "The file is"+Str$(l)+" Bytes in size" Print "Or"+Str$((L/1024)+1)+"K in size" Print Print "The Full path to the file directory is: "+@{" Gui Dir$ " link guidirs} Print "The Filename on its own is: "+@{" Gui File$ " link guifiles} @endnode @node "guidirs" @{b}Action:@{ub} Get the directory path of the filename from Gui Asl$ @{b}Usage:@{ub} A$=Gui Dir$ @{b}See Also:@{ub} @{" Gui File$ " link guifiles} Returns the path from the previous call to the @{"Gui Asl$()" link guiasls} command. If CANCEL was selected on the requester, it will return an empty string. @endnode @node "guifiles" @{b}Action:@{ub} Get the filename from Gui Asl$() @{b}Usage:@{ub} A$=Gui File$ @{b}See Also:@{ub} @{" Gui Dir$ " link guidirs} Returns the filename from the previous call to the @{" Gui Asl$() " link guiasls} command. If CANCEL was selected on the requester, it will return an empty string. @endnode @node "guiink" @{b}Action:@{ub} Specify the default drawing colour in the current gfx output @{b}Usage:@{ub} Gui Ink colour @{b}See Also:@{ub} @{" Gui Gfx " link guigfx} Gui Ink will simply set the ink colour for future gfx commands such as @{" Gui Draw " link guidraw} and @{" Gui Plot " link guiplot} @endnode @node "guidraw" @{b}Action:@{ub} Draw a line on the current gfx output @{b}Usage:@{ub} Gui Draw x,y to xx,yy Gui Draw To xx,yy Gui Draw draws a line from x,y to xx,yy using the current ink value. It operates in just the same way as the regular DRAW command. To draw a line from the current position of the graphics cursor, use the Draw To followed by a single set of coordinates. @endnode @node "guibar" @{b}Action:@{ub} Draw a filled bar @{b}Usage:@{ub} GUI BAR x,y to xx,yy @{b}See Also:@{ub} @{"Gui Box" link guibox} Gui Bar draws a solid block on the screen/window, with the current ink colour, in exactly the same way as the AMOS command BAR. @endnode @node "guicls" @{b}Action:@{ub} Clear the current graphics output @{b}Usage:@{ub} Gui Cls colour @{b}See Also:@{ub} @{"Gui Clw" link "Gui_Clw" 0} Gui Cls clears all of the current graphics output with the colour specified. Note: Gui Cls will also clear all of the window borders! To clear only graphics, you should use the command @{"Gui Clw" link guiclw} or @{"Gui Bar" link guibar} to clear only portions of the display @endnode @node "guiellipse" @{b}Action:@{ub} Draw an ellipse on the current gfx output @{b}Usage:@{ub} Gui Ellipse x,y,width,height Gui Ellipse will draw an ellipse with its centre point at x,y, and its width and height specified accordingly. @endnode @node "guipasteblock" @{b}Action:@{ub} Paste an AMOS block @{b}Usage:@{ub} Gui Paste Block block,x,y @{b}See Also:@{ub} @{" Gui Paste Icon " link guipasteicon} @{" Gui Paste Bob " link guipastebob} Gui Paste Block will paste a block previously grabbed from within AMOS in the current graphics output at position x,y @{b}NOTE: The palette of the block will only turn out correct if the screen palette has been set accordingly, using a command such as @{" Gui Rgb " link guirgb} @{ub} @endnode @node "guipastebob" @{b}Action:@{ub} Paste an AMOS bob @{b}Usage:@{ub} Gui Paste Bob image,x,y @{b}See Also:@{ub} @{" Gui Paste Block " link guipasteblock} @{" Gui Paste Icon " link guipasteicon} Gui Paste Bob will paste an AMOS bob to the current graphics output. It acts in the same way as the Paste Bob command in AMOS. @{b}NOTE: The palette of the bob will only turn out correct if the screen palette has been set accordingly, using a command such as @{" Gui Rgb " link guirgb} @{ub} @endnode @node "guipasteicon" @{b}Action:@{ub} Paste an AMOS icon @{b}Usage:@{ub} Gui Paste Icon icon,x,y @{b}See Also:@{ub} @{" Gui Paste Block " link guipasteblock} @{" Gui Paste Bob " link guipastebob} Gui Paste Icon will paste an AMOS icon to the current graphics output. It acts in the same way as the Paste Icon command in AMOS. @{b}NOTE: The palette of the icon will only turn out correct if the screen palette has been set accordingly, using a command such as @{" Gui Rgb " link guirgb} @{ub} @endnode @node "guiactual" @{b}Action:@{ub} Returns the current graphics output window @{b}Usage:@{ub} A=Gui Actual @{b}See Also:@{ub} @{" Gui Selected" link guiselected} This variable function returns the window number set by the @{" Gui Gfx " link guigfx} command @endnode @node "guiwidth" @{b}Action:@{ub} Return the width of the specified window @{b}Usage:@{ub} A=Gui Width(window) @{b}See Also:@{ub} @{" Gui Height " link guiheight} @{" Gui In Width " link guiinwidth} @{" Gui In Height " link guiinheight} Gui Width will return the width of the specified window in pixels. @endnode @node "guiheight" @{b}Action:@{ub} Return the height of the specified window @{b}Usage:@{ub} A=Gui Height(window) @{b}See Also:@{ub} @{" Gui Width " link guiwidth} @{" Gui In Width " link guiinwidth} @{" Gui In Height " link guiinheight} Gui Height will return the height of the specified window in pixels. @endnode @node "guiborder" @{b}Action:@{ub} Return the border size on specified side of window @{b}Usage:@{ub} A=Gui Border(window,border) Gui Border returns the size of the border of each of the four sizes of the specified window. The border parameter can be one of: 0 - Left Border 1 - Top Border 2 - Right Border 3 - Bottom Border @endnode @node "guix" @{b}Action:@{ub} Return the X-coordinate of the specified window @{b}Usage:@{ub} A=Gui X (window) @{b}See Also:@{ub} @{" Gui Y " link guiy} Gui X will return the X screen coordinate of the specified window. @endnode @node "guiy" @{b}Action:@{ub} Return the Y-coordinate of the specified window @{b}Usage:@{ub} A=Gui Y (window) @{b}See Also:@{ub} @{" Gui X " link guix} Gui Y will return the Y screen coordinate of the specified window. @endnode @node "guiresize" @{b}Action:@{ub} Change the size of an existing window @{b}Usage:@{ub} Gui Resize window,width,height @{b}See Also:@{ub} @{" Gui Change " link guichange} Gui Resize will resize the specified window to the new dimensions. @endnode @node "guisensitive" @{b}Action:@{ub} Turn window font sensititvity on or off @{b}Usage:@{ub} Gui Sensitive On Gui Sensitive Off Gui Sensitive On will make your GUI windows use your Workbench font settings for displaying, and will try its best to adapt itself to your enviroment. If the new sizes cause the window to not fit on-screen anymore, the command will be ignored by the system. This is the default setting. Gui Sensitive Off makes your windows use the topaz/8 font as used when you create the GUI in GadToolsBox. Note: Custom (image) gadgets are NOT font sensitive. @endnode @node "guiwaitvbl" @{b}Action:@{ub} Wait for the next vertical blank period @{b}Usage:@{ub} Gui Wait Vbl Gui Wait Vbl vbls Gui Wait Vbl is exactly like the AMOS Wait Vbl command, except for intuition. A parameter can be added which causes the program to wait for the specified vbl count. @endnode @node "guiscroll" @{b}Action:@{ub} Scroll an area of the current gfx output @{b}Usage:@{ub} Gui Scroll x,y to xx,yy,numx,numy Gui Scroll scrolls the area x,y to xx,yy by numx pixels horizontally, and numy pixels vertically @endnode @node "guiiconify" @{b}Action:@{ub} Iconify the specified window @{b}Usage:@{ub} Iconify ID=Gui Iconify(window,icon Name,icon path) Iconify the specified window. The specified window will be closed, and a AppIcon with the specified Name and Icon will appear. The number of the window just closed will be used as AppIcon number. So if you iconify the Window number 5, the AppIcon number 5 will be created. This function return the Iconify ID. You need it in order to uniconify the window later. See the @{" Gui Uniconify" link guiuniconify} command. If you don't specify the icon to be used, the system default TOOL icon will be used. @endnode @node "guiuniconify" @{b}Action:@{ub} Uniconify a window previously iconified with @{" Gui Iconify" link guiiconify} @{b}Usage:@{ub} Gui Uniconify Iconify ID Uniconify the specified window. Be sure to pass the correct Iconify ID returned by a previous call to @{" Gui Iconify " link guiiconify} or a nice guru will visit you ;) @endnode @node "guikeyshift" @{b}Action:@{ub} Returns the status of the shift keys @{b}Usage:@{ub} bitmap=Gui Key Shift It's the equivalent of the Amos Key Shift command. When Gui Wait report a Keyboard event, you can check the status of the so called 'control keys' like shift,ctrl,Alt and so on. The bitmap value returned is the same of the standard Key Shift: Bit Key Tested 0 Left shift 1 Right shift 2 Caps Lock 3 Ctrl 4 Left Alt 5 Right Alt 6 Left Amiga 7 Right Amiga @endnode @node "guiread" @{b}Action:@{ub} Return the status of the specified gadget @{b}Usage:@{ub} A=Gui Read(window,gadget) @{b}See Also:@{ub} @{" Gui Read$ " link guireads} @{" Gui Code " link guicode} @{" Gui Code$ " link guicodes} It will return the current status of the specified gadget from the specified window. Gui Read is similar to @{" Gui Code " link guicode} except it doesnt need to be called after the specified gadget is selected and reported by @{" Gui Wait " link guiwait}. @endnode @node "guireads" @{b}Action:@{ub} Return text held in the specified String/Listview gadget @{b}Usage:@{ub} A$=Gui Read$(window,gadget) @{b}See Also:@{ub} @{" Gui Read " link guiread} @{" Gui Code " link guicode} @{" Gui Code$ " link guicodes} It returns the string held in the specified gadget. The result will depend on the kind of gadget, which can be one of the following: LISTVIEW Selected item CYCLE Selected item STRING Text entered For all the other kind of gadgets a @{B}empty@{UB} string will be returned. @endnode @node "guibeep" @{b}Action:@{ub} Cause the screen to flash @{b}Usage:@{ub} Gui Beep This command use the system beep function... it will flash your current screen, or perform the playing of a sample, depending on how you have your workbench preferences set. The command is used to alert the user at certain parts in your program. @endnode @node "guionoff" @{b}Action:@{ub} Enable/Disable a specified window @{b}See Also:@{ub} @{" Gui Lock " link guilock} @{" Gui Unlock " link guiunlock} @{b}Usage:@{ub} Gui On window Gui Off window Gui On and Gui Off enable and disable the specified window. When a window is disabled, the user can't interact with it (i.e. can't select gadgets, menus etc.) and the busy pointer will be displayed (only with OS 3.x). Gui On will turn the window back on again. @endnode @node "guilock" @{b}Action:@{ub} Disable all windows except the specified one @{b}Usage:@{ub} Gui Lock window @{b}See Also:@{ub} @{" Gui Unlock " link guiunlock} Gui Lock will disable all the open windows @{B}except@{UB} the specified window. When a window is locked, the user can't interact with it (i.e. can't select gadgets, menus etc.) and the busy pointer will be displayed (only with OS 3.x) This command can prove handy in multi-window programs, to prevent accidental selection in another window. It can also be used to force a user to make a selection in a specific window. The command @{"Gui Unlock" link guiunlock} will re-enable all the windows @endnode @node "guiunlock" @{b}Action:@{ub} Re-enable all the windows previously locked using Gui Lock @{b}Usage:@{ub} Gui Unlock @{b}See Also:@{ub} @{" Gui Lock " link guilock} In order to reactivate all the inputs in the windows previously locked by Gui Lock you need this command. @endnode @node "guirememberonoff" @{b}Action:@{ub} Trigger remembering of previous window positions @{b}Usage:@{ub} Gui Remember On Gui Remember Off Gui Remember On will make the system remember where exactly a window was when it was closed, so if it is opened again in the future, it will keep its old positions. Gui Remember Off will simply set the window back to its original settings each time it is closed, as set in the GadToolsBox editor. @endnode @node "guititles" @{b}Action:@{ub} Set the title of the specified window and screen @{b}Usage:@{ub} Gui Titles window,window title$,screen title$ Gui Titles will set the title of the specified window, and also that of the screen it is opened on. The extra screen title function can be used to provide help/info as the user is progressing through an input gadget or some other part of your program. If you pass a empty string in one of the title string th old one will be left unchanged. @endnode @node "guiinwidth" @{b}Action:@{ub} Return the internal width of the specified window @{b}Usage:@{ub} Gui In Width(window) @{b}See Also:@{ub} @{" Gui Border " link guiborder} Gui In Width return the width of the specified window, excluding the window borders. @endnode @node "guiinheight" @{b}Action:@{ub} Return the internal height of the specified window @{b}Usage:@{ub} Gui In Height(window) @{b}See Also:@{ub} @{" Gui Border " link guiborder} Gui In Height return the height of the specified window, excluding the window borders. @endnode @node "guitext" @{b}Action:@{ub} Write some text into the current gfx output @{b}Usage:@{ub} Gui Text x,y,text$ @{b}See Also:@{ub} @{" Gui Pen " link guipen} @{" Gui Paper " link guipaper} @{" Gui Writing " link guiwriting} Gui Text prints the supplied string inside on the current graphics output at coordinates x and y, similar to that of the AMOS command Text. @endnode @node "guipaper" @{b}Action:@{ub} Set the text output paper colour @{b}Usage:@{ub} Gui Paper colour @{b}See Also:@{ub} @{" Gui Pen " link guipen} Gui Paper sets the paper colour to be used for @{" Gui Text " link guitext} calls. It act in exactly the same way as the Amos Paper command. @endnode @node "guipen" @{b}Action:@{ub} Set the text output pen colour @{b}Usage:@{ub} Gui Pen colour @{b}See Also:@{ub} @{" Gui Paper " link guipaper} Gui Pen sets the pen colour to be used for @{" Gui Text " link guitext} calls. It act in exactly the same way as the Amos Pen command. @endnode @node "guiwriting" @{b}Action:@{ub} Change the graphic writing mode @{b}Usage:@{ub} Gui Writing bitpattern This command is used to set the graphic mode used for drawing lines, text, and filled shapes. The bitpattern can be made up with the following: %000 - Only draw graphics using the current ink colour. %001 - Replace any existing graphics with new graphics (default) %010 - Change old graphics that overlap with new graphics using XOR. %100 - Reverse ink and paper colours, creating inverse video effect. @endnode @node "guievent" @{b}Action:@{ub} Return the current window status @{b}Usage:@{ub} A=Gui Event @{b}See Also:@{ub} @{" Gui Wait " link guiwait} Gui Event is very similar to the command Gui Wait, except it will not stop the program execution until a event occur. The command will simply make a check and return the same values as in Gui Wait so your program can still perform other tasks at the same time. @{B}It returns the value -7 if nothing is happened...@{UB} The command is extremely handy for smaller functions, such as clicking "Abort" whilst copying a file etc. It is also important that you dont use Gui Event when you could use @{" Gui Wait " link guiwait}!! @endnode @node "guirange" @{b}Action:@{ub} Limit input for integer gadgets @{b}Usage:@{ub} Gui Range window,gadget,minvalue,maxvalue Gui Range will limit input in integer gadgets between the MIN and MAX values specified. All the values entered by the user will be clipped in the specified range. For example, if you have done Gui Range 1,1,10,20, and the user inputs 5, it will automatically be set to 10. Similarly, if the user inputs 2273226, it will be set to 20. @endnode @node "guiaslscreen" @{b}Action:@{ub} Call the standard ASL screenmode requester @{b}Usage:@{ub} F=Gui Asl Screen Gui Asl Screen causes the ASL Screenmode requester to appear, allowing you to pick an available screenmode. When selected, the DisplayID value of the screen will be returned. If the value returned is -1 then the user hit Cancel on the requester. @endnode @node "guigfx" @{b}Action:@{ub} Set graphics output to screen/window @{b}Usage:@{ub} Gui Gfx type,number Gui Gfx tells the system where graphic operations such as @{" Gui Draw " link "Gui_Draw" 0} and @{" Gui Plot " link guiplot} are carried out. The Type parameter can be one of: 0 - Window 1 - Screen The Number parameter tells the system which window or screen to direct the output to. For example, if you wanted to send all output to Screen 1, you could use: Gui Gfx 1,1 .. Or to direct it to window number 5: Gui Gfx 0,5 Obviously the specified window or screen must be open :) @endnode @node "guiaslfont" @{b}Action:@{ub} Calls the ASL font requester and return the selected font name @{b}Usage:@{ub} A$=Gui Asl Font Calls the ASL font requester and loads A$ with the selected font name (including the .font extension). Example: 'Gui Asl Font demo 'Written by Andy "Mushroom" Kellett of Mushroom PD Amos To Back F$=Gui Asl Font : A=Gui Font Size : Rem Grab a font from the requester If F$="" Print "No Font Selected." : End End If Print "You Chose font "+F$ Print "The font is"+str$(A)+" pixels tall." Amos To Front @endnode @node "guixgad" @{b}Action:@{ub} Get the X position of the specified gadget @{b}See Also:@{ub} @{" Gui Gad Width " link guigadwidth} @{" Gui Gad Height " link guigadheight} @{b}Usage:@{ub} A=Gui X Gad(window,gadget) This function return the X position of the specified gadget (in pixels) relative to the top-left of the window. @endnode @node "guiygad" @{b}Action:@{ub} Get the Y position of the specified gadget @{b}See Also:@{ub} @{" Gui Gad Width " link guigadwidth} @{" Gui Gad Height " link guigadheight} @{b}Usage:@{ub} A=Gui Y Gad(window,gadget) This function return the Y position of the specified gadget (in pixels) relative to the top-left of the window. @endnode @node "guigadwidth" @{b}Action:@{ub} Return the width (in pixels) of the specified gadget @{b}Usage:@{ub} A=Gui Gad Width(window,gadget) Gui Gad Width will simply return the width of the specified gadget. Its especially handy for when you are using the @{" Gui Sensitive On" link guisensitiveonoff} command since the GUI will try to adapt itself to your workbench settings. @endnode @node "guigadheight" @{b}Action:@{ub} Return the height (in pixels) of the specified gadget @{b}Usage:@{ub} A=Gui Gad Height(window,gadget) Gui Gad Height will simply return the width of the specified gadget. Its especially handy for when you are using the @{" Gui Sensitive On" link guisensitiveonoff} command since the GUI will try to adapt itself to your workbench settings. @endnode @node "guixfont" @{b}Action:@{ub} Get the X size of the font @{b}Usage:@{ub} A=Gui X Font Gui X Font will return the width of the system font currently used. @endnode @node "guiyfont" @{b}Action:@{ub} Get the Y size of the font @{b}Usage:@{ub} A=Gui Y Font Gui Y Font will return the height of the system font currently used. @endnode @node "guigadadr" @{b}Action:@{ub} Get the structure address of a gadget. @{b}Usage:@{ub} A=Gui Gad Adr(window,gadget) Gui Gad Adr returns the structure address of the specified gadget. @{b}Note: Its not a good idea to mess around with the structure values in memory unless you know what you are doing!@{ub} @endnode @node "guiactivate" @{b}Action:@{ub} Activate an input gadget on the specified window @{b}Usage:@{ub} Gui Activate window,gadget Gui Activate will activate the specified input gadget (wether it be a string/integer gadget) encouraging the user to type something in. @endnode @node "guikind" @{b}Action:@{ub} Return the gadget type @{b}Usage:@{ub} A=Gui Kind(window,gadget) Gui Kind returns the kind of the specified gadget which will be one of the following: 0 - BUTTON (with image) 1 - BUTTON 2 - CHECKBOX 3 - INTEGER 4 - LISTVIEW 5 - MX 6 - NUMBER 7 - CYCLE 8 - PALETTE 9 - SCROLLER 10 - reserved 11 - SLIDER 12 - STRING 13 - TEXT 14 - reserved 15 - PROGRESS BAR @endnode @node "guilen" @{b}Action:@{ub} Get the length of a text string (in pixels) @{b}Usage:@{ub} A=Gui Len(string,mode) Gui Len will return the length (in pixels) of the string. It works just like the AMOS command Text Length(). This command is especially handy which using the @{" Gui Sensitive On" link guisensitiveonoff} function. @endnode @node "guisw" @{b}Action:@{ub} Return the pixel width with font sensitivity @{b}Usage:@{ub} A=Gui Sw(width) @{b}See Also:@{ub} @{" Gui Sx " link guisx} @{" Gui Sy " link guisy} @{" Gui Sh " link guish} Gui Sw return the pixel width rescaled by the font sensitivity routine. See the @{" Gui Sx " link guisx} command for more info. @endnode @node "guisx" @{b}Action:@{ub} Return the X position of a point with font sensitivity @{b}Usage:@{ub} A=Gui Sx(X) @{b}See Also:@{ub} @{" Gui Sy " link guisy} @{" Gui Sw " link guisw} @{" Gui Sh " link guish} Gui Sx will return the new X position of a point, when scaled as the gadgets are with Gui Sensitive On. For example, if you were to do Gui Bar 10,15 To 25,30 with the topaz/8 font, you should do Gui Bar Gui Sx(10),Gui Sy(15) To Gui Sx(25),Gui Sy(30) instead, if you put font sensitivity on (it is by default). If you need to rescale the width and height of a object, use the Gui Sw and Gui Sh commands. @endnode @node "guisy" @{b}Action:@{ub} Return the Y position of a point with font sensitivity @{b}Usage:@{ub} A=Gui Sy(Y) @{b}See Also:@{ub} @{" Gui Sx " link guisx} @{" Gui Sw " link guisw} @{" Gui Sh " link guish} Gui Sy will return the new Y position of a point, when scaled as the gadgets are with Gui Sensitive On. For example, if you were to do Gui Bar 10,15 To 25,30 with the topaz/8 font, you should do Gui Bar Gui Sx(10),Gui Sy(15) To Gui Sx(25),Gui Sy(30) instead, if you put font sensitivity on (it is by default). If you need to rescale the width and height of a object, use the Gui Sw and Gui Sh commands. @endnode @node "guish" @{b}Action:@{ub} Return the pixel height with font sensitivity @{b}Usage:@{ub} A=Gui Sh(height) @{b}See Also:@{ub} @{" Gui Sx " link guisx} @{" Gui Sy " link guisy} @{" Gui Sw " link guisw} Gui Sh return the pixel height rescaled by the font sensitivity routine. See the @{" Gui Sx " link guisx} command for more info. @endnode @node "guiclw" @{b}Action:@{ub} Clear the specified window with the specified colour @{b}Usage:@{ub} Gui Clw window,colour @{b}See Also:@{ub} @{" Gui Cls " link guicls} @{" Gui Bar " link guibar} Gui Clw will clear all of the graphics from the specified window, with the specified colour. Note, that all gadgets and integers will be erased, and screen borders and titles will be left intact, unlike @{" Gui Cls " link guicls} @endnode @node "guios" @{b}Action:@{ub} Get the operating system version @{b}Usage:@{ub} A=Gui Os Gui Os will simply return the operating system version number. @endnode @node "guimousewx" @{b}Action:@{ub} Get the mouse X position in relation to current window @{b}Usage:@{ub} X=Gui Mouse Wx @{b}See Also:@{ub} @{" Gui Mouse Ex " link guimouseex} @{" Gui Mouse Ey " link guimouseey} @{" Gui Mouse X " link guimousex} @{" Gui Mouse Y " link guimousey} @{" Gui Mouse Wy " link guimousewy} The command will return the X coordinate of the mouse in the current window. The top-left coordinates of a window are 0,0. @endnode @node "guimousewy" @{b}Action:@{ub} Get the mouse Y position in relation to current window @{b}Usage:@{ub} Y=Gui Mouse Wy @{b}See Also:@{ub} @{" Gui Mouse Ex " link guimouseex} @{" Gui Mouse Ey " link guimouseey} @{" Gui Mouse X " link guimousex} @{" Gui Mouse Y " link guimousey} @{" Gui Mouse Wx " link guimousewx} The command will return the Y coordinate of the mouse in the current window. The top-left coordinates of a window are 0,0. @endnode @node "guimouseex" @{b}Action:@{ub} Get the X mouse position related to the last event occured @{b}Usage:@{ub} X=Gui Mouse Ex @{b}See Also:@{ub} @{" Gui Mouse Ey " link guimouseey} @{" Gui Mouse X " link guimousex} @{" Gui Mouse Y " link guimousey} @{" Gui Mouse Wx " link guimousewx} @{" Gui Mouse Wy " link guimousewy} When Gui Wait return a GUI related event (see the list below), you can use this command to find out the exact position of the mouse when the event occured. Supported events: -11 Mouse click -12 Mouse move -15 Icon drag'n'drop For example, if the user click the mouse you'll receive the -11 event, but if you try to get the mouse coords using @{" Gui Mouse Wx " link guimousewx} you'll get the CURRENT mouse coord wich may be different from the point where the user has clicked. @endnode @node "guimouseey" @{b}Action:@{ub} Get the Y mouse position related to the last event occured @{b}Usage:@{ub} Y=Gui Mouse Ey @{b}See Also:@{ub} @{" Gui Mouse Ex " link guimouseex} @{" Gui Mouse X " link guimousex} @{" Gui Mouse Y " link guimousey} @{" Gui Mouse Wx " link guimousewx} @{" Gui Mouse Wy " link guimousewy} When Gui Wait return a GUI related event (see the list below), you can use this command to find out the exact position of the mouse when the event occured. Supported events: -11 Mouse click -12 Mouse move -15 Icon drag'n'drop For example, if the user click the mouse you'll receive the -11 event, but if you try to get the mouse coords using @{" Gui Mouse Wy " link guimousewx} you'll get the CURRENT mouse coord wich may be different from the point where the user has clicked. @endnode @node "guiplot" @{b}Action:@{ub} Plot a point on the current gfxoutput @{b}Usage:@{ub} Gui Plot X,Y @{b}See Also:@{ub} @{" Gui Draw " link guidraw} @{" Gui Bar " link guibar} Simply plots a single point at the coordinates specified, with the currently defined ink colour. @endnode @node "guibbox" @{b}Action:@{ub} Draw a bevelbox on current gfx output @{b}Usage:@{ub} Gui Bbox x,y,xx,yy,mode @{b}See Also:@{ub} @{" Gui Box " link guibox} @{" Gui Draw " link guidraw} @{" Gui Plot " link guiplot} Draw a bevel box at the specified X and Y coordinnates, XX and YY pixels in width/height. If mode is set to anything other than 0, then the box is drawn recessed. @endnode @node "guimousemode" @{b}Action:@{ub} Alter frequency of Mouse Click events @{b}Usage:@{ub} Gui Mouse Mode 0 Gui Mouse Mode 1 Gui Mouse Mode is a neat little command in which you can control the events which occur when you press the mouse button. When you click on a GUI, be default you'll receive two -11 events, 1 when you click the button, and another when you let go. If you set Gui Mouse Mode to 1, this will change to just 1 event, whereas mode 0 is the default. @endnode @node "guifontsize" @{b}Action:@{ub} Get the size of the selected font in the ASL font requester @{b}Usage:@{ub} SIZE=Gui Font Size @{b}See Also:@{ub} @{" Gui Asl Font " link guiaslfont} When the user selects a font in the ASL Font requester, you can use this command to obtain the size of the font selected. @endnode @node "guipubscreen" @{b}Action:@{ub} Attempt access to the named public screen @{b}Usage:@{ub} LOCK=Gui Pub Screen(NAME$) @{b}See Also:@{ub} @{" Gui Pub Free " link guipubfree} In order to be able to open your GUI in a public screen, you must obtain the access to do it. This command attempt to obtain access to the named public screen. If the screen exists and can be locked, then it will be made accessible by your program, or else the value returned in LOCK will be 0. @endnode @node "guipubfree" @{b}Action:@{ub} Free public screen locked with Gui Pub Screen @{b}Usage:@{ub} Gui Pub Free @{b}See Also:@{ub} @{" Gui Pub Screen " link guipubscreen} This command free's the public screen, previously locked into place by @{" Gui Pub Screen" link guipubscreen}. You MUST always free a public screen when you have finished with it. If you try to lock another screen with Gui Pub Screen, the previous screen will be freed automatically. @endnode @node "guipublist" @{b}Action:@{ub} Get list of all Public Screens on system @{b}Usage:@{ub} Gui Pub List @{b}See Also:@{ub} @{" Gui Pub List Free " link guipublistfree} @{" Gui Pub Name$ " link guipubnames} The command will obtain a list of all public screens currently opened on your Amiga. @{b}@{u}ATTENTION: While you are reading the list of screens, the system is locked. You must read all the names as soon as you can!@{ub}@{uu} The correct way to read the list is: Gui Pub List For I=0 To 31 : PUB$(I)=Gui Pub Name$ : Exit If PUB$(I)="" : Next Gui Pub List Free @endnode @node "guipubnames" @{b}Action:@{ub} get a public screen name from the system list @{b}Usage:@{ub} A$=Gui Pub Name$ @{b}See Also:@{ub} @{" Gui Pub List " link guipublist} @{" Gui Pub List Free " link guipublistfree} The command returns the next public screen name from the Amiga's list of Public Screens obtained with the @{" Gui Pub List " link guipublist} command. See @{"Gui Pub List" link guipublist} for more info. @endnode @node "guipublistfree" @{b}Action:@{ub} Free Public Screen List @{b}Usage:@{ub} Gui Pub List Free @{b}See Also:@{ub} @{" Gui Pub List " link guipublist} @{" Gui Pub Name$ " link guipubnames} Use this command to free the Public screens list from memory. You @{b}@{u}MUST@{ub}@{uu} use this command when you have finished with the list. See @{"Gui Pub List" link guipublist} for more info. @endnode @node "guipubtofront" @{b}Action:@{ub} Put specified Public screen to front of display @{b}Usage:@{ub} Gui Pub To Front SCREEN @{b}See Also:@{ub} @{" Gui Pub Screen " link guipubscreen} @{" Gui Pub To Back " link guipubtoback} Bring the specified Public screen to the front of the view. The value in SCREEN is the value returned by the command @{" Gui Pub Screen " link guipubscreen}. @endnode @node "guipubtoback" @{b}Action:@{ub} Put specified Public screen to back of display @{b}Usage:@{ub} Gui Pub To Back SCREEN @{b}See Also:@{ub} @{" Gui Pub Screen " link guipubscreen} @{" Gui Pub To Front " link guipubtofront} Bring the specified Public screen to the front of the view. The value in SCREEN is the value returned by the command @{" Gui Pub Screen " link guipubscreen}. @endnode @node "guirmb" @{b}Action:@{ub} Enable the use of the Right mouse button in a window @{b}Usage:@{ub} Gui Rmb window,mode @{b}See Also:@{ub} @{" Gui Code " link guicode} When the right mouse button is pressed in a window, by default, the OS will try and pop up a menu. This command allows you to monitor it as an event so you can use it for other things: Gui Rmb 1,True The RMB will be detected as normal by intuition Gui Rmb 1,False Now you have the control of the RMB. When the user will hold down the RMB, the Gui Wait command will return a -11 (mouse click) event. See @{" Gui Code " link guicode} Gui Rmb will only work for the specified windows. @{B}Remember:If YOU monitor the right mouse button, the menus aren't displayed!@{UB} @endnode @node "guipaint" @{b}Action:@{ub} Fill an area of screen from specified coordinates @{b}Usage:@{ub} Gui Paint X,Y @{b}See Also:@{ub} @{" Gui Bar " link guibar} Works in exactly the same way as the Amos command Paint. It will simply fill any section of the current gfx output with a solid block of colour using the currently defined ink. @endnode @node "guipoint" @{b}Action:@{ub} Get the colour of the pixel at specified coordinates @{b}Usage:@{ub} INK=Gui Point(X,Y) Works in exactly the same way as the Amos command Point. It will simply returns the colour of the point at the specified X,Y coordinates. @endnode @node "guitextbase" @{b}Action:@{ub} Get the text base of the current font @{b}Usage:@{ub} T=Gui Text Base Works in the same way as the Amos command Text Base. What the command does, is it will return the number of pixels from the top of a character, and at the point from which it will be printed on the screen. It can be considered a "hot spot" in which all fonts have. The value is calculated for the currently used font. @endnode @node" guiscreenwidth" @{b}Action:@{ub} Get the width of the current screen @{b}Usage:@{ub} W=Gui Screen Width @{b}See Also:@{ub} @{" Gui Screen Height " link guiscreenheight} @{" Gui Screen Colours " link guiscreencolours} @{" Gui Screen Depth " link guiscreendepth} Returns the pixels width of the current screen. @endnode @node" guiscreenheight" @{b}Action:@{ub} Get the height of the current screen @{b}Usage:@{ub} W=Gui Screen Height @{b}See Also:@{ub} @{" Gui Screen Width " link guiscreenwidth} @{" Gui Screen Colours " link guiscreencolours} @{" Gui Screen Depth " link guiscreendepth} Returns the pixel height of the current screen. @endnode @node "guicolours" @{b}Action:@{ub} Return the number of colours of the current screen @{b}Usage:@{ub} C=Gui Screen Colours @{b}See Also:@{ub} @{" Gui Screen Width " link guiscreenwidth} @{" Gui Screen Height " link guiscreenheight} @{" Gui Screen Depth " link guiscreendepth} Return the number of colours of the current screen. @endnode @node "guiscreenopen" @{b}Action:@{ub} Open a screen @{b}Usage:@{ub} Gui Screen Open screen number,width,height,colours,ModeID,name Gui Screen Open screen number,width,height,colours,modeID,name,font name,font size @{b}See Also:@{ub} @{" Gui Asl Open " link guiaslopen} @{" Gui Screen Close " link guiscreenclose} @{" Gui Pub Mode " link guipubmode} Opens an OS public screen, with the specified ModeID and name. If you specify the font name, and the font isn't available, the current WB font will be used. The opened screen became the current screen... if you've previously locked a public screen, it will be automatically unlocked. By default the screen is set to private state... if you want make it Public use the @{" Gui Pub Mode " link guipubmode} command. @endnode @node "guiscreenclose" @{b}Action:@{ub} Close an screen @{b}Usage:@{ub} Gui Screen Close number @{b}See Also:@{ub} @{" Gui Asl Open " link guiaslopen} @{" Gui Screen Open " link guiscreenopen} Closes a previously opened screen. If there are some windows opened on the screen, they will be automatically closed. @endnode @node "guichange" @{b}Action:@{ub} Move and resize a GUI at the same time @{b}Usage:@{ub} Gui Change window,x,y,width,height @{b}See Also:@{ub} @{" Gui Move " link guimove} @{" Gui Resize " link guiresize} Move and resize a gui at the same time. Use it if you must quickly move and resize your window, instead of Gui Move followed by Gui Resize. @endnode @node "guimousereport" @{b}Action:@{ub} Activate events reports on every mouse movement @{b}Usage:@{ub} Gui Mouse Report window,mode @{b}See Also:@{ub} @{" Gui Mouse Ex " link guimouseex} @{" Gui Mouse Ey " link guimouseey} @{" Gui Gadget " link guigadget} You must use this command if you want to be informed about every mouse movement. When the user move the mouse, gui wait will returns a -12 event. In order to know the @{b}exact@{ub} mouse position for every event returned by @{" Gui Wait " link guiwait} you have to use the @{"Gui Mouse Ex/Ey" link guimouseex} commands. Example: Gui Mouse Report 1,True Activate mouse movement report on window 1 Gui Mouse Report 1,False Deactivate mouse movement report The command works for the specified window(s) only. @endnode @node "guiaslid" @{b}Action:@{ub} Return the screen Mode selected in the Asl screen requester @{b}Usage:@{ub} A=Gui Asl Id @{b}See Also:@{ub} @{" Gui Asl Screen " link guiaslscreen} @{" Gui Asl Width " link guiaslwidth} @{" Gui Asl Height " link guiaslheight} @{" Gui Asl Colours " link guiaslcolours} @{" Gui Asl Depth " link guiasldepth} Return the screen mode selected in the previously opened Asl screen requester using the @{" Gui Asl Screen " link guiaslscreen} command. @endnode @node "guiaslwidth" @{b}Action:@{ub} Return the screen width selected in the Asl screen requester @{b}Usage:@{ub} A=Gui Asl Width @{b}See Also:@{ub} @{" Gui Asl Screen " link guiaslscreen} @{" Gui Asl Id " link guiaslid} @{" Gui Asl Height " link guiaslheight} @{" Gui Asl Colours " link guiaslcolours} @{" Gui Asl Depth " link guiasldepth} Return the screen width selected in the previously opened Asl screen requester using the @{" Gui Asl Screen " link guiaslscreen} command. @endnode @node "guiaslheight" @{b}Action:@{ub} Return the screen height selected in the Asl screen requester @{b}Usage:@{ub} A=Gui Asl Height @{b}See Also:@{ub} @{" Gui Asl Screen " link guiaslscreen} @{" Gui Asl Id " link guiaslid} @{" Gui Asl Colours " link guiaslcolours} @{" Gui Asl Depth " link guiasldepth} Return the screen height selected in the previously opened Asl screen requester using the @{" Gui Asl Screen " link guiaslscreen} command. @endnode @node "guiaslcolours" @{b}Action:@{ub} Return the number of colours selected in the Asl screen requester @{b}Usage:@{ub} A=Gui Asl Colours @{b}See Also:@{ub} @{" Gui Asl Screen " link guiaslscreen} @{" Gui Asl Id " link guiaslid} @{" Gui Asl Height " link guiaslheight} @{" Gui Asl Depth " link guiasldepth} Return the number of colours selected in the previously opened Asl screen requester using the @{" Gui Asl Screen " link guiaslscreen} command. @endnode @node "guiasldepth" @{b}Action:@{ub} Return the number of planes of the screen selected in the Asl screen requester @{b}Usage:@{ub} A=Gui Asl Depth @{b}See Also:@{ub} @{" Gui Asl Screen " link guiaslscreen} @{" Gui Asl Id " link guiaslid} @{" Gui Asl Height " link guiaslheight} @{" Gui Asl Colours " link guiaslcolours} Return the number of planes of the screen selected in the previously opened Asl screen requester using the @{" Gui Asl Screen " link guiaslscreen} command. @endnode @node "guiaslopen" @{b}Action:@{ub} Open a screen using the Asl Screen Requester settings @{b}Usage:@{ub} Gui Asl Open screen number,name Gui Asl open screen number,name,font name,font size @{b}See Also:@{ub} @{" Gui Screen Open " link guiscreenopen} @{" Gui Screen Close " link guiscreenclose} Opens a screen using the settings (width,height,screen mode,colours etc) specified by the user in the @{" Asl Screen Mode requester " link guiaslscreen} It's the best way to open a user definable screen! @endnode @node "guicheck" @{b}Action:@{ub} Check a gadgets existance at specified coordinates @{b}Usage:@{ub} A=Gui Check(window,x,y) Checks the window at the specified X and Y coordinates to see if a gadget exists. If a gadget does exist, the number of the gadget is returned, else -1 is reported. @endnode @node "guipause" @{b}Action:@{ub} Pause the program in a friendly way @{b}See Also:@{ub} @{" Gui Wait Vbl " link guiwaitvbl} @{" Gui Timer " link guitimer} @{b}Usage:@{ub} Gui Pause vbls Will pause the program for the specified number of vbl's in a system friendly way, using 0% CPU time. Handy for repetitive tasks, as it wont take anywhere near as much CPU intensity as any other Amos method of waiting. @endnode @node" guiscreendepth" @{b}Action:@{ub} Get the planes depth of the current screen @{b}Usage:@{ub} W=Gui Screen Depth @{b}See Also:@{ub} @{" Gui Screen Height " link guiscreenheight} @{" Gui Screen Colours " link guiscreencolours} @{" Gui Screen Width " link guiscreenwidth} Returns the plane depth of the current screen. @endnode @node "guirgb" @{b}Action:@{ub} Change current screen colours @{b}Usage:@{ub} Gui Rgb colour,value Gui Rgb colour,red,green,blue @{b}See Also:@{ub} @{" Gui Colour " link guicolour} Gui rgb will allow you to change the specified colour of the screen's palette. It uses the regular values 0 (black) to 4095 (white). The second version of the command also allows you to specify the RGB values of the colour. Gui Rgb automatically detect AGA or OCS/ECS, and so automatically use the 4bit or 32bit(AGA) colour precision. So if you use a 32bit definition on a ECS machine, it will be automatically scaled to 4bit. On AGA machines you @{b}MUST@{ub} use 32bit value! Gui Rgb 15,15,15 isn't white! the correct way is Gui Rgb 255,255,255. And so the best way is to use always the 32bit precision, because when necessary it's scaled as well. @endnode @node "guicolour" @{b}Action:@{ub} Return the specified colour value @{b}Usage:@{ub} C=Gui Colour(colour number) @{b}See Also:@{ub} @{" Gui Rgb " link guirgb} Return the colour's value of the specified colour number as the Amos Colour command. @endnode @node "guiarrayread" @{b}Usage:@{ub} A=Gui Array Read(window,listview,element) @{b}See Also:@{ub} @{" Gui Read " link guiread} @{" Gui Array " link guiarray} Is the equivalent of Gui Read(), but it returns the number of the array associated to the specified element of the listview. i.e A$(0)="Hello" A$(1)="" A$(2)="World!" A$(3)="" A$(4)="Amiga RULEZ!" the listview will be: Hello World! Amiga RULEZ! if the user click on 'World!' Gui Read() returns 1. But the array is A$(2) :( Using Gui Array Read you'll obtain the correct value i.e 2 :) See also Gui Array If the listview is the gadget number 5 and the GUI number 2: AR=Gui Array Read(2,5,1) @endnode @node "guiarray" @{b}Action:@{ub} Get correct array positions, even with blanks @{b}Usage:@{ub} A=Gui Array(element) @{b}See Also:@{ub} @{" Gui Read " link guiread} @{" Gui Array Read " link guiarrayread} It's the equivalent of @{" Gui Code " link guicode}, but returns the correct array value associated to the listview element. Useful for listview gadget only. @endnode @node "guiput" @{b}Action:@{ub} Place a string into a file @{b}Usage:@{ub} Gui Put file$,string$ @{b}See Also:@{ub} @{" Gui Get$" link guigets} Works in the opposite to @{" Gui Get$" link guigets}, by placing the string into the file. See Gui Get$ for information. @endnode @node "guigets" @{b}Action:@{ub} Load a file into a string @{b}Usage:@{ub} A$=Gui Get$(file name) @{b}See Also:@{ub} @{" Gui Put " link guiput} Loads the file into the specified string. This command is good for config data and such. It does not require the Open In...Line Input#...Close commands. @endnode @node "guired" @{b}Action:@{ub} Return the RED level of the specified colour @{b}Usage:@{ub} R=Gui Red(RGB colour) @{b}See Also:@{ub} @{" Gui Green " link guigreen} @{" Gui Blue " link guiblue} This function returns the RED level of the specified colour @endnode @node "guigreen" @{b}Action:@{ub} Return the GREEN level of the specified colour @{b}Usage:@{ub} R=Gui Green(RGB colour) @{b}See Also:@{ub} @{" Gui Red " link guired} @{" Gui Blue " link guiblue} This function returns the GREEN level of the specified colour @endnode @node "guiblue" @{b}Action:@{ub} Return the BLUE level of the specified colour @{b}Usage:@{ub} R=Gui Blue(RGB colour) @{b}See Also:@{ub} @{" Gui Green " link guigreen} @{" Gui Red " link guired} This function returns the BLUE level of the specified colour @endnode @node "guicenter" @{b}Action:@{ub} Switch on or off, the auto-centre feature of window opening @{b}Usage:@{ub} Gui Center X-Bool,Y-Bool @{b}See Also:@{ub} @{" Gui Remember " link guiremember} Switch on/off the ability to centre widows on the current screen. It is possibly to specify if windows are to be centred on an X, Y or both coordinate basis: Gui Center True,False The windows will be centered only the X coord Gui Center False,True The windows will be centered only the Y coord Center True,True The windows will be centered in the screen (x and y) @endnode @node "guiinputs" @{b}Action:@{ub} Read a line of text from the current input @{b}Usage:@{ub} A$=Gui Input$ @{b}See Also:@{ub} @{" Gui Output " link guioutput} It reads a line (requires a RETURN) from the current input, for example STDIN. @endnode @node "guioutputs" @{b}Action:@{ub} Send a line of text to the current output stream @{b}Usage:@{ub} Gui Output string @{b}See Also:@{ub} @{" Gui Input$ " link guiinputs} It send a line of text (requires a RETURN) to the current output stream, for the example the Shell used to run the program. @endnode @node "guiclone" @{b}Action:@{ub} Clone an AMOS screen to work on an OS screen @{b}Usage:@{ub} Gui Clone GUI Screen,mode Display the current AMOS screen into the GUI Screen. @{i}No copper hacks or bitplanes hacking.. it's a 100% OS friendly system@{ui}. The GUI screen will display the AMOS one, cloning automatically the colours. Now you can work as usual into the AMOS screen, using all the available extensions with turbo-fast graphic commands, and the result will be available under intuition :) Gui Clone 1,True : Rem display the current AMOS screen into GUI Screen 1 Gui Clone 1,False : Rem restore the original intuition screen Using this system, you can open a DblPAL screen and promote the AMOS screen into it, so in AMOS you've access to a DblPAL AMOS screen using the usual gfx command. @{b}Actually the Double buffer and the rainbows aren't supported, and this commands works only using the Amiga Chipset... with a Gfx Card it doesn't works!!@{ub} If you must change a colour you must use Gui Rgb, since you're working under intuition. @endnode @node "guiarrayup" @{b}Action:@{ub} Cycle up contents of a string array @{b}Usage:@{ub} Gui Array Up array address,start position @{b}See Also:@{ub} @{" Gui Array Down " link guiarraydown} The command will cycle upwards the contents of a string array, starting from the specified element. Example: A$(0)="Hello" A$(1)="" A$(2)="World!" A$(3)="" A$(4)="Amiga RULEZ!" Gui Array Up Array(A$(0)),0 : Rem the result is...... A$(0)="" A$(1)="World!" A$(2)="" A$(3)="Amiga RULEZ!" A$(4)="Hello" if you call it again..... A$(0)="World!" A$(1)="" A$(2)="Amiga RULEZ!" A$(3)="Hello" A$(4)="" @{b}This is useful if you must remove some elements from a listview i.e@{ub} A$(0)="String1" A$(1)="String2" A$(2)="String3" A$(3)="String4" A$(1)="" : Gui Array up Array(A$(0)),1 @{b}Result:@{ub} A$(0)="String1" A$(1)="String3" A$(2)="String4" A$(3)="" @endnode @node "guiarraydown" @{b}Action:@{ub} Cycle down contents of a string array @{b}Usage:@{ub} Gui Array Down array address,start position @{b}See Also:@{ub} @{" Gui Array Up " link guiarrayup} Works in the same way as Gui Array Up, except works downwards instead of upwards. See @{" Gui Array Up " link guiarrayup} for more info. @endnode @node "guidisplayiff" @{b}Action:@{ub} Display an IFF image to a screen @{b}Usage:@{ub} Gui Display bank To screen @{b}See Also:@{ub} @{" Gui Save Iff " link guisaveiff} Display the IFF file loaded in the bank, into the specified screen. If the screen already exist,it will be closed and reopened. First you must bload a IFF file in a bank :) Why?? Using this method you can: - share the same buffer for several IFF files. You reserve the bank only one time, and you can load several files into it.... a good method for prevent memory fragmentation. - this is the only method for saving IFF(AGA) files togheter your program. @endnode @node "guibest" @{b}Action:@{ub} Get nearest Colour Equivalent @{b}Usage:@{ub} C=Gui Best(Red,Green,Blue) Normally you don't know the colour preferences of the user's WB of your program.... but if you need a specific colour you can use Gui Best() This function will attempt to find the color in the screen closest to the specified color. If there is no color within your tolerance, then a new one will be allocated, if available. If none is available, then the closest one found will be returned. So if you need the red... C=Gui Best(255,0,0) : Gui Ink C @{b}@{i}This command require the OS3.x!!!!! othewise returns -1!@{ub}@{ui} @endnode @node "guimousequeue" @{b}Action:@{ub} Expand mouse queue limit @{b}Usage:@{ub} Gui Mouse Queue window,queue limit @{b}See Also:@{ub} @{" Gui Mouse Report " link guimousereport} When you activate the @{" Gui Mouse Report" link guimousereport}, tons of inputs are sent to your program! Usually intuition queue a maximum of 5 mouse movements, and discard all the other if you don't read them in time! If your program can't handle these events fast, you can expand the queue limit using this command. @endnode @node "guishowtitle" @{b}Action:@{ub} Show/Hide the titlebar of a screen @{b}Usage:@{ub} Gui Show Title screen,mode Show/Hide the title bar of the specified screen. This can be usefull in games, so you can use more of the screen, and also remove the annonying bar. Gui Show Title 1,True : Rem display the title bar Gui Show Title 1,False : Rem hide the title bar @{b}If you hide the title bar, you can't drag the screen!@{ub} @endnode @node "guimonitor" @{b}Action:@{ub} Check if a screen display mode is available @{b}Usage:@{ub} A=Gui Monitor(modeID) This command checks the specified monitor ID for its existence. For example, if you wanted to check the DblPal for its availability, you would use: A=Gui Monitor($A9004) If the monitor is available, then the result returned will be 1, else it will be 0. @endnode @node "guihelp" @{b}Action:@{ub} Activate help system for your GUI @{b}Usage:@{ub} Gui Help window,display gadget,array address Activate the help system. When the user move the mouse pointer over a gadget of your GUI, a message defined by you will be automatically displayed into the specified display gadget. Example: gad$(0)="Hello!" gad$(1)="This is a listview" gad$(2)="Amiga Rulez!" gad$(3)="GUI Extension rulez :)" Gui Help 1,2,Array(GAD$(0))) Now when the user move the mouse pointer over a gadget of the window 1, a message will be displayed into gadget number 2. For the gadget number one will be displayed the string GAD$(1) for the gadget number 3 will be displayed GAD$(3) and so on... In order to disable this function, call it again with the array address set to 0. Obviously the 'display gadget' @{b}MUST! be a TEXT or STRING gadegt!!!@{ub} @endnode @node "guiguide" @{b}Action:@{ub} Display a AmigaGuide document @{b}Usage:@{ub} Gui Guide document A important feature of your programs must be the on-line help. This command allows you to display a AmigaGuide document. Your program is freezed until the amigaguide doc will be closed. @endnode @node "guiscreenbase" @{b}Action:@{ub} Get the base address of the specified GUI screen. @{b}Usage:@{ub} V=Gui Screen Base(screen) The command basically explains itself. It will return the start address in memory of the screen structure, so you can access directly to its informations. Don't modify it if you don't know what are you doing! @endnode @node "guiscreenmove" @{b}Action:@{ub} Attempt to move a screen by the pixel increments specified @{b}Usage:@{ub} Gui Screen Move deltaX,deltaY The command moves the screen by the specified pixels increments. If the DeltaX and DeltaY variables you specify would move the screen in a way that violates any system restriction, the screen will be moved as far as possible @endnode @node "guiaga" @{b}Action:@{ub} Convert an 8-bit palette value into AGA 32-bit. @{b}Usage:@{ub} A=Gui Aga(colour palette) This command is especially handy when it comes to converting a palette from a regular AMOS screen into an AGA screen, as it cuts down a lot of maths within your program. @endnode @node "guinotify" @{b}Action:@{ub} Start DOS notification on the specified file/dir @{b}Usage:@{ub} A=Gui Notify(file) @{b}See Also:@{ub} @{" Gui Rem Notify " link guiremnotify} This simple command gives you a advanced function.. the DOS Notification. You can monitor a specified file or directory, and when something modify it you'll be informed (Gui Wait return -14, and Gui Code the notify ID. The Notify ID is the value returned by the Gui Notify command). You can monitor as many files as you want. A tipical example are the virus checkers.. they monitor the s:startup-sequence file.. if you try to modify it, the virus checker is allerted! There are several use of this function, for example if you write a complex utility, you can split it in 2 separate programs.. the main program and the config program. The main program will monitor its prefs file.... when the Config program change it, the main program is notified, and so it load the new prefs file and adapt itself to the new config. For example the Workbench and its several prefs utilities works using this method. @endnode @node "guiappid" @{b}Action:@{ub} Returns the number of the selected AppIcon @{b}Usage:@{ub} I=Gui App Id @{b}See Also:@{ub} @{" Gui App Name$ " link guiappnames} When the user interacts with one of your appicons, it returns the number of the used one like @{" Gui Window " link guiwindow}returns the number of the used GUI. @endnode @node "guiappnames" @{b}Action:@{ub} Returns the name of the file(s) dragged on the AppIcon @{b}Usage:@{ub} N$=Gui App Name$ When the user drag a icon(s) on your appicon, you can obtain the full path name of all the dragged files using this command. You've to call it as many time as the number of files dragged. In order to know how many icons has been dragged, you've to use as usual @{" Gui Code " link guicode} Example: W=Gui Wait If W=-15 NUM=Gui Code : Rem NUM is the number of icons dragged ' Print the name of the files... For I=1 To NUM Print Gui App Name$ Next End If @endnode @node "guigadget" @{b}Action:@{ub} Returns the number of the interactive gadget @{b}Usage:@{ub} GAD=Gui Gadget @{b}See Also:@{ub} @{" Gui Mouse Report " link guimousereport} @{" AppWindows support " link appcmd} @{" Gui Wait " link guiwait} When Gui Wait returns one of the events listed below, you can obtain the number of the gadget involved... - Mouse Mouvements ( event -12) - Drag'n'drop icons ( event -16) - Mouse Click ( event -11) ...ok... some examples :) @{b}Drag'n'drop Icons:@{ub} If you drag a icon in a window Gui Wait returns -16 (AppWindow)... now you can check where the icon has been exactly dragged using the Gui Gadget function. This function checks if the icon has been drag'n'dropped on a gadget, and return its number. So you can offer a really interactive GUI.. example: if you drag the icon on a listview gadget, you can insert its path name in the listview... or if you drag it on the "delete" gadget you can delete it.. or... everything you want :) If the icon is not dragged over a gadget, Gui Gadget returns -1. @{b}Mouse Movements:@{ub} If you activate the @{" Gui Mouse Report " link guimousereport} function, everytime Gui Wait returns a mouse event, using the Gui Gadget command you can discover if the mouse pointer is over a gadget or not. It checks to see where the mouse pointer was located, and if has entered a gadget, the number of that gadget is returned otherwise it returns -1. @{b}Mouse Click:@{ub} Gui Wait return a mouse click event (-11) only if you don't click on a active gadget... anyway there are some gadgets that cannot be clicked like a TEXT gadget. Now, if necessary, you can know if the user has clicked one of this gadgets using the Gui Gadget function. Now you can offer @{b}REALLY@{ub} interactive GUI, using all together the above new features, improving the professional look of your programs. @endnode @node "guicatalogopen" @{b}Action:@{ub} Open a catalog file @{b}Usage:@{ub} C=Gui Catalog Open(catalog file,gui bank number) @{b}See Also:@{ub} @{" Gui Catalog Close " link guicatalogclose} @{" Gui Catalog$ " link guicatalogs} @{" Gui User Catalog " link guiusercatalog} Open the specified catalog file (if exist....) and automatically localize the specified GUI bank. The process is automatic.... if the system is localized in French, the command search the French catalog.. if it's in German, it search the German catalog as so on.... @{b}IMPORTANT: You must localize your bank BEFORE open anyone of its GUI!!! When all the GUI of this bank are closed, you can localize it. So the best solution is to localize your GUI bank at the !START! of the program and not later.@{ub} If the needed catalog is not available, the command return 0, and the built-in strings of the GUI bank will be used. For this reason you must create your GUI in english, and then release a catalog for your local language. The value returned by the command is the catalog-ID, wich is necessary later in order to close the catalog and free the allocated memory. See the @{" Gui Catalog Close " link guicatalogclose} command. @endnode @node "guicatalogclose" @{b}Action:@{ub} Close a previously opened catalog file @{b}Usage:@{ub} Gui Catalog Close catalog-ID @{b}See Also:@{ub} @{" Gui Catalog Open " link guicatalogopen} @{" Gui Catalog$ " link guicatalogs} @{" Gui User Catalog " link guiusercatalog} Close the specified catalog. The memory allocated for the catalogs isn't deallocated automatically by the extension, and so at the end of the program, you must use this command. @{b}NEVER@{ub} close a catalog when there are some GUI using its strings!!! Be sure to use a correct catalog ID (... the catalog ID is the value returned by @{" Gui Catalog Open " linkguicatalogopen}), because some strange effects will appear if you use a incorrect value :) @endnode @node "guicatalogs" @{b}Action:@{ub} Returns a string held in the loaded catalog file @{b}Usage:@{ub} A$=Gui Catalog$(number) Returns the specified string held in the current loaded catalog. A catalog is like a Amos resource bank... you've access to its built-in strings using this command. The number of each string is indicated in the .ct (catalog translator) file created by the GUI Converter. Example: ; ;AMOSPro Gui Compiler Shell ©1995-1999 DSOFT ; MSG21_WINDOW_TITLE In this case the title of the window is the string number 21. As you can see the string number is indicated just after the MSG suffix. Example: A$=Gui Catalog$(21) Return the string number 21 of the catalog. @endnode @node "guiappicon" @{b}Action:@{ub} Create a new appicon on your WB screen @{b}Usage:@{ub} Gui App Icon number,name,icon path @{b}See Also:@{ub} @{" Gui App Id " link guiappid} @{" Gui App Remove " link guiappremove} This command creates a new appicon on the WB screen. For example, if you want create a appicon using the AMOSPro Icon... Gui App Icon 1,"AMOS","AMOSPro_System:AMOSPro" Now on the WB will appear a AppIcon called AMOS with the AMOSPro icon. @{b}Please note that in the icon path you DON'T need to specify the .info extension.@{ub} This is the AppIcon number 1. There is not limit to the number of appicons that you can create! If you don't specify the icon path, the system default TOOL icon will be used. @endnode @node "guiline3d" @{b}Action:@{ub} Draw a line in the 3d space @{b}Usage:@{ub} Gui Line 3d x,y,z To x1,y1,z1 @{b}See Also:@{ub} @{" Gui Eye 3d " link guieye3d} @{" Gui Draw " link guidraw} This command allows you to draw a line in a 3d space using the x,y,z coords. (It's the equivalent of the Turbo Plus extension...) You can change the point of view using the @{" Gui Eye 3d " link guieye3d} command. @endnode @node "guieye3d" @{b}Action:@{ub} Set the eye position in the 3d space @{b}Usage:@{ub} Gui Eye 3d x,y @{b}See Also:@{ub} @{" Gui Line 3d " link guiline3d} This command simply change the x,y position of the eye in the 3d space. @endnode @node "xfaplay" @{b}Action:@{ub} Play the specified XFA animation file @{b}Usage:@{ub} Xfa Play file name,loop,auto pause,wait start,slow,mode id @{b}See Also:@{ub} @{" Xfa Rtg Play " link xfartgplay} @{" Xfa Check " link xfacheck} @{" Gui Cgx " link guicgx} Play the specified XFA animation file. You have a complete control of the animation execution using the several command parameters: The parameteres are BOOLEAN, you can set them to 0 (false) or 1 (true) @{b}Loop@{ub} Infinite loop mode. TRUE does an infinite loop play, FALSE a single shot play. @{b}AutoPause@{ub} Pause mode. TRUE pauses the animation automatically everytime there are no objects moving on the screen. FALSE executes the animation respecting the real animation timings. @{b}WaittStart@{ub} User start mode. TRUE start to play only when the user clicks and releases the left mouse button. FALSE starts to play immediately, without waiting. @{b}Slow@{ub} Slow Mode. TRUE The animation is played at half speed. FALSE the animation is played at full speed. @{b}Mode ID@{ub} Force a wb-like screen. TRUE the output is forced on a workbench-like screen mode. FALSE the output is forced on a PAL screen. During the play, mouse buttons can be used as follows: @{i}Left Mouse Button:@{ui} - Start the animation - Restart from an autopause - If AutoPause = FALSE then pause the execution until release @{i}Right Mouse Button:@{ui} - exit the animation if in autopause - If AutoPause = FALSE and you press both right and left exit the animation @endnode @node "xfartgplay" @{b}Action:@{ub} Play the specified XFA animation with RTG support @{b}Usage:@{ub} Xfa Rtg Play file name,loop,auto pause,wait start,slow,mode id @{b}See Also:@{ub} @{" Xfa Play " link xfaplay} @{" Xfa Check " link xfacheck} @{" Gui Cgx " link guicgx} It's the equivalent of the @{" Xfa Play " link xfaplay} command, but it works with gfx cards. @endnode @node "xfacheck" @{b}Action:@{ub} Checks if the file is a XFA animation @{b}Usage:@{ub} C=Xfa Check(file name) This function return TRUE if the specified file is a XFA anim, otherwise returns 0 @endnode @node "xfawidth" @{b}Action:@{ub} Returns the pixel width of a XFA anim @{b}Usage:@{ub} W=Xfa Width @{b}See Also:@{ub} @{" Xfa Height " link xfaheight} @{" Xfa Depth " link xfadepth} @{" Xfa Pack " link xfapack} @{" Xfa Frames " link xfaframes} @{" Xfa Mode Id " link xfamodeid} Returns the pixel width of the XFA animation file previously checked using the @{" Xfa Check " link xfacheck} command. @endnode @node "xfaheight" @{b}Action:@{ub} Returns the pixel height of a XFA anim @{b}Usage:@{ub} W=Xfa Height @{b}See Also:@{ub} @{" Xfa Width " link xfawidth} @{" Xfa Depth " link xfadepth} @{" Xfa Pack " link xfapack} @{" Xfa Frames " link xfaframes} @{" Xfa Mode Id " link xfamodeid} Returns the pixel height of the XFA animation file previously checked using the @{" Xfa Check " link xfacheck} command. @endnode @node "xfadepth" @{b}Action:@{ub} Returns the planes depth of a XFA anim @{b}Usage:@{ub} W=Xfa Depth @{b}See Also:@{ub} @{" Xfa Height " link xfaheight} @{" Xfa Width " link xfawidth} @{" Xfa Pack " link xfapack} @{" Xfa Frames " link xfaframes} @{" Xfa Mode Id " link xfamodeid} Returns the planes depth of the XFA animation file previously checked using the @{" Xfa Check " link xfacheck} command. @endnode @node "xfapack" @{b}Action:@{ub} Returns the compression mode a XFA anim @{b}Usage:@{ub} W=Xfa Pack @{b}See Also:@{ub} @{" Xfa Height " link xfaheight} @{" Xfa Depth " link xfadepth} @{" Xfa Width " link xfawidth} @{" Xfa Frames " link xfaframes} @{" Xfa Mode Id " link xfamodeid} Returns the compression mode of the XFA animation file previously checked using the @{" Xfa Check " link xfacheck} command. @endnode @node "xfaframes" @{b}Action:@{ub} Returns the frames number of a XFA anim @{b}Usage:@{ub} W=Xfa Frames @{b}See Also:@{ub} @{" Xfa Height " link xfaheight} @{" Xfa Depth " link xfadepth} @{" Xfa Pack " link xfapack} @{" Xfa Width " link xfawidth} @{" Xfa Mode Id " link xfamodeid} Returns the frames number of the XFA animation file previously checked using the @{" Xfa Check " link xfacheck} command. @endnode @node "xfamodeid" @{b}Action:@{ub} Returns the screen mode of a XFA anim @{b}Usage:@{ub} W=Xfa Mode Id @{b}See Also:@{ub} @{" Xfa Height " link xfaheight} @{" Xfa Depth " link xfadepth} @{" Xfa Pack " link xfapack} @{" Xfa Frames " link xfaframes} @{" Xfa Width " link xfawidth} Returns the screen mode of the XFA animation file previously checked using the @{" Xfa Check " link xfacheck} command. @endnode @node "guipubmode" @{b}Action:@{ub} Change the "public" status of a screen @{b}Usage:@{ub} Gui Pub Mode screen number,mode @{b}See Also:@{ub} @{" Gui Pub Check " link guipubcheck} All the screens opened using the @{" Gui Screen Open " link guiscreenopen} command are public, but reserved to @{b}private use @{ub}by default. You can change the status of the screen with this command. If you set the mode to 0, the screen became PRIVATE. The other applications cannot open their windows on your screen. If you set the mode value <> 0, the screen is PUBLIC, and so the other applications are allowed to open their windows on your screen. @endnode @node "guipubcheck" @{b}Action:@{ub} Checks if other applications are using your screen @{b}Usage:@{ub} C=Gui Pub Check(screen number) @{b}See Also:@{ub} @{" Gui Pub Mode " link guipubmode} Return the number of windows opened on the specified Screen. When you set the screen mode to @{b}PUBLIC@{ub} using the @{" Gui Pub Mode " link guipubmode} command other applications can open their windows on your screen. You can't close the screen if other windows are opened... so you can check this situation using this command, and advise the user that you can't close the screen because other applications are using it. @endnode @node "guisaveiff" @{b}Action:@{ub} Save the specified screen as IFF file image @{b}Usage:@{ub} Gui Save Iff screen number,file name @{b}See Also:@{ub} @{" Gui Load Iff " link guiloadiff} It allows you to save the specified screen as a IFF image. @{b}IMPORTANT: This command requires the xfa.libray!@{ub} @endnode @node "guisetmode" @{b}Action:@{ub} Enable or disable the iconify gadget @{b}Usage:@{ub} Gui Set Mode mode @{b}See Also:@{ub} @{" Gui Iconify " link guiiconify} Allows you to enable or disable the presence of the iconify (zoom) gagdet in the titlebar of your windows. If you disable the gadget (default) the user cannot iconify your windows. Example: Gui Set Mode 1 The iconify gadget is enabled Gui Set MOde 0 The iconify gadget is disabled When the user clicks the iconify gadget, the window IS NOT automatically iconified, but @{" Gui Wait " link guiwait} returns the value -6, and you to use the @{" Gui Iconify " link guiiconify} command to perform the job. Example: W=Gui Wait : WIN=Gui Window If W=-6 WIN1=Gui Iconify (WIN,"HELLO","") EndIf Now the window will be closed, and the appicon will appear. In order to uniconify the window, you've to wait that user clicks your AppIcon. Example: if the Window number 1 is iconified, the AppIcon number 1 is created... W=Gui Wait : APP=Gui App Id If W=-15 If APP=1 Gui Uniconify WIN1 EndIf EndIf @{b}Please note:@{ub} this command doesn't modify the windows already opened, but only those opened later! @endnode @node "guititle$" @{b}Action:@{ub} Returns the window's title @{b}Usage:@{ub} T$=Gui Title$(window number) @{b}See Also:@{ub} @{" Gui Titles " link guititles} Returns the title of the specified window. @endnode @node "guireservezone" @{b}Action:@{ub} Reserve memory for detection zones @{b}Usage:@{ub} Gui Reserve Zone window,number of zones @{b}See Also:@{ub} @{" Gui Free Zone " link guifreezone} @{" Gui Set Zone " link guisetzone} This command must be used to allocate enough memory for the exact number of zones required, before a @{" Gui Set Zone " link guisetzone} command is given. There is no limit to the number of zones, except the amount of free memory. The allocated zones works only for the specified window! @{b}Note:@{ub} When you close a window the zones ARE NOT erased! When you reopen the window the zones are already there so you don't need to redifine them! See @{" Gui Free Zone " link guifreezone}. @endnode @node "guifreezone" @{b}Action:@{ub} Erase all the reserved zones of a window @{b}Usage:@{ub} Gui Free Zone window number @{b}See Also:@{ub} @{" Gui Rerserve Zone " link guireservezone} @{" Gui Set Zone " link guisetzone} Erase all the zones of the specified window, previously allocated using the @{" Gui Reserve Zone " link guireservezone} command. @{b}Note:@{ub} When a window is closed the zones ARE NOT erased! When you reopen the window the zones are already there so you don't need to redifine them! @endnode @node "guisetzone" @{b}Action:@{ub} Set a zone for testing @{b}Usage:@{ub} Gui Set Zone window,zone number,x,y To x1,y1 @{b}See Also:@{ub} @{" Gui Mouse Zone " link guimousezone} @{" Gui Zone " link guizone} Like the Amos one, Gui Set Zone is used to define a rectangular area wich can be tested by the different Zone functions. @endnode @node "guimousezone" @{b}Action:@{ub} Return the zone number under specified mouse coordinates @{b}Usage:@{ub} Gui Mouse Zone window,x,y @{b}See Also:@{ub} @{" Gui Zone " link guizone} Returns the number of zone at the specified mouse coordinates. If no zone are present, the value -1 is returned. @endnode @node "guizone" @{b}Action:@{ub} Returns the number of the interactive zone @{b}Usage:@{ub} Z=Gui Zone @{b}See Also:@{ub} @{" Gui Mouse Zone " link guimousezone} It works exactly like the @{" Gui Gadget " link guigadget} function, except it detects the window zones instead of the gadgets! @endnode @node "tcpoverview" This is a overview of the GUI Extension TCP/IP methods, wich explains how it works and how to use it. The GUI Extension use a 100% bsdsocket.library based core, wich offers a better performance than before and a more readable system. All the network operations are performed @{b}asynchronously@{ub} without blocking your system. Like all the other events, Gui Wait handles the TCP/IP events too and returns the @{b}value -9@{ub} when you'll receive one of them. The command @{" Gui Code " link guicode} returns the associated code, wich describes the type of event that you've received. These are the possible values returned by Gui Code: 1 there is a connection to accept (See @{" Tcp Listen " link tcplisten}) 2 connection completed (See @{" Tcp Open " link tcpopen}) 6 some bytes have been downloaded (See @{" Tcp Download " link tcpdownload}) 8 there are some bytes available for reading 16 socket is writeable 32 error on socket 64 connection closed A very simple example: 'Wait some events.... '--------------------- W=Gui Wait : CD=Gui Code 'Checks for a TCP/IP event '------------------------- If W=-9 If CD=2 Print "Connection established!" Else If CD=64 Print "Connection closed!" EndIf EndIf This is a really stupid example.. it just tests if you receive a TCP/IP event (Gui Wait returns -9) and then if the event is a connect (Gui Code=2 ) or disconnect (Gui Code=64) event. In order to open a connection there is the @{" Tcp Open " link tcpopen} command. As said before all the operations are asynchronous, and so when you use the Tcp Open() function the connection is not immediately established, but you've to wait the proper message. But, this command returns an essential value, it's the socket number associated with this connection. Every connection with a server is indetified by a socket number... you can open up to 64 simultaneous connections ranging from 0 to 63. After which you can work with a specific connection using the socket number associated. The basic method for opening and handling a TCP/IP connection is the following: 'open a HTTP connection... ' 'SOCK is the socket number associated to this connection... '---------------------------------------------------------- SOCK=Tcp Open("www.amiga.org",80,0) W=Gui Wait : CD=Gui Code : SO=Tcp Socket You have to check if Gui Wait is equal to -9. If so Gui Code tells you what kind of event you've received, and @{" Tcp Socket " link tcpsocket} returns the socket number associated with the TCP/IP message returned by Gui Wait. Now you can check when the www.amiga.org site will be connected: If W=-9 If CD=2 If SO=SOCK Print "www.amiga.org connected!!" EndIF EndIF Endif Ok, that's all about the general design. The final note is the asynchronous design. You have to carefully consider this aspect, EVERYTHING is asynchronus so do not try to send or read data from a socket if you have not received the "connect" (Event -9 Code 2) message... do not try to send data to a socket if the previous transfer is not complete (event -9 Code 16) and do not try to read data if there is no data available in the socket (event -9 code 8). @endnode @node "tcpcmd" This section explain the GUI Extension TCP/IP support command. It's a good idea to read the... @{" GUI Extension TCP/IP overview " link tcpoverview} - A brief introduction... @{" Tcp Open " link tcpopen} - Open a connection. @{" Tcp User " link tcpuser} - Returns the user data associated to a socket. @{" Tcp Set " link tcpset} - Set the user data of a socket. @{" Tcp Close " link tcpclose} - Close a previously opened socket. @{" Tcp Send " link tcpsend} - Send a specified number of bytes to a socket. @{" Tcp Send$ " link tcpsends} - Send a string to a socket. @{" Tcp Read " link tcpread} - Read a specified number of bytes from a socket. @{" Tcp Line$ " link tcplines} - Read a line fo text from a socket. @{" Tcp Socket " link tcpsocket} - Return the socket number associated to an event. @{" Tcp Listen " link tcplisten} - Createa new socket in listen mode. @{" Tcp Accept " link tcpaccept} - Establish a connection request from a remote server. @{" Tcp Download " link tcpdownload} - Automaticllay download data from a specified socket. @{" Tcp Total " link tcptotal} - Returns the total number of bytes received @{" Tcp Recvd " link tcprecvd} - Returns the number of bytes just recevived. @{" Tcp Response " link tcpresponse} - Automatically returns the value of a response code. @{" Tcp Host$ " link tcphosts} - Returns the host name assigned to your computer. @endnode @node "tcpopen" @{b}Action:@{ub} Establishes a network connection with the specified host @{b}Usage:@{ub} S=Tcp Open(URL$,port,user data) This command establishes a connection with the specified URL$ at the specified port. By default the connection mode is set to asynchronous and non-blocking, and so this command returns immediately without waiting for the connection response from the remote server. When the remote server is connected, the Gui Wait command will inform you. (event -9, code 2). Example: ' Open a HTTP (port 80) connection with the www.amiga.org site '------------------------------------------------------------- S=Tcp Open("www.amiga.org",80,0) 'Wait some events.... '--------------------- W=Gui Wait : CD=Gui Code : TS=Tcp Socket 'Checks for a TCP/IP event '------------------------- If W=-9 If CD=2 : Print "Socket"+Str$(TS)+" connected!" : EndIf EndIf The value returned by Tcp Open is the number of the socket assigned to the connection. By default you can handle up to 64 connections (range 0-63). This command may fail, in this case it returns a negative value. -1 = Unable to alocate a socket -2 = Unable to get host information -3 = Unable to open connection As the name suggests, the "user data" is a free value for the user and can be set as you want. You can futher read/modify this value for every socket using the commands @{" Tcp User " link tcpuser} and @{" Tcp Set " link tcpset}. @endnode @node "tcpuser" @{b}Action:@{ub} Returns the user data associated to the socket @{b}Usage:@{ub} D=Tcp User(socket) @{b}See Also:@{ub} @{" Tcp Open " link tcpopen} @{" Tcp Set " link tcpset} Returns the user data associated to the socket @endnode @node "tcpset" @{b}Action:@{ub} Set the user data of a socket @{b}Usage:@{ub} Tcp Set socket,value @{b}See Also:@{ub} @{" Tcp Open " link tcpopne} @{" Tcp User " link tcpuser} Set the user data of a socket. You can read it using the @{" Tcp User " link tcpuser} command. @endnode @node "tcpclose" @{b}Action:@{ub} close the connection on the specified socket(s) @{b}Usage:@{ub} Tcp Close Tcp Close socket If you call it without parameters, ALL the sockets will be closed and deallocated. Otherwise you can specify the number of the socket to be closed. @endnode @node "tcpsend" @{b}Action:@{ub} Send the specified number of bytes to a socket @{b}Usage:@{ub} A=Tcp Send(socket number,address,length) @{b}See Also:@{ub} @{" Tcp Send$ " link tcpsends} Send the specified number of bytes (length), starting from the memory address, to the socket. Like all the other I/O operations, this commands is asynchronous, and Gui Wait will inform you when the transfer has been completed (event -9, code 16). @{b}NOTE: since the socket is in non-blocking mode you cannot send other data until the previous transfer has been complete.@{ub} The value returned is the number of bytes transferred. @endnode @node "tcpsends" @{b}Action:@{ub} Send a string to a socket @{b}Usage:@{ub} A=Tcp Send$(socket,string) @{b}See Also:@{ub} @{" Tcp Send " link tcpsend} This is the equivalent of @{"Tcp Send" link "TCP_Send" 0}, but it's a shortcut to send a string to a socket. @endnode @node "tcpread" @{b}Action:@{ub} Read the specified number of bytes from a socket @{b}Usage:@{ub} B=Tcp Read(socket,address,length} @{b}See Also:@{ub} @{" Tcp Line$ " linktcplines} Read the specified number of bytes (length) from the socket, and put them at the memory address. The value returned is the @{b}REAL@{ub} number of bytes received. @{b}It returns -1 if no data is available.@{ub} It is a good idea to use it only when Gui Wait informs you that there are some bytes to read (event -9 code 8)... a Tcp Read() busy loop is a really bad idea! @endnode @node "tcplines" @{b}Action:@{ub} Read a line of text (CR+LF terminated) from the socket. @{b}Usage:@{ub} T$=Tcp Line$(socket) @{b}See Also:@{ub} @{" Tcp Read " linktcpread} Read a line of text (CR+LF terminated) from the socket. The CR+LF chars are not included in the string. @endnode @node "tcpsocket" @{b}Action:@{ub} Returns the socket number associated to the last TCP/IP event @{b}Usage:@{ub} S=Tcp Socket When you receive a TCP/IP event Gui Wait returns -9, and then the Tcp Socket functions returns the socket number associated to the event. @endnode @node "tcplisten" @{b}Action:@{ub} Create a socket @{b}Usage:@{ub} SOCK=Tcp Listen(Port,user data) @{b}See Also:@{ub} @{" Tcp Accept " link tcpaccept} This function creates a new socket, and puts it in Listen mode using the specified port of your computer. Now you'll able to accept connections FROM a remote client. The value returned by the function is the socket number associated to the port of your system. When someone tries to open a connection with the specified port, Gui Wait will inform you ( event -9, code 1), and you will be able to accept (establish) the connection using the @{" Tcp Accept " link tcpaccept} command. Example: ' Puts in listen mode the port 80 ' When someone tries to open a HTTP ( WWW ) connection with your computer you will ' be informed '--------------------------------------- MYSOCK=Tcp Listen(80,0) W=Gui Wait : CD=Gui Code : SOCK=Tcp Socket If W=-9 If CD=1 If SOCK=MYSOCK CON=Tcp Accept(MYSOCK) ' Now the remote client is connected, and we can exchange data with it ' trough the CON socket returned by Tcp Accept() End If EndIf EndIf @endnode @node "tcpaccept" @{b}Action:@{ub} Accept a connection from a remote client @{b}Usage:@{ub} S=Tcp Accept(socket) @{b}See Also:@{ub} @{" Tcp Listen " link tcplisten} This function allows you to accept a connection request from a remote client. You must pass as "socket" param the socket number returned by a previous call to @{" Tcp Listen " link tcplisten} @{b}Tcp Accept creates and returns a new socket associated to the remote client, thus using this socket you can exchange data with it@{ub} Example: ' Puts in listen mode the port 80 ' When someone tries to open a HTTP ( WWW ) connection with your computer you will ' be informed '--------------------------------------- MYSOCK=Tcp Listen(80,0) W=Gui Wait : CD=Gui Code : SOCK=Tcp Socket If W=-9 If CD=1 If SOCK=MYSOCK CON=Tcp Accept(MYSOCK) ' Now the remote client is connected, and we can exchange data with it ' trough the CON socket returned by Tcp Accept End If EndIf EndIf @endnode @node "tcpdownload" @{b}Action:@{ub} Start the automatic data download @{b}Usage:@{ub} Tcp Download socket To file name,mode @{b}See Also:@{ub} @{" Tcp Total " link tcptotal} @{" Tcp Recvd " link tcprecvd} A really usefull command that allows you to automatically download data from the specified socket and save them into a file. Example: Tcp Download 1 To "Work:Download/AmiGate.lha" Now when some datas are available at the socket 1, they will be automatically downloaded and saved into the specified file. All the operations are buffered & asynchronous and automatically handled by the extension. You just need to wait the end of the file transfer! :)) Everytime the datas are automatically downloaded, Gui Wait will inform you (event -9 and code 6), so you can realtime monitor how many bytes has been downloaded using the @{" Tcp Total " link tcptotal} and @{" Tcp Recvd " link tcprecvd} funtions. The MODE parameter allows you to de/activate the resume transfer support. If the specified file already exists, you have 2 possibilities: mode = 0 The file will be overwritten with the new data mode = 1 The new data will be added to the end of the file. This is useful if you want resume a previously stopped file transfer. @endnode @node "tcprecvd" @{b}Action:@{ub} Returns the number of bytes just downloaded @{b}Usage:@{ub} BYTES=Tcp Recvd @{b}See Also:@{ub} @{" Tcp Download " link tcpdownload} @{" Tcp Total " link tcptotal} When Gui Wait informs you that some data has been automatically downloaded (event -9, code 6) thanks to a previous Tcp Download call, you can monitor how many bytes has been just received using this function. @endnode @node "tcptotal" @{b}Action:@{ub} Returns the total number of bytes downloaded @{b}Usage:@{ub} BYTES=Tcp Total @{b}See Also:@{ub} @{" Tcp Download " link tcpdownload} @{" Tcp Recvd " link tcprecvd} When Gui Wait informs you that some data has been automatically downloaded (event -9, code 6) thanks to a previous Tcp Download call, you can monitor the TOTAL number of bytes received from the beginnig of the transfer. @endnode @node "tcpresponse" @{b}Action:@{ub} Return the numeric value of a server response @{b}Usage:@{ub} R=Tcp Response @{b}See Also:@{ub} @{" Tcp Line$ " link tcplines} When you open a connection with a server port, usually you will receive some strings of text depending on the service used. Example: If you open a connection with a Mail server you'll receive a string like this: 200 HELLO mail.server.com The Tcp Response function returns automatically the value of the response code held in the string (in this case it returns the value 200) just received with @{" Tcp Line$ " link tcplines}. Obviously you must use this command @{b}AFTER@{ub} the Tcp Line$ command :) @endnode @node "tcphosts" @{b}Action:@{ub} Returns the host name assigned to your computer @{b}Usage:@{ub} HOST$=Tcp Host$ This function simply returns the host name assigned to your computer @endnode @node "guitimer" @{b}Action:@{ub} Send a timer request @{b}Usage:@{ub} Gui Timer seconds,micro seconds This command send a timer request and returns immediately the control to your program... when the specified time period is elapsed Gui Wait will inform you (event -13) @{b}Before sending a new timer request, you've to wait the end of the previous one otherwise it'll be ignored!@{ub} @endnode @node "guiclipreads" @{b}Action:@{ub} Read the content of the Clipboard @{b}Usage:@{ub} C$=Gui Clip Read$ @{b}See Also:@{ub} @{" Gui Clip Write$ " link guiclipwrites} This useful function returns the current content of the system clipboard. Obviously it works only if some characters are present... @endnode @node "guiclipwrites" @{b}Action:@{ub} Put a string in the system clipboard @{b}Usage:@{ub} Gui Clip Write$ string @{b}See Also:@{ub} @{" Gui Clip Read$ " link guiclipreads} Put the specified string in the system clipboard. @endnode @node "guibox" @{b}Action:@{ub} Draw a graphic box @{b}Usage:@{ub} Gui Box x,y To x1,y1 @{b}See Also:@{ub} @{" Gui Bar " link guibar} Draw a graphic box in the actual gfx output using the current Ink colour @endnode @node "tcpabort" @{b}Action:@{ub} Abort the Tcp Download action @{b}Usage:@{ub} T=Tcp Abort(socket) @{b}See Also:@{ub} @{" Tcp Download " link tcpdownload} If you need to stop the automatic data download started using @{" Tcp Download " link tcpdownload} you can use this command instead of @{" Tcp Close " link tcpclose}. The difference is that Tcp Abort doesn't close the network connection with the remote server but simply disable the automatic download. Now you need to "manually" handle all the data received. @{b}NOTE: Only on the specified socket the download is aborted@{ub} @endnode @node "tcperror" @{b}Action:@{ub} Returns the last network error code @{b}Usage:@{ub} E=Tcp Error If during a network connection something goes wrong, Gui Wait report the error condition (event=-9 and code=32). Using Tcp Error you can obtain the error code associated to the event. This is the list of the possible value: EPERM equ 1 ENOENT equ 2 ESRCH equ 3 EINTR equ 4 EIO equ 5 ENXIO equ 6 E2BIG equ 7 ENOEXEC equ 8 EBADF equ 9 ECHILD equ 10 EDEADLK equ 11 ENOMEM equ 12 EACCES equ 13 EFAULT equ 14 ENOTBLK equ 15 EBUSY equ 16 EEXIST equ 17 EXDEV equ 18 ENODEV equ 19 ENOTDIR equ 20 EISDIR equ 21 EINVAL equ 22 ENFILE equ 23 EMFILE equ 24 ENOTTY equ 25 ETXTBSY equ 26 EFBIG equ 27 ENOSPC equ 28 ESPIPE equ 29 EROFS equ 30 EMLINK equ 31 EPIPE equ 32 EDOM equ 33 ERANGE equ 34 EAGAIN equ 35 EWOULDBLOCK equ EAGAIN EINPROGRESS equ 36 EALREADY equ 37 ENOTSOCK equ 38 EDESTADDRREQ equ 39 EMSGSIZE equ 40 EPROTOTYPE equ 41 ENOPROTOOPT equ 42 EPROTONOSUPPORT equ 43 ESOCKTNOSUPPORT equ 44 EOPNOTSUPP equ 45 EPFNOSUPPORT equ 46 EAFNOSUPPORT equ 47 EADDRINUSE equ 48 EADDRNOTAVAIL equ 49 ENETDOWN equ 50 ENETUNREACH equ 51 ENETRESET equ 52 ECONNABORTED equ 53 ECONNRESET equ 54 ENOBUFS equ 55 EISCONN equ 56 ENOTCONN equ 57 ESHUTDOWN equ 58 ETOOMANYREFS equ 59 ETIMEDOUT equ 60 ECONNREFUSED equ 61 ELOOP equ 62 ENAMETOOLONG equ 63 EHOSTDOWN equ 64 EHOSTUNREACH equ 65 ENOTEMPTY equ 66 EPROCLIM equ 67 EUSERS equ 68 EDQUOT equ 69 ESTALE equ 70 EREMOTE equ 71 EBADRPC equ 72 ERPCMISMATCH equ 73 EPROGUNAVAIL equ 74 EPROGMISMATCH equ 75 EPROCUNAVAIL equ 76 ENOLCK equ 77 ENOSYS equ 78 EFTYPE equ 79 EAUTH equ 80 ENEEDAUTH equ 81 ELAST equ 81 Errrmm... you've to read the bsdsocket.library docs in order to understand them ;) @endnode @node "guiusercatalog" @{b}Action:@{ub} Returns the number of the first user string defined in the catalog @{b}Usage:@{ub} C=Gui User Catalog @{b}See Also:@{ub} @{" Gui Catalog$ " link guicatalogs} When the GUI Converter creates the catalog files for your application, it insert all the strings defined in the windows/screen held in the selected .gui file, and the USER strings defined in the program listing currently loaded in the editor. In order to know where the user strings are located in the catalog, you can use this command. @endnode @node "guiremap" @{b}Action:@{ub} Remap the colour map of the specified RTG bob bank @{b}Usage:@{ub} Gui Remap bank @{b}See Also:@{ub} @{" Create a image gadget " link guibnk} This command allows you to adapt the colour map of the specified RTG Bob bank with the colours of the current screen, so the images will looks correctly. @{b}Don't erase a RTG Bob bank if some GUI are using its images!!!!@{ub} @endnode @node "guisets" @{b}Action:@{ub} Update a string/text gadget with a new string @{b}Usage:@{ub} Gui Set$ window,gadget,string @{b}See Also:@{ub} @{" Gui Set " link guiset} It's a shortcut of the @{" Gui Set " link guiset} command. You can easly upgrade your string/text gadget with a new string in a more easy (... and fast) way. @endnode @node "phoenix" Like the phoenix rise again from its ashes, the AMOSPro Phoenix project wants revive AMOSPro. A new distribution available for free download will be uploaded in the next few months to the Amos Factory: http://members.xoom.com/AmosFactory/ The GUI Extension V2 and its accessories are a first segmnet of the whole distribution. Enjoy, Pietro Ghizzoni (ghizzo@agonet.it) @endnode