Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!iuvax!uxc!tank!shamash!com50!pwcs!stag!daemon From: to_stdnet@stag.UUCP Newsgroups: comp.sys.atari.st Subject: GEMFAST version 1.2 Message-ID: <812@stag.UUCP> Date: 8 May 89 08:27:36 GMT Sender: daemon@stag.UUCP Lines: 343 From: stag!thelake!steve@bungia.mn.org (Steve Yelvington) Ian Lepore has released version 1.2 of his GEMFAST bindings, which work with various assemblers and C compilers including Sozobon C. I just grabbed them from FWBBS in Denver, 303-469-4954, where they can be found in the "Programmer's Ref" room. As soon as I discover a valid UUCP mail path to the moderator of comp.bin|src.atari.st, I'll mail them for posting. The files are: 33536 Mon May 8 02:01:38 1989 GEMFST12.ARC (the libraries) 78080 Mon May 8 02:06:44 1989 GEMFSC12.ARC (MadMac sources) 29056 Mon May 8 02:18:20 1989 GEMFXM12.ARC (example programs) Following is Ian's .DOC file for the current release. O/ cut here ======O\================================ GEMFAST v1.20. 04/08/89 by Ian Lepore. Version 1.20 of GEMFAST is a full release. You will find new source code, new libraries (VDIFAST.A and AESFAST.A), docs, & an example program. See the README file for a full packing list and installation instructions. The primary reason for this release is to fix a bug that was zapping Laser C users (upon return the CCR flags need to match the return value), and to implement the correct bindings for shel_get/put. If you are using the Atari 'aln' linker, be sure to create new .NDX files by running the DOINDEX utility against these new bindings. ;************************************************************************* ; AESFAST v1.20 notes. ;************************************************************************* ;------------------------------------------------------------------------- ; Summary of AES bindings changes in v1.20: ;------------------------------------------------------------------------- - The 'quick' mouse functions graqon_mouse(), graqof_mouse(), and graq_mstate() were fixed to work under all TOS versions. - The shel_get() and shel_put() functions were implemented as described in the TOS 1.4 release notes (see docs below). - Another emulation version of fsel_exinput() was added. This version emulates the prompt feature only, beyond that it is identical to the TOS 1.0 fsel. This one is only half the size of the full emulation. - A lot of the source modules were split into smaller modules containing less functions. This makes the library bigger, but might make your programs a bit smaller, as there will be less tendancy to include bindings that your program will never use. - A TST.W D0 instruction was added to the common return-to-user routine so that the flags in the CCR will match the return value in register d0. This is needed because the Laser C compiler assumes it will be so, and will not generate TST.x instructions inline under some circumstances, like if a call is coded as "if (!rsrc_load(filename))". - A TST.W D0 (or equivelent) was also added to all the utility routines which are not defined as type 'void'. ;************************************************************************* ; New functions added to AESFAST v1.20: ;************************************************************************* ;------------------------------------------------------------------------- ; shel_get / shel_put ;------------------------------------------------------------------------- status = shel_get(char *bufadr, int buflen) status = shel_put(char *bufadr, int buflen) These functions read and write the desktop's internal buffer which holds a copy of the DESKTOP.INF file. The buffer holds an exact image of the file, in plain ASCII text. If 'status' is returned as zero, an error occurred. The Atari docs say that the buffer should never exceed 1024 bytes, but I've been told that it *can* in fact exceed this length. ;------------------------------------------------------------------------- ; fsel_smallexinput ;------------------------------------------------------------------------- This function has calling parameters identical to fsel_exinput() (see below), but it's behavior (return values, etc) is identical to that of fsel_input() (the original). This function will call the real 'exinput' routine if on TOS 1.4, but if on an earlier version it emulates only the prompting of 'exinput', it does not save the path or DTA, or handle correctly, or any of the other nice TOS 1.4 features. On the other hand, it's only half as big as the full emulator for fsel_exinput(), so it's handy for accessories and other small-memory applications. (It will add about 450 bytes to your program, as opposed to 800). I'd like to recommend that you do not code calls to fsel_smallexinput() directly in your program. Instead, just code fsel_exinput(), and at the top of your C source, code: #define fsel_exinput fsel_smallexinput and let the C compiler handle the rest for you. This ought to keep your code compatible many years into the future... ;************************************************************************* ; VDIFAST v1.20 notes. ;************************************************************************* Summary of VDI bindings changes in v1.20: - A bug in v_contourfill() was fixed (call no longer causes 3 bombs). ; end of docs for v1.2 ;************************************************************************* ; AESFAST v1.10 notes. ;************************************************************************* ;------------------------------------------------------------------------- ; Summary of AES bindings changes in v1.10: ;------------------------------------------------------------------------- - A global variable was added to AES@NOTE such that the version number is part of the variable name. Allows a quick version-check via a link map. - New TOS 1.4 function 'wind_new()' added. - New TOS 1.4 function 'fsel_exinput()' added (see docs below). - 'Undocumented' functions 'form_button()' and 'form_keybd()' added. - Some cleanup in AESCOMN.S. - All of the variables in the 'global' array now have unique accessable names which can be accessed from C. The AESFAST.A file is much bigger than v1.0. This is primarily due to the addition the new fsel_exinput function (see below), and the vast amount of code required to simulate its actions on pre-TOS 1.4 systems. If you don't use this function, the increase in size won't affect you. ;************************************************************************* ; New functions added to AESFAST v1.10: ;************************************************************************* Two function calls in the AES Form Manager have existed in all versions of TOS, but were not included in the original DRI docs. These functions are now included in AESFAST. The following is a brief overview of these functions. For more info, see Tim Oren's PRO-GEM series of articles (#13). (I have shamelessly plagerized Tim's article and source code to provide these descriptions). ;------------------------------------------------------------------------- ; form_keybd ;------------------------------------------------------------------------- keyret = form_keybd(tree, object, nxtobject, thechar, &nxtobject, &thechar); (All values are 16-bit words, except 'tree', which is OBJECT *). The form_keybd routine acts as a filter on character input. When it recognizes a control character, it processes it and zeroes the keyboard word. Other chararacters can be passed on to objc_edit to be inserted in the editable object. If the routine returns a zero, a default object is selected (). (Hints: If 'nxtobject' is not equal to 'object' after this call, form_keybd() has detected a TAB or ARROW key to move to the next edit field, so call objc_edit(..., EDEND) for the current field, as long as nxtobject is non-zero. If 'thechar' comes back non-zero, pass it to objc_edit(..., EDCHAR). If this doesn't make sense, get the Tim Oren articles and make your own interpretations.) ;------------------------------------------------------------------------- ; form_button ;------------------------------------------------------------------------- btnret = form_button(tree, object, clicks, &nxtobject); (All values are 16-bit words, except 'tree', which is OBJECT *). I can't tell you as much about this one. This routine handles an already-occurred mouse button event. It handles changing the selected object into reverse video. It (presumably) handles radio buttons. 'object' is the index of the object the mouse is over, so I presume have have to call objc_find() first to get this. 'nxtobject' is the new selected object index. If the routine returns a zero, a default or exit object was selected. ;************************************************************************* ; About TOS 1.4... ;************************************************************************* MAJOR CAVEAT/DISCLAIMER... Atari has released TOS 1.4 for beta testing only. Any information in the release notes is subject to change before final ROM release. The same is true of all information about TOS 1.4 in this doc. You MAY NOT hold Atari responsible for preserving anything I have written here. If Atari changes any of these functions before final release, I will change AESFAST and its docs to match. I am providing access to the new functions in AESFAST so that developers can work with TOS 1.4 before its final release. The TOS 1.4 release notes contain documentation for the following: form_error form_alert shel_write shel_get shel_put fsel_exinput wind_new Of these, the form_error/alert seem to be just a clarification of the docs without any functional changes. The 'shel' functions baffle me, I think I'm missing a couple pages in my original DRI docs, and will try to nail these things down by v1.20. The wind_new and fsel_exinput functions have been added to AESFAST, and are described below... ;------------------------------------------------------------------------- ; About the AES 'global' array, and version numbers... ;------------------------------------------------------------------------- The TOS 1.4 release notes say that the appl_init() call will return a value of $0130 in global[0] under TOS 1.4. I found that my ROM TOS 1.0 returns a value of $0120, whereas running the beta RAM TOS 1.4 returned $0104. Anyway, since checking version numbers will be an issue from now on, I gave a name to global[0] (and to all the other vars). The full set of globally-visable names is: aespb - The AES parmameter block, pointers to the other parameter and control structures. aescontrol - The AES 'control' structure, which holds the counts of items in the other structures, and the AES opcode. global - The whole array/structure. gl_apversion - The AES version number. gl_apcount - The max # of GEM aps that can be active at once. gl_apid - The application ID. gl_apprivate - A longword of anything the ap wants it to be. gl_aptree - Pointer to resource tree stuff. gl_aprsvd - Array of 4 longwords reserved for future use. You can use these in your C code by defining: extern int global[]; /* this is one way. */ extern int gl_apversion, gl_apid, /* etc */ ; /* this is another. */ extern struct { /* yet a third way, but */ int gl_apversion, gl_apcount, gl_apid; /* don't mix this with */ long gl_apprivate; /* either of the above, */ RSH *gl_aptree; /* unless you change */ } global; /* all the names. */ If you use the structure, remember to access vars via global.gl_apid, etc. The data in these global variables is not valid until after the appl_init() call has been made. ;------------------------------------------------------------------------- ; wind_new ;------------------------------------------------------------------------- void wind_new(); The 'wind_new' function is for doing a major cleanup after a GEM application. It closes & deletes all windows, flushes all the windows' buffers (of redraw msgs, I presume), clears the wind_update flag, and restores ownership of the mouse to the system (whatever that means). The documentation is not clear on whether this function should be used by an application that wants to shut down everything quickly, or whether it is intended for a shell's use in cleaning up after an application exits. I tend to suspect the latter, and I think this function was developed because shell writers all begged Atari to provide something that could clean up after an application the way the desktop does (and I begged Atari to make desktop clear the wind_update flags as part of recovery). ;------------------------------------------------------------------------- ; fsel_exinput ;------------------------------------------------------------------------- status = fsel_exinput(in_path, in_sel, &exitbtn, prompt_text); (status and exitbtn are 16-bit ints, others are char *). This routine is functionally equivelent to fsel_input, except that it also allows you to specify a prompt string of up to 30 characters to be displayed along with the file selector. While the function is new with TOS 1.4, the AESFAST bindings support it in all versions via a routine which checks the AES version number and simulates the actions of fsel_exinput by using fsel_input and objc_draw. If running under TOS 1.4, the system will display your prompt text in place of the words 'FILE SELECTOR' inside the fsel box. If running under pre-TOS 1.4, the simulation routines place the prompt text in a box which appears between the menu bar and the fsel box. The software simulation stuff is provided so that EVERYONE WILL BEGIN PUTTING PROMPTS IN THEIR FILE SELECTORS IMMEDIATELY! (Excuse me for shouting, but I *hate* unprompted file selectors). Anyway, I wanted to make it easy for developers to handle the transition between TOS 1.0 and the day when we can assume that *everyone* has 1.4. Other TOS 1.4 changes to the fsel routines that are supported by the simulation software on pre-TOS 1.4 systems... - The file selector now allows you to edit the pathname and hit RETURN without exiting the dialog. If you edit the filename and hit , you will exit as if you clicked on OK. - If the initial pathname has a leading '\', it will be appended to the end of the current default drive and path, and the entire resulting string will be returned if the user exits via OK or . - The current default drive and path are preserved, and the contents of the current DTA are preserved. Only the default path on the default drive is saved with the simulation software. If the user changes devices during file selection, the default path on all devices may be changed except for the device that was the default when fsel_exinput was called. The executable code for the fsel_exinput binding is big -- about 1500 bytes. Also, it uses about 350 bytes of stack space during the call. Still, having a prompted file selector that works correctly on all machines will lend a touch of class to your application (IMHO). Note that all of the above fsel ehancements which are supported by the simulation on pre-TOS 1.4 systems are supported ONLY if you call fsel_exinput; if you call fsel_input on a pre-1.4 system the default path et. al. will behave as they always have. (Hint: USE exinput). ;************************************************************************* ; VDIFAST v1.10 notes. ;************************************************************************* Summary of VDI bindings changes in v1.10: - A global variable was added to VDI@NOTE such that the version number is part of the variable name. Allows a quick version-check via a link map. - Misnamed function vq_extend was renamed to vq_extnd in VDIINQR1.S - The stack parms for vq_extnd were wrong, now fixed. The VDIFAST.A file is slightly smaller. This is due to a change in the way I build the library. Instead of adding everything to the library, then running the Sozobon GLOBS program to remove non-global symbols from the files, I ran GLOBS on each file individually before adding it to the library. I didn't expect any difference, and I don't know why there is one, but since it made the library smaller I'm not complaining. ; end of docs. /* * UUCP: {uunet!rosevax,amdahl!bungia,chinet,killer}!orbit!thelake!steve * ARPA: crash!orbit!thelake!steve@nosc.mil * #member The ST Developers Network */