===========================================================================
                      quickref for Niceline routines
                  (function names in alphabetical order)
===========================================================================

ù nice_chk_object(tree%,obj)
  --------------------------
  checks if the object pointed to by tree%,obj& 
  really IS a Niceline object.
  --> tree%  pointer to the objecttree
      obj&   number of the object
  <-- TRUE   object is a Niceline object
      FALSE  object is something else


ù nice_count_lines(tree%) 
  -----------------------
  function counts the number of objects in objecttree tree% 
  that can/will be replaced by Niceline objects.
  Objects counted have:
    - OB_TYPE is G_STRING (value 28 in lower byte)
    - OB_SPEC pointing at string beginning with "-"
    - OB_STATE bit #3 set (disabled)
  --> tree%  pointer to the objecttree (usually a menu)
  <-- number of objects that can be converted to Nicelines
  uses function obj_get_last()


ù nice_get_global_colors(VAR col1,col2)
  -------------------------------------
  returns in both parameters col1& and col2& the GLOBAL colors 
  set for the first and second line to be drawn. These GLOBAL 
  colors are used for Niceline objects that have no LOCAL colors
  set. (high byte of OB_STATE is 0)
  --> two word variables that will be filled
  <-- FALSE object is not a Niceline object
      TRUE  global colors in col1& and col2&
            (a value of 0 for either col1& or col2& means this
             line will NOT be drawn)


ù nice_get_local_colors(tree%,obj,VAR col1,col2)
  ----------------------------------------------
  returns in both parameters col1& and col2& the LOCAL colors
  set for the first and second line to be drawn. These LOCAL
  colors are used ONLY for the Niceline object pointed to by
  tree%,obj&. (local colors are stored in the high byte of 
  the objects OB_STATE word)
  --> tree%  pointer to the objecttree
      obj&   number of the object
      two word variables that will be filled
  <-- FALSE object is not a Niceline object
      TRUE  global colors in col1& and col2&
            (a value of 0 for either col1& or col2& means this
             line will NOT be drawn)


ù nice_get_style(VAR topline%,bottomline%)
  ----------------------------------------
  returns in parameters topline% and bottomline% the style in 
  which the lines are drawn. Only the lower 16 bits are used,
  where each bit set means a pixel is drawn. Since we need
  ALL 16 bits (UNsigned words), topline% and bottomline% are
  of type LONG integer (%). Using Gfa WORDS (&) leads to error-
  message 4: 'Not Word -32768 .. 32767'
  --> two LONG integer variables
  <-- LONG value both lines combined or 0 (=error)


ù nice_init(tree%)
  ----------------
  this function is called by procedure nice_on(), if it finds no
  working array (nline%()). You are ofcourse allaowed to call it
  yourself. It creates a working array, and fills the essential
  values in the assemblerroutine niceline%.
  --> tree%  pointer to the objecttree (MENU(-1))
  <-- number of objects found to be converted to Nicelines
  uses function nice_count_lines()


ù nice_off(tree%)
  ---------------
  Switches Niceline-drawing off, restores converted objects to
  their original types (OB_TYPE=28, OB_SPEC points to the string)
  It also erases the working array nline%()
  --> tree%  pointer to the objecttree (MENU(-1))
  <-- nothing
  uses function obj_get_last()


ù nice_on(tree%)
  --------------
  Switches Niceline-drawing on, converts OB_STATEs from 28 (G_STRING)
  to &H1C18 (high-byte=28, low-byte=24=G_PROGDEF), sets OB_SPECs to
  point to the working array nline%() and fills this array with the
  values needed for AES. 
  nline%() is the routine's APPLBLK, where for each object, the first
  LONG value is a pointer to the drawing routine held in the INLINE, 
  and the second LONG value holds the objects old OB_SPEC.
  If needed, it calls function nice_init(), so in fact all you have to
  do if you want nicelines, is to call this procedure.
  --> tree%  pointer to the objecttree (MENU(-1))
  <-- nothing
  uses function obj_get_last()


ù nice_set_global_colors(col1,col2)
  ---------------------------------
  Sets the GLOBAL colors to be used for the first and second line
  for all Niceline objects that have no LOCAL colors. 
  (high byte of OB_STATE is 0)
  --> two word variables containing the colors (0-15)
  <-- FALSE object is not a Niceline object
      TRUE  global colors in col1& and col2& are set


ù nice_set_local_colors(tree%,obj,col1,col2)
  ------------------------------------------
  Sets the LOCAL colors to be used for the first and second line
  ONLY used for the Niceline objects pointed to by tree%,obj& 
  (colors are packed into high-byte of the objects OB_STATE)
  --> tree%  pointer to the objecttree
      obj&   number of the object
      two word variables containing the colors (0-15)
  <-- FALSE object is not a Niceline object
      TRUE  local colors in col1& and col2& are set


ù nice_set_style(topline%,bottomline%)
  ------------------------------------
  Sets the style in which the lines are drawn according to the
  lower 16 bits of parameters topline% and bottomline%.
  Each bit set means a pixel is drawn. Since we need
  ALL 16 bits (UNsigned words), topline% and bottomline% are
  of type LONG integer (%). Using Gfa WORDS (&) leads to error-
  message 4: 'Not Word -32768 .. 32767'
  --> two LONG integer variables
  <-- LONG value both lines combined holding the FORMER
      linestyles or 0 (=error)


ù vdi_paramblk
  ------------
  A function to create a VDI-parameterblock needed by the Niceline
  drawing routine. 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. 
  --> nothing
  <-- address of the 20 byte parameterblock (=V:vdipb%(0))

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