[gaim-migrate @ 989]

More patches! More patches! :)

1 files changed, 70 insertions, 5 deletions

diff --git a/HACKING b/HACKING
index c14e95f5d0..ea441af68b 100644
--- a/HACKING
+++ b/HACKING
@@ -34,16 +34,68 @@ on in the preferences) whether or not --enable-debug was selected. Most
 of the information that's printed is useless anyway though; so the
 --enable-debug option really doesn't do a whole lot.
 
-This file was last modified by $Author: warmenhoven $ on $Date: 2000-10-09 20:02:02 -0400 (Mon, 09 Oct 2000) $.
+This file was last modified by $Author: warmenhoven $ on $Date: 2000-10-12 05:02:56 -0400 (Thu, 12 Oct 2000) $.
 
 
 PROGRAM FLOW
 ============
 
-This has completely changed since multiple connections were added. Please
-be patient; as soon as the code starts to settle this will get rewritten.
-Most of the source files stayed the same though; only the one that got
-added (multi.c) isn't covered below.
+Before gaim does anything you can see, it initializes itself, which is
+mostly just reading .gaimrc (handled by the functions in gaimrc.c). It
+then draws the login window by calling show_login, and waits for input.
+
+At the login window, when "Accounts" is clicked, account_editor() is
+called. (NOTE: the login window will probably be changed soon.) This
+then displays all of the users and various information about them.
+
+When the "Sign on/off" button is clicked, serv_login is passed the
+username and the password for the account. If the password length is
+zero (the password field is a character array rather than pointer so
+it will not be NULL) then the Signon callback will prompt for the
+password before calling serv_login. serv_login then finds the user,
+and signs in using the specified protocol. (This is a bad way of doing
+things and should be fixed.) We'll assume TOC for the rest of this
+discussion; Oscar has a lot of bad hacks to get it working that I don't
+even want to think about.
+
+After you're signed in (I'll skip that discussion - I doubt many people
+are going to change the login process, since it pretty much just follows
+PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and
+waits for input from two places: the server and the user. The first place
+it gets input from after signon is invariably the server, when the server
+tells Gaim which buddies are signed on.
+
+When there is information ready to be read from the server, toc_callback
+is called (by GDK) to parse the incoming information. On an UPDATE,
+serv_got_update is called, which takes care of things like notifying
+conversation windows of the update if need be; notifying the plugins;
+and finally, calling set_buddy.
+
+set_buddy is one of the most frequently called functions in gaim, one of
+the largest functions in gaim, and probably one of the buggiest functions
+in gaim. It is responsible for updating the pixmaps in the buddy list;
+notifying plugins of various events; updating the tooltips for buddies;
+making sounds; and updating the ticker. It's also called once per online
+buddy every 20 seconds per connection (by GTK through update_all_buddies).
+
+New connections happen the exact same way as described above. Each aim_user
+can have one gaim_connection associated with it. aim_user and gaim_connection
+both have a protocol field; gaim_connection's should be constant once it is
+set in the appropriate (protocol)_login function. There are lots of details
+that are connected with multiple connections that are best explained by
+reading the code.
+
+When the user opens a new conversation window, new_conversation is called.
+That's easy enough. If there isn't a conversation with the person already
+open (checked by calling find_conversation), show_conv is called to
+create the new window. All sorts of neat things happen there, but it's
+mostly drawing the window. show_conv is the best place to edit the UI. Be
+prepared for some incredibly bad GTK programming. (Rob's fixing this as
+we speak no doubt.)
+
+That's pretty much it for the quick tutorial. I know it wasn't much but
+it's enough to get you started. Make sure you know GTK before you get too
+involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.
 
 
 SOURCE FILES
@@ -130,6 +182,19 @@ idle.c:
   a good look at it, but I think what it was supposed to have done is
   set you as being away when a screensaver came on.
 
+multi.c:
+  This is the file that tries to take care of most of the major issues
+  with multiple connections. The best function in here by far is the
+  account_editor(). auto_login() is also in here (I'm just reading
+  multi.h now...); auto_login has problems. Someone please fix it.
+  account_editor is really the only function that the UI needs to be
+  concerned with. If you want to remove multiconnectivity from gaim,
+  all you would really need to do is comment out any lines that make
+  reference to this function (there are only two - one in aim.c and one
+  in buddy.c). The login window UI would have to be changed but it would
+  be simple to take an old version of gaim and copy code (it won't drop-in
+  because there were other changes, but it should be simple to hand-edit).
+
 network.c:
   This has two functions: get_address and connect_address, both of which
   call proxy functions. If you want to see how these are used, look at