home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d559 / apig.lha / APIG / apiglib_v11.lzh / release_info < prev    next >
Text File  |  1991-09-28  |  19KB  |  638 lines
  1.  
  2. This is version 1.1 of APIG
  3.  
  4.  
  5.  
  6. ---------------------------------------------------------------------
  7. ---------------------------------------------------------------------
  8. APIG version 1.1  Released September 21, 1991
  9. ---------------------------------------------------------------------
  10. ---------------------------------------------------------------------
  11.  
  12.   Minor changes and minor bugs fixed.
  13.  
  14.     
  15.   * * * * *   Documentation Changes  * * * * *
  16.  
  17.   Too many to list (spelling and such), hopefully the doc file reads
  18.   better now.
  19.  
  20.  
  21.   ---------------
  22.   MAKEMENU      doc changed, all the parms were not listed
  23.   MAKEITEM      doc changed
  24.   MAKESUBITEM   doc changed
  25.  
  26.  
  27.   ---------------
  28.   SETSOFTSTYLE (added in version 0.5)  was not listed in the doc.
  29.  
  30.  
  31.   ---------------
  32.   TEXT
  33.   TEXTLENGTH
  34.  
  35.   The length of the text is computed for you only if the 'count' parm is 
  36.   less than zero, otherwise it uses the 'count' parm specified (including
  37.   zero).
  38.  
  39.  
  40.   ---------------
  41.   WINDOWINFO
  42.   
  43.   Code values have changed, see WINDOWINFO function docs.
  44.  
  45.  
  46.   ---------------
  47.   The Exec list functions INSERTNODE, REMHEAD, and REMTAIL were documented
  48.   wrong, (extraneous or missing parms), they worked per RKM.
  49.  
  50.  
  51.  
  52.   * * * * *   Changed Functions * * * * *
  53.  
  54.   ---------------
  55.   ENQUEUE
  56.  
  57.   Bug fix, this function was really doing a AddHead().
  58.  
  59.  
  60.   ---------------
  61.   LOADIFF
  62.   LOADIMAGE
  63.   MAKEBITMAP
  64.   MAKEITEXT
  65.   MAKEBOOLGADGET
  66.   MAKEBORDER
  67.   MAKEITEM
  68.   MAKEMENU
  69.   MAKEPROPGADGET
  70.   MAKERASTPORT
  71.   MAKEREQUESTER
  72.   MAKESTRGADGET
  73.   MAKESUBITEM
  74.   
  75.   These functions were changed to allow the use of an 'owner'.
  76.  
  77.  
  78.   ---------------
  79.   MAKEPROPGADGET
  80.   
  81.   Parms and their order have changed, see docs.
  82.  
  83.  
  84.   ---------------
  85.   MAKEMENU
  86.   MAKEITEM
  87.   MAKESUBITEM
  88.   
  89.   These functions were totally buggy, hopefully they are fixed now, the 
  90.   parms have changed a bit too.
  91.  
  92.  
  93.   ---------------
  94.   REQUEST/ENDREQUEST
  95.  
  96.   Mulitple requesters can now be put up with Request().
  97.   Note: AutoRequest still only allows one requester to be put up.
  98.  
  99.   Bug fix, ENDREQUEST would not end unless an Intuition Message was received.
  100.   eg.
  101.        /*  code like the following should now work  */
  102.  
  103.        x = Request( ... )     /* put up a requester */
  104.  
  105.        wait 5 sec             /* dont do anything   */
  106.  
  107.        x = Endrequest( ... )  /* end the requester  */
  108.        
  109.  
  110.  
  111.   ---------------
  112.   SETRGB4
  113.  
  114.   Parm change, last parm no longer required.
  115.  
  116.   eg.  x = SETRGB4(screen/window,pen,r,g,b,'S'/'W')
  117.  
  118.   The last parm indicated whether the first parm was a screen/window pointer
  119.   this is no longer neccessary.
  120.  
  121.   eg.  x = SETRGB4(screen/window,pen,r,g,b)
  122.  
  123.  
  124.   ---------------
  125.   SETVALUE
  126.  
  127.   Bug fix, this function did not work, possibly crashed, if 
  128.   the 'value' was null/zero when using the 'P'/'S' option.
  129.  
  130.   eg.  x = setvalue(mypointer,0,4,'p',0,0)
  131.                                       ^
  132.                                       +---- this being zero caused problems
  133.  
  134.  
  135.   ---------------
  136.   SETWINDOWTITLES 
  137.   SETWINDOWTITLE 
  138.  
  139.   Bug fix, title would disappear after setting it.
  140.  
  141.  
  142.   ---------------
  143.   WINDOWINFO
  144.   
  145.   Removed the redundant LeftEdge code, see WINDOWINFO function docs.
  146.  
  147.  
  148.  
  149.   * * * * *   New Functions * * * * *
  150.  
  151.   ---------------
  152.   FREEITEXT
  153.   FREEMENU
  154.   FREETHIS
  155.   
  156.   Frees memory allocated for specified structure. (See docs)
  157.  
  158.  
  159.   
  160.   ---------------
  161.   GETPREFS         Intuition Library
  162.   GETDEFPREFS      Intuition Library
  163.   SETPREFS         Intuition Library
  164.   GETSCREENDATA    Intuition Library
  165.  
  166.   ---------------
  167.   MAKEPOINTER
  168.   MAKESTRUCT
  169.  
  170.   These functions create an APIG pointer to a block of memory.
  171.  
  172.  
  173.   ---------------
  174.   SET_APIG_GLOBALS
  175.  
  176.   This function initializes many of the global constants used by/in the
  177.   various Intuition/Graphic data structures.
  178.  
  179.  
  180.  
  181.   * * * * *   General Notes & Things * * * * *
  182.  
  183.   ---------------
  184.   General
  185.  
  186.   *  Most structures can now 'own' another structure.
  187.   
  188.   *  Parms which are 'hex-strings' are now checked for odd addresses, if so
  189.      the parm is set to NULL, causing the function call to fail instead of
  190.      crashing with an illegal address error.
  191.  
  192.   *  Parms which are 'hex-strings' which point to low-mem (usually caused
  193.      by parms in the wrong order) are set to NULL, causing the function
  194.      call to fail. Low-mem means addresses in the first 1K.
  195.  
  196.   *  All functions are affected by the above changes since parms are 
  197.      converted before being passed to the 'glue' routines of the function
  198.      call. Functions which expect non-null pointers will simply return (fail).
  199.  
  200.   *  APIG now tries to determine if the parameters you pass are legal.
  201.      eg.  PRINTITEXT(rp,itptr,...) will not print the intuitext if 'itptr' 
  202.           does not point to an Intuitext structure. The call will fail,
  203.           returning zero.
  204.      
  205.   *  Because of the large number of string names used by SET_APIG_GLOBALS,
  206.      and parameter validation, the APIG library has grown considerably.
  207.  
  208.  
  209.   ---------------
  210.   ARexx quirks
  211.  
  212.   *  I suspect their is a bug in ARexx when passing 'hex-string' parms
  213.      to internal functions.  
  214.  
  215.      eg. If you have some generic function that processes a gadget lets say,
  216.          then code like the following may or may not work all the time.
  217.  
  218.  
  219.          /*  */
  220.  
  221.          mygad = makeboolgadget(w,...)
  222.  
  223.          x = processgadget(mygad)
  224.  
  225.          exit         
  226.  
  227.          processgadget:  procedure
  228.  
  229.          arg gadptr /* gadptr should be the 'hex-string' you passed  */
  230.                     /* well, sometimes it is and sometimes it is not */
  231.  
  232.          return something
  233.  
  234.          /*  */
  235.  
  236.     
  237.     I have not yet confirmed that this is a real ARexx bug with W. Hawes.
  238.     But if it is a real bug you can circumvent it with something like
  239.     this:
  240.  
  241.  
  242.          /*  */
  243.  
  244.          mygad = makeboolgadget(w,...)
  245.  
  246.          passgad = c2d(mygad)       /* this is gonna become a pain     */
  247.  
  248.          x = processgadget(passgad) /* would be nice if you could just */
  249.                                     /* pass it and not worry about it  */
  250.          exit         
  251.  
  252.          processgadget:  procedure
  253.  
  254.          arg passedarg
  255.          
  256.          gadptr = d2c(passedarg,4)  /* the '4' makes it 4byte 'hex-string' */
  257.  
  258.          then use gadptr
  259.  
  260.          return something
  261.  
  262.          /*  */
  263.  
  264.     Or you can 'expose' it, making it available to the procedure.
  265.     
  266.        eg.   processgadget: procedure expose mygad
  267.  
  268.  
  269.  
  270.     Or you can you use all global variables (ie. never use 'procedure')
  271.  
  272.  
  273.  
  274.  
  275. ---------------------------------------------------------------------
  276. ---------------------------------------------------------------------
  277. APIG version 0.5  Released June 14, 1991
  278. ---------------------------------------------------------------------
  279. ---------------------------------------------------------------------
  280.  
  281.    Font memory not fixed
  282.    
  283.    
  284.   * * * * *   Documentation Changes  * * * * *
  285.    
  286.  
  287.    -----------------
  288.    GETWINDOWRASTPORT
  289.    
  290.                   No change made to function. Documentaion did not
  291.                   show full name of function.  
  292.                   GETWINRASTPORT should have been GETWINDOWRASTPORT
  293.                   
  294.  
  295.    ---------------
  296.    SAVEIFFCLIP    No change made to function. Documentation changed - 
  297.                   Width of image must be expressed in bytes, NOT 
  298.                   pixels.
  299.  
  300.  
  301.    ---------------
  302.    WINDOWINFO     Codes 4 & 12 ARE redundant they both return the
  303.                   LeftEdge of the window, unchanged.
  304.                   
  305.                   Code 21 = GZZMouseX
  306.                   Code 22 = GZZMouseY
  307.                   The doc file had these reversed
  308.  
  309.  
  310.   * * * * *   Changed Functions * * * * *
  311.   
  312.   
  313.    ---------------
  314.    AUTOREQUEST    Bug fix, contrary to the documentation this function
  315.                   did return immediately, the result always being the
  316.                   value one.  The response to the requester was sent 
  317.                   to the window's port when the request ended.
  318.                   Changed to return when request ends, and the response
  319.                   to the requester is returned as a result of the
  320.                   function call.
  321.                   ie.  x = autorequest() returns 1 if 'positive' gadget
  322.                        selected, returns 0 if 'negative' gadget selected.
  323.                   
  324.    
  325.    ---------------
  326.    MAKEBORDER     changed to allow linking of border structures, also
  327.                   create 'auto' borders.
  328.                   new form of function call is now
  329.                   
  330.             MAKEBORDER(window,arrayptr,arraycnt,left,top,fp,bp,dm,borderptr)
  331.             
  332.              if the parm 'arrayptr' is 0, then a 'auto' border is built
  333.              using 'left' as the width of the border, and using 'top' as
  334.              the height of the border.  The parm 'arraycnt' determines
  335.              how 'thick' the border will be.
  336.  
  337.              the last parm 'borderptr' is a pointer to another border 
  338.              structure to which the new allocated border will be linked.
  339.              
  340.              borderptr - pointer to a border structure, code a 0 if not
  341.                          linking borders.
  342.              
  343.              All other parms are unchanged.
  344.             
  345.  
  346.    ---------------
  347.    MAKEREQUESTER  changed to allow specification of requester flags and
  348.                   to allow use of predrawn bitmap imagery
  349.                   new form of function call is now
  350.                   
  351.             MAKEREQUESTER(window,arrayptr,arraycnt,left,top,fp,bp,dm,border,
  352.                               flags,relLeft,relTop,bm)
  353.             
  354.              flags   - numeric, specifies POINTREL or PREDRAWN
  355.              relLeft - numeric, specifies left offset from mouse pointer            
  356.              relTop  - numeric, specifies top offset from mouse pointer
  357.                        (relLeft & relTop used with POINTREL)
  358.              bm      - pointer to bitmap, if using PREDRAWN requester
  359.                        imagery.
  360.                        
  361.              All other parms are unchanged.
  362.  
  363.    
  364.    ---------------
  365.    MODIFYPROP      Bug fix, function registers were loaded incorrectly,
  366.                    causing this function to hang.
  367.                    
  368.    ---------------
  369.    NEWMODIFYPROP   Bug fix, function registers were loaded incorrectly,
  370.                    causing this function to hang.
  371.                    
  372.    ---------------
  373.    WINDOWINFO     Bug fix, Code 11 = window Flag, was returning a short 
  374.                   when it should have been returning a long.
  375.                   now returns full 32bit long flag value                  
  376.                   
  377.                   
  378.                   
  379.   * * * * *   New Functions * * * * *
  380.   
  381.       ------------------------ 
  382.   <>  GADSELECTED( gadgetptr )
  383.   
  384.         This function returns TRUE/FALSE depending on the state of 
  385.         the gadget. 
  386.       
  387.         Inputs:
  388.  
  389.              gadgetptr  - pointer to a gadget
  390.           
  391.         Returns:        - returns 1 if the gadget state is SELECTED,
  392.                           otherwise returns 0.
  393.  
  394.  
  395.       ---------------------------- 
  396.   <>  GETGADPTR( window,gadgetid )
  397.  
  398.         This function searches the window's gadget list for a gadget with 
  399.         GadgetID equal to 'gadgetid' and returns a pointer to the gadget.
  400.       
  401.         Inputs:
  402.  
  403.             window     - pointer to window opened with OPENWINDOW().
  404.           
  405.             gadgetid   - numeric, gadgetid 
  406.           
  407.        Returns:        - pointer (ARexx hex-string) to gadget.
  408.  
  409.  
  410.  
  411.      ------------------------------ 
  412.   <> GETVALUE(ptr,offset,size,type)
  413.  
  414.    This function allows you to retreive the value of any parameter in
  415.    any data structure.
  416.  
  417.    ptr    - pointer, (ARexx hex string) to any data structure, ie. window
  418.             screen, bitmap, etc.
  419.  
  420.    offset - numeric, specifies the relative position, from the beginning
  421.             of the data structure, of data value you want to retrieve.
  422.             (see RKM or include '.i' files for offsets)
  423.  
  424.    size   - numeric, specifies the size of the data value you want to
  425.             retrieve.  This value must be either 1, 2, or 4.  Any other
  426.             value will cause the function to return a NULL ('0000 0000'x).
  427.             
  428.    type   - string, either a 'N', 'P' or 'S', this specifies the type
  429.             of data you are retrieving.
  430.  
  431.             'N' specifies that you want the value returned as a numeric.
  432.                 for sizes of 1 and 2 the returned value is always as a 
  433.                 numeric.
  434.  
  435.             If the size is 4 then you can also use (in addition to 'N')
  436.             the following:
  437.  
  438.             'P' specifies that you want the value returned as a pointer.
  439.                 (ie. ARexx hex string)
  440.  
  441.             'S' specifies that you want the value returned as a string.
  442.  
  443.                 VERY IMPORTANT NOTE !!! 
  444.                 When using 'P' or 'S',  'ptr' + 'offset' must result 
  445.                 in an address which contains a pointer to something.
  446.  
  447.  
  448.             eg.  You can retrieve the window title string with:
  449.             
  450.                  title = getvalue(windowpointer,32,4,'S')
  451.                  
  452.                  say "Your Window title is" title
  453.                  
  454.                  (the title string pointer is offset 32 from the beginning
  455.                   of the window structure)
  456.                   
  457.                  
  458.             eg.  To have the window title pointer returned as a pointer:
  459.                  
  460.                  titleptr = getvalue(win,32,4,'p')
  461.                  
  462.                  say "Window Title Pointer is " d2x(c2d(titleptr))
  463.                  
  464.                  
  465.             eg.  To return the contents of a string gadget:
  466.  
  467.                  specialstringinfo = getvalue(gadgetpointer,34,4,'P')
  468.                  gadcontents = getvalue(specialstringinfo,0,4,'S')      
  469.                  say "Your gad string is" gadcontents
  470.  
  471.  
  472.             eg.  Determining if a gadget is SELECTED:
  473.   
  474.                  if bittst(d2c(getvalue(gadpointer,12,2,'N')),7) = 1 then
  475.                     say "Gadget SELECTED"
  476.                  else
  477.                     say "Gadget NOT SELECTED"
  478.  
  479.                  getvalue(gadpointer,12,2,'N') returns the gadget Flags
  480.                  d2c() converts the result to form 'nnnn'x
  481.                  bittst() test bit 7, the gad select bit.
  482.                  
  483.  
  484.    returns -  the value you specified in the form specified.
  485.               defaults to returning numeric if type not 'N', 'P', or 'S'
  486.               returns NULL ('0000 0000'x) if size not 1, 2, or 4.
  487.               (their is no way to distinguish between returning a valid
  488.                null pointer ('P' type) and error in size)
  489.  
  490.  
  491.    ---------------------------------------- 
  492. <> SETVALUE(ptr,offset,size,type,value,len)
  493.  
  494.    This function allows you to set the value of any parameter in
  495.    any data structure.  Please be very certain about the parameters you
  496.    use in this function.
  497.  
  498.    ptr    - pointer, (ARexx hex string) to any data structure, ie. window
  499.             screen, bitmap, etc.
  500.  
  501.    offset - numeric, specifies the relative position, from the beginning
  502.             of the data structure, of the data value you want to set.
  503.             (see RKM or include '.i' files for offsets)
  504.  
  505.    size   - numeric, specifies the size of the data value you want to
  506.             set.  This value must be either 1, 2, or 4.  Any other
  507.             value will cause the function to return a NULL ('0000 0000'x).
  508.             
  509.    type   - string, either a 'N', 'P' or 'S', this specifies the form 
  510.             of the data 'value' you are passing.
  511.  
  512.             'N' specifies that the value is a numeric.
  513.                 for sizes of 1 and 2 the value is always taken (assumed)
  514.                 to be  a numeric.
  515.  
  516.             If the size is 4 then you can also use (in addition to 'N')
  517.             the following:
  518.  
  519.             'P' specifies that the value you are passing is a pointer.
  520.                 (ie. ARexx hex string)
  521.  
  522.             'S' specifies that the value you are passing is a string.
  523.  
  524.                 VERY IMPORTANT NOTE !!! 
  525.                 When using 'P' or 'S',  'ptr' + 'offset' must result 
  526.                 in an address which contains a pointer to something.
  527.  
  528.  
  529.    len    - numeric, used in conjuction with type 'S', this specifies
  530.             the maximum number of characters to be moved into the 
  531.             area pointed to by the pointer at 'ptr' + 'offset'.  
  532.             If you specify -1 the entire string will be copied into the 
  533.             area pointed to by the pointer.
  534.             
  535.             eg.  You can set the window title string with:
  536.             
  537.                  x = setvalue(windowpointer,32,4,'S',"MY NEW TITLE",-1)
  538.  
  539.                  This statement DIRECTLY modifies the contents of the
  540.                  buffer pointed to by the window title pointer.
  541.                  
  542.                  
  543.            The proper thing to do would be to modify where the window 
  544.            title pointer points.
  545.  
  546.            eg. 
  547.                mynewtitle = ALLOCMEM(length("MY NEW TITLE")+1,'0001 0000'x)
  548.  
  549.                call EXPORT(mynewtitle,"MY NEW TITLE")
  550.  
  551.                x = setvalue(windowpointer,32,4,'P',mynewtitle,0)
  552.                
  553.  
  554.    returns -  1 if successful, otherwise 0 
  555.  
  556.  
  557.       -------------------- 
  558. <>    WINTASKNAME(window)
  559.  
  560.       This function returns the name of the task managing the windows 
  561.       IDCMP port.  This is also the name of the public message port 
  562.       for the window.
  563.       
  564.       Inputs:
  565.       
  566.           window  - pointer to a window opened with OPENWINDOW().
  567.                  
  568.        
  569.       Returns:    - window task name string, ie. 'apig.task.N'
  570.                      
  571.  
  572.  
  573. ----  (Intuition/Graphic Library Functions Added) ----
  574.      
  575. <>   INTUITEXTLENGTH(itext)
  576.  
  577. <>   CLEARPOINTER(window)
  578.  
  579. <>   SETPOINTER(window,pointer,height,width,xoffset,yoffset)
  580.  
  581. <>   SETSOFTSTYLE(rp,style,enable)
  582.  
  583. <>   REMOVEGLIST(window,gadget,numgad)
  584.    
  585.    
  586.  
  587.  
  588. ---- (Exec Library Functions Added) ----
  589.      
  590.      All parameters for these functions must be 'hex-strings'
  591.      
  592. <>   ADDHEAD(list,node)
  593.  
  594. <>   ADDTAIL(list,node)
  595.  
  596. <>   ENQUEUE(list,node)
  597.  
  598. <>   INSERTNODE(list,node,listnode)
  599.      (note name differs, since ARexx has function with the name INSERT )
  600.  
  601. <>   NEWLIST(list)
  602.  
  603. <>   REMHEAD(list)
  604.  
  605. <>   REMOVE(node)
  606.  
  607. <>   REMTAIL(list)
  608.  
  609.  
  610. ---- APIG Library List related functions ----
  611.      
  612. <>   EMPTYLIST(list) - returns 1, if the list is empty, else returns 0
  613.  
  614. <>   LISTEMPTY(list) - same as EMPTYLIST()
  615.  
  616. <>   FIRSTNODE(list,node) - returns 1 if the node is first node in the list
  617.                             else returns 0.
  618.  
  619. <>   LASTNODE(list,node)  - returns 1 if the node is the last node in the list
  620.                             else returns 0.
  621.    
  622.  
  623.  
  624.  
  625. ---------------------------------------------------------------------
  626. ---------------------------------------------------------------------
  627. APIG version 0.1  Released May 18, 1991
  628. ---------------------------------------------------------------------
  629. ---------------------------------------------------------------------
  630.    
  631.  
  632.  Known bugs:
  633.    For some reason Font memory is not returned to the system memory
  634.    pool.
  635.  
  636.  
  637.  
  638.