Mercurial > pidgin
annotate doc/plugin-ids.dox @ 22651:21f1acb9090f
Patch from Maiku: "When the buddy list is set to sort contacts by status,
contacts who have a tune set are scored lower than contacts who aren't, even
though their status apart from that is the same."
Also added more detail to the comment that was intended to prevent this ever
happening. Fixes #5493 -- thanks!
author | Will Thompson <will.thompson@collabora.co.uk> |
---|---|
date | Sat, 12 Apr 2008 17:55:44 +0000 |
parents | e96daf6bc511 |
children |
rev | line source |
---|---|
7335 | 1 /** @page plugin-ids Plugin IDs |
2 | |
3 @section Introduction | |
4 Every plugin contains a unique identifier to prevent duplicate plugin | |
20808
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
5 loading and conflicts. Third-party plugins (that is, plugins written by |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
6 anyone who is not a libpurple, Pidgin, or Finch developer) are expected |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
7 to use a plugin ID that follows a specific format. This format |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
8 categorizes plugins and makes duplicate IDs highly unlikely. |
7335 | 9 |
10 @section Format | |
11 The basic format of a plugin ID is as follows: | |
12 | |
13 <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt> | |
14 | |
15 The @em type indicator specifies the type of plugin. This must be one | |
16 of the following: | |
17 | |
20808
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
18 - core - A core libpurple plugin, capable of being loaded in any |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
19 program using libpurple. Core plugins may not contain any |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
20 UI-specific code. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
21 - prpl - A protocol plugin. This is a special type of core plugin, |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
22 which provides libpurple the ability to connect to |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
23 another IM or chat network. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
24 - lopl - A loader plugin, which loads scripts as plugins. Perl and |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
25 Tcl plugins are made possible by loader plugins. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
26 - gtk - A GTK+ 2.x (a.k.a. Pidgin) plugin. These plugins may use |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
27 GTK+ code, but may not use window toolkit code, such as |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
28 X11, Win32, Cocoa, or Carbon. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
29 - gtk-x11 - A GTK+ 2.x plugin that uses X11 code. These plugins may |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
30 use both GTK+ code and X11 code, allowing to hook into |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
31 features specific to X11. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
32 - gtk-win32 - A GTK+ plugin that uses Win32 code. These plugins may use |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
33 both GTK+ code and Win32 code, allowing to hook into |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
34 features available on Windows. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
35 - gnt - A GNT (a.k.a. Finch) plugin. These plugins may use GNT code. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
36 - qpe - A plugin for the (now-abandoned) Qutopia user interface. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
37 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
38 The @em username must be a unique identifier for you. It |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
39 @em should be your http://developer.pidgin.im Trac user ID. Failing that, you |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
40 could use your SourceForge user ID or your Freenode IRC nickname, if you |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
41 have either. The http://developer.pidgin.im Trac user ID is preferred. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
42 Do @em not leave this field blank! |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
43 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
44 The @em pluginname is the name of your plugin. It is usually all |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
45 lowercase letters and matches the static plugin ID (the first argument to |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
46 the PURPLE_INIT_PLUGIN() macro call), although it can be anything you |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
47 like. Do @em not include version information in the plugin ID--the |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
48 #PurplePluginInfo structure already has a field for this. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
49 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
50 @section nospaces One Last Rule for Plugin IDs |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
51 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
52 The last rule of plugin IDs is the most important of all. Plugin IDs may |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
53 @em NOT contain spaces. If you need a space, use another hyphen (-). |
7335 | 54 |
20808
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
55 @section exceptions Exceptions to the Rule |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
56 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
57 As with any rule there are exceptions. If you browse through the source |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
58 tree you will see that the plugins we distribute with the Pidgin source |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
59 do not contain a username field. This is because while one developer may |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
60 have written each specific plugin, the plugins are maintained |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
61 collectively by the entire development team. This lack of a username |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
62 field is also an indicator that the plugin is one of our plugins and not |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
63 a third-party plugin. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
64 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
65 Another exception to the rule is the <a |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
66 href="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
67 Pack</a>. All plugins whose lives started in the Purple Plugin Pack use |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
68 <tt>"plugin_pack"</tt> for the username field to indicate origination in |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
69 the Purple Plugin Pack. |
7335 | 70 |
20808
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
71 These two exceptions are mentioned here for completeness. We don't |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
72 encourage breaking the conventions set forth by the rules outlined above. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
73 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
74 @section examples Examples of Well-Chosen Plugin IDs |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
75 |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
76 The following is a list of well-chosen Plugin IDs listing a few good examples. |
7335 | 77 |
20808
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
78 - <tt>"gtk-amc_grim-guifications"</tt> - This is the plugin ID for the |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
79 Guifications 2.x plugin. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
80 - <tt>"gtk-rlaager-album"</tt> - This is the plugin ID for the Album |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
81 plugin, which is now part of the |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
82 Purple Plugin Pack. Its ID follows the |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
83 rules because its life started prior |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
84 to its inclusion in the Plugin Pack. |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
85 - <tt>"core-rlaager-irchelper"</tt> - This is the plugin ID for the IRC |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
86 Helper plugin, which is now part |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
87 of the Purple Plugin Pack. Its ID |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
88 follows the rules because its |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
89 life started prior to its |
e96daf6bc511
I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents:
20807
diff
changeset
|
90 inclusion in the Plugin Pack. |
7335 | 91 |
92 @section plugin-db Plugin Database | |
93 Although it doesn't exist yet, in time there will be a plugin database | |
16196 | 94 on the Pidgin website, where users can download and install new plugins. |
7335 | 95 Plugins will be accessed by your plugin ID, which is one reason why it |
96 must be unique. | |
97 | |
98 */ | |
99 | |
20807
e0613cf8c493
Add some links from signal documentation back to the documentation for the
Will Thompson <will.thompson@collabora.co.uk>
parents:
16196
diff
changeset
|
100 // vim: syntax=c.doxygen tw=75 et |