to_stdnet@stag.UUCP (05/08/89)
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 <CR>
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 (<CR>).
(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 <CR>,
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 <CR>.
- 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 <STdNET> The ST Developers Network
*/