Mercurial > pidgin.yaz
annotate plugins/HOWTO @ 9465:8a4797a608ae
[gaim-migrate @ 10290]
1) Fixes the parsing for Win32 clipboard format so that we more accurately
grab the right text
2) Revises our Win32 clipboard format conversion to act more like IE,
since this is as close as we will get to "the right way"
3) Makes clipboard pasting not paste HTML comments (this one effects
linux too, and fixes a problem i've seen pasting from oo.o)
committer: Tailor Script <tailor@pidgin.im>
author | Tim Ringenbach <marv@pidgin.im> |
---|---|
date | Wed, 07 Jul 2004 01:35:27 +0000 |
parents | 258c19be6d84 |
children |
rev | line source |
---|---|
7327 | 1 Everything in this file should be considered old and potentially out of |
2 date. For more reliable information, install doxygen and graphiz dot, | |
3 then run | |
4 make docs | |
5 in the gaim source tree. This will produce html docs in gaim/docs/html | |
6 that will provide an api reference and in the related pages section, | |
7 information on perl and c plugins. | |
8 | |
9 | |
93 | 10 Ok, this howto is going to be really short and sweet and to the point. |
11 | |
12 First off, before you do anything else, in all of the files for your plugin, | |
13 put the lines | |
14 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
15 #define GAIM_PLUGINS |
93 | 16 #include "gaim.h" |
17 | |
18 I mean this. Without this, all kinds of things will not work correctly. If you | |
19 really want to know exactly what this does, read ../src/gaim.h and learn. But | |
20 if you don't want to do that, just know that it's important. | |
21 | |
22 Now that you've put that there, make sure gaim.h is in your include path. | |
23 | |
24 Ok, now you're ready to write the plugin. | |
25 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
26 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
|
27 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
|
28 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
|
29 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
|
30 it effectively becomes a part of gaim, and anything that goes wrong will look |
93 | 31 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
|
32 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
|
33 problems though.) |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
34 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
35 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
|
36 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
|
37 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
|
38 somehow. |
93 | 39 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
40 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
|
41 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
|
42 file in this directory for more details. |
391
be408b41c172
[gaim-migrate @ 401]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
144
diff
changeset
|
43 |
93 | 44 You can basically do anything you want in the plugin. You can make function |
45 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
|
46 really neat thing is you can do things at events. For example, when one of |
93 | 47 your buddies signs on, you can instantly send them a message. You can modify |
48 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
|
49 you want. Check out SIGNALS for more information. |
93 | 50 |
51 Plugins can share globals with gaim, but will not share with other plugins. | |
52 This is so if you have a global variable GtkWidget *window in your plugin and | |
53 J. Random Hacker also has the same name on a global variable, you won't be | |
54 constantly overwriting each others' variables. Unfortunately, this also means | |
55 that plugins will have difficulty working together. But then again, that's | |
56 what shared memory is for. | |
57 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
58 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
|
59 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
|
60 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
|
61 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
|
62 it pop up a dialog window; but it's your plugin. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
63 |
93 | 64 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
65 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
|
66 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
|
67 have attached to gaim signals will be removed. |
93 | 68 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
69 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
|
70 (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
|
71 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
|
72 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
|
73 done the necessary cleanup. |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
74 |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
75 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
|
76 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
|
77 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
|
78 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
|
79 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
|
80 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
|
81 you want to link with. |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
82 |
93 | 83 There are a few examples in this directory. Enjoy. |