Mercurial > pidgin.yaz
annotate plugins/HOWTO @ 314:f6183455b855
[gaim-migrate @ 324]
Sha na na na, na na na na, hey hey hey, go-od bye
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Fri, 02 Jun 2000 15:50:03 +0000 |
parents | e8dae982b37c |
children | be408b41c172 |
rev | line source |
---|---|
93 | 1 Ok, this howto is going to be really short and sweet and to the point. |
2 | |
3 First off, before you do anything else, in all of the files for your plugin, | |
4 put the lines | |
5 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
6 #define GAIM_PLUGINS |
93 | 7 #include "gaim.h" |
8 | |
9 I mean this. Without this, all kinds of things will not work correctly. If you | |
10 really want to know exactly what this does, read ../src/gaim.h and learn. But | |
11 if you don't want to do that, just know that it's important. | |
12 | |
13 Now that you've put that there, make sure gaim.h is in your include path. | |
14 | |
15 Ok, now you're ready to write the plugin. | |
16 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
17 The only function that is required is gaim_plugin_init(void *). This gets |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
18 called as soon as it gets loaded (sort of - man dlopen for more details). If |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
19 your function never returns, it will crash gaim! If your plugin uses up all |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
20 the memory in the system, it will crash gaim! Once your plugin gets loaded, |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
21 it effectively becomes a part of gaim, and anything that goes wrong will look |
93 | 22 like it is a problem with gaim itself. I write bugfree code! :) Therefore, it |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
23 is your problem, not mine. (I'm usually nice and willing to help you with your |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
24 problems though.) |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
25 |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
26 The void * that gets passed to gaim_plugin_init is the handle for the plugin. |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
27 DO NOT CHANGE THIS POINTER! Bad things will happen. You've been warned. It's |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
28 needed for connecting to signals and things. It's a good idea to remember it |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
29 somehow. |
93 | 30 |
31 You can basically do anything you want in the plugin. You can make function | |
32 calls, change public widgets, display new widgets, things like that. But the | |
95
19cffb5bd129
[gaim-migrate @ 105]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
94
diff
changeset
|
33 really neat thing is you can do things at events. For example, when one of |
93 | 34 your buddies signs on, you can instantly send them a message. You can modify |
35 the incoming and outgoing text. You can do all kinds of crazy things. Whatever | |
36 you want. Check out SIGNALS and CRAZY for more information and ideas. | |
37 | |
38 Plugins can share globals with gaim, but will not share with other plugins. | |
39 This is so if you have a global variable GtkWidget *window in your plugin and | |
40 J. Random Hacker also has the same name on a global variable, you won't be | |
41 constantly overwriting each others' variables. Unfortunately, this also means | |
42 that plugins will have difficulty working together. But then again, that's | |
43 what shared memory is for. | |
44 | |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
45 Plugins can be configured. This makes is so they don't have to be recompiled |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
46 in order to change things internal to them, and it's also just a cool feature |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
47 to have :). It's optional; to allow your plugin to be configured, add a |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
48 function called gaim_plugin_config(). The advised course of action is to have |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
49 it pop up a dialog window; but it's your plugin. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
50 |
93 | 51 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
52 doesn't have to be there, but it's nice if, say, you create a window, and when | |
98
c2d22261e281
[gaim-migrate @ 108]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
95
diff
changeset
|
53 the plugin gets unloaded, it removes the window. Also, all the callbacks you |
c2d22261e281
[gaim-migrate @ 108]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
95
diff
changeset
|
54 have attached to gaim signals will be removed. |
93 | 55 |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
56 Compilation of the plugins is fairly straight-forward; there is a Makefile in |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
57 this directory that has a rule for making the .so file from a .c file. No |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
58 modification of the Makefile should be necessary, unless if you simply want |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
59 to type 'make' to have it made; otherwise, 'make filename.so' will take |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
60 filename.c and make the .so plugin from it. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
61 |
93 | 62 There are a few examples in this directory. Enjoy. |