src/frontends/xforms/forms/README

   1 All .fd files go in this directory.
   2 Each .fd file should have just one form in them
   3
   4 NOTE: An exception to the above is any tabbed form which
   5       xforms requires multiple forms to create.  In that case
   6       the group of forms constitutes one gui form.
   7
   8 All forms should be named form_xxx and saved into a file by the same name.
   9 For example, the copyright notice is called form_copyright and is stored in
  10 form_copyright.fd.  Its used by class FormCopyright.  If you match this pattern
  11 the fdfix.sh script will do all the conversions for you.  That'll make
  12 updating the source incredibly easy.
  13
  14 Name all buttons and other form components that are likely to cause a callback.
  15 The names should be of the form:  button_ok, radio_group_item and so on.
  16
  17 Being more explicit (Angus, 12 Mar 2002):
  18         class             | prefix
  19         ------------------+-------
  20         FL_BROWSER        | browser
  21         FL_BUTTON         | button
  22         FL_PIXMAPBUTTON   | button
  23         FL_CHECKBUTTON    | check
  24         FL_CHOICE         | choice
  25         FL_COUNTER        | counter
  26         FL_DIAL           | dial
  27         FL_INPUT          | input
  28         FL_FRAME          | frame
  29         FL_LABELFRAME     | frame
  30         FL_ROUND3DBUTTON,
  31         RADIO_BUTTON      | radio
  32         FL_SLIDER         | slider
  33         FL_VALSLIDER      | slider
  34         FL_TABFOLDER      | tabfolder
  35         FL_TEXT           | text
  36
  37 The only exceptions to this are objects that are to be converted in the sed
  38 scripts. At the moment this applies only to bmtable:
  39
  40         Convert an FL_BUTTON to a FL_BMTABLE by using prefix "bmtable".
  41
  42 Enter the full name of the callback eg.:
  43         C_FormBaseOkCB
  44
  45 That is, they all have the same format: C_##FormName##CallbackName.
  46 Your code will then need to use the appropriate macro to setup this C callback
  47 function which will in turn call the corresponding static class member function
  48 of the form FormName::CallbackName.  You should be able to copy the macro
  49 entries from a similar dialog for reuse without having to change anything.
  50
  51 The name of the wrapped dialog will be dialog_ eg.
  52         typedef struct {
  53         ...
  54         } FD_form_copyright;
  55
  56         FD_form_copyright * dialog_;
  57
  58 Angus Leeming has modified the scripts to forward declare FD_form_xxxx thereby
  59 removing one inter-file dependency and removing the struct declaration from the
  60 FormXxxx.h file which was the previous practice.
  61
  62 If you follow these simple rules then the generated code for create_form_form_xxxx
  63 can will be converted as the FormXxxx::build_xxxx method without any extra
  64 editting to make it work.  Every forms implementation will thereby follow a very
  65 simple pattern and make it easier to maintain.
  66
  67 All the forms are rebuild by running `make test`.  This will generate all
  68 the form_xxxx.[Ch] files. You should run `make updatesrc` to install them in the
  69 parent directory.  `make updatesrc` will also regenerate all the files for you
  70 so you don't have to do the `make test` step unless, for example, you are
  71 testing the conversion scripts. The files fdfix.sh, fdfixc.sed, fdfixh.sed and
  72 makefile contain the necessary smarts to convert the generated code into
  73 something that can be used directly in the LyX codebase.
  74
  75 The easiest way to fit into the pattern is to copy an existing dialogs
  76 implementation and adjust it to suit, keeping the variable names the same.
  77 Take a look at the existing .fd files as well to see what is needed in there
  78 in the way of callback names and widget names.
  79
  80 In addition a lot of work can be saved by using the code that has already been
  81 written in the "lyx" module of the LyX CVS repository. This is where the old
  82 development branch is kept.  The code there will need to be modified slightly
  83 to meet these new guidelines.  In addition, an earlier generation signalling
  84 system was used in that code. A conversion script called gtkmmconvert2 is
  85 available from the gtk-- distribution.  It updates all the signals to use
  86 libsigc++.
  87
  88 Don't reinvent the wheel.  There's 18 months worth of code in the "lyx" cvs
  89 module that you should at least use as a guide even if you don't actually make
  90 direct use of it.
  91
  92 Allan. (ARRae)