home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
568a.lha
/
APIG_v1.1
/
release_info.pp
/
release_info
Wrap
Text File
|
1991-11-08
|
19KB
|
638 lines
This is version 1.1 of APIG
---------------------------------------------------------------------
---------------------------------------------------------------------
APIG version 1.1 Released September 21, 1991
---------------------------------------------------------------------
---------------------------------------------------------------------
Minor changes and minor bugs fixed.
* * * * * Documentation Changes * * * * *
Too many to list (spelling and such), hopefully the doc file reads
better now.
---------------
MAKEMENU doc changed, all the parms were not listed
MAKEITEM doc changed
MAKESUBITEM doc changed
---------------
SETSOFTSTYLE (added in version 0.5) was not listed in the doc.
---------------
TEXT
TEXTLENGTH
The length of the text is computed for you only if the 'count' parm is
less than zero, otherwise it uses the 'count' parm specified (including
zero).
---------------
WINDOWINFO
Code values have changed, see WINDOWINFO function docs.
---------------
The Exec list functions INSERTNODE, REMHEAD, and REMTAIL were documented
wrong, (extraneous or missing parms), they worked per RKM.
* * * * * Changed Functions * * * * *
---------------
ENQUEUE
Bug fix, this function was really doing a AddHead().
---------------
LOADIFF
LOADIMAGE
MAKEBITMAP
MAKEITEXT
MAKEBOOLGADGET
MAKEBORDER
MAKEITEM
MAKEMENU
MAKEPROPGADGET
MAKERASTPORT
MAKEREQUESTER
MAKESTRGADGET
MAKESUBITEM
These functions were changed to allow the use of an 'owner'.
---------------
MAKEPROPGADGET
Parms and their order have changed, see docs.
---------------
MAKEMENU
MAKEITEM
MAKESUBITEM
These functions were totally buggy, hopefully they are fixed now, the
parms have changed a bit too.
---------------
REQUEST/ENDREQUEST
Mulitple requesters can now be put up with Request().
Note: AutoRequest still only allows one requester to be put up.
Bug fix, ENDREQUEST would not end unless an Intuition Message was received.
eg.
/* code like the following should now work */
x = Request( ... ) /* put up a requester */
wait 5 sec /* dont do anything */
x = Endrequest( ... ) /* end the requester */
---------------
SETRGB4
Parm change, last parm no longer required.
eg. x = SETRGB4(screen/window,pen,r,g,b,'S'/'W')
The last parm indicated whether the first parm was a screen/window pointer
this is no longer neccessary.
eg. x = SETRGB4(screen/window,pen,r,g,b)
---------------
SETVALUE
Bug fix, this function did not work, possibly crashed, if
the 'value' was null/zero when using the 'P'/'S' option.
eg. x = setvalue(mypointer,0,4,'p',0,0)
^
+---- this being zero caused problems
---------------
SETWINDOWTITLES
SETWINDOWTITLE
Bug fix, title would disappear after setting it.
---------------
WINDOWINFO
Removed the redundant LeftEdge code, see WINDOWINFO function docs.
* * * * * New Functions * * * * *
---------------
FREEITEXT
FREEMENU
FREETHIS
Frees memory allocated for specified structure. (See docs)
---------------
GETPREFS Intuition Library
GETDEFPREFS Intuition Library
SETPREFS Intuition Library
GETSCREENDATA Intuition Library
---------------
MAKEPOINTER
MAKESTRUCT
These functions create an APIG pointer to a block of memory.
---------------
SET_APIG_GLOBALS
This function initializes many of the global constants used by/in the
various Intuition/Graphic data structures.
* * * * * General Notes & Things * * * * *
---------------
General
* Most structures can now 'own' another structure.
* Parms which are 'hex-strings' are now checked for odd addresses, if so
the parm is set to NULL, causing the function call to fail instead of
crashing with an illegal address error.
* Parms which are 'hex-strings' which point to low-mem (usually caused
by parms in the wrong order) are set to NULL, causing the function
call to fail. Low-mem means addresses in the first 1K.
* All functions are affected by the above changes since parms are
converted before being passed to the 'glue' routines of the function
call. Functions which expect non-null pointers will simply return (fail).
* APIG now tries to determine if the parameters you pass are legal.
eg. PRINTITEXT(rp,itptr,...) will not print the intuitext if 'itptr'
does not point to an Intuitext structure. The call will fail,
returning zero.
* Because of the large number of string names used by SET_APIG_GLOBALS,
and parameter validation, the APIG library has grown considerably.
---------------
ARexx quirks
* I suspect their is a bug in ARexx when passing 'hex-string' parms
to internal functions.
eg. If you have some generic function that processes a gadget lets say,
then code like the following may or may not work all the time.
/* */
mygad = makeboolgadget(w,...)
x = processgadget(mygad)
exit
processgadget: procedure
arg gadptr /* gadptr should be the 'hex-string' you passed */
/* well, sometimes it is and sometimes it is not */
return something
/* */
I have not yet confirmed that this is a real ARexx bug with W. Hawes.
But if it is a real bug you can circumvent it with something like
this:
/* */
mygad = makeboolgadget(w,...)
passgad = c2d(mygad) /* this is gonna become a pain */
x = processgadget(passgad) /* would be nice if you could just */
/* pass it and not worry about it */
exit
processgadget: procedure
arg passedarg
gadptr = d2c(passedarg,4) /* the '4' makes it 4byte 'hex-string' */
then use gadptr
return something
/* */
Or you can 'expose' it, making it available to the procedure.
eg. processgadget: procedure expose mygad
Or you can you use all global variables (ie. never use 'procedure')
---------------------------------------------------------------------
---------------------------------------------------------------------
APIG version 0.5 Released June 14, 1991
---------------------------------------------------------------------
---------------------------------------------------------------------
Font memory not fixed
* * * * * Documentation Changes * * * * *
-----------------
GETWINDOWRASTPORT
No change made to function. Documentaion did not
show full name of function.
GETWINRASTPORT should have been GETWINDOWRASTPORT
---------------
SAVEIFFCLIP No change made to function. Documentation changed -
Width of image must be expressed in bytes, NOT
pixels.
---------------
WINDOWINFO Codes 4 & 12 ARE redundant they both return the
LeftEdge of the window, unchanged.
Code 21 = GZZMouseX
Code 22 = GZZMouseY
The doc file had these reversed
* * * * * Changed Functions * * * * *
---------------
AUTOREQUEST Bug fix, contrary to the documentation this function
did return immediately, the result always being the
value one. The response to the requester was sent
to the window's port when the request ended.
Changed to return when request ends, and the response
to the requester is returned as a result of the
function call.
ie. x = autorequest() returns 1 if 'positive' gadget
selected, returns 0 if 'negative' gadget selected.
---------------
MAKEBORDER changed to allow linking of border structures, also
create 'auto' borders.
new form of function call is now
MAKEBORDER(window,arrayptr,arraycnt,left,top,fp,bp,dm,borderptr)
if the parm 'arrayptr' is 0, then a 'auto' border is built
using 'left' as the width of the border, and using 'top' as
the height of the border. The parm 'arraycnt' determines
how 'thick' the border will be.
the last parm 'borderptr' is a pointer to another border
structure to which the new allocated border will be linked.
borderptr - pointer to a border structure, code a 0 if not
linking borders.
All other parms are unchanged.
---------------
MAKEREQUESTER changed to allow specification of requester flags and
to allow use of predrawn bitmap imagery
new form of function call is now
MAKEREQUESTER(window,arrayptr,arraycnt,left,top,fp,bp,dm,border,
flags,relLeft,relTop,bm)
flags - numeric, specifies POINTREL or PREDRAWN
relLeft - numeric, specifies left offset from mouse pointer
relTop - numeric, specifies top offset from mouse pointer
(relLeft & relTop used with POINTREL)
bm - pointer to bitmap, if using PREDRAWN requester
imagery.
All other parms are unchanged.
---------------
MODIFYPROP Bug fix, function registers were loaded incorrectly,
causing this function to hang.
---------------
NEWMODIFYPROP Bug fix, function registers were loaded incorrectly,
causing this function to hang.
---------------
WINDOWINFO Bug fix, Code 11 = window Flag, was returning a short
when it should have been returning a long.
now returns full 32bit long flag value
* * * * * New Functions * * * * *
------------------------
<> GADSELECTED( gadgetptr )
This function returns TRUE/FALSE depending on the state of
the gadget.
Inputs:
gadgetptr - pointer to a gadget
Returns: - returns 1 if the gadget state is SELECTED,
otherwise returns 0.
----------------------------
<> GETGADPTR( window,gadgetid )
This function searches the window's gadget list for a gadget with
GadgetID equal to 'gadgetid' and returns a pointer to the gadget.
Inputs:
window - pointer to window opened with OPENWINDOW().
gadgetid - numeric, gadgetid
Returns: - pointer (ARexx hex-string) to gadget.
------------------------------
<> GETVALUE(ptr,offset,size,type)
This function allows you to retreive the value of any parameter in
any data structure.
ptr - pointer, (ARexx hex string) to any data structure, ie. window
screen, bitmap, etc.
offset - numeric, specifies the relative position, from the beginning
of the data structure, of data value you want to retrieve.
(see RKM or include '.i' files for offsets)
size - numeric, specifies the size of the data value you want to
retrieve. This value must be either 1, 2, or 4. Any other
value will cause the function to return a NULL ('0000 0000'x).
type - string, either a 'N', 'P' or 'S', this specifies the type
of data you are retrieving.
'N' specifies that you want the value returned as a numeric.
for sizes of 1 and 2 the returned value is always as a
numeric.
If the size is 4 then you can also use (in addition to 'N')
the following:
'P' specifies that you want the value returned as a pointer.
(ie. ARexx hex string)
'S' specifies that you want the value returned as a string.
VERY IMPORTANT NOTE !!!
When using 'P' or 'S', 'ptr' + 'offset' must result
in an address which contains a pointer to something.
eg. You can retrieve the window title string with:
title = getvalue(windowpointer,32,4,'S')
say "Your Window title is" title
(the title string pointer is offset 32 from the beginning
of the window structure)
eg. To have the window title pointer returned as a pointer:
titleptr = getvalue(win,32,4,'p')
say "Window Title Pointer is " d2x(c2d(titleptr))
eg. To return the contents of a string gadget:
specialstringinfo = getvalue(gadgetpointer,34,4,'P')
gadcontents = getvalue(specialstringinfo,0,4,'S')
say "Your gad string is" gadcontents
eg. Determining if a gadget is SELECTED:
if bittst(d2c(getvalue(gadpointer,12,2,'N')),7) = 1 then
say "Gadget SELECTED"
else
say "Gadget NOT SELECTED"
getvalue(gadpointer,12,2,'N') returns the gadget Flags
d2c() converts the result to form 'nnnn'x
bittst() test bit 7, the gad select bit.
returns - the value you specified in the form specified.
defaults to returning numeric if type not 'N', 'P', or 'S'
returns NULL ('0000 0000'x) if size not 1, 2, or 4.
(their is no way to distinguish between returning a valid
null pointer ('P' type) and error in size)
----------------------------------------
<> SETVALUE(ptr,offset,size,type,value,len)
This function allows you to set the value of any parameter in
any data structure. Please be very certain about the parameters you
use in this function.
ptr - pointer, (ARexx hex string) to any data structure, ie. window
screen, bitmap, etc.
offset - numeric, specifies the relative position, from the beginning
of the data structure, of the data value you want to set.
(see RKM or include '.i' files for offsets)
size - numeric, specifies the size of the data value you want to
set. This value must be either 1, 2, or 4. Any other
value will cause the function to return a NULL ('0000 0000'x).
type - string, either a 'N', 'P' or 'S', this specifies the form
of the data 'value' you are passing.
'N' specifies that the value is a numeric.
for sizes of 1 and 2 the value is always taken (assumed)
to be a numeric.
If the size is 4 then you can also use (in addition to 'N')
the following:
'P' specifies that the value you are passing is a pointer.
(ie. ARexx hex string)
'S' specifies that the value you are passing is a string.
VERY IMPORTANT NOTE !!!
When using 'P' or 'S', 'ptr' + 'offset' must result
in an address which contains a pointer to something.
len - numeric, used in conjuction with type 'S', this specifies
the maximum number of characters to be moved into the
area pointed to by the pointer at 'ptr' + 'offset'.
If you specify -1 the entire string will be copied into the
area pointed to by the pointer.
eg. You can set the window title string with:
x = setvalue(windowpointer,32,4,'S',"MY NEW TITLE",-1)
This statement DIRECTLY modifies the contents of the
buffer pointed to by the window title pointer.
The proper thing to do would be to modify where the window
title pointer points.
eg.
mynewtitle = ALLOCMEM(length("MY NEW TITLE")+1,'0001 0000'x)
call EXPORT(mynewtitle,"MY NEW TITLE")
x = setvalue(windowpointer,32,4,'P',mynewtitle,0)
returns - 1 if successful, otherwise 0
--------------------
<> WINTASKNAME(window)
This function returns the name of the task managing the windows
IDCMP port. This is also the name of the public message port
for the window.
Inputs:
window - pointer to a window opened with OPENWINDOW().
Returns: - window task name string, ie. 'apig.task.N'
---- (Intuition/Graphic Library Functions Added) ----
<> INTUITEXTLENGTH(itext)
<> CLEARPOINTER(window)
<> SETPOINTER(window,pointer,height,width,xoffset,yoffset)
<> SETSOFTSTYLE(rp,style,enable)
<> REMOVEGLIST(window,gadget,numgad)
---- (Exec Library Functions Added) ----
All parameters for these functions must be 'hex-strings'
<> ADDHEAD(list,node)
<> ADDTAIL(list,node)
<> ENQUEUE(list,node)
<> INSERTNODE(list,node,listnode)
(note name differs, since ARexx has function with the name INSERT )
<> NEWLIST(list)
<> REMHEAD(list)
<> REMOVE(node)
<> REMTAIL(list)
---- APIG Library List related functions ----
<> EMPTYLIST(list) - returns 1, if the list is empty, else returns 0
<> LISTEMPTY(list) - same as EMPTYLIST()
<> FIRSTNODE(list,node) - returns 1 if the node is first node in the list
else returns 0.
<> LASTNODE(list,node) - returns 1 if the node is the last node in the list
else returns 0.
---------------------------------------------------------------------
---------------------------------------------------------------------
APIG version 0.1 Released May 18, 1991
---------------------------------------------------------------------
---------------------------------------------------------------------
Known bugs:
For some reason Font memory is not returned to the system memory
pool.