Small introduction to helping development of GNOME Clipboard Manager
--===---------------------------------------------------------------

Important
---------
* You must follow the Tao Of Programming if you want to contribute to the Gnome Clipboard Manager.
  You can find a copy of the book here : http://www.terrible.cx/tao/
  Note that you must replace "FORTRAN" with "C" and "COBOL" with "Visual Basic and COBOL".

* You must agree with the following :

  a) In the beginning was the Tao. The Tao gave birth to Space and Time. Therefore Space and
     Time are the Yin and Yang of programming. The Tao gave birth to machine language. Machine
     language gave birth to the assembler. The assembler gave birth to the compiler.  Now there
     are ten thousand languages. Each language has its purpose, however humble.  Each language
     expresses the Yin and Yang of software.  Each language has its place within the Tao. except,
     of course, Visual Basic and COBOL.

  b) The use of COBOL cripples the mind; its teaching should, therefore, be regarded as a criminal
     offense. -- Edsgar Dijkstra
 
  c) Visual Basic is not a programming language.
 
* You are required to have fun while programming. If you do not have fun while programming,
  then don't help us.

* Our development mailinglist; You should subscribe to it :
  http://lists.sourceforge.net/lists/listinfo/gcm-devel

* Try to reduce memoryleaks (duh!) or just don't make them at all.

* If you have CVS commit access frequently update the ChangeLog. If you send
  patches also update the ChangeLog and use cvs diff -u > patchfile.diff. After
  that send patchfile.diff to the development mailinglist with a short description
  about your patch in the Email body. Remember to ALWAYS use the unified diff format.

* Try to be consitent with the GUI, function/struct/etc -names in the source and comment
  your code.
  
* Comment keywords :
  /* todo: */   Indacates that it is on your todo list
  /* fixme: */  Indicates that there is a bug here
  /* Future: */ An idea for a future release
  /* help: */   Request for help in the source
  
The (for me) obvious stuff
--------------------------

1. All (or most) widgets on a window are in it's struct. For example the MainWin is
a struct (in mainwin.h) wich has some children. All buttons and objects (children) that
are located on the MainWin can be reached using it's struct. All windows are a GNOME widget
which you can access using a MACRO (example GNOME_MAINWIN() for the mainwin) Example how
to get the pointer to a button on the toolbar of the mainwin : mwin->toolbar_edititem.


2. All callbacks have a pointer to the main widget where the object that generated the signal
is located. For exmaple :

MainWin *mwin;
...
g_signal_connect (G_OBJECT (mwin->toolbar_edititem), "clicked",
                      G_CALLBACK (on_toolbar_edititem_clicked),
                      mwin);

This is the signal_connect for the "on edititem button clicked" in the mainwin.
mwin is the GtkWidget of the MainWin and we pass a pointer to the callback. In
the callback you can reach each object on the mainwin using (1).

3. All windows have a pointer to their windowparent. This is the widget that called the
window. The only exeption is the MainWin which has a pointer to itself (check main.c
vs. mainwin.c). This way each window can reach each object in the application using
the MACRO's explained in (1). For example, if you want to touch a button in the mainwin
from the textitemwin then you could use GNOME_MAINWIN(twin->windowparent)->toolbar_edititem
where twin is the GtkWidget that presents the TextItemWin.

4. All windows have a function called windowname_new(GtkWidget *windowparent). This
function creates a new window of the type windowname. Some windows (like the
textitemwin) can be created more then once while some can only be created once
(example : the newitemwin can only be created once). This is because in the mainwin
struct there is a GtkWidget defined to hold the newitemwin. If this widget is 
already created then the function will nolonger create a new one but instead use
the one that was already created.

5. There are a several structs which hold your data. An item/Selection is a struct
that holds information about one item in the clipboard shelf. A SaveAsData is
a struct that holds some information about "what and where to save the selected
items". All data-holding structs have a "free" function. For example selection_free()
and saveasdata_free(). These MUST be used when the data is nolonger needed.
Note that all structs are passed ByRef so it's not always nessesairy to free the
data.

6. All preferences are saved using GConf in a struct called Prefs. This struct
holds all information that was loaded from GConf and is used in the application.
We never use values from GConf directly. There is a function called reload_prefs()
that should be called each time preferences need to be reloaded.
Steps to add a new preference :
	- Add it to the GUI of the preferences window
	- Checkout the function prefswin_getprefs in prefswin.c
	- Checkout the function getprefs_fromfile in mainwin.c
	- Checkout the function reload_prefs() in mainwin.c
	- Checkout the function saveprefs_tofile in mainwin.c
	- Use mwin->prefs in the application. This struct holds the preferences.

7. The function app_update_menus() updates the menu's. Use it when needed
and make sure that menu's and buttons are set unsensitive when they should
not be used anylonger. (located in mainwin.c).



The tree (unimportand and obvious files are ignored)
----------------------------------------------------
|-- AUTHORS									A file with some information about the AUTHORS and contrubutors
|-- COPYING									The GPL
|-- ChangeLog								The ChangeLog

|-- GNOME_Clipboard_Manager.desktop.in		The desktopentry file
|-- GNOME_Clipboard_Manager.glade			A glade file generated by Anjuta
|-- GNOME_Clipboard_Manager.prj				The project file used by Anjuta
|-- GNOME_Clipboard_Manager.pws				A file used by Anjuta
|-- HACKING -> doc/HACKING					A symlink to this File
|-- INSTALL									HOWTO Information for the users to install gcm
|-- Makefile.am								The main Makefile.am used by automake to generate a Makefile
|-- NEWS									The NEWS file
|-- README									The README file
|-- TODO									A TODO list for developpers and others
|-- configure.in							The main configure.in file used by automake to generate a configure script
|-- gnome_clipboard_manager.desktop			A file used/generated by Anjuta
|-- gnome_clipboard_manager.desktop.in		A file used/generated by Anjuta
|-- gnome_clipboard_manager.glade			A file used/generated by Anjuta

|-- doc
|   |-- HACKING								This file
|   |-- Makefile.am							Makefile.am for the documentation
|   |-- Makefile.in							Used by automake
|   |-- advanced.html						User manual for advanced useage
|   |-- faq.html							The FAQ
|   |-- index.html							The intropage of the documentation
|   |-- installing.html						Documentation about how to install GCM
|   `-- using.html							Documentation about how to use GCM

|-- glade
|   |-- README								Some info for developpers using Glade
|   |-- aboutwin.glade						The GUI of the aboutwin
|   |-- dataitemwin.glade					The GUI of the (unused) dataitemwin
|   |-- mainwin.glade						The GUI of the mainwin
|   |-- newitemwin.glade					The GUI of the newitemwin
|   |-- prefswin.glade						The GUI of the prefswin
|   `-- textitemwin.glade					The GUI of the textitemwin

|-- pixmaps									Some (custom) pixmaps used by the GUI
|   |-- bfoldc.xpm
|   |-- bfoldo.xpm
|   |-- file_file.xpm
|   `-- new_folder.xpm

|-- po										The translation files
|   |-- ChangeLog							ChangeLog fot the translation files
|   |-- GNOME_Clipboard_Manager.pot
|   |-- Makefile.in.in
|   |-- POTFILES.in
|   |-- cat-id-tbl.c
|   |-- gnome_clipboard_manager.pot
|   |-- nl.gmo
|   |-- nl.po								Dutch translation by freax
|   `-- stamp-cat-id

|-- src
|   |-- Makefile.am							The Makefile.am for the source files
|   |-- Makefile.in
|   |-- config.h.in							This file will generate config.h; a file included in
|   |										all .c files (so this config can be used everywhere)
|   |-- main.c								Inits GConf and the mainwin
|   |-- main.h
|   |-- mainwin.c							The mainwin widget
|   |-- mainwin.h
|   |-- newitemwin.c						The widget to create a new item
|   |-- newitemwin.h
|   |-- prefswin.c							The preferences-window widget
|   |-- prefswin.h
|   |-- textitemwin.c						The "Edit" window widget
|   |-- textitemwin.h
|   `-- .._callbakcs.c/h					All Windows have a callbacks file containing it's callbackfunctions
|-- dist									Distrubution files (packages, diffs, etc)
|   |-- README
|   |-- bsd
|   |   `-- README
|   |-- debian
|   |   `-- README
|   |-- mdk
|   |   `-- README
|   |-- redhat
|   |   `-- README
|   `-- suse
|       `-- README


-- 
The wise programmer is told about Tao and follows it.  The average
programmer is told about Tao and searches for it.  The foolish programmer is
told about Tao and laughs at it.

If it were not for laughter, there would be no Tao.

The highest sounds are hardest to hear.  Going forward is a way to retreat. 
Great talent shows itself late in life.  Even a perfect program still has
bugs.
