doc/DEVEL

   1 -*-outline-*-
   2
   3 This is the developers' hint guide.
   4 Some parts are based on mail messages.
   5
   6 Please feel free to add your name to this list:
   7 by Miguel de Icaza
   8
   9 * Working with the Midnight Commander
  10
  11    If you plan on working on the Midnight Commander, here are some
  12    tips on how to make your development easier and my job of merging
  13    your code easier, I find them useful.
  14
  15 o  Run make depend if you modify the source code structure (e.g. you
  16    add/remove include files).  This is very important, it will help you
  17    to get an accurate compilation.
  18
  19 o  It's recommended that you use GNU Make (if you want to use the
  20    depend feature).
  21
  22 o  I work with the tags feature of GNU emacs.  Run the make tags
  23    command to get an updated TAGS file.  The command Alt-. will take
  24    you to any function or variable definition.
  25
  26 o  Try to keep the indenting style as it is currently.  Normally if you
  27    just created a new file with a different coding style, run the GNU
  28    indent program on it (remember to make a backup copy first) like
  29    this: indent -kr -i4 -psl -pcs filename.c
  30
  31 o  This code is distributed under the GNU General Public License and
  32    Keep this in mind when adding code to the program.
  33
  34 * Code structure.
  35
  36    The program uses extensively the dialog manager written by Radek
  37    Doulik.  To understand how the dialog manager works, please read
  38    the dlg.c and dlg.h.  You will find the basic widgets in the file
  39    widget.c and the widget.h file.  If you understand this two files,
  40    you are done.  The files option.c and boxes.c contain some examples
  41    of how the dialog manager functions are used.  For a more complete
  42    example, take a look at the main.c file.
  43
  44    The file util.c has a lot of utility functions.  Get familiar with
  45    them, they are very simple.
  46
  47    The code has almost no hardcoded limits, there are a lot of ways of
  48    avoiding them.  For example, when you want to concatenate strings,
  49    use the g_strconcat functions, it is used like this:
  50
  51         new_text = g_strconcat (username, " ", password, NULL);
  52
  53    This mallocs the required area, so it still needs to be freed.
  54
  55 * Upcoming changes.
  56
  57 * Panels
  58
  59 * Input handling
  60
  61 The routines for input handling on the Midnight Commander are:
  62 getch, get_key_code, mi_getch and get_event.
  63
  64 getch is an interface to the low level system input mechanism.  It
  65 does not deal with the mouse.
  66
  67     In the case of ncurses, this is a function implemented in the
  68     ncurses library that translates key sequences to key codes (\E[A to
  69     something like KEY_UP and so on).
  70
  71     In the case of S-Lang there is no such conversion, that's why we
  72     load a set of extra definitions.
  73
  74 The get_key_code routine converts the data from getch to the
  75 constants the Midnight Commander uses.
  76
  77     In the case of S-Lang, it will actually do all the jobs that getch
  78     does for curses.  In the case of curses it patches a couple of
  79     sequences that are not available on some terminal databases.  This
  80     routine is the one you want to use if you want a character without
  81     the mouse support.
  82
  83 get_event is the routine you want to use if you want to handle mouse
  84 events, it will return 0 on a mouse event, ERR if no input is
  85 available or a key code if there is some input available.  This
  86 routine in turn uses get_key_code to decode the input stream and
  87 convert it to useful constants.
  88
  89 mi_getch is just a wrapper around get_event that ignores all the mouse
  90 events.  It's used only in a couple of places, this routine may return
  91 ERR if no input is available (if you have set the nodelay option of
  92 ncurses or S-Lang with nodelay) or a character code if no such option is
  93 available.
  94
  95 * Mouse support.
  96
  97 The mouse support in the Midnight Commander is based on the get_event
  98 routine.  The core of the mouse event dispatching is in the
  99 dlg.c:run_dlg routine.
 100
 101 * ncurses
 102
 103 Althougt S-Lang is now used by default, we still support it ncurses.  We
 104 basically are using a small subset of ncurses because we want to be
 105 compatible with Slang.
 106
 107
 108 * The Dialog manager and the Widgets
 109
 110 ** Button widget
 111
 112 ** Check box widget
 113
 114 ** Radio widget
 115
 116 ** Input widget
 117
 118 ** Listbox widget
 119