Frozen Fish 1: Amiga

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

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d559 / apig.lha / APIG / apiglib_v11.lzh / apig.doc < prev next >

Wrap

Text File | 1991-09-28 | 135KB | 3,657 lines

ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) (apig.library) This program is in the public domain, it may be freely distributed and copied without restriction. Ronnie E. Kelly ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) This library provides programmers with a means to access most of the Intuition/Graphic library functions from ARexx. The library functions allow you to specify most of the parameters used in the underlying data structures of the Intuition/Graphic routines. Using the parameters you specify the APIG library builds an instance of the data structure and passes a pointer to it back to you. Hopefully you will be able to create more custom looking interface for your ARexx applications. The APIG library, for the most part, simply converts the ARexx string parameters to the appropriate form the Intuition/Graphic functions expects and then makes a call directly to the corresponding Intuition/ Graphic library function. Few assumptions have been made about how you will use these functions, therefore this library does very little validating of the inputs you supply. The library supports the following structures: Menus, MenuItems, SubItems Requesters Boolean, String, and Proportional gadgets Borders IntuiText Arrays of short (16-bit) integers Layers Images ( via iff.library ) APIG uses Christian Weber's iff.library for IFF support, you will need the iff.library (version 18) if you plan to use any of the IFF functions. If you are not familiar with the Intuition/Graphic library functions or the data structures used by these functions, then I would strongly recommend obtaining a copy of the latest revision of the RKM manual (Autodocs & Includes) and/or the Intuition Reference manual. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Using The Library: Like all libraries the APIG library must first be placed in your 'LIBS:' directory, the iff.library should be placed in 'LIBS:' as well. Before calling any of the APIG library functions you must add the APIG library to ARexx's external library function list. To do this include the following statement at the beginning of your ARexx program: call addlib("apig.library",0,-30,0) You do not need to do this for the iff.library, APIG will open/close the iff.library when needed. APIG does not have a 'color requester' or a 'filerequester' function and I have no plans of adding them. However you can still use WGL's rexxarplib.library or whatever, if you want. In the case of rexxarplib.library, their are a couple of function name conflicts (OpenScreen and OpenWindow). You can resolve these as prescribed in the ARexx manual by using the ARexx RemLib() function. ie. If you are gonna start calling functions in rexxarplib.library you may want to do: call remlib('apig.library') removing apig.library from the external function list, then be sure to add it back on when you go to call an APIG library function. (you really only need to do the remlib() if the function you are calling conflicts with some other library function name) You are now ready to use to the APIG library functions. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Most of the functions have the same name as their Amiga Intuition/Graphics library counterpart and are used the same way. The number of parameters, their order, and their type are the same as described in the RKM manual. eg. The Intuition function DrawImage() expects a pointer to a RastPort, a pointer to an Image structure, and X & Y coordinates. The APIG library function DrawImage() expects the same parameters, the same type, and in the same order as the Intuition function. Unless otherwise noted in the function descriptions below this will always be the rule. All function parameters must be specified and must be of the type expected by the function. If you specify more parameters than the function expects the superflous parameters will be ignored. If you specify fewer parameters than the function expects, then the function will return with a ARexx error code of 17, your ARexx program will terminate as well. BIG WARNING !!! Parameters specified in the wrong order or wrong type will more than likely bring on the GURU. If your ARexx program terminates with windows/screens still open it may still be possible to close the windows/screens and recover the memory used by them, see the OPENWINDOW() function description on how this is done. The APIG functions always return a result to you, even if the Intuition, Graphic, or Layer function returns no result. If the Amiga library function returns a result, then the result returned is that result. If the Amiga library function does not return a result, then the value returned to you is either 1 or 0. A return value of 1 indicates that the APIG library made the call to the Amiga library function. A return value of 0 indicates that the Amiga library function was not called (possibly due to error). Their are several functions in the library for building instances of the various Amiga graphic structures. Use these functions to create the pointers (ARexx 'hex' strings) needed by the other functions. Functions which return pointers, either return a valid (valued) hex string or they return NULL (ie. '0000 0000'x). You should verify that you do indeed have a valid (non-null) pointer before using it. The library checks for null pointers and will not perform a function if it expects the pointer argument(s) to be non-null. Valid pointers are the actual address of the data structure created. All fields within the structure are available for your use (via GETVALUE/SETVALUE), field offsets are as defined in the RKM's for 1.3. Their is only ONE exception, the field ExtData in the Window structure has been appropriated by the APIG library. Do not modify in any way the ExtData field in the Window structure. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Many of the graphic data structures contain 'flags' which describe certain characteristics of the structure. The APIG library uses the same flag values as defined in the RKM manuals, without exception. (see SET_APIG_GLOBALS function description below) Where multiple flag values are required (needed) you can simply sum all the values together. The flag values you specify are not 'touched' and get passed directly to the Amiga library function/data structure. Their are very few defaults so be sure to specify all that you need. The APIG library should return all memory allocated to the system memory pool. Version 1.1 of APIG allocates memory for the structures differently than in version 0.5. IN VERSION 0.5 OF APIG, GADGETS, INTUITEXT, REQUESTERS, MENUS AND SUCH WERE ALLOCATED TO A SPECIFIC WINDOW AND EXISTED UNTIL THE WINDOW WAS CLOSED. THEIR WERE NO FUNCTIONS IN VERSION 0.5 FOR FREEING THE MEMORY USED BY THESE STRUCTURES, SINCE ALL MEMORY WAS 'OWNED' BY THE WINDOW. IN VERSION 1.1 OF APIG, GADGETS, INTUITEXT, REQUESTERS, MENUS AND SUCH CAN NOW BE INDEPENDENTLY FREED PRIOR TO CLOSING THE WINDOW. MENUS NO LONGER NEED BE RE-CREATED EACH TIME A WINDOW IS CLOSED AND THEN RE-OPENED. IN FACT MOST OF THE DATA STRUCTURES CAN BE ALLOCATED INDEPENDENTLY AND, CAN BE 'OWNERS' OF OTHER STRUCTURES. STRUCTURES WHICH ARE ALLOCATED TO (OWNED BY) A WINDOW ARE FREED WHEN THE WINDOW CLOSES, SIMILARLY STRUCTURES WHICH ARE 'OWNED' BY OTHER STRUCTURES ARE FREED WHEN THEIR 'OWNER' IS FREED. THE USE OF AN 'OWNER' SIMPLY ALLOWS YOU TO BIND THE EXISTENCE OF THE STRUCTURE TO THE LIFE OF ITS OWNER. WHEN THE OWNER IS FREED, EVERYTHING IT OWNS IS ALSO FREED. THUS IF YOU WANTED, YOU COULD MAKE A WINDOW THE OWNER OF EVERYTHING YOU ALLOCATE, WHEN THE WINDOW IS CLOSED ALL MEMORY ALLOCATED, GADGETS, INTUITEXT, REQUESTERS, BORDERS, ETC. WILL BE FREED AS WELL. THIS ALSO ALLOWS YOU TO HAVE MULTIPLE WINDOWS OWNING WHAT THEY NEED AND SHARING INDEPENDENT STRUCTURES, WHICH REMAIN VALID AFTER THE WINDOW IS CLOSED. You should find that this relieves you of having to keep track of all the structures you have allocated then having to explicity free each one. By logical (planned) allocation of structures to an 'owner' you can reduce the amount of memory being used by structures that are no longer needed. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) eg. creating a requester req = makerequester(0, ... ) /* 0 = independent */ gad1 = makeboolgadget( req,...,req ) /* req owns this gadget */ /* and link it to req */ gad2 = makestrgadget( req,...,req ) /* req owns this gadget */ /* and link it to req */ gad3 = makepropgadget( req,...,req ) /* req owns this gadget */ /* and link it to req */ gad4 = makeboolgadget( 0,...,gad3 ) /* 0 = independent */ txt1 = makeitext( req,...,req ) /* req owns this itext */ /* and link it to req */ txt2 = makeitext( req,...,txt1 ) /* req owns this itext */ /* and link it to txt1 */ /* which is the same as */ /* linking it to req */ txt3 = makeitext( req,...,txt2 ) /* req owns this itext */ /* and link it to txt2 */ /* which is the same as */ /* linking it to req */ (linking here means the gadget/itext is added to the gadget/itext list in the structure, see function descriptions below) The requester created is independent of any other structure, and must be explictly freed. It need not be re-created each time and can be put in any window (via REQUEST()) you happen to open. When done with the window, the window can close, but the requester will still be useable. Now when the requester is freed the gadgets, gad1, gad2, and gad3 will also be freed, the intuitext, txt1, txt2, txt3 will be freed as well. Gadget gad4 will not be freed, it is independent, even though it has been linked to gadget gad3. This is unsafe,so dont do it. With one single 'free' call all the structures needed by the requester are freed with it. The gadgets and intuitext owned by the requester cannot be independently freed. APIG will not be able to find the gadgets and intuitext owned by the requester on the lists APIG maintains of allocated structures. APIG could find them but it would have to search each and every memory BLOCK that it allocated. In the above situation APIG would only see two STRUCTURE allocations (req and gad4) but it wont search the memory BLOCKS owned by them. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Now their are some restrictions on what can be an owner and what can be owned, they are simply 1). A WINDOW is ALWAYS independent and can own ANYTHING, except a screen. (a window can never be 'owned') 2). A SCREEN is ALWAYS independent and can own ANYTHING, except a window. (a screen can never be 'owned') 3). GADGETS, INTUITEXT, REQUESTERS, and BORDERS can all be owners and all can be owned. However they cannot own a menu/menuitem/subitem. A border can own a requester, though it makes more sense for a requester to own a border. 4). MENU structures can own ANYTHING that can be owned, including, gadgets, intuitext, requesters, borders, etc. Menus can only be owned by another menu, a window, or a screen. 5). MENUITEMS and SUBITEMS cannot be owners, and can only be owned by a menu, a window, or screen. 6). BITMAPS, RASTPORTS, and IMAGES, are the same as (3) above. An image can own Intuitext, Gadget, etc. but cannot own a menu/menuitem/subitem. Basically ownership of a menu/menuitems are restricted to windows, screens, and other independent menus. Only 'independent' structures can be owners, eg. a gadget owned by a window cannot be an 'owner'. 'Independent' structures must be explictly freed. When allocating a structure to an 'owner', if APIG is unable to find the 'owner' it will allocate the structure as an independent structure and place it in the appropriate list. eg. lets say you load an IFF pic as follows pic = loadiff("mypic",itsowner) if 'itsowner' is not found by APIG, then pic will be allocated as an independent structure and placed in the bitmap list. You will then need to explictly free it with FREEBITMAP(pic). eg. itext = makeitext(itsowner,...) /* 'itsowner' not found */ The IntuiText structure would be placed in the intuitext list, and you would then need to use FREEITEXT(itext). ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) APIG Library Function Descriptions: The following functions are provided to allow building and managing of the basic data structures used by the Intuition, Graphic, and Layer functions. <> CONVERTRAWKEY(keycode,qualifier,keymap) This function is used to convert a 'raw' keycode value into its equivalent ascii character string. Inputs: keycode - numeric, the raw keycode value to be converted qualifier - numeric, the value of any key qualifiers such as LSHIFT,LAMIGA, etc. keymap - pointer to a keymap structure This value is currently ignored, but must be present. In a future release keymap support maybe provided, for now code this as zero. Returns - the ascii character string for the specified keycode and key qualifier. ------------------------------------------------ <> BMDEPTH(bm) <> BMHEIGHT(bm) <> BMWIDTH(bm) These functions return the depth, height, and width values for the bitmap. These values are useful when doing blits. Inputs: bm - must be a pointer to a bitmap structure Returns: - depth, height, or width ------------------------------------------------ <> IMGDEPTH(image) <> IMGHEIGHT(image) <> IMGWIDTH(image) These functions return the depth, height, and width values for the image. These values are useful when doing blits. Inputs: image - must be a pointer to an image structure Returns: - depth, height, or width ------------------------------------------------ <> FREEAREA(window) This function releases the memory allocated for the areafill/flood functions. Inputs: window - pointer to a window opened with OPENWINDOW(). A prior call to MAKEAREA() should have been made to the same window. Returns: - always returns 1 ------------------------------------------------ <> FREEBITMAP(pointertobitmap) <> FREEIMAGE(pointertoimage) <> FREERASTPORT(pointertorastport) <> FREEBIRASIM(pointer) <> FREEMENU(menustrippointer) <> FREEITEXT(intuitextpointer) <> FREETHIS(pointer to any independent structure) These functions return the memory allocated for the bitmap, image rasterport, menustrip, intuitext, or whatever to the system. The APIG library maintains separate list for bitmaps, images, rastports, bitplane, and menustrip memory allocations. Using FREEBITMAP, FREEIMAGE, FREERASTPORT, FREEMENU, FREEITEXT will cause only the appropriate list to be searched, hopefully to save search time. FREEBIRASIM, will check only the bitmap, rastport, and image lists, until it finds the allocated structure or fails to find it. FREETHIS will check ALL list. Note independent requesters, gadgets, and borders are freed with the FREETHIS() function (after awhile this does get a bit redundant). Inputs: pointer - must be a pointer to an independent bitmap, image, rastport or whatever. Pointer must be obtained from the corresponding make function (MAKEBITMAP(), etc.) Returns: - returns positive non-zero value if successful, the value will vary and is the number of 'things' that were 'owned' by the object freed. eg. FREEBITMAP() typically may return a value of 12, the 12 represents the bitplane allocations and any other allocations (eg. CMAP chunks) that were owned by the bitmap. - Returns zero if nothing was freed, ie. did not find the structure. ------------------------------------------------ <> 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. ------------------------------------------------ <> GETARRAY(arrayptr,arrayindx) This function allows you to retrieve the 16-bit value stored in the array pointed to by 'arrayptr'. Inputs: arrayptr - pointer to array (block of memory) as returned by ARexx ALLOCMEM(). arrayindx - numeric, index position you wish to get Returns: - returns value stored in array position 'arrayindx'. Also See: SETX(), SETY(), GETX(), GETY(), SETARRAY() ------------------------------------------------ <> 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. ------------------------------------------------ <> GETIDCMP(window) This function allows you to retrieve the current value of IDCMPFlags for the window. Inputs: window - pointer to window as returned by OPENWINDOW(). Returns: - windows IDCMPFlags value ------------------------------------------------ <> GETLAYERINFO(layer) This function allows you to retrieve the pointer to the layers layer_info structure. Inputs: layer - pointer to layer Returns: - pointer to layer info for the layer ------------------------------------------------ <> GETLAYERRASTPORT(layer) This function allows you to retrieve the pointer to the layers RastPort. You will need the rastport pointer for the layer when using the drawing functions. Inputs: layer - pointer to layer as returned by CREATEUPFRONTLAYER() or CREATEBEHINDLAYER() functions. Returns: - pointer to rastport for the layer ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> GETRPBITMAP(rp) This function allows you to retrieve the pointer to the BitMap of the RastPort. Inputs: rp - pointer to RastPort structure. Returns: - pointer to bitmap for the rastport ------------------------------------------------ <> GETSCREENBITMAP(screen) This function allows you to retrieve the pointer to the BitMap of the screen. Inputs: screen - pointer to screen, returned by OPENSCREEN(). Returns: - pointer to bitmap for the rastport ------------------------------------------------ <> GETSCREENRASTPORT(screen) This function allows you to retrieve the pointer to the RastPort of the screen. Inputs: screen - pointer to screen, returned by OPENSCREEN(). Returns: - pointer to rastport for the screen ------------------------------------------------ <> GETSTRGAD( window,gadgetid ) This function retrieves the value of the string gadget. Inputs: window - pointer to window opened with OPENWINDOW(). gadgetid - numeric, gadgetid of the string gadget Returns: - string contents of the string gadget ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> 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/type) ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> GETWINDOWLAYER(window) This function allows you to retrieve the windows layer pointer. Inputs: window - pointer to window as returned by OPENWINDOW(). Returns: - pointer to rastport for the layer ------------------------------------------------ <> GETWINDOWRASTPORT(window) This function allows you to retrieve the windows rastport pointer Inputs: window - pointer to window as returned by OPENWINDOW(). Returns: - pointer to rastport for the window ------------------------------------------------ <> GETX(arrayptr,xindex) This function does the same as GETARRAY(), the difference is that it computes the index offset value for the X-pair for you. eg. if arrayptr is an array of 20 XY-pairs (40 16-bit values) then x = getx(arrayptr,8), retrieves the value for the 8th X value. the equivalent using GETARRAY() would be x = getarray(arrayptr,32) Inputs: arrayptr - pointer to array as returned by ARexx ALLOCMEM(). xindex - numeric, index position you wish to set Returns: - returns the value stored in array position xindex. Also See: SETX(), SETY(), GETY(), GETARRAY(), SETARRAY() ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> GETY(arrayptr,yindex) This function does the same as GETARRAY(), the difference is that it computes the index offset value for the Y-pair for you. Inputs: arrayptr - pointer to array as returned by ARexx ALLOCMEM(). yindex - numeric, index position you wish to retreive. Returns: - returns the value stored in array position yindex. Also See: SETX(), SETY(), GETY(), GETARRAY(), SETARRAY() ------------------------------------------------ <> HORIZPOT(gadgetptr) This function returns the value of the horizontal component of the pot gadget. Inputs: gadgetptr - pointer to a proportional gadget, return from MAKEPROPGADGET(). Returns: - returns the numeric value of HorizPot ------------------------------------------------ <> IFFDEPTH(pointer) <> IFFHEIGHT(pointer) <> IFFWIDTH(pointer) These functions return the various dimensions of the IFF image pointed to by the bitmap pointer. Note that BMDEPTH()/BMHEIGHT/BMWIDTH() will return the same values. The difference is where the information is obtained, the BM... functions retrieve the values from the bitmap itself. The IFF... functions retrieve the values from the 'BMHD' chunk that was loaded with the IFF file. The two sets of values should always be the same since the 'BHMD' chunk values are used to allocate the bitmap. (Unless, of course, the IFF was blitted into a different bitmap) Inputs: pointer - pointer to a IFF bitmap (returned by LOADIFF()). This must be the original bitmap pointer (or copy of it) returned by the LOADIFF() function. You cannot use a pointer returned by MAKEBITMAP() into which you have blitted the IFF. If the pointer was returned from MAKEBITMAP() then use BMDEPTH() etc. Returns: - returns the width, height, depth of the IFF image. ------------------------------------------------ <> IFFVIEWMODE(pointer) This function returns the viewmodes (HAM/HIRES/LACE etc.) word for the IFF. Inputs: pointer - pointer to a IFF bitmap (returned by LOADIFF()). This must be the original bitmap pointer (or copy of it) returned by the LOADIFF() function. You cannot use a pointer returned by MAKEBITMAP() into which you have blitted the IFF. Returns: - returns the viewmodes word ------------------------------------------------ <> IFFCOLORS(pointer) This function returns the number of colors used in the IFF Inputs: pointer - pointer to a IFF bitmap (returned by LOADIFF()). This must be the original bitmap pointer (or copy of it) returned by the LOADIFF() function. You cannot use a pointer returned by MAKEBITMAP() into which you have blitted the IFF. Returns: - returns number of colors ------------------------------------------------ <> IFFCOLORTAB(pointer) This function returns a pointer to the color table used by the IFF. Inputs: pointer - pointer to a IFF bitmap (returned by LOADIFF()). This must be the original bitmap pointer (or copy of it) returned by the LOADIFF() function. You cannot use a pointer returned by MAKEBITMAP() into which you have blitted the IFF. Returns: - returns a pointer (ARexx string) to a color table (array of short integers) which specify the color values used in the IFF. returns 0 if not a pointer to IFF or if the IFF does not contain a CMAP chunk. ------------------------------------------------ <> LOADIFF(filename,owner) This function uses Christian Weber's iff.library to load an IFF file. Inputs: filename - the name of the IFF file. owner - pointer to object which will own this IFF. if 0 then this will be an independent IFF bitmap which must be explictly freed. Owner can also be ANY of the owners described in the MAKEBOOLGADGET description. Returns: - This function returns a pointer to the bitmap structure containing the IFF imagery. Note that no display of the IFF imagery is done. To display the imagery use one of the blit functions contained in this library, to blit it into the bitmap/rastport of your choice. When you are done using the bitmap imagery you should free the memory allocated to it, by calling FREEBITMAP() or FREEBIRASIM(). - returns null ('0000 0000'x) if load fails ------------------------------------------------ <> LOADIMAGE(filename,imageptr,left,top,owner) This function uses Christian Weber's iff.library to load an IFF file. The difference between this function and LOADIFF() is that this function returns a pointer to an Image structure. The bitmap planes of the IFF file are re-arranged to conform with the layout required for ImageData. Inputs: filename - the name of the IFF file. imageptr - pointer to image structure if this is non-null the loaded image will be linked to this image. left - numeric, the value to set the LeftEdge of the image structure top - numeric, the value to set the TopEdge of the image structure owner - pointer to object which will own this Image. if 0 then this will be an independent image which must be explictly freed. Owner can also be ANY of the owners described in the MAKEBOOLGADGET description. Returns: - This function returns a pointer to an Image structure containing the IFF imagery. Note that no display of IFF imagery is done. To display the imagery you use the DRAWIMAGE() function. The returned value can also be used in defining imagery for gadgets. When you are done using the Image you should free the memory allocated to it, by calling FREEIMAGE() or FREEBIRASIM(). - returns null ('0000 0000'x) if load fails ------------------------------------------------ <> MAKEAREA(window,xsize,ysize,maxvectors) Initializes the windows rastport for use with the Area-Fill-Flood functions. This function consumes a large chuck of your CHIP memory you should get your area fill operations done as quickly as possible then free up the memory with the function FREEAREA(). This function must be called before you do any areafill/floodfills. The memory remains allocated until FREEAREA() is called. Inputs: window - pointer to window opened with OPENWINDOW(). xsize - numeric, specifies the width of the largest area you plan to fill. ysize - numeric, specifies the height of the larges area you plan to fill. (Recommended that xsize,ysize be the same size as the rasport you are drawing into.) maxvectors - numeric, specifies the number of vertices (points) you expect to draw. This parameter is NOT ignored and must be non-zero. Returns: - always returns 1, this simply indicates that the library made the call to the Intuition/Graphics library function. ------------------------------------------------ <> MAKEBITMAP(width,height,depth,owner) This function allocates and builds a bitmap structure and returns a pointer to it. The purpose for this is to allow you to build off-screen bitmaps then blit them on screen when ready. Inputs: width - width of the bitmap height - height of the bitmap depth - depth, number of bit planes, of the bitmap owner - pointer to object which will own this bitmap. code as zero if independent bitmap, in which case it must be explicitly freed, with FREEBITMAP or FREEBIRASIM. - pointer Any other independent owner see description of owners under MAKEBOOLGAGET. Their are no restrictions on who/what can own a bitmap. Returns: - pointer to bitmap structure - returns null ('0000 0000'x) if call fails ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKEBOOLGADGET( owner,left,top,width,hgt,flags,activation, itext,bpen,render,select,gadid,linkto ) Allocates and builds a boolean gadget structure. Inputs: owner - pointer to object which will own the memory allocated for this gadgets structure. For gadgets the owner can be any one of the following: 0). 0 - independent structure If the 'owner' is coded as zero then the gadget created can be used as an owner for other structures. 1). pointer to window The gadget will be owned by this window, the gadget memory will be freed when the window is closed. NOTE THE GADGET IS NOT PLACED IN THE WINDOWS GADGET LIST. 2). pointer to screen The gadget will be owned by this screen, the gadget memory will be freed when the screen is closed. 3). pointer to requester The gadget will be owned by this requester, the gadget memory will be freed when the requester is freed. NOTE THE GADGET IS NOT PLACED IN THE REQUESTERS GADGET LIST. 4). pointer to intuitext The gadget will be owned by this intuitext, the gadget memory will be freed when the intuitext is freed. 5). pointer to gadget the created gadget will be owned by the specified gadget, the created gadget memory will be freed when the specified owner gadget is freed. NOTE THE GADGETS ARE NOT LINKED. 6). pointer to border The gadget will be owned by this border, the gadget memory will be freed when the border is freed. 7). pointer to menustrip The gadget will be owned by this menustrip, the gadget memory will be freed when the menu is freed. left - numeric, left edge placement of gadget top - numeric, top edge placement of gadget width - numeric, width of gadget in pixels hgt - numeric, height of gadget in pixels flags - numeric, gadget flags GADGHCOMP/GADGIMAGE/GRELRIGHT/GRELWIDTH/SELECTED/etc. activation - numeric, IDCMP flags for the gadget TOGGLESELECT/GADGIMMEDIATE/RELVERIFY/etc. itext - pointer to intuitext to be displayed with the gadget. Note that this can be a linked list of IntuiText. Keep in mind that the position of the IntuiText is relative to the gadgets left & top coordinates. bpen - numeric, border pen color this function will build a border (only if 'render' parm is zero) to 'box' the gadget, this is the color you want the border lines to be. render - pointer to Border/Gadget imagery. If this is zero then APIG will build a default border structure to 'box' the gadget. If this is non-zero then APIG assumes this is a pointer to an appropriate structure for the GadgetRender parm and uses it as-is. You may still link a Border/Image structure in afterwards. If this is -1 then APIG will leave the GadgetRender parm of the Gadget structure NULL, you can then link a Border/Image structure in afterwards. select - pointer to Border/Gadget imagery to display when selected. APIG uses what ever you specify so do not put a -1 here, put a 0 if you want it to be NULL. gadid - numeric, any value you wish to identify this gadget. linkto - pointer to GADGET to which this gadget should be linked this allows you to string several gadgets together into a linked list. The new allocated gadget will be placed at the end of the list. You may also specify a pointer to a WINDOW or a pointer to a REQUESTER as the 'linkto'. If 'linkto' is a window pointer then APIG will AddGadget() the new gadget to the windows gadget list. You however must do gadget refreshing. If 'linkto' is a requester pointer then APIG will place the new gadget at the end of the requesters gadget list. Be sure to specify appropriate flags for requester gadgets. Returns: - pointer to allocated gadget as an ARexx hex string. - returns null ('0000 0000'x) if call fails ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKEBORDER( owner,arrayptr,arraycnt,left,top,fp,bp,dm,linkto) Allocates and builds a border structure. Inputs: owner - pointer to object which will own this border. if 0 then this will be an independent border which must be explictly freed. Owner can also be ANY of the owners described in the MAKEBOOLGADGET description. arrayptr - pointer to array of short integers, taken as XY pairs. The array can be allocated with ALLOCMEM(), and the XY pair values set with SETX() and SETY() functions. If you code a zero here then MAKEBORDER() will generate a border array for you. See parms below. arraycnt - numeric, number of XY pairs in the array, must be less than 128. If 'arrayptr' was specified as zero then this parm will be the 'thickness' of the border. If this is the case then 'arraycnt' must be <= 25. A value of 0 defaults to 1. left - numeric, borders left edge If 'arrayptr' was specified as zero then this parm will be the width of the border. top - numeric, borders top edge If 'arrayptr' was specified as zero then this parm will be the heigth of the border. fp - numeric, borders front pen color bp - numeric, borders back pen color dm - numeric, drawmode to use linkto - pointer to a BORDER structure to which the new border will be linked. Code this as zero if not linking the border. You may also specify a pointer to a GADGET or a pointer to a REQUESTER as the 'linkto'. If 'linkto' is a GADGET pointer then APIG will place the new border at the end of the gadgets GadgetRender list. This implies that gadget has a GadgetRender list consisting only of borders or the gadgets GadgetRender pointer is NULL. Note that the SelectRender pointer is not modified. If 'linkto' is a REQUESTER pointer then APIG will place the new border at the end of the requesters ReqBorder border list. Returns: - pointer to allocated Border structure. - returns null ('0000 0000'x) if call fails ------------------------------------------------ <> MAKEITEM( menustrip,text,menu,left,top,width,height,flags, ME,COM,fp,bp,dm,itemfill,selectfill ) Builds and attaches a menu-item to a menu All arguments are the same as MAKESUBITEM. See MAKESUBITEM below, also see menu hints. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> MAKEITEXT( owner,text,xpos,ypos,fpen,bpen,dmode,fontattr,linkto ) Allocate and build an IntuiText structure. The memory allocated for the IntuiText will be 'owned' by the task managing the windows IDCMP port. Inputs: owner - pointer to object which will own this IntuiText. if 0 then this will be an independent IntuiText which must be explictly freed. Owner can also be ANY of the owners described in the MAKEBOOLGADGET description. text - string, text you want to build IntuiText for xpos - numeric, x displacement in pixels ypos - numeric, y displacement in pixels fpen - numeric, foreground pen color bpen - numeric, background pen color dmode - numeric, draw mode (ie. JAM1,JAM2, etc.) fontattr - pointer, to text font attributes (returned by MAKETATTR) code as zero to get default linkto - pointer, to IntuiText structure to which this IntuiText should be linked. You may also specify a pointer to a GADGET, pointer to a REQUESTER, pointer to a MENUITEM, or a pointer to a MENUSUBITEM as the 'linkto'. If 'linkto' is a GADGET pointer then APIG will place the new IntuiText at the end of the gadgets GadgetText list. If 'linkto' is a REQUESTER pointer then APIG will place the new IntuiText at the end of the requesters ReqText list. If 'linkto' is a MENUITEM pointer then APIG will place the new IntuiText at the end of the MENUITEMs ItemFill list. This implies that the ItemFill of the MENUITEM consist of IntuiText and is not an IMAGE. MENUSUBITEMS are treated the same way. Note the SelectFill is not modified. Returns: - pointer to the allocated IntuiText - returns null ('0000 0000'x) if call fails ------------------------------------------------ <> MAKEMENU( menuowner,menutext,leftedge,width,flags,menupointer ) This function creates/builds a menu header. The parm 'menupointer' determines whether a new menustrip is being constructed or whether a new header is being added to an existing menustrip. The initial call to MAKEMENU should set the parm 'menupointer' to 0, this indicates the start of a new menustrip. The initial call builds a MENU structure and returns a pointer to it. All subsequent calls MUST then use the return value from the initial call to add new menu headers to the menustrip. Also remember that items/subitems will need an owner, it is this initial value that you will use. (if not using a window/screen) eg. /* the last parm is 0, indicating start a new menustrip */ /* the first parm is 0, indicating independent menu */ menu0 = MAKEMENU( 0,"Project",left,width,flags,0 ) menustrip = menu0 eg. /* the last parm is 0, indicating start a new menustrip */ /* the first parm is window, indicating menu is owned */ /* by the window, and will be freed when window closes */ menu0 = MAKEMENU( window,"Project",left,width,flags,0 ) menustrip = menu0 to add additional menu headers to the menustrip the return value menu0 must now must be used as the 'menupointer' parm. eg. /* the last parm is non-null, indicating link the */ /* new menu to it, owner simply says who owns the */ /* new allocated menu structure memory */ menu1 = MAKEMENU( menu0,"This",left,width,flags,menu0 ) menu2 = MAKEMENU( menu0,"That",left,width,flags,menu0 ) or menu3 = MAKEMENU( menustrip,"Whatever",left,width,flags,menu0 ) (since menustrip was assigned the value of menu0) menu headers which are not owners returned from the initial call cannot be used to build the menustrip. eg. menu4 = MAKEMENU( menu1,"Lastone",left,width,flags,menu0 ) the above will NOT work, menu1, was not returned from the initial call, result is a null pointer for the value of menu4. This differs from APIG version 0.5, and allows you to re-use menu strips after the window has been closed. You must now explicitly release memory that has been allocated to independent menustrips, using the FREEMENU() function. Inputs: menuowner - pointer to object which will own the MENU. For menus valid owners can only be: 0). 0 - code as zero when creating new independent menustrip. You will need to free it with FREEMENU. 1). pointer to window 2). pointer to screen 3). pointer to independent MENU Menus cannot be owned by any other structure. ie. gadgets, intuitext, etc. cannot be owners of a menu. menutext - string, text to be displayed in menu header leftedge - numeric, location of menu select box. (measured in pixels) If leftedge >= 0 then the left edge is measured from the right edge of the MENU which PRECEDES it. If leftedge < 0 then the left edge is measured from the leftedge of the screen. +--------+ +--------+ +----------+ | MENU 1 | | MENU 2 | ... | MENU N-1 | +--------+ +--------+ +----------+ | | | | | |<--- meas. left | |from here if edge |<--- meas. |'leftedge' >= 0 screen --> |from here |for MENU N | if 'leftedge' < 0 | | for MENU N | | | width - numeric specifies width of MENU select box. (measured in pixels) If zero, then the IntuiTextLength of the 'menutext' is used. If 'menutext' is a NULL string then the IntuiTextLength of 1 character is used. flags - numeric, this is the Flags variable of the Menu structure, only meaningful values are MENUENABLED or 0 (menu will be disabled). menupointer - pointer to a menustrip in which this menu should be linked. If this is zero then it indicates you are building a new menu strip. Returns: - pointer to menu. - null ('0000 0000'x) if call fails Note that the menu strip is not attached to the window, the menu is simply constructed. You will need to call SetMenuStrip to actually attach the menu strip to the window. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKEPROPGADGET( owner,left,top,width,hgt,flags,activation,itext, ,piflags,hbody,vbody,gadid,linkto,knobimage) Allocate and build a proportional gadget structure. (Note parms are different than version 0.5, hbody/vbody/knobimage) Inputs: owner - pointer to object which will own this Gadget. See description of MAKEBOOLGAGET. left - numeric, left edge placement of gadget top - numeric, top edge placement of gadget width - numeric, width of gadget in pixels hgt - numeric, height of gadget in pixels flags - numeric, gadget flags activation - numeric, IDCMP flags for the gadget itext - pointer to intuitext to be displayed with the gadget piflags - numeric, specifies the prop gadgets characteristics AUTOKNOB/FREEHORIZ/FREEVERT/KNOBHIT/PROPBORDERLESS hbody - numeric, specifies the horizontal step (percentage) amount vbody - numeric, specifies the vertical step (percentage) amount gadid - numeric, any value you wish to identify this gadget linkto - pointer, gadget to which this gadget should be linked. See description of MAKEBOOLGADGET all the same applies. knobimage - pointer, this points to an image. This image will be used as the prop gadgets knob. This allows you to use custom slider knobs in your proportional gadgets instead of just a rectangluar knob. Returns: - pointer to allocated gadget as a rexx hex string. - returns null ('0000 0000'x) if call fails Note: HORIZPOT & VERTPOT will be initialized to zero. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKERASTPORT(width,height,depth,owner) This function allocates and builds a rastport structure and returns a pointer to it. The purpose for this is to allow you to build off-screen rastports then blit them on screen when ready. Inputs: width - numeric, width of the rastports bitmap height - numeric, height of the rastports bitmap depth - numeric, number of bit planes in rastports bitmap owner - pointer to object which will own this rastport. code as zero if independent rastport, in which case it must be explicitly freed, with FREERASTPORT or FREEBIRASIM. - pointer Any other independent owner see description of owners under MAKEBOOLGAGET. Their are no restrictions on who/what can own a rastport. Returns: - pointer to rastport structure - returns null ('0000 0000'x) if call fails ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKEREQUESTER(window,left,top,width,height,gadget,text,border, backfill,flags,relleft,reltop,bm) This function builds an instance of a requester structure to be used with the REQUEST() function. Inputs: owner - pointer to object which will own this Gadget. See description of MAKEBOOLGAGET. left - numeric, left edge offset of the requester top - numeric, top edge offset of the requester width - numeric, width of the requester height - numeric, height of the requester gadget - pointer to first gadget of list of gadgets within the requester. YOU should also make sure that at least one of the gadgets in the list has its ENDGADGET flag set. APIG will set the gadgettype flag of all gadgets in this list to REQGADGET. text - pointer to intuitext for the requester border - pointer to a border structure backfill - numeric, pen color to fill requester, before graphics are rendered flags - numeric, requester flags specify POINTREL,PREDRAWN otherwise code as zero relleft - numeric, left offset for requesters displayed relative to the mouse pointer (ie. POINTREL set) reltop - numeric, top offset for requesters displayed relative to the mouse pointer (ie. POINTREL set) bm - pointer to a bitmap containing imagery for the requester, the PREDRAWN flag must be set. Code as zero if not using your own imagery. Returns: - pointer to a requester structure - null ('0000 0000'x) if call fails ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKESTRGADGET( window,left,top,width,hgt,flags,activation, itext,bpen,render,select,gadid,linkto,strlen) Allocate and build a string gadget structure. Inputs: owner - pointer to object which will own this Gadget. See description of MAKEBOOLGAGET. left - numeric, left edge placement of gadget top - numeric, top edge placement of gadget width - numeric, width of gadget in pixels hgt - numeric, height of gadget in pixels flags - numeric, gadget flags activation - numeric, IDCMP flags for the gadget itext - pointer to intuitext to be displayed with the gadget bpen - border pen color this function will build a border structure (only if 'render' parm is NULL/ZERO) to 'box' the gadget, this is the color you want the border lines to be. render - pointer to Border/Gadget imagery. If this is zero then APIG will build a default border structure to 'box' the gadget. If this is -1 then APIG will leave the GadgetRender parm of the Gadget structure NULL, you can then link a Border/Image structure in afterwards. select - pointer to Border/Gadget imagery to display when selected. APIG uses whatever you specify so do not put a -1 here, code a 0 if you want it to be NULL. gadid - numeric, any value you wish to identify this gadget linkto - pointer, gadget to which this gadget should be linked. See description of MAKEBOOLGADGET all the same applies. strlen - numeric, max number of characters allowed in gadget Returns: - pointer to allocated gadget as a rexx hex string. - returns null ('0000 0000'x) if call fails ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> MAKESUBITEM( menustrip,text,item,left,top,width,height,flags, ME,COM,fp,bp,dm,itemfill,selectfill ) This function builds and attaches a sub-item to a menu-item. This description also applies to MAKEITEM(). Inputs: menustrip - pointer to a menustrip, returned from initial call of MAKEMENU(). text - text string, item text to be used this parm along with fp,bp, and dm parameters will be used to build an IntuiText structure. The 'itemfill' variable of the MenuItem structure will be initialized to point to the IntuiText constructed. item - pointer to a menu-item, as returned by MAKEITEM() function. This is the menu-item you want to attach the sub-item to For MAKEITEM() this is menu pointer returned by MAKEMENU() left - numeric, left offset relative to menu select box The value you specify here is critical to the placement of the item select box, this value determines where the LEFTEDGE of the select box will be placed. eg. +-------------------+ | MENU | | HEADER | | BOX | +-------------------+ | | | | | | |from | |this | |edge | | | -x | +x | <--- out ---> | | | | | +----------+ | MENUITEM | menuitem will be positioned +----------+ relative menu box. +----------+ | SUB ITEM | subitem will be positioned +----------+ relative menu box. top - numeric, top offset relative to menu select box the value you specify here is critical to the placement of the item select box. if 'top' < 65535 then the select box is measured from the bottom of the previous menu. eg. top = 0, places top edge of select box immediately below the item/subitem that precedes it. top = 20, places top edge of select box 20 pixels below the item/subitem that precedes it. if 'top' < 0 then the select box is measured from the top edge of the previous menu item. (the height of the previous item is NOT included) if 'top' > 65535 then the select box is measured from the top edge of the menu (modulo 65536). +----------------+ top > 65535 measure | MENU BAR | from here down +----------------+ . . MENU ITEMS . . +----------------+ top <= -1 measusre previous | ^ MENU/ITEM | from here down menu item | | | | | | | height | | | | | | | | v | +----------------+ 0 <= top < 65535 measure from here down +-----------+ <--- this edge will be | SUB ITEM | relative to one of +-----------+ the edges above, depending on value of 'top' width - numeric, width of the item select box code as zero to get default, the default width is the IntuiTextLength of the 'text' string parameter. Do Not use negative values here. height - numeric, height of the item select box code as zero to get default, the default height is the text height of the font for the rastport. Do Not use negative values here. flags - numeric, flags for the item Code as zero to get default, the default value for menu-items and sub-items is ITEMTEXT+HIGHCOMP+ITEMENABLED If you specify a non-zero value here then you must COMPLETELY specify the flag value. eg. If you use COMMSEQ to specify that command sequence character be displayed, then the flag value is simply set to COMMSEQ. the complete flag value should be specified as ITEMTEXT+HIGHCOMP+ITEMENABLED+COMMSEQ (or whatever you want) ME - numeric, mutual exclude mask COM - text string, command sequence character the first character of the string is used fp - numeric, front pen color for the item text bp - numeric, back pen color for the item text dm - numeric, draw mode to use for the item text itemfill - pointer to an IntuiText, or Image structure If this parameter is non-zero, then it will be used, the IntuiText structure will NOT be built from the text, fp, bp, and dm parameters. If this parameter is -1 then APIG will leave the menuitem's ItemFill parameter NULL. Yes you can specify a pointer to an Image structure here. selectfill - pointer to an Image structure this Image will be displayed when the mouse pointer is pointing to this sub-item. To use this the HIGHIMAGE flag must be set. If no image to display then code this as a zero. APIG uses whatever you put here, do not use -1. Returns: - pointer to sub-item Note that the menu is not attached to the window, the item is simply constructed. You will need to call SetMenuStrip to actually attach the menu strip to the window. Also see menu hints. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) ------------------------------------------------ <> MAKESTRUCT(owner,type,size,mem_type) MAKEPOINTER is synonymous with MAKESTRUCT This function allocates an Intuition structure pointer. All pointers made by APIG have specific information about the pointer at negative offsets. APIG uses this information to validate the pointer. See the section below describing APIG pointers. ------------------------------------------------ <> MAKETATTR(window,fontname,fontsize ) Allocate and build an Text Font Attribute structure. The value returned by this function is used with OPENFONT() to load a text font from disk, and to specify fonts for intuitext. Note OPENFONT() returns a pointer to a TextFont structure, which is NOT used in MAKEITEXT(). Inputs: window - pointer to a window opened with OPENWINDOW(). This must be a pointer to a window. fontname - string, name of the font to use fontsize - numeric, size of the specified font to use Returns: - pointer (rexx hex string) to the allocated TextAttr - returns null ('0000 0000'x) if call fails ------------------------------------------------ <> MENUNUMBER(menustrip,menu,item,subitem) This function generates a 'MENUNUMBER'. Inputs: menustrip - pointer to first menu in a menustrip menu - pointer to a menu within the menustrip item - pointer to a menu-item within the specified menu subitem - pointer to a sub-item within the specified item (code as zero if no sub-item) Returns: - numeric, 'MENUNUMBER'. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> MOUSEFREQUENCY(window,N) This function allows you to specify how often you want to receive MOUSEMOVE messages from INTUITION. The task managing the windows IDCMP builds an ARexx message for the MOUSEMOVE event it receives, and immediately replies to INTUITION, afterwhich it then sends the ARexx message packet to you. The rate at which INTUITION sends MOUSEMOVEs might be faster than your ARexx macro can keep up with. This function will cause the task to 'swallow' every 'Nth' MOUSEMOVE message. Inputs: window - pointer to window opened with OPENWINDOW(). N - numeric, frequency at which MOUSEMOVES should be sent to you eg. x = mousefrequency(window,50) will cause you to receive every 50th MOUSEMOVE message. eg. x = mousefrequency(window,1) will get you all MOUSEMOVE messages. specifing a value of zero will default to 1. When a window is initially opened its mousefrequency is 1. Returns: - returns N, the value you specified. Note that you must specify MOUSEMOVES in the idcmp parameter in order to get MOUSEMOVE event messages. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> OPENWINDOW( portname,left,top,wid,hgt,dpen,bpen,IDCMP,flags, title,scr,console,bitmap,chkmark ) Opens a window for use with the graphics/intuition library functions. Each call to this function creates a separate task to manage the IDCMP port for the window. Inputs: portname - name of the public message port where IDCMP messages should be sent. The public port should be allocated prior to making the call to 'OPENWINDOW'. The parameter 'portname' is a string which is the name of a public message port opened with the ARexx OPENPORT function. eg. portname = 'myport' msgport = openport(portname) left - numeric, position of the left edge of the window top - numeric, position of the top edge of the window wid - numeric, width of the window hgt - numeric, height of the window dpen - numeric, detail pen to use bpen - numeric, block pen to use IDCMP - numeric, IDCMP flags - the set of messages that will be reported. The value you specify here determines what types of messages you will receive from INTUITION. Be careful about the value you put here, since this value gets passed to Intuition's OpenWindow() function. eg. If you code a zero then Intuition doesnt even bother opening up an IDCMP, and the window task will never send you a message packet. (youll then find yourself waiting forever for a message to arrive at your Rexx message port) flags - numeric, window flags title - string, window title string scr - screen in which window should appear, this should be a pointer returned by the 'OPENSCREEN' function. If the window is to appear in the workbench screen code this as a zero console - numeric, this parameter determines whether a 'console' will be attached to the window. Specifying any non-zero value here will cause a 'console' to be attached. You will then be able to write to the window using WRITECONSOLE(). Note: Their is no function to read from the console use the IDCMP RAWKEY or VANILLAKEYS flag. bitmap - pointer to bitmap, if non-zero this implies that the window is a superbitmap window. 'bitmap' should then point to a valid bitmap obtained from MAKEBITMAP() function. You must also set the appropriate window/screen flag values. chkmark - pointer to an image, if non-zero this should point to an image obtained with the function LOADIMAGE(). This imagery will be used as the check mark for menu items. Only a few of the inputs are checked for validity, I can only assume you know what you want to do. So be careful when specifing the inputs. Returns: - returns pointer to a window as a Rexx hex string. returns null hex string (ie. '0000 0000'x) if open fails. Intuition events received at the windows IDCMP port will be sent to the public port specified by portname. If the public port cannot be found the OPENWINDOW call will fail. Intuition events are sent to the public port as RexxMsg packets. Depending on the type of intuition event received, the argument slots of the packet will contain specific information about the event. The intui-event information is returned in separate slots of the ARexx message packet as follows: arg0 - CLASS numeric string, class of the intui-event arg1 - CODE numeric string, code of the intui-event arg2 - QUALIFIER numeric string, qualifier of the intui-event arg3 - MOUSEX numeric string, mouse position x coord. arg4 - MOUSEY numeric string, mouse position y coord. arg5 - SECONDS numeric string, event time stamp arg6 - MICROS numeric string, event time stamp arg7 - WINDOW a Rexx hex string, which is the address of the window in which the event occured. arg8 - IADDRESS a Rexx hex string, IAddress of the intui-event this typically will be the address of a gadget causing the event arg9 - GADGETID numeric string, if the event is a gadget related event this will be the GadgetID of the gadget The remaining slots are not used Upon receiving a message you should then use the ARexx functions GETPKT(), and GETARG() to examine the values of the intuition message. After you are done using the message you should then 'reply' back to the window task using the ARexx function REPLY(). eg. After allocating a port and opening a window; exitme = 0 do forever /* loop forever */ x = waitpkt(portname) /* wait for next message(s) to arrive */ do forever /* loop thru all received messages */ msg = GETPKT(portname) if msg = '0000 0000'x then leave class = GETARG(msg,0) code = GETARG(msg,1) qualifier = GETARG(msg,2) mousex = GETARG(msg,3) mousey = GETARG(msg,4) seconds = GETARG(msg,5) micros = GETARG(msg,6) window = GETARG(msg,7) iaddress = GETARG(msg,8) gadgetid = GETARG(msg,9) /* zero if not gadget related */ if class = 512 then exitme = 1 /* class 512 = CLOSEWINDOW */ x = REPLY(msg,0) /* you MUST reply to all messages */ end if exitme = 1 then leave end ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) The window task created will have the name 'apig.task.N', where N is a sequential number used to uniquely identify the task managing the windows IDCMP port. This tasks creates several private msgports for communicating with the library functions, however one public message port is created for sending commands directly to the task. The name of this public message port will be the same as the task name (ie. 'apig.task.N'). Commands are sent to the public message port via the Rexx 'address' command. The only commands recognized at the task public message port are "DIE" - this command tells the task to kill itself and return all allocated resources it owns back to the system. Note the task knows nothing about independent structures that have been allocated and will NOT free them. It does know about all other memory that has been allocated to (owned by) its window and thus WILL free it. The primary use for this command will arise when the window is left hanging open due to termination of your ARexx macro because of an error. eg. from CLI prompt you could enter (assuming you are running WSHELL) > "address 'apig.task.1' DIE" This will (hopefully) tell the apig.task.1 to close the window and kill itself. If the window is opened on a custom screen the screen will be closed as well. If multiple windows are opened on a custom screen then each window must be told to die. When the last window is closed the custom screen will be closed. Note: If you know the address of the window you can also close it from the command line with: > "say closewindow('wwww wwww'x)" where 'wwww wwww'x is the hex address of the window. if the window is on a screen, the screen will NOT be closed, even if the window is the last/only window in the screen. Memory (gadgets, intuitexts, menus, etc.) allocated to the window will be freed. > "say closescreen('ssss ssss'x)" will close a screen from the command line APIG will only close windows/screens which it has opened. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> OPENSCREEN( left,top,width,height,depth,dpen,bpen,vmodes, type,title ) Opens a custom screen for your use. Inputs: left - numeric, screens left edge top - numeric, screens top edge width - numeric, screens width height - numeric, screens height depth - numeric, screen depth, number of bit planes dpen - numeric, detail pen to use bpen - numeric, block pen to use vmodes - numeric, view modes flag type - numeric, type of screen CUSTOMSCREEN, WBENCHSCREEN, SCREENBEHIND, etc. title - string, screen title Returns: - returns pointer to screen as a Rexx hex string returns null hex string (ie. '0000 0000'x) if open fails. ------------------------------------------------ <> PITEXT(rp,left,top,text,fp,bp,dm,font) This function builds an IntuiText structure using the values you specify and then calls PrintIText to display the text in the RastPort. The IntuiText structure created is immediately discarded. The purpose is to allow you to render text in the rastport, without having to make SetAPen,SetBPen etc. calls between Text() calls. Inputs: rp - pointer to rastport in which to display text left - numeric, left edge offset relative to rastport top - numeric, top edge offset relative to rastport text - text string to be displayed fp - numeric, front pen color bp - numeric, back pen color dm - numeric, draw mode (JAM1,JAM2,etc) font - font to use, ( from MAKETATTR() ) Returns: - always returns 1 ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> SAVEIFF(bitmap,filename,colortab,HAM,compress) This function uses Christian Weber's iff.library to save an IFF file. Inputs: bitmap - pointer to bitmap containing IFF imagery. filename - the name of the file to save IFF. colortab - pointer to a color table, ie. array of 16bit values. HAM - numeric, if non-zero specifies to save as HAM image. compress - numeric, if non-zero specifies to save UN-COMPRESSED default is to save COMPRESSED Returns: - returns 1 if sucessful, otherwise zero. ------------------------------------------------ <> SAVEIFFCLIP(bitmap,filename,x,y,w,h,colortab,HAM,compress) This function uses Christian Weber's iff.library to save a rectangular region of a bitmap as an IFF file. Inputs: bitmap - pointer to bitmap containing IFF imagery. filename - the name of the file to save IFF. x - numeric, horizontal offset into bitmap y - numeric, vertical offset into bitmap w - numeric, width of rectangle, expressed in bytes. (ie. number of pixels divided by 8) h - numeric, height of rectangle, expressed in lines. (ie. number of raster lines) colortab - pointer to a color table, ie. array of 16bit values. HAM - numeric, only meaningful value here is a viewmode of HAM (2048). ie. a value of 2048 specifies to save as HAM image. code as 2048 (0x0800) or zero compress - numeric, if non-zero specifies to save UN-COMPRESSED default is to save COMPRESSED Returns: - returns 1 if sucessful, otherwise zero. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> SET_APIG_GLOBALS() This function initializes many of the global constants used by/in the various Intuition/Graphic data structures and makes them available to your ARexx macro. Calling this function will modify your ARexx macro environment so that the variables listed below are defined and valued. Of course you could just as well make assignments in your ARexx macro. (any value not listed below you will have to assign in your ARexx pgm) Inputs: - none All of the variables listed below are numeric with the exception of MEMF_CHIP, MEMF_CLEAR, MEMF_FAST, MEMF_PUBLIC. These four constant are created as 4byte hex-strings in order to be compatiable with the ARexx ALLOCMEM() function. ie. MEMF_CLEAR = '10000'x /* = MEMF_CLEAR */ MEMF_PUBLIC = '10001'x /* = MEMF_CLEAR + MEMF_PUBLIC */ MEMF_CHIP = '10002'x /* = MEMF_CLEAR + MEMF_CHIP */ MEMF_FAST = '10004'x /* = MEMF_CLEAR + MEMF_FAST */ Also be aware that the use of the 'procedure' keyword in an internal function creates a new symbol table, these variables will not be defined within the procedure unless you also call SET_APIG_GLOBALS from within the procedure. SET_APIG_GLOBALS creates and sets the following variables: ACTIVATE ACTIVEWINDOW ALTKEYMAP AUTOBACKPEN AUTODRAWMODE AUTOFRONTPEN AUTOITEXTFONT AUTOKNOB AUTOLEFTEDGE AUTONEXTTEXT AUTOTOPEDGE BACKDROP BOOLGADGET BORDERLESS BOTTOMBORDER CHECKED CHECKIT CHECKWIDTH CLOSEWINDOW COMMSEQ COMMWIDTH COMPLEMENT CUSTOMSCREEN DELTAMOVE DISKINSERTED DISKREMOVED ENDGADGET FOLLOWMOUSE FREEHORIZ FREEVERT GADGDISABLED GADGETDOWN GADGETUP GADGHBOX GADGHCOMP GADGHIGHBITS GADGHIMAGE GADGHNONE GADGIMAGE GADGIMMEDIATE GIMMEZEROZERO GRELBOTTOM GRELHEIGHT GRELRIGHT GRELWIDTH HAM HIGHBOX HIGHCOMP HIGHFLAGS HIGHIMAGE HIGHITEM HIGHNONE HIRES IECLASS_EVENT IECLASS_GADGETDOWN IECLASS_GADGETUP IECLASS_NULL IECLASS_RAWKEY IECLASS_RAWMOUSE IECODE_LBUTTON IECODE_MBUTTON IECODE_NOBUTTON IECODE_RBUTTON IECODE_UP_PREFIX IEQUALIFIER_CAPSLOCK IEQUALIFIER_CONTROL IEQUALIFIER_LALT IEQUALIFIER_LCOMMAND IEQUALIFIER_LEFTBUTTON IEQUALIFIER_LSHIFT IEQUALIFIER_MIDBUTTON IEQUALIFIER_NUMERICPAD IEQUALIFIER_RALT IEQUALIFIER_RBUTTON IEQUALIFIER_RCOMMAND IEQUALIFIER_RELATIVEMOUSE IEQUALIFIER_RSHIFT INACTIVEWINDOW INTUITICKS INVERSVID ISDRAWN ITEMENABLED ITEMTEXT JAM1 JAM2 KNOBHIT LACE LAYERBACKDROP LAYERREFRESH LAYERSIMPLE LAYERSMART LAYERSUPER LAYERUPDATING LEFTBORDER LONGINT LOWCHECKWIDTH LOWCOMMWIDTH MAXBODY MAXPOT MEMF_CHIP MEMF_CLEAR MEMF_FAST MEMF_PUBLIC MENUDOWN MENUENABLED MENUNULL MENUPICK MENUTOGGLE MENUTOGGLED MENUUP MENUVERIFY MOUSEBUTTONS MOUSEMOVE NEWPREFS NEWSIZE NOCAREREFRESH NOISYREQ NOITEM NOMENU NOSUB POINTREL PREDRAWN PROPBORDERLESS PROPGADGET RAWKEY REFRESHWINDOW RELVERIFY REPORTMOUSE REQCLEAR REQSET REQVERIFY RIGHTBORDER RMBTRAP SCREENBEHIND SCREENQUIET SELECTDOWN SELECTED SELECTUP SHOWTITLE SIMPLE_REFRESH SIZEBBOTTOM SIZEBRIGHT SIZEVERIFY SMART_REFRESH STRGADGET STRINGCENTER STRINGRIGHT SUPER_BITMAP TOGGLESELECT TOPBORDER VANILLAKEY WBENCHMESSAGE WBENCHSCREEN WINDOWACTIVE WINDOWCLOSE WINDOWDEPTH WINDOWDRAG WINDOWREFRESH WINDOWSIZING eg. after calling SET_APIG_GLOBALS say "Lace = " lace should display Lace = 4 ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> SETARRAY( arrayptr, arrayindx, value ) This function allows you to store 16-bit values into the array pointed to by 'arrayptr'. Primarily intended for initializing arrays of 16bit integers for functions like LOADRGB(), POLYDRAW(), and MAKEBORDER(). Inputs: arrayptr - pointer to array (block of memory) as returned by ARexx ALLOCMEM(). The array should be allocated in multiples of 2bytes. arrayindx - numeric, index position you wish to set value - numeric, value to set position to Returns: - returns the value the array position was set to. Also See: SETX(), SETY(), GETX(), GETY(), GETARRAY() ------------------------------------------------ <> SETIMAGE(image,left,top,ppick,ponoff) This function modifies the variables of an Image structure. This allows you to link Images together, so that when they are drawn they are offset by dx, dy. Otherwise the images would be displayed one on top of each other. Inputs: image - pointer to an image structure left - numeric, value to set leftedge use -1 if value is not to be modified top - numeric, value to set topedge use -1 if value is not to be modified ppick - numeric, value to set PlanePick use -1 if value is not to be modified ponoff - numeric, value to set PlaneOnOff use -1 if value is not to be modified Returns: - always returns 1 ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> SETSTRGAD( gadgetptr,text ) This function sets the value of the string gadget to 'text' You must refresh the gadget to see the new string. Inputs: gadgetptr - pointer to a string gadget text - text string to be stored in the string gadget Note to clear a string gadget use a empty string using double quotes. eg. x = SETSTRGAD(mygad,"") THIS x = SETSTRGAD(mygad,0) NOT this this puts the character '0' in the gadget Returns: - returns the length of the string installed in the string gadget buffer. This should be the length of the 'text' you specified. If the length of the 'text' is greater than the max chars the string gadget buffer can hold, then (maxchars - 1) are placed in the buffer. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> 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. (If you're gonna shoot yourself in the foot this is the gun to do it with.) 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. (ie. '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 succesful, otherwise 0 ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> SETX( arrayptr,xindex,value ) This function does the same as SETARRAY(), the difference is that it computes the index offset value for X-pair for you. Inputs: arrayptr - pointer to array as returned by ARexx ALLOCMEM(). xindex - numeric, index position you wish to set value - numeric, value to set position to Returns: - returns the value the array position was set to. ------------------------------------------------ <> SETY( arrayptr,yindex,value ) This function does the same as SETARRAY(), the difference is that it computes the index offset value for Y-pair for you. Inputs: arrayptr - pointer to array as returned by ARexx ALLOCMEM(). yindex - numeric, index position you wish to set value - numeric, value to set position to Returns: - returns the value the array position was set to. ------------------------------------------------ <> VERTPOT(gadgeptr) This function returns the value of the vertical component of the pot gadget. Inputs: gadgetptr - pointer to a proportional gadget, return from MAKEPROPGADGET(). Returns: - returns the numeric value of VertPot ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> TICKFREQUENCY(window,N) This function allows you to specify how often you want to receive INTUITICK messages from INTUITION. The task managing the windows IDCMP builds an ARexx message for the INTUITICK event it receives, and immediately replies to INTUITION, afterwhich it then sends the ARexx message packet to you. The rate at which INTUITION sends INTUITICKS is about 10 times per sec, which might be faster than your ARexx macro can keep up with. This function will cause the task to 'swallow' every 'Nth' INTUITICK message. Inputs: window - pointer to window opened with OPENWINDOW(). N - frequency at which INTUITICKS should be sent to you eg. x = tickfrequency(window,50) will cause you to receive every 50th INTUITICK message. (approx. one every 5 seconds) eg. x = tickfrequency(window,1) will get you all INTUITICK messages. specifing a value of zero will default to 1. When a window is initially opened its tickfrequency is 20. Returns: - returns N, the value you specified. ------------------------------------------------ <> USEIFFCOLOR(pointer,scr) This functions sets the screens color registers to the colors contained in the 'CMAP' chunk of the IFF. If the IFF has no CMAP then no change is made to the screen colors. Inputs: pointer - pointer to a IFF bitmap (returned by LOADIFF()). This must be the original bitmap pointer (or copy of it) returned by the LOADIFF() function. You cannot use a pointer returned by MAKEBITMAP() into which you have blitted the IFF. scr - pointer to a screen opened with OPENSCREEN() Returns: - does a LOADRGB() of the IFF colors into the screen and returns 1 if successful. returns 0 if not a pointer to IFF or if the IFF does not contain a CMAP chunk. ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> WINDOWINFO(window,code) This function returns various values from the window structure. Inputs: window - pointer to window opened with OPENWINDOW(). code - numeric, code which specifies which value from the window structure you would like. The code values are: CODE Returns --------- --------------------------- 1 Windows Left Edge value 2 Windows Top Edge value 3 Windows Width value 4 Windows Height value 5 Windows MouseY value 6 Windows MouseX value 7 Windows MinWidth value 8 Windows MinHeight value 9 Windows MaxWidth value 10 Windows MaxHeight value 11 Windows Flags value 12 Windows Requester count value 13 Windows Border Left value 14 Windows Border Top value 15 Windows Border Right value 16 Windows Border Bottom value 17 Windows IDCMP Flags value 18 Windows Detail Pen value 19 Windows Block Pen value 20 Windows GZZMouseX value 21 Windows GZZMouseY value 22 Windows GZZWidth value 23 Windows GZZHeight value ------------------------------------------------ <> 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' ------------------------------------------------ ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> WRITECONSOLE(window,text) This function writes the text to console of the window. The window must have been opened with a console attached. Inputs: window - pointer to window opened with OPENWINDOW(). text - text string to be written to console. Returns: - the number of characters written to the console. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Graphics Library Functions After parameter conversion the following functions result in a direct call to the Amiga Graphic Library function of the same name. Please refer to your favorite Amiga reference book(s) for a detailed description. <> AREACIRCLE(rp,cx,cy,radius) <> AREADRAW(rp,x,y) <> AREAELLIPSE(rp,cx,cy,a,b) <> AREAEND(rp) <> AREAMOVE(rp,x,y) <> BLTBITMAP(srcbm,srcx,srcy,dstbm,dstx,dsty,sizex,sizey,minterm, mask,tempa) <> BLTBITMAPRASTPORT(srcbm,srcx,srcy,rp,destx,desty,sizex,sizey,minterm) <> BLTCLEAR(memblock,bytecount,flags) <> BLTMASKBITMAPRASTPORT(scrbm,srcx,srcy,rp,destx,desty,sizex,sizey, minterm,bltmask) <> BLTPATTERN(rp,mask,x1,y1,x2,y2,bytecnt) <> BLTTEMPLATE(srctemplate,srcx,srcmod,rp,dstx,dsty,sizex,sizey) <> CLEAREOL(rp,x,y) Note: The Amiga Graphics library function has one argument. X,Y (starting pixel position) are included in this call to mark where the clearing should start from. <> CLEARSCREEN(rp,x,y) Note: The Amiga Graphics library function has one argument. X,Y are included in this call to mark where the clearing should start from. <> CLIPBLIT(srcrp,srcx,srcy,destrp,destx,desty,xsize,ysize,minterm) <> DRAW(rp,x,y) <> DRAWCIRCLE(rp,cx,cy,r) <> DRAWELLIPSE(rp,cx,cy,a,b) <> FLOOD(rp,mode,x,y) <> INITAREA - see MAKEAREA function <> INITBITMAP - see MAKEBITMAP function <> INITRASTPORT - see MAKERASTPORT function <> LOADRGB4(screen,arrayptr,count) <> MOVE(rp,x,y) <> OPENFONT(textAttr) Note: textAttr is obtained from MAKETATTR() <> POLYDRAW(rp,count,array) <> READPIXEL(rp,x,y) <> RECTFILL(rp,xmin,ymin,xmax,ymax) <> SCROLLRASTER(rp,dx,dy,xmin,ymin,xmax,ymax) <> SETAFPT(rp,pattern,patternsize) <> SETAPEN(rp,pen) <> SETBPEN(rp,pen) <> SETDRMD(rp,mode) <> SETDRPT(rp,linepattern) <> SETFONT(rp,font) <> SETOPEN(rp,pen) <> SETRAST(rp,pen) <> SETRGB4(screen/window,pen,r,g,b) Note: This function does the same as SETRGB4() but the parameters are different. The first parameter is a pointer to a screen or window. <> SETSOFTSTYLE(rp,style,enable) <> SETWRMSK(rp,wrtmask) <> TEXT(rp,string,count) Note: If the count parameter is less than zero, then the length of the string will be computed for you. eg. call TEXT(rp,string,-1), the length of string is computed for you (string must be null terminated) <> TEXTLENGTH(rp,string,count) Note: If the count parameter is less than zero, then the length of the string will be computed for you. (string must be null terminated) <> WRITEPIXEL(rp,x,y) ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Intuition Library Functions After parameter conversion the following functions result in a direct call to the Amiga Intuition Library function of the same name. Please refer to your favorite Amiga reference book(s) for a detailed description. <> ACTIVATEGADGET(gadget,window,requester) <> ACTIVATEWINDOW(window) <> ADDGADGET(window,gadget,position) <> ADDGLIST(window,gadget,position,numgad,requester) <> AUTOREQUEST(window,itext,itext,itext,posflags,newflags,width,hgt) Note: This function does not return until the requester is satisfied. Only one requester can be put up at a time. <> BEGINREFRESH(window) <> CLEARDMREQUEST(window) <> CLEARMENUSTRIP(window) Note: APIG library will call CLEARMENUSTRIP() before closing a window. The library will also call CLEARMENUSTRIP() before setting a new menu strip. You will need this function however if you set a menustrip, but then later want to remove the menu without setting a new one. (ie. no menus displayed) <> CLEARPOINTER(window) <> CLOSESCREEN(screen) APIG will refuse to close a screen if a window is still open. APIG will refuse to close a screen that it did not open. <> CLOSEWINDOW(window) APIG will refuse to close a window that it did not open. <> DISPLAYBEEP(screen) <> DOUBLECLICK(startsecs,startmicros,currentsecs,currentmicros) <> DRAWBORDER(rp,border,leftoffset,topoffset) <> DRAWIMAGE(rp,image,leftoffset,topoffset) <> ENDREFRESH(window,complete) <> ENDREQUEST(requester,window) <> GETDEFPREFS(prefbuffer,size) <> GETPREFS(prefbuffer,size) <> GETSCREENDATA(buffer,size,type,screen) <> ITEMADDRESS(menustrip,menunumber) <> ITEMNUM(menunumber) <> INITREQUESTER - see MAKEREQUESTER <> INTUITEXTLENGTH(itext) <> MENUNUM(menunumber) <> MODIFYIDCMP(window,idcmpflags) <> MODIFYPROP(gadget,window,requester,flags,hpot,vpot,hbody,vbody) <> NEWMODIFYPROP(gadget,window,requester,flags,hpot,vpot,hbody,vbody, numgad) <> MOVESCREEN(screen,deltax,deltay) <> MOVEWINDOW(window,deltax,deltay) <> OFFGADGET(gadget,window,requester) <> OFFMENU(window,menunumber) <> ONGADGET(gadget,window,requester) <> ONMENU(window,menunumber) <> PRINTITEXT(rp,itext,leftoffset,topoffset) <> REFRESHGADGETS(gadgets,window,requester) <> REFRESHGLIST(gadgets,window,requester,numgad) <> REFRESHWINDOWFRAME(window) <> REMOVEGADGET(window,gadget) <> REMOVEGLIST(window,gadget,numgad) <> REPORTMOUSE(boolean,window) ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> REQUEST(requester,window) This function unlike the AUTOREQUEST() function, returns immediately. In v1.1 of APIG multiple requesters can be put up. This function will return 1 if the requester was successfully put up in the window, else it returns 0. If successful you should then enter a loop to receive messages from the window task. The IDCMP of the window will have been modified, you will get your normal IDCMP messages in addition to GADGETDOWN, GADGETUP, REQCLEAR and REQSET messages. When the requester is satisfied, the IDCMP will be restored. eg. after building a requester reqputup = request(myrequester,mywindow) if reqputup = 1 then /* if result is 1 request successful */ do /* else requester was not put up */ exitme = 0 do forever if exitme = 1 then leave x = waitpkt(portname) do forever msg = getpkt(portname) if msg = '0000 0000'x then leave class = getarg(msg,0) if class = REQCLEAR then exitme = 1 if class = GADGETDOWN then do gadid = getarg(msg,9) if gadid = mygadgetid1 then do x = dosomething1() exitme = 1 end end if class = GADGETUP then do gadid = getarg(msg,9) if gadid = mygadgetid2 then do x = dosomething2() exitme = 1 end end x = replymsg(msg,0) end end end ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) <> SCREENTOBACK(screen) <> SCREENTOFRONT(screen) <> SETDMREQUEST(window,dmrequester) <> SETMENUSTRIP(window,menu) Note: APIG library keeps track of whether a menu strip has been attached to a window. Therefore you can call SETMENUSTRIP() multiple times without having to precede it with a CLEARMENUSTRIP() call. The library will call CLEARMENUSTRIP() for you if it sees that a menu is still attached to the window. It will also call CLEARMENUSTRIP() before closing a window as well. <> SETPOINTER(window,pointer,height,width,xoffset,yoffset) <> SETPREFS(prefbuffer,size,inform) <> SETWINDOWTITLE(window,widnowtitle,screentitle) <> SHOWTITLE(screen,showit) <> SIZEWINDOW(window,deltax,deltay) <> SUBNUM(menunumber) <> WBENCHTOBACK() <> WBENCHTOFRONT() <> WINDOWLIMITS(window,minwidth,minheight,maxwidth,maxheight) <> WINDOWTOBACK(window) <> WINDOWTOFRONT(window) ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Layers Library Functions After parameter conversion the following functions result in a direct call to the Amiga Layers Library function of the same name. Please refer to your favorite Amiga reference book(s) for a detailed description. <> BEHINDLAYER(layer) Note that only one parameter is used. layer - is a pointer to a layer structure <> CREATEBEHINDLAYER(windowpointer,x0,y0,x1,y1,flags,bm2) Note that a window pointer (obtained from OPENWINDOW()) is used instead of the parameters layerinfo and bitmap as described in the RKM manual. The layerinfo and bitmap pointers are obtained from the window parameter, all other parameters are as described in RKM. <> CREATEUPFRONTLAYER(windowpointer,x0,y0,x1,y1,flags,bm2) Note that a window pointer (obtained from OPENWINDOW()) is used instead of the parameters layerinfo and bitmap as described in the RKM manual. The layerinfo and bitmap pointers are obtained from the window parameter, all other paramenters are as described in RKM. <> DELETELAYER(layer) Note that only one parameter is used. layer - is a pointer to a layer structure <> MOVELAYERINFRONTOF(layertomove,targetlayer) <> MOVELAYER(layer,dx,dy) Note that only three parameters are used. layer - is a pointer to a layer structure <> SCROLLLAYER(layer,dx,dy) Note that only three parameters are used. layer - is a pointer to a layer structure <> SIZELAYER(layer,dx,dy) Note that only three parameters are used. layer - is a pointer to a layer structure <> UPFRONTLAYER(layer) Note that only one parameter is used. layer - is a pointer to a layer structure ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Exec Library Functions After parameter conversion the following functions result in a direct call to the Amiga Exec Library function of the same name. Please refer to your favorite Amiga reference book(s) for a detailed description. When using the list functions, parameters are allocated from system memory using the ARexx function ALLOCMEM(). Be sure that you allocate at least as much memory required for the list or node data structure. <> 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. You may find these functions useful when working with Exec list structures. <> 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. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Some Menu Hints Menu Text You will find that using pre-constructed IntuiText allows for better placement of the menu/item/subitem text. When menu text is specified in the make... call APIG builds a simple IntuiText structure. Using pre-constructed IntuiText, you could make the select box as large as you like and place the text anywhere within the select box (since the IntuiText will be relative to its containing menu/item/subitem select box. eg. instead of this (1) myitem = makeitem(w,"My Item Text",...,0,0) do this myitemIntuiText = makeitext(w,'My Item Text',...) (2) myitem = makeitem(w,"",...,0,myitemIntuiText) (dont forget that the IntuiText can be linked too!) (allowing multiple text be displayed for a single menu) Form (1) allows you to quickly get the menu structure/layout built, afterwhich you can go back and fill in the details with pre-constructed IntuiText, form (2). The 'top' parameter It is the value of 'top' that allows you to position items/subitems on the same line. eg. makeitem(w,'AA',m,0,0,... ) makeitem(w,'AB',m,0,0,... ) makeitem(w,'AC',m,x,65536,... ) makeitem(w,'AD',m,x,0,... ) would produce +------------------------+ | AA item AC item | | AB item AD item | +------------------------+ the 'top' value of 65536 (mod(top,65536) = 0 ) will cause the top edge of of item AC to be measured from zero. The item AD is measured from the item which precedes it, which is item AC, AD has a 'top' value of 0, therefore it is measured from the bottom of AC. If AD had a non-zero 'top' value < 65536 then the menu would look something like this +------------------------+ | AA item AC item | | AB item | <--- | | AD top pixels (ADtop < 65536) | | | AD item | <--- +------------------------+ there are 'ADtop' number of pixels between the BOTTOM of AC and the top of item AD. if item 'ADtop' value were negative then their would be 'ADtop' number of pixels between the TOP of AC and the top of item AD. +------------------------+ <--- | AA item AC item | | AB item | | | AD top pixels | | | AD item | <--- +------------------------+ Note you must shift the items over 'x' number of pixels so that AC does overlay item AA. If item AC had a 'top' value > 65536 then the menu would look something like this +------------------------+ <--- | AA item | mod(ACtop,65536) | AB item | pixels | AC item | <--- | | | | | | | AD item | +------------------------+ item AD will still be measured relative to the one that precedes, ie. item AC. If both item AC and AD had top values >= 65536 then the menu might look something like below depending on the 'top' values for items AC and AD. +--------------------------------+ | AA item AC item AD item | | AB item | | | +--------------------------------+ or this +--------------------------------+ | AA item AC item | | AB item | | | | AD item | +--------------------------------+ The 'height' parameter The 'height' parameter determines how tall the select box is, for sub-items you will want the select boxes to be close together, so that the menu layer is not re-drawn as you move from sub-item to sub-item. If your sub-items flicker/jump/wiggle or whatever you call it, then you probably will want to adjust the height parameter. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) A little about APIG pointers. In version 0.5 APIG simply returned a pointer (ACTUAL address) to the allocated structure, APIG knew nothing about the pointer or what it pointed to. In fact one could simply hand hardcode a block of memory for a particular structure and APIG 0.5 would use it. In version 1.1 APIG verifies that the pointer you passed in a function call, points to a structure of the appropriate type. It does this by storing information about the pointer at negative offsets, similar to ARexx argstrings. ALL pointers returned (made) by APIG have the following information stored at negative offsets from the pointer: format 1: APIGTAG contents | $4AFA | ptr | type | structure memory block | offset | -8 | -6 | -2 | size | 2 | 4 | 2 | ^ APIG gives you this addr $4AFA - 2bytes Motorola says this will be illegal/trap forever ptr - 4bytes address of structure (points back to the structure) type - 2bytes numeric type of data structure allocated by APIG APIG will check the validity of all pointers passed to it and return (fail) if it is not formatted as above. If the allocated structure is a BitMap or RastPort allocated with MAKEBITMAP/MAKERASTPORT or a bitmap/image loaded with LOADIFF or LOADIMAGE then the following format is used. format 2: APIGTAG contents | bmhdr | $4AFA | ptr | type | structure memory block | offset | -12 | -8 | -6 | -2 | size | 4 | 2 | 4 | 2 | ^ APIG gives you this addr bmhdr - 4bytes, points to the IFF BMHD header that was loaded with the IFF bitmap/image by iff.library. If the APIG IFF functions do not provide all the information you need, you can use GETVALUE() with proper offsets to get the information from the BMHD itself. (See bmhdr format below) The IFF functions, eg. USEIFFCOLOR, do check the validity of the 'bmhdr' pointer. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) If MAKEBITMAP/MAKERASTPORT were used to create the pointer then the 'bmhdr' pointer will be NULL. Any function that uses a bitmap/rastport pointer, will NOT check for validity, since you can grab a bitmap/rastport from any window/screen/layer. The following are the current values used for 'type' at offset -2, use these values with the MAKESTRUCT/MAKEPOINTER functions. Type 00 = just a block of memory 15 = Gadget (bool/string/prop) 21 = IntuiText 27 = Requester 33 = Border 39 = Bitmap 45 = Rastport 51 = Image 57 = Menu 63 = MenuItem 69 = SubItem 75 = PropInfo (made internally, for gadgets) 81 = StringInfo (made internally, for gadgets) 87 = Text Attr Note: Window/Screen pointers are the pointers returned by Intuition OpenWindow/OpenScreen functions, and do not have the above format. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) Given the above, a new function has been added to allow hard coding of structures. <> MAKESTRUCT(owner,type,size,memtype) MAKEPOINTER - synonymous with MAKESTRUCT Allocate a null structure/memory block. Inputs: owner - pointer to object which will own this structure. See description of MAKEBOOLGAGET. type - numeric, type as specified above The size allocated is implicit in the type you specify. size - numeric, size of mem block to allocate APIG uses 'type' to determine the amount of memory to allocate. If 'size' is non-zero then it specifies an extra number of bytes to be allocated in addition to the standard structure size. memtype - 4byte hex-string, memory type to allocate (MEMF_CHIP/MEMF_CLEAR/MEMF_FAST/MEMF_PUBLIC) Returns: - pointer to allocated structure as a rexx hex string. - returns null ('0000 0000'x) if call fails eg. allocate memory for a gadget structure mygad = allocstruct(0,15,0,MEMF_CLEAR) returns an APIG pointer, formatted as above with negative offset values, to a null memory block the size of a Gadget structure. The 'owner' is 0, indicating an independent structure which must be explicitly freed (using FREETHIS()). You could make 'owner' a window, so that when the window is closed the memory is freed. Note the 'size' parm is 0, type 15 tells APIG how much memory to allocate. If 'size' were non-zero then APIG would allocate the standard structure size + 'size' bytes. ie. mygad = allocstruct(0,15,30,MEMF_CLEAR) would allocate an additional 30 bytes, along with the 'standard' size of a Gadget structure. eg. allocate a block of memory mymem = allocstruct(0,0,400,MEMF_CLEAR) or mymem = allocpointer(0,0,400,MEMF_CLEAR) 'owner' is zero, so must be freed explicitly 'type' is zero, thus ... 'size' determines total amount of memory to actually allocate After allocating the structure SETVALUE can then be used to assign values to the structures data fields. ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) If you were hard coding an image structure you might do the following: image = makestruct(0,51,0,MEMF_CLEAR) imagedata = makepointer(image,0,72,MEMF_CHIP) (note imagedata is just a block of mem, 'owned' by 'image', thus when 'image' is freed so is the imagedata block) x = setvalue(image,0,2,'n',0,0) /* left edge */ x = setvalue(image,2,2,'n',0,0) /* top edge */ x = setvalue(image,4,2,'n',16,0) /* width */ x = setvalue(image,6,2,'n',9,0) /* height */ x = setvalue(image,8,2,'n',4,0) /* depth */ x = setvalue(image,10,4,'p',imagedata,0) /* imagedata */ x = setvalue(image,14,1,'n',255,0) /* planepick */ x = setvalue(image,15,1,'n',255,0) /* planeonoff */ x = setvalue(image,16,4,'p',0,0) /* next image */ Assuming, of course you have stuffed some data into imagedata, the 'image' pointer can now be used with the DrawImage() function. If the ALLOCMEM() function had been used to allocate the block then used in DrawImage(), DrawImage would have found the pointer to be invalid and simply would have returned (failed). ARexx Programmers Intuition & Graphics Library ( version 1.1 09/21/91 ) The 'bmhdr' pointer points to the following structure: STRUCTURE iffinfoblock,0 UWORD iffviewmode ; offset 0, View Modes for the IFF UWORD iffcolors ; offset +2, number of colors STRUCT bmheader,SIZEOF_bmhd ; BitMapHeader Info from the IFF file ; as shown below STRUCT cmheader,128 ; offset +24 ; ColorMap Info from the IFF file ; max 64 colors @ 2bytes per color ------------------------- STRUCTURE BitMapHeader,0 UWORD bmh_Width ; offset +4 from bmhdr pointer UWORD bmh_Height ; offset +6 WORD bmh_XPos ; offset +8 WORD bmh_YPos ; offset +10 UBYTE bmh_nPlanes ; offset +12 UBYTE bmh_Masking ; offset +13 UBYTE bmh_Compression ; offset +14 UBYTE bmh_Pad1 ; offset +15 UWORD bmh_TranspCol ; offset +16 UBYTE bmh_XAspect ; offset +18 UBYTE bmh_YAspect ; offset +19 WORD bmh_PageWidth ; offset +20 WORD bmh_PageHeight ; offset +22 eg. what APIG effectively does to obtain the width of an IFF pic. bmhdr = getvalue(pic,-12,4,'p') width = getvalue(bmhdr,4,2,'n') --- THE END ---