Mercurial > pidgin.yaz
annotate plugins/HOWTO @ 5295:399390d74514
[gaim-migrate @ 5667]
(17:45:56) deryni: http://deryni.perlmonk.org/idle_timer.diff <- turns off the 30 second update timer when 'show idle times' is off (it shouldn't affect anything else)
committer: Tailor Script <tailor@pidgin.im>
author | Luke Schierer <lschiere@pidgin.im> |
---|---|
date | Sun, 04 May 2003 21:47:33 +0000 |
parents | f74eefb55a78 |
children | 258c19be6d84 |
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 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
17 The only function that is required is gaim_plugin_init(GModule *). This gets |
94
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 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
26 The GModule* that gets passed to gaim_plugin_init is the handle for the plugin. |
94
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 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
31 gaim_plugin_init should return a char*. If the char* returned is not NULL, it |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
32 is interpreted as an error, and used as an error message. See the ChangeLog |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
33 file in this directory for more details. |
391
be408b41c172
[gaim-migrate @ 401]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
144
diff
changeset
|
34 |
93 | 35 You can basically do anything you want in the plugin. You can make function |
36 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
|
37 really neat thing is you can do things at events. For example, when one of |
93 | 38 your buddies signs on, you can instantly send them a message. You can modify |
39 the incoming and outgoing text. You can do all kinds of crazy things. Whatever | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
40 you want. Check out SIGNALS for more information. |
93 | 41 |
42 Plugins can share globals with gaim, but will not share with other plugins. | |
43 This is so if you have a global variable GtkWidget *window in your plugin and | |
44 J. Random Hacker also has the same name on a global variable, you won't be | |
45 constantly overwriting each others' variables. Unfortunately, this also means | |
46 that plugins will have difficulty working together. But then again, that's | |
47 what shared memory is for. | |
48 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
49 Plugins can be configured. This makes it so they don't have to be recompiled |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
50 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
|
51 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
|
52 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
|
53 it pop up a dialog window; but it's your plugin. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
54 |
93 | 55 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
56 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
|
57 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
|
58 have attached to gaim signals will be removed. |
93 | 59 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
60 Plugins can also unload themselves. To do this, call gaim_plugin_unload(GModule *) |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
61 (the GModule* is the handle passed to gaim_plugin_init). When your plugin gets |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
62 unloaded, gaim will remove all of your callbacks. It will not call your |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
63 gaim_plugin_remove function, however, since it will assume you have already |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
64 done the necessary cleanup. |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
65 |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
66 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
|
67 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
|
68 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
|
69 to type 'make' to have it made; otherwise, 'make filename.so' will take |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
70 filename.c and make the .so plugin from it. If you need to link in with extra |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
71 libraries, you can set the environment variable PLUGIN_LIBS to be the libraries |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
72 you want to link with. |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
73 |
93 | 74 There are a few examples in this directory. Enjoy. |