Amiga Tools 2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Tools 2 / Amiga Tools 2.iso / tools / arexx-scripts / arexx-pack / apiglibv33.lha / APIG_Lib / old_release_info < prev next >

Wrap

Text File | 1992-01-18 | 18.5 KB | 634 lines

--------------------------------------------------------------------- --------------------------------------------------------------------- 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.