Mercurial > pidgin.yaz
annotate doc/PERL-HOWTO.dox @ 30639:597840eccfa7
merge of '0627a49f54e3d5317e6a8dd97956ee2abfa32f9d'
and '8bc0a157fd0b23d8e7b6dc9b581fc636e9a0f258'
author | Paul Aurich <paul@darkrain42.org> |
---|---|
date | Fri, 18 Jun 2010 20:14:06 +0000 |
parents | 36379bf98ed6 |
children |
rev | line source |
---|---|
6598 | 1 /** @page perl-howto Perl Scripting HOWTO |
2 | |
11278 | 3 @section Introduction |
16196 | 4 libpurple Perl Plugins are set up very similarly to their C counterparts. Most of the API calls are implemented and are divided into packages. There are some significant differences between the Perl and C API. Much like the C API, the best place to seek guidance is the source, which is located in the *.xs files in the [libpurple|pidgin]/plugins/perl/common directories. The tutorial that follows will be example based and attempt to touch on some of the notable features of the embedded perl interpreter. It is also important to note that some of the C API is missing in libpurple's perl API. |
10408 | 5 |
16196 | 6 It is possible to get Gtk2-Perl to work with libpurple's Perl API, however you must not load the module with @c use, but rather with @c require. Keep this in mind if you would like to use other perl modules that are dynamically loaded. You can avoid the problem by always using @c require instead of @c use. |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
7 |
11278 | 8 @section first-script Writing your first script |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
9 |
16196 | 10 Let us start with a simple example of a perl plugin. The following code sample is a complete plugin that can be copied and used as-is. |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
11 |
11278 | 12 @code |
16196 | 13 use Purple; |
6598 | 14 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
15 %PLUGIN_INFO = ( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
16 perl_api_version => 2, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
17 name => "Perl Test Plugin", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
18 version => "0.1", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
19 summary => "Test plugin for the Perl interpreter.", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
20 description => "Your description here", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
21 author => "John H. Kelm <johnhkelm\@gmail.com", |
16196 | 22 url => "http://pidgin.im", |
6598 | 23 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
24 load => "plugin_load", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
25 unload => "plugin_unload" |
7182
65acffe70a6d
[gaim-migrate @ 7750]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
26 ); |
6598 | 27 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
28 sub plugin_init { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
29 return %PLUGIN_INFO; |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
30 } |
6598 | 31 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
32 sub plugin_load { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
33 my $plugin = shift; |
16196 | 34 Purple::Debug::info("testplugin", "plugin_load() - Test Plugin Loaded.\n"); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
35 } |
6598 | 36 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
37 sub plugin_unload { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
38 my $plugin = shift; |
16196 | 39 Purple::Debug::info("testplugin", "plugin_unload() - Test Plugin Unloaded.\n"); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
40 } |
11278 | 41 @endcode |
42 | |
16196 | 43 It is necessary to load the libpurple perl package with the @code use Purple; @endcode line; this makes all the libpurple perl API available to the script. The @c \%PLUGIN_INFO hash contains all the information that will be displayed in the Plugin frame of the Preferences dialog, it also contains information about how the plugin is to be handled. The @c load and @c unload keys specify subroutines to be called when the plugin is loaded and unloaded. There are other key values that may be present in the @c \%PLUGIN_INFO hash; some of those will be covered in the following sections. |
11278 | 44 |
16196 | 45 The Perl subroutine @c plugin_init is executed when the plugin is probed by the plugin subsystem. What this means is that as soon as Pidgin or Finch is started, this subroutine is run once, regardless of whether or not the plugin is actually loaded. The other two subroutines present are the @c load and @c unload routines specified in the @c \%PLUGIN_INFO hash and will receive the plugin handle as an argument. When the plugin is loaded and subsequently unloaded, it will print a message to the debug window using the @c Purple::Debug::info() API call. |
11278 | 46 |
16196 | 47 In order to use this simple plugin, save the script text in a file with a @c .pl extension in your ~/.purple/plugins directory. After restarting Pidgin, you should see the plugin ("Perl Test Plugin") listed in the plugin list under "Tools -> Plugins". To view the debug output, make sure you run Pidgin from the console with the '-d' flag or open the Debug Window which is available in the "Help" menu. When you check the checkbox next the plugin, you should see a message appear in the Debug Window (or console); similarly, when you uncheck the checkbox you should see another message appear. You have now created a framework that will allow you to create almost any kind of libpurple plugin you can imagine. |
11278 | 48 |
49 @section account-api Account and Account Option Functions | |
50 | |
16196 | 51 The Account API is in the @c Purple::Account:: and @c Purple::Accounts:: packages; |
52 both are nearly identical to their C counterparts, @c purple_account_ and @c | |
53 purple_accounts_. The Account Option API is in the @c Purple::Account::Option | |
54 package and is identical to the C implementation, @c purple_account_option. | |
11278 | 55 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
56 The Account* APIs allow scripts to create, remove, and edit accounts. An |
16196 | 57 account will have the Perl type of "PurpleAccount". (Note: Purple types have no real |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
58 meaning in perl scripts, other than that the types passed to perl subroutines |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
59 need to be correct.) This section will not go into detail about the @c |
16196 | 60 Purple::Account::Option package since its use is mainly in building protocol |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
61 plugins, which are outside the scope of this document. However, the API for the |
16196 | 62 @c Purple::Account::Option package should function as expected, should you need to |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
63 use it. |
11278 | 64 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
65 To reduce redundant code, the following code examples will use the simple plugin |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
66 from the previous section as a template. To highlight some of the more useful |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
67 features of the Account API, we will be replacing the @c plugin_load perl |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
68 subroutine. For testing purposes, we will display output on the command line by |
12364 | 69 using perl @c print commands. |
11278 | 70 |
71 @code | |
72 sub plugin_load { | |
73 $plugin = shift; | |
74 | |
30141
36379bf98ed6
Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents:
27348
diff
changeset
|
75 # Testing was done using AIM, but this should work regardless of the protocol chosen |
36379bf98ed6
Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents:
27348
diff
changeset
|
76 my $protocol = "prpl-aim"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
77 my $account_name = "test"; |
11278 | 78 |
79 # Create a new Account | |
16196 | 80 print "Testing: Purple::Account::new()... "; |
81 $account = Purple::Account->new($account_name, $protocol); | |
12364 | 82 if ($account) { print "ok.\n"; } else { print "fail.\n"; } |
11278 | 83 |
84 # Add a new Account | |
16196 | 85 print "Testing: Purple::Account::add()..."; |
86 Purple::Accounts::add($account); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
87 print "pending find...\n"; |
6598 | 88 |
11278 | 89 # Find the account we just added to verify its existence |
16196 | 90 print "Testing: Purple::Accounts::find()..."; |
91 $account = Purple::Accounts::find($account_name, $protocol); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
92 if ($account) { print "ok.\n"; } else { print "fail.\n"; } |
6598 | 93 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
94 # Return the username |
16196 | 95 print "Testing: Purple::Account::get_username()... "; |
12364 | 96 $user_name = $account->get_username(); |
97 if ($user_name) { | |
98 print "Success: $user_name.\n"; | |
99 } else { | |
100 print "Failed!\n"; | |
101 } | |
11278 | 102 # Verify if the user is connected |
16196 | 103 print "Testing: Purple::Account::is_connected()"; |
12364 | 104 if ($account->is_connected()) { |
105 print " Connected.\n"; | |
106 } else { | |
107 print " Disconnected.\n"; | |
108 } | |
11278 | 109 |
12364 | 110 # The status mechanism is how users are Connected, set Away, |
111 # Disconnected (status set to Offline), etc | |
16196 | 112 # $status is now a Purple::Status perl type. |
113 print "Testing: Purple::Accounts::get_active_status()... "; | |
12364 | 114 if ($account->get_active_status()) { |
115 print "Okay.\n"; | |
116 } else { | |
117 print "Failed!\n"; | |
118 } | |
11278 | 119 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
120 # It follows that to connect a user you must set the account status to |
12364 | 121 # "available" similarly we can disconnect a user by setting the account |
122 # status to "offline" | |
123 | |
16196 | 124 print "Testing: Purple::Accounts::connect()...pending...\n"; |
11278 | 125 |
12364 | 126 $account->set_status("available", TRUE); |
16196 | 127 $account->set_enabled(Purple::Core::get_ui(), TRUE); |
12364 | 128 $account->connect(); |
129 | |
11278 | 130 } |
131 @endcode | |
132 | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
133 The above code is mostly explained in the comments, however there are a few |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
134 notable points to make. The variables above are all specialized Perl types that |
16196 | 135 contain pointers to the actual Purple types. They can be reassigned at will, just |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
136 like any other variable in Perl. The only way to edit the internal values of a |
16196 | 137 Purple type from within perl is to use the accessor methods, e.g. |
138 @c Purple::Account::get_username(). If you would like to assign a C @c NULL value, | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
139 simply use @c undef. |
11278 | 140 |
141 @section buddylist-api Buddylist, Group and Chat API | |
142 | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
143 The BuddyList, Group and Chat APIs are very similar and whatever is shown for |
16196 | 144 the @c Purple::BuddyList API should carry over to @c Purple::BuddyList::Chat and |
145 @c Purple::BuddyList::Group. Note that a @c Purple::Find package was created to | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
146 keep the naming consistent with the C API. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
147 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
148 @code |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
149 sub plugin_load { |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
150 my $plugin = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
151 |
30141
36379bf98ed6
Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents:
27348
diff
changeset
|
152 my $protocol = "prpl-aim"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
153 my $account_name = "test"; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
154 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
155 # This is how we get an account to use in the following tests. You should replace the username |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
156 # with an existing user |
16196 | 157 $account = Purple::Accounts::find($account_name, $protocol); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
158 |
16196 | 159 # Testing a find function: Note Purple::Find not Purple::Buddy:find! |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
160 # Furthermore, this should work the same for chats and groups |
16196 | 161 Purple::Debug::info("testplugin", "Testing: Purple::Find::buddy()..."); |
162 $buddy = Purple::Find::buddy($account, "BUDDYNAME"); | |
163 Purple::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
164 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
165 # If you should need the handle for some reason, here is how you do it |
16196 | 166 Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::get_handle()..."); |
167 $handle = Purple::BuddyList::get_handle(); | |
168 Purple::Debug::info("", ($handle ? "ok." : "fail.") . "\n"); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
169 |
16196 | 170 # This gets the Purple::BuddyList and references it by $blist |
171 Purple::Debug::info("testplugin", "Testing: Purple::get_blist()..."); | |
172 $blist = Purple::get_blist(); | |
173 Purple::Debug::info("", ($blist ? "ok." : "fail.") . "\n"); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
174 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
175 # This is how you would add a buddy named "NEWNAME" with the alias "ALIAS" |
16196 | 176 Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::Buddy::new..."); |
177 $buddy = Purple::BuddyList::Buddy::new($account, "NEWNAME", "ALIAS"); | |
178 Purple::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
179 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
180 # Here we add the new buddy '$buddy' to the group "GROUP" |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
181 # so first we must find the group |
16196 | 182 Purple::Debug::info("testplugin", "Testing: Purple::Find::group..."); |
183 $group = Purple::Find::group("GROUP"); | |
184 Purple::Debug::info("", ($group ? "ok." : "fail.") . "\n"); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
185 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
186 # To add the buddy we need to have the buddy, contact, group and node for insertion. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
187 # For this example we can let contact be undef and set the insertion node as the group |
16196 | 188 Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::add_buddy...\n"); |
189 Purple::BuddyList::add_buddy($buddy, undef, $group, $group); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
190 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
191 # The example that follows gives an indication of how an API call that returns a list is handled. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
192 # In this case the buddies of the account found earlier are retrieved and put in an array '@buddy_array' |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
193 # Further down an accessor method is used, 'get_name()' -- see source for details on the full set of methods |
16196 | 194 Purple::Debug::info("testplugin", "Testing: Purple::Find::buddies...\n"); |
195 @buddy_array = Purple::Find::buddies($account, undef); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
196 if (@buddy_array) { |
16196 | 197 Purple::Debug::info("testplugin", "Buddies in list (" . @buddy_array . "): \n"); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
198 foreach $bud (@buddy_array) { |
16196 | 199 Purple::Debug::info("testplugin", Purple::BuddyList::Buddy::get_name($bud) . "\n"); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
200 } |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
201 } |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
202 } |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
203 @endcode |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
204 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
205 The BuddyList API allows plugins to edit buddies in the list, find the buddies |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
206 for a given account, assign aliases, and further manipulate the structure |
16196 | 207 as needed. It is also contains methods for accessing @c Purple::BuddyList::Group |
208 and @c Purple::BuddyList::Chat types. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
209 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
210 @section conn-api Connection API |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
211 |
16196 | 212 The @c Purple::Connection API is one of the many packages that will not be covered |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
213 in-depth in this tutorial. It is most useful to protocol plugin developers. |
16196 | 214 However, the entire @c purple_connection_ API has corresponding, functioning perl subroutines. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
215 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
216 @section conv-api Conversation API |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
217 |
16196 | 218 The libpurple perl APIs for @c purple_conversation_ and @c pidgin_conv_window_ allow |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
219 plugins to interact with existing conversations, create new conversations, and |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
220 modify conversations at will. In the example script, a new window is created, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
221 displayed and a new conversation instant message is created. The following |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
222 example again replaces the @c plugin_load subroutine in the simple plugin |
16196 | 223 template. The @c Purple::Conversation::Chat package handles the |
224 @c purple_conv_chat_ portion of the API very similarly to how the | |
225 Purple::Conversation::IM package is used in the examples that follow. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
226 |
16196 | 227 Notice that the interaction with the conversation window is in the @c Pidgin package as it |
228 is UI-specific code interacting with Pidgin and not libpurple. | |
229 To use any of the Pidgin:: functionality, you will need to add the following to the top of your script: @code use Pidgin; @endcode | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
230 |
11278 | 231 |
232 @code | |
233 sub plugin_load { | |
234 my $plugin = shift; | |
30141
36379bf98ed6
Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents:
27348
diff
changeset
|
235 my $protocol = "prpl-aim"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
236 my $account_name = "test"; |
11278 | 237 |
16196 | 238 $account = Purple::Accounts::find($account_name, $protocol); |
11278 | 239 |
240 # First we create two new conversations. | |
16196 | 241 print "Testing Purple::Conversation->new()..."; |
242 $conv1 = Purple::Conversation->new(1, $account, "Test Conversation 1"); | |
12340 | 243 if ($conv1) { print "ok.\n"; } else { print "fail.\n"; } |
11278 | 244 |
16196 | 245 print "Testing Purple::Conversation->new()..."; |
246 $conv2 = Purple::Conversation->new(1, $account, "Test Conversation 2"); | |
12340 | 247 if ($conv2) { print "ok.\n"; } else { print "fail.\n"; } |
11278 | 248 |
249 # Second we create a window to display the conversations in. | |
16196 | 250 # Note that the package here is Pidgin::Conversation::Window |
251 print "Testing Pidgin::Conversation::Window->new()...\n"; | |
252 $win = Pidgin::Conversation::Window->new(); | |
11278 | 253 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
254 # The third thing to do is to move second the conversation to a new window. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
255 # The subroutine add_gtkconv() returns the number of conversations |
12340 | 256 # present in the window. |
16196 | 257 print "Testing Pidgin::Conversation::Window::add_conversation()..."; |
258 $gtkconv2 = Pidgin::Conversation::get_gtkconv($conv2); | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
259 $gtkconv2->get_window()->remove_gtkconv($gtkconv2); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
260 $conv_count = $win->add_gtkconv($gtkconv2); |
12340 | 261 if ($conv_count) { |
262 print "ok..." . $conv_count . " conversations...\n"; | |
263 } else { | |
264 print "fail.\n"; | |
265 } | |
11278 | 266 |
267 # Now the window is displayed to the user. | |
16196 | 268 print "Testing Pidgin::Conversation::Window::show()...\n"; |
12340 | 269 $win->show(); |
11278 | 270 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
271 # Use get_im_data() to get a handle for the conversation |
16196 | 272 print "Testing Purple::Conversation::get_im_data()...\n"; |
12340 | 273 $im = $conv1->get_im_data(); |
274 if ($im) { print "ok.\n"; } else { print "fail.\n"; } | |
11278 | 275 |
276 # Here we send messages to the conversation | |
16196 | 277 print "Testing Purple::Conversation::IM::send()...\n"; |
12340 | 278 $im->send("Message Test."); |
11278 | 279 |
16196 | 280 print "Testing Purple::Conversation::IM::write()...\n"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
281 $conv2->get_im_data()->write("SENDER", "<b>Message</b> Test.", 0, 0); |
11278 | 282 } |
283 @endcode | |
284 | |
12340 | 285 The next block of code shows how a script can close a known conversation window |
286 @c $win. | |
11278 | 287 |
288 @code | |
16196 | 289 print "Testing Pidgin::Conversation::Window::get_gtkconv_count()...\n"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
290 $conv_count = $win->get_gtkconv_count(); |
12340 | 291 print "...and it returned $conv_count.\n"; |
292 if ($conv_count > 0) { | |
16196 | 293 print "Testing Pidgin::Conversation::Window::destroy()...\n"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
294 $win->destroy(); |
12340 | 295 } |
11278 | 296 @endcode |
297 | |
298 @section plugin-pref-api Plugin Preference and Gtk Preference API | |
299 | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
300 The plugin preference API allows plugins to display options for manipulating the |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
301 plugin's behavior in a popup window. The method used for creating the pane in |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
302 native C plugins does not allow a direct mapping into perl. Therefore, perl |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
303 plugin writers must be aware that there will be significant differences in how |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
304 they create plugin preference panes. |
11278 | 305 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
306 To first create a standard plugin preference tab, we need specify the |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
307 @c prefs_info key/value pair in the @c \%PLUGIN_INFO hash. This specifies the |
16196 | 308 name of the perl subroutine that will build and return a @c Purple::Pref::Frame. |
6598 | 309 |
11278 | 310 @code |
311 %PLUGIN_INFO = { | |
312 ..., | |
313 prefs_info => "prefs_info_cb" | |
314 }; | |
315 @endcode | |
316 | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
317 The perl subroutine @c prefs_info_cb will be called to create the preferences |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
318 popup for the perl plugin. The following example will demonstrate creating a |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
319 preference frame. It is necessary to first initialize the preferences to be used |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
320 in the @c plugin_load subroutine, as follows. |
11278 | 321 |
322 @code | |
323 sub plugin_load { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
324 my $plugin = shift; |
11278 | 325 |
27348
77dfed554b2b
Clarify that Purple::Prefs::add_none() really is necessary
Paul Aurich <paul@darkrain42.org>
parents:
16196
diff
changeset
|
326 # This is necessary to create each level in the preferences tree. |
77dfed554b2b
Clarify that Purple::Prefs::add_none() really is necessary
Paul Aurich <paul@darkrain42.org>
parents:
16196
diff
changeset
|
327 Purple::Prefs::add_none("/plugins/core/perl_test"); |
11278 | 328 # Here we are adding a set of preferences |
329 # The second argument is the default value for the preference. | |
16196 | 330 Purple::Prefs::add_bool("/plugins/core/perl_test/bool", 1); |
331 Purple::Prefs::add_string("/plugins/core/perl_test/choice_str", "ch1"); | |
332 Purple::Prefs::add_int("/plugins/core/perl_test/choice_int", 1); | |
333 Purple::Prefs::add_string("/plugins/core/perl_test/text", "Foobar"); | |
11278 | 334 } |
335 @endcode | |
336 | |
15936
b449dc6b8a20
A little doxygen love and some tiny gaim->purpleisms
Mark Doliner <mark@kingant.net>
parents:
15070
diff
changeset
|
337 Now we can provide an UI for manipulating these preferences in our @c prefs_info |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
338 function. |
6598 | 339 |
11278 | 340 @code |
341 sub prefs_info_cb { | |
16196 | 342 # The first step is to initialize the Purple::Pref::Frame that will be returned |
343 $frame = Purple::PluginPref::Frame->new(); | |
11278 | 344 |
12364 | 345 # Create a new boolean option with a label "Boolean Label" and then add |
346 # it to the frame | |
16196 | 347 $ppref = Purple::PluginPref->new_with_label("Boolean Label"); |
12364 | 348 $frame->add($ppref); |
11278 | 349 |
16196 | 350 $ppref = Purple::PluginPref->new_with_name_and_label( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
351 "/plugins/core/perl_test/bool", "Boolean Preference"); |
12364 | 352 $frame->add($ppref); |
11278 | 353 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
354 # Create a set of choices. To do so, we must set the type to 1 which is |
16196 | 355 # the numerical equivalent of the PurplePrefType for choice. |
356 $ppref = Purple::PluginPref->new_with_name_and_label( | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
357 "/plugins/core/perl_test/choice_str", "Choice Preference"); |
12364 | 358 $ppref->set_type(1); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
359 $ppref->add_choice("ch0", "ch0"); |
11278 | 360 # The following will be the default value as set from plugin_load |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
361 $ppref->add_choice("ch1", "ch1"); |
12364 | 362 $frame->add($ppref); |
11278 | 363 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
364 # Create a set of choices. To do so we must set the type to 1 which is |
16196 | 365 # the numerical equivalent of the PurplePrefType for choice. |
366 $ppref = Purple::PluginPref->new_with_name_and_label( | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
367 "/plugins/core/perl_test/choice_int", "Choice Preference 2"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
368 $ppref->set_type(1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
369 $ppref->add_choice("zero", 0); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
370 # The following will be the default value as set from plugin_load |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
371 $ppref->add_choice("one", 1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
372 $frame->add($ppref); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
373 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
374 |
12364 | 375 # Create a text box. The default value will be "Foobar" as set by |
376 # plugin_load | |
16196 | 377 $ppref = Purple::PluginPref->new_with_name_and_label( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
378 "/plugins/core/perl_test/text", "Text Box Preference"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
379 $ppref->set_type(2); |
12364 | 380 $ppref->set_max_length(16); |
381 $frame->add($ppref); | |
6598 | 382 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
383 return $frame; |
11278 | 384 } |
385 @endcode | |
386 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
387 <!-- |
11377 | 388 Using the Gtk2-Perl module for Perl it is possible to create tailored @c GtkFrame elements and display them in a preference window. Note that Gtk2-Perl must be loaded with @c require and not @c use . The first step is to create the proper key/value pairs in the @c \%PLUGIN_INFO hash noting that the @c prefs_info key is no longer valid. Instead the keys @c GTK_UI and @c gtk_prefs_info must be set as follows. |
11278 | 389 |
390 @code | |
391 %PLUGIN_INFO = { | |
392 ..., | |
393 # Used to differentiate between a regular and a Gtk preference frame | |
394 GTK_UI => TRUE, | |
395 gtk_prefs_info => "gtk_prefs_info_cb", | |
396 } | |
397 @endcode | |
398 | |
399 To finish this example @c gtk_prefs_info_cb needs to be defined. To introduce some of the flexibility of using Gtk2-Perl the example also includes a button and a callback for the button. Explaining Gtk2-Perl is beyond the scope of this tutorial and more info can be found at the project's website <a href="http://gtk2-perl.sourceforge.net/">http://gtk2-perl.sourceforge.net/</a>. | |
6598 | 400 |
11278 | 401 @code |
402 # A simple call back that prints out whatever value it is given as an argument. | |
403 sub button_cb { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
404 my $widget = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
405 my $data = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
406 print "Clicked button with message: " . $data . "\n"; |
11278 | 407 } |
408 | |
409 sub gtk_prefs_info_cb { | |
11377 | 410 # Create a button that prints a message to the console and places it in the frame. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
411 use Glib; |
11377 | 412 require Gtk2; |
11278 | 413 |
11377 | 414 $frame = Gtk2::Frame->new(\'Gtk Test Frame\'); |
415 $button = Gtk2::Button->new(\'Print Message\'); | |
11278 | 416 |
11377 | 417 $frame->set_border_width(10); |
418 $button->set_border_width(150); | |
419 $button->signal_connect("clicked" => \&button_cb, "Message Text"); | |
420 $frame->add($button); | |
11278 | 421 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
422 $button->show(); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
423 $frame->show(); |
11377 | 424 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
425 return $frame; |
11278 | 426 } |
427 @endcode | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
428 --> |
6598 | 429 |
11278 | 430 @section request-api Request Dialog Box API |
431 | |
16196 | 432 The @c Purple::Request package allows plugins to have interactive dialog boxes |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
433 without the need to directly interact with the UI (e.g. GTK+). This allows core |
16196 | 434 (libpurple) plugins to create a UI that can be displayed on whichever UI frontend |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
435 is being used. The portion of the Request API available to perl scripts is |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
436 listed below, followed by an example illustrating its use. |
11278 | 437 |
438 These arguments are the same for each of the three request types: | |
439 @arg @em handle - The plugin handle. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
440 @arg @em title - String title for the dialog. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
441 @arg @em primary - The first sub-heading. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
442 @arg @em secondary - The second sub-heading. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
443 @arg @em ok_text - The Text for the OK button. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
444 @arg @em ok_cb - The string name of the perl subroutine to call when the OK button is clicked. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
445 @arg @em cancel_text - The text for the Cancel button. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
446 @arg @em cancel_cb - The string name of the perl subroutine to call when the Cancel button is clicked. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
447 @arg @em default_value - Default text string to display in the input box. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
448 @arg @em multiline - Boolean where true indicates multiple line input boxes are allowed. |
11278 | 449 @arg @em masked - Boolean indicating if the user can edit the text. |
450 @arg @em hint - See source for more information - can be left blank. | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
451 @arg @em filename - String default file name value. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
452 @arg @em savedialog - Boolean where true indicates use as a save file dialog and false indicates an open file dialog. |
6598 | 453 |
11278 | 454 @code |
455 # Create a simple text input box | |
16196 | 456 Purple::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb); |
11278 | 457 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
458 # Prompt user to select a file |
16196 | 459 Purple::Request::file(handle, title, filename, savedialog, ok_cb, cancel_cb); |
11278 | 460 |
461 # Create a unique input dialog as shown in the following example | |
16196 | 462 Purple::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb); |
11278 | 463 @endcode |
464 | |
16196 | 465 The following is an example of a @c Purple::Request::fields() dialog box with a |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
466 callback for the OK button and another for the Cancel Button. |
11278 | 467 |
468 @code | |
469 sub ok_cb_test{ | |
470 # The $fields is passed to the callback function when the button is clicked. | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
471 # To access a specific field, it must be extracted from $fields by name. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
472 $fields = shift; |
16196 | 473 $account = Purple::Request::Fields::get_account($fields, "acct_test"); |
474 $int = Purple::Request::Fields::get_integer($fields, "int_test"); | |
475 $choice = Purple::Request::Fields::get_choice($fields, "ch_test"); | |
11278 | 476 } |
477 | |
478 sub cancel_cb_test{ | |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
479 # Cancel does nothing but is equivalent to the ok_cb_test |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
480 } |
6598 | 481 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
482 sub plugin_load { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
483 my $plugin = shift; |
6598 | 484 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
485 # Create a group to pool together multiple fields. |
16196 | 486 $group = Purple::Request::Field::Group::new("Group Name"); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
487 |
16196 | 488 # Each field is created with Purple::Request::*_new(), is made viewable with Purple::Request::field_*_set_show_all() |
489 # and is then added to the group with Purple::Request::field_group_add_field() | |
6598 | 490 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
491 # Add an account combobox containing all active accounts |
16196 | 492 $field = Purple::Request::Field::account_new("acct_test", "Account Text", undef); |
493 Purple::Request::Field::account_set_show_all($field, 0); | |
494 Purple::Request::Field::Group::add_field($group, $field); | |
6598 | 495 |
11278 | 496 # Add an integer input box |
16196 | 497 $field = Purple::Request::Field::int_new("int_test", "Integer Text", 33); |
498 Purple::Request::Field::Group::add_field($group, $field); | |
6598 | 499 |
11278 | 500 # Add a list of choices |
16196 | 501 $field = Purple::Request::Field::choice_new("ch_test", "Choice Text", 1); |
502 Purple::Request::Field::choice_add($field, "Choice 0"); | |
503 Purple::Request::Field::choice_add($field, "Choice 1"); | |
504 Purple::Request::Field::choice_add($field, "Choice 2"); | |
6598 | 505 |
16196 | 506 Purple::Request::Field::Group::add_field($group, $field); |
11278 | 507 |
16196 | 508 # Create a Purple::Request and add the group that was just created. |
509 $request = Purple::Request::Fields::new(); | |
510 Purple::Request::Fields::add_group($request, $group); | |
6598 | 511 |
11278 | 512 # Display the dialog box with the input fields added earlier with the appropriate titles. |
16196 | 513 Purple::Request::fields( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
514 $plugin, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
515 "Request Title!", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
516 "Primary Title", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
517 "Secondary Title", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
518 $request, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
519 "Ok Text", "ok_cb_test", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
520 "Cancel Text", "cancel_cb_test"); |
11278 | 521 } |
522 @endcode | |
6598 | 523 |
11278 | 524 @section timeout-cb Misc: Plugin Actions, Timeouts and Callbacks |
6598 | 525 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
526 This section of the manual covers some of the important features that can be |
16196 | 527 added to libpurple perl Plugins. Plugin actions are callback functions that are |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
528 accessible to the user from the Buddy List window under "Tools -> [Plugin Name]". |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
529 Timeouts allow a plugin to execute a perl subroutine after a given period of time. |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
530 Note that timeouts only occur once, so if the timeout must occur periodically, |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
531 the timeout needs to be re-added at the end of the timeout callback function. |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
532 Callbacks are functions that are called when an event occurs (such as a buddy |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
533 signing-on, or a message being received). The following three examples will |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
534 demonstrate the usage of these features. |
11278 | 535 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
536 Plugin actions require the @c \%PLUGIN_INFO hash to have a key/value pair added, |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
537 specifying a perl subroutine which will list the available actions; each action |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
538 listed must have a definition, including a reference to a callback subroutine, |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
539 added to the @c \%plugin_actions hash. |
6598 | 540 |
11278 | 541 @code |
542 %PLUGIN_INFO = { | |
543 ..., | |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
544 plugin_action_sub => "plugin_actions_cb", |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
545 } |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
546 |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
547 sub plugin_actions_cb { |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
548 my @actions = ("Action 1", "Action 2"); |
11278 | 549 } |
6598 | 550 |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
551 %plugin_actions = ( |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
552 # The callback subroutine that is called when "Tools -> Plugin -> Action 1" is selected |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
553 "Action 1" => \&action1_cb, |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
554 # The callback subroutine that is called when "Tools -> Plugin -> Action 2" is selected |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
555 "Action 2" => \&action2_cb |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
556 ); |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
557 |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
558 sub action1_cb { |
16196 | 559 Purple::Debug::info("Test Plugin", "Action 1 activated\n"); |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
560 } |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
561 |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
562 sub action2_cb { |
16196 | 563 Purple::Debug::info("Test Plugin", "Action 2 activated\n"); |
11278 | 564 } |
565 @endcode | |
6598 | 566 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
567 Timeouts allow a perl subroutine to be executed after a specified time. They only occur once, so, as stated earlier, the timeout must be re-registered after every time it is called. |
11278 | 568 |
569 @code | |
570 sub timeout_cb { | |
571 my $plugin = shift; | |
16196 | 572 Purple::Debug::info("testplugin", "Timeout occurred.\n"); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
573 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
574 # Reschedule timeout |
16196 | 575 Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
576 } |
6603
21084026030b
[gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents:
6602
diff
changeset
|
577 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
578 sub plugin_load { |
11278 | 579 $plugin = shift; |
580 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
581 # Schedule a timeout for ten seconds from now |
16196 | 582 Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin); |
11278 | 583 } |
584 @endcode | |
6598 | 585 |
15070
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
586 Callbacks are handled by creating a perl subroutine to serve as the callback and |
3d6f2568457c
[gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
15066
diff
changeset
|
587 then attaching the callback to a signal. |
11278 | 588 |
589 @code | |
590 sub signal_cb { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
591 # The signal data and the user data come in as arguments |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
592 my ($account, $data) = @_; |
16196 | 593 Purple::Debug::info("testplugin", "Account \"" . $account->get_username() . "\" just connected.\n"); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
594 } |
6598 | 595 |
11278 | 596 sub plugin_load { |
597 $plugin = shift; | |
598 | |
599 # User data to be given as an argument to the callback perl subroutine. | |
600 $data = ""; | |
6598 | 601 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
602 # A pointer to the handle to which the signal belongs needed by the callback function |
16196 | 603 $accounts_handle = Purple::Accounts::get_handle(); |
6598 | 604 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
605 # Connect the perl subroutine 'signal_cb' to the event 'account-connecting' |
16196 | 606 Purple::Signal::connect($accounts_handle, "account-connecting", $plugin, \&signal_cb, $data); |
11278 | 607 } |
608 @endcode | |
609 | |
610 @section Resources | |
611 @see API Documentation | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
612 |
6598 | 613 */ |