ADDITIONS

                          API Additions to Widgets
                          ========================
                          
                          


When designing Widgets, the idea is to provide a full set of API's to allow
developers to manipulate it.  Sometimes, new API's may need to be added if 
the initial implementation of some Widget didn't implement a complete set.

Everybody always wants their favorite function implemented in the library, 
because it would make *their* job easier.  Thus, the temptation exists to keep 
adding ``useful'' little functions, just to satisfy everybody.

There are several reasons why this is a bad idea:


  - Lots of small ad-hoc functions will make a Widget much harder for
    everybody to learn.

  - Since a Widget implements a certain abstraction, adding lots of functions
    will make it harder to maintain the simplicity of the abstraction.

  - Lots of functions will also make it more difficult to keep the software
    implementation consistent.

  - It will make it harder to reach a point of ``closure'' i.e. one keeps
    adding things, instead of attaining completeness.


To curb wild-growth in API's, we prefer to add API's judiciously.  In order for 
a function to be added to the library, one should demonstrate:


  - That the utility of this new function appeals to a large audience.
  
  - The function fills a real gap in functionality.

  - The function adds functionality that existing API's are unable to provide.

  - The new function does not break the abstraction that the Widget provides.

  - Appropriate rationale for its inclusion can be given. [This has to be a
    better argument than: ``Because I need it!''].


Goals for Widget API's should be:


  1) Orthogonality.  This augments transferability of knowledge from one
     situation to the next.

  2) Predictability.  Naming should strongly reflect function.  Functions
     should have no side-effects not reflected in the name; preferably,
     one function should do one thing only.

  3) Symmetry.  This means for example every ``set'' function should have a
     corresponding ``get,'' every ``open'' should have a ``close'' and so on.

  4) Completeness.  All parameters can be accessed, and all features of the
     Widget can be used, without any need for backdoors etc.

  5) Minimality.  A set of API's is minimal if one can not take away anything
     without making the API incomplete.  Minimality makes it much easier to
     maintain consistent state in the Widget.

  6) Philosophical fit.  The FOX library has been developed with certain
     underlying paradigms, both in concept as well as in implementation; API's
     should adhere to these, as deviation from them will make things less
     easy to understand, or less easy to extend.

  7) Wide Appeal.  When convenience API's are added, it must be true that these
     functions have broad appeal, i.e. expected to be used by a large fraction 
     of the library's users.