sample/libtui/doc/EXPANDING

   1 Tui New Widget Guide
   2 Copyright Mike Glover, 1995, 1996, 1997, 1998, 1999
   3 -------------------------------------------------------------------------------
   4
   5 If you want to create a new widget for Tui, and want it in the standard
   6 dist of Tui, you will have to follow some requisites that I have. I state
   7 these because Tui has been worked on for quite some time and I finally
   8 got it to a state where the functions calls are somewhat consistent. Any new
   9 widgets should adhere to this. The requirements are as follows:
  10
  11         * The function names should be like:
  12         newTUIXXX, destroyTUIXXX, setTUIXXX, drawTUIXX,...
  13         Any widgets with functions not in this format should be 'private'.
  14         If this is not the case one of three things will happen:
  15                 1) The widget will not get accepted
  16                 2) I will mail you back asking you to follow the standards.
  17                 3) I will do it myself. (HIGHLY unlikely)
  18
  19         * The first parameter of the newTUIXXX function should be of type
  20           TUISCREEN.
  21         * If applicable, the next two parameters should be xpos and ypos in
  22           that order.
  23         * If applicable, the next two parameters should be the height and
  24           width of the widget.
  25         * If the widget has a title, the next parameter should be a char *
  26           for the title.
  27         * If the widget has a label, the next parameter should be a char *
  28           for the label.
  29         * The last two parameters of the newTUIXXX function should be:
  30           Boolean box, Boolean shadow if the parameters apply.
  31         * The drawTUIXXX function should only have the pointer to the object and
  32           a Boolean box as it's parameters. (in that order)
  33         * The first parameters of any other function relating to the widget
  34           should be a pointer to the widget type. ie: TUIRADIO *, TUIFSELECT *...
  35         * A destroyTUIXXX function has to be provided as well as a drawTUIXXX
  36           function.
  37         * Try to contain anything specific to the widget in a single file. This
  38           keeps the overhead of misc. files from floating around.
  39         * Create a standalone header file which includes tui.h if needed.
  40
  41 If you follow the guidelines, then the files you need to change to sew the new
  42 widget into Tui, are:
  43
  44         tuiscreen.c     So this widget will get refreshed on a refreshTUIScreen
  45                         function call.
  46         binding.c       To allow key bindings for the widget. If it is possible
  47                         to have key bindings I stress that this be incorporated.
  48         tui.h           To add in the function def's to the header file. (ie:
  49                         include the newly created header file.)
  50         Makefile        Add in the new widget files.
  51
  52 If you have done all of this then what I need from you is the following:
  53
  54         * A diff of all the files from the dist. that you modified. Use
  55         patch, I prefer it. If you haven't got it, get it and use it. It makes
  56         life easy.
  57         * A copy of the new widget file.
  58         * tar this up and send it to me at
  59         glover@credit.erin.utoronto.ca or at mike@vexus.ca
  60         I will mail you back when I get it and I will tell you if everything is
  61         OK or not.
  62
  63 I hate to be such a nit pick, but if we follow the above standards, Tui will
  64 evolve into a very nice library, with a lot of really nice widgets.
  65
  66 If you want to get a hold of me mail me at one of the following:
  67         glover@credit.erin.utoronto.ca
  68         mike@vexus.ca
  69
  70 The TUI Web page has several homes. They are:
  71         http://www.vexus.ca/TUI.html (official)
  72         http://www.datasoft.on.ca/~tui (Sponsored by the nice folks at Datasoft)
  73
  74
  75 ttfn,
  76         Mike