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.