annotate plugins/SIGNALS @ 133:e277d5f0c1dd

[gaim-migrate @ 143] Let's see if I can remember everything I did: - Fixed a bug I let slip. If you choose the new option to not play login sounds when you log in, and then quit before the timeout is up, it would save that you didn't want login sounds at all. - Added two new plugin events: event_away and event_buddy_away. - Made GtkWidget *imaway in away.c and void play(uchar *, int) in sound.c not static any more (though not referenced in gaim.h). This is so plugins can use those (and not have to worry about writing their own sound code). - Wrote a quick plugin to auto-iconify windows when you go away. I had just been locally patching my own copy, since I figured it wasn't worth including as an option. It also demonstrates some of the issues of deciding between USE_APPLET and not. Perhaps plugins are the way to go with some things that would otherwise have been options (for example, the Lag-O-Meter is one of those things that could possibly have been a plugin instead of hard-coded in). I think that's everything. committer: Tailor Script <[e-mail]>

enum gaim_event {
	event_signon = 0,
	event_signoff,
	event_away,
	event_im_recv,
	event_im_send,
	event_buddy_signon,
	event_buddy_signoff,
	event_buddy_away,
	event_blist_update
};

To add a signal handler, call the fuction gaim_signal_connect with the
following arguments:

void *, enum gaim_event, void *, void *

The first arg is the handle that was passed to gaim_signal_init. You did
	save it, right?
The second arg is hopefully obvious.
The third arg is a pointer to a function that takes various args
	depending on which event you're dealing with.
The fourth arg is any data you want to send to your function, as a final
	argument.

To remove a signal handler, call the function gaim_signal_disconnect with the
following arguments:

void *, enum gaim_event, void *

The first arg is the handle that was passed to gaim_signal_init.
The second arg is hopefully obvious.
The third arg is a pointer to the function you attached.

Note that it deletes *all* functions matching the function you pass, not just
one. Sorry, that's just the way it works.

So here are the args that get passed to your functions in various events:

event_signon:
	(none)

	Note that you can get the username (which would probably be the only
	useful information here) from other places. (Read gaim.h for details).

event_signoff:
	(none)

event_away:
	(none)

event_im_recv:
	char **who, char **text

	'who' is the username of the person who sent the message.
	'text' is the actual strict text (with HTML tags and all) of the
		message they sent.
	
	Note that you can modify these values. (You are encouraged to do so!)
	Note that *other* plugins can also modify these values, so you should
	check that they are not NULL, and try not to leave them as NULL.

event_im_send:
	char *who, char **text

	'who' is the username of the person you're sending the message to.
	'text' is the actual strict text (with HTML tags and all) of the
		message you're sending.

	Note that you can modify outgoing text. (You are _not_ encouraged to
		do so ;-) .)

event_buddy_signon:
	char *who
	
	'who' is who signed on.

event_buddy_signoff:
	char *who

	'who' is who signed off.

event_buddy_away:
	char *who

	'who' is who went away.

event_blist_update:
	(none)
	
	This event is called when the buddylist is updated (automatically every
	20 seconds)