----- HACKING THE GUI SOURCECODE -----

(see also the BUGS and TODO files if you don't know what to do ;)


FIRST OF ALL...

don't tell me how bad the code is and/or how much it sucks. I know that, but
honestly I don't care. It works for most people most of the time. Make it better
and send a patch, and I will care ;)




THINGS THAT I WILL _CURRENTLY_ NOT PUT INTO THE GUI (BUT MAYBE LATER):

* Glade: Glade is great, but it adds additional bloat and dependencies
  and I don't like that

* Port to gtk+-2.0: When I wrote the GUI, my goal was (and still is) to
  make it work on as many systems as possible. That was one of the reasons
  why I chose gtk+ and not Qt, as the former is installed on virtually every
  system that has X installed, whereas Qt isn't.
  gtk+-2.0 is great, but currently it is not as widely spread as gtk+-1.2 yet,
  therefore I would like the GUI to be based on gtk+1.2 for the time being.
  However, patches with #if GTK_MAJOR_VERSION that make the GUI compile with
  gtk+-2.0 and/or make it work better with gtk+-2.0 are of course very welcome.

* XML for the config files. This is bloat and absolutely unnecessary for the
  kind of information we have to store and retrieve. Parsing with sscanf() and
  friends is fully sufficient in my opinion ...

* SQL - no, we don't need to store our stats values in an SQL database ;)




STRINGS

* if you write new code, please make use the N_() and _() macros to mark strings
  that need no translation and those which need translation. Example:
  g_snprintf (buf, sizeof(buf)/sizeof(gchar), N_("%u"), number);
  g_snprintf (buf, sizeof(buf)/sizeof(gchar), _("%u apples"), number);




HOW THE CODE IS ORGANISED:

main.c initialises whatever needs to be initialised, then draws the main window
and then hands over control to the gtk event loop.

The stuff that concerns the main window (mainly creation/deletion and drag'n'drop stuff)
is then in mainwindow.c. The notebook is created page-by-page in notebook.c
Each notebook page has its own file (e.g. about_page.c, options_page.c etc.).

Most lists are dealt with in the following way: we have a record for each list
item (different lists have different structures for those records), and keep
all records of a list in a pointer array (GPtrArray). Then there is the visual
representation of that list, which is a gtk clist. The clists are only updated
when necessary.

parse_message.c parses all information coming from the core.

If you can't find the code you are looking for, let me know...



MAIN PROGRAM FLOW:

(Assumption: window is initialised and GUI is connected to a core).

Stuff happens (widgets are manipulated, commands sent to the core) in three cases:

(1) user input
     (a) in form of clicks, text input etc. (dealt with in the bla_page.c files)
     (b) in form of drag'n'drop (dealt with in mainwindow.c)

(2) input from the core (dealt with in parse_message.c)

(3) a timer expires (called every minute, general_update_timer() in main.c)



Happy hacking :)




