===========================================================================
                 quickref for XRSC and XRSC+ routines
                (function names in alphabetical order)
===========================================================================

 vdi_paramblk
  ------------
  A function to create a VDI-parameterblock needed by the CICON_24 or
  the DRAWCICN drawing routines. 
  To save on memory, this routine does not reserve memory for the CONTRL, 
  INTIN, PTSIN etc. arrays, but uses those already present in your 
  GfA program. 
  This function was also used for NICELINE
  --> nothing
  <-- address of the 20 byte parameterblock (=V:vdipb%(0))


 xrsc_chg_obtype(xheader%,oldtype,newtype)
  -----------------------------------------
  with this function you can change ALL objects in the resource
  with OB_TYPE=oldtype& into objects OB_TYPE=newtype&
  --> xheader% address of extended resource header
      oldtype& look for any object with this OB_TYPE word
      newtype& convert oldtype& objects into this
  <-- number of objects converted


 xrsc_cicon2progdef(xheader%,cicondraw%)
  ---------------------------------------
  changes ALL G_CICON objects within the resource to G_PROGDEF objects,
  with the high byte of their OB_TYPE word = 33.
  Also it creates a working array ub_cicon%() and fills it with the values
  needed when AES meets an object like this on OBJC_DRAW().
  (this array is the program's APPLBLK)
  You need this function if you decide to draw color icons, using the
  CICON_24.INL, not when you draw them using DRAWCICN.INL.
  --> xheader%    extended resource header, created with xrsc_fix()
      cicondraw%  the address of the drawing routine (CICON_24.INL+10)
  <-- the number of objects changed


 xrsc_cicon_config(newcfg)
  -------------------------
  a function with which you can decide how the DRAWCICN() or CICON_24()
  routine draws a color icon when in either SELECTED or DISABLED state:
  --> newcfg& =-1: inquire configuration, don't set
              =>0: bitmap (currently only uses lower 2 bits)
                   bit 0=0 --> darken icon if selected (like Interface)
                   bit 0=1 --> invert icon if selected
                               this bit 0 is only effective when the
                               color-icon has no selected data to draw
                   bit 1=0 --> disable whole square (like Interface)
                   bit 1=1 --> disable icon-shape only, when background is
                               white or filled with pattern 2, style 4
  <-- FORMER setting


 xrsc_cicon_init(ciconroutine%,cicon_cfg)
  ----------------------------------------
  fills the first ten bytes of the assembler drawing routine in the
  INLINE. This procedure MUST be called quite early in your program
  if you want to use the DRAWCICN() or CICON_24() routine
  --> ciconroutine% the starting address of the INLINE
      cicon_cfg&    a bitmap, telling the routine how to draw
                    (see description of xrsc_cicon_config())
  <-- nothing


 xrsc_draw_cicon(tree%,obj)
  --------------------------
  draws the color icon pointed to by tree%,obj&
  Using this procedure in stead of OBJC_DRAW() will ensure
  the icon IS drawn, regardless of the AES-version of the machine.
  This procedure holds the GfA code for drawing.
  MUCH faster is the assembler routine in DRAWCICN.INL, which
  simply is called: ~C:drawcicn%(L:tree%,W:obj&)
  If you decide to use CICON_24.INL, there is no need to install
  this function, because AES will jump to the drawing routine.
  --> tree%  pointer to the objecttree
      obj&   number of the object
  <-- nothing


 xrsc_draw_tree(tree%,clipx,clipy,clipw,cliph)
  ---------------------------------------------
  should be used in stead of OBJC_DRAW() if you want a tree drawn,
  containing color icons, using the DRAWCICN.INL.
  It tests for OB_TYPE 33 (G_CICON) and if found, calls the routine
  to draw these objects.
  This procedure always CLIPS using clipx&, clipy&, clipw& and cliph&.
  Not needed when you use CICON_24.INL.
  --> tree%  pointer to the objecttree
      clipx& .. cliph&  are the dimensions of the bounding rectangle
                        in which can be drawn.
  <-- nothing


 xrsc_fix(rsc%)
  --------------
  This procedure creates a new, extended resource header array xrsh%()
  and fixes the resource pointed to by parameter rsc%. It fixes both
  addresspointers and coordinates, the latter using GLOBAL charw& and 
  charh& variables. (obtained by ~GRAF_HANDLE(charw&,charh&,d&,d&))
  As a bonus, this routine will patch any OBLAST and/or OB_H errors
  found in the resource.
  --> rsc% is the address of the loaded or INLINEd 'raw' resource file
           in memory. Once a resource is 'fixed' you should remember
           this and NEVER fix it for a second time. This procedure
           will NOT remember it for you !!
  <-- nothing


 xrsc_gaddr(type,index,xheader%,VAR adr%)
  ----------------------------------------
  this function replaces RSRC_GADDR() and has one extra type& value
  included: type&=17, which will fill parameter adr% with the address
  of a CICONBLK.
  --> type&  decides what address to calculate (like RSRC_GADDR())
      index& the INDEX number of the object or tree 
             (this is the order in which the trees/objects are stored
             in the resource file, NOT the 'normal' objectnumber)
      xheader%  the address of the extended resource header, created
             by xrsc_fix()
      adr%   this LONG will contain the wanted address after the call
  <-- 0: no errors; parameter adr% has a VALID value
      1: error; parameter adr% is empty, object (type) does NOT exist


 xrsc_load(rscfile$)
  -------------------
  This function replaces RSRC_LOAD().
  It allocates memory for the resource file, loads it, calls xrsc_fix()
  and returns the address of the extended header (=V:xrsh%(0))
  --> rscfile$ holds the FULL path and filename for the resource
  <-- the address of the extended header or 0 (=error, file not found)


 xrsc_progdef2cicon(xheader%)
  ----------------------------
  changes ALL objects back from G_PROGDEF to G_CICON and reinstalls the
  original OB_SPECs.
  the function expects OB_TYPE=&H2118 (high-byte=33, low-byte=24), as set
  with function xrsc_cicon2progdef()
  --> xheader%    extended resource header, created with xrsc_fix()
  <-- the number of objects changed


 xrsc_set(xheader%)
  ------------------
  function sets some values of the loaded and fixed resource into GEM's
  GLOBAL array. You only need this if you're planning on using standard
  AES functions RSRC_GADDR() and RSRC_SADDR().
  It is much better NOT to use those, but xrsc_gaddr() instead, because
  an older AES-version machine (<3.30) will not be able to RSRC_GADDR()
  beyond 64 Kb !
  --> the address of the extended header, created by xrsc_fix()
  <-- nothing


===========================================================================
                    Theo Ros   (theo.ros@rnw.nl)
===========================================================================

