annotate doc/PERL-HOWTO.dox @ 29956:04c84a3f9553

yahoo: Fix a few race-condition crashes at login (if the account disconnects while these fetches are in-progress).
author Paul Aurich <paul@darkrain42.org>
date Sun, 16 May 2010 20:56:47 +0000
parents 36379bf98ed6
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
1 /** @page perl-howto Perl Scripting HOWTO
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
2
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
3 @section Introduction
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
f53c59c95f03 [gaim-migrate @ 11656]
Mark Doliner <mark@kingant.net>
parents: 10161
diff changeset
5
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
8 @section first-script Writing your first script
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
9
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
12 @code
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
13 use Purple;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
14
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
15 %PLUGIN_INFO = (
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
22 url => "http://pidgin.im",
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
23
15065
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
27
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
28 sub plugin_init {
15065
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
31
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
32 sub plugin_load {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
33 my $plugin = shift;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
36
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
37 sub plugin_unload {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
38 my $plugin = shift;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
41 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
42
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
44
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
46
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
48
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
49 @section account-api Account and Account Option Functions
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
50
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
51 The Account API is in the @c Purple::Account:: and @c Purple::Accounts:: packages;
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
52 both are nearly identical to their C counterparts, @c purple_account_ and @c
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
53 purple_accounts_. The Account Option API is in the @c Purple::Account::Option
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
54 package and is identical to the C implementation, @c purple_account_option.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
55
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
56 The Account* APIs allow scripts to create, remove, and edit accounts. An
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
57 account will have the Perl type of "PurpleAccount". (Note: Purple types have no real
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
diff changeset
59 need to be correct.) This section will not go into detail about the @c
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
60 Purple::Account::Option package since its use is mainly in building protocol
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
61 plugins, which are outside the scope of this document. However, the API for the
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
62 @c Purple::Account::Option package should function as expected, should you need to
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
63 use it.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
64
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
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: 15065
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: 15065
diff changeset
68 subroutine. For testing purposes, we will display output on the command line by
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
69 using perl @c print commands.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
70
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
71 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
72 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
73 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
74
29730
36379bf98ed6 Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents: 27266
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: 27266
diff changeset
76 my $protocol = "prpl-aim";
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
77 my $account_name = "test";
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
78
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
79 # Create a new Account
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
80 print "Testing: Purple::Account::new()... ";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
81 $account = Purple::Account->new($account_name, $protocol);
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
82 if ($account) { print "ok.\n"; } else { print "fail.\n"; }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
83
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
84 # Add a new Account
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
85 print "Testing: Purple::Account::add()...";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
86 Purple::Accounts::add($account);
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
87 print "pending find...\n";
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
88
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
89 # Find the account we just added to verify its existence
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
90 print "Testing: Purple::Accounts::find()...";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
91 $account = Purple::Accounts::find($account_name, $protocol);
15065
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
93
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
94 # Return the username
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
95 print "Testing: Purple::Account::get_username()... ";
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
96 $user_name = $account->get_username();
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
97 if ($user_name) {
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
98 print "Success: $user_name.\n";
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
99 } else {
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
100 print "Failed!\n";
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
101 }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
102 # Verify if the user is connected
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
103 print "Testing: Purple::Account::is_connected()";
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
104 if ($account->is_connected()) {
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
105 print " Connected.\n";
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
106 } else {
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
107 print " Disconnected.\n";
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
108 }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
109
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
110 # The status mechanism is how users are Connected, set Away,
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
111 # Disconnected (status set to Offline), etc
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
112 # $status is now a Purple::Status perl type.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
113 print "Testing: Purple::Accounts::get_active_status()... ";
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
114 if ($account->get_active_status()) {
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
115 print "Okay.\n";
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
116 } else {
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
117 print "Failed!\n";
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
118 }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
119
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
120 # It follows that to connect a user you must set the account status to
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
121 # "available" similarly we can disconnect a user by setting the account
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
122 # status to "offline"
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
123
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
124 print "Testing: Purple::Accounts::connect()...pending...\n";
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
125
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
126 $account->set_status("available", TRUE);
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
127 $account->set_enabled(Purple::Core::get_ui(), TRUE);
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
128 $account->connect();
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
129
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
130 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
131 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
132
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
diff changeset
134 notable points to make. The variables above are all specialized Perl types that
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
135 contain pointers to the actual Purple types. They can be reassigned at will, just
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
136 like any other variable in Perl. The only way to edit the internal values of a
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
137 Purple type from within perl is to use the accessor methods, e.g.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
138 @c Purple::Account::get_username(). If you would like to assign a C @c NULL value,
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
139 simply use @c undef.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
140
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
141 @section buddylist-api Buddylist, Group and Chat API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
142
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
143 The BuddyList, Group and Chat APIs are very similar and whatever is shown for
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
144 the @c Purple::BuddyList API should carry over to @c Purple::BuddyList::Chat and
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
145 @c Purple::BuddyList::Group. Note that a @c Purple::Find package was created to
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
146 keep the naming consistent with the C API.
15065
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
29730
36379bf98ed6 Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents: 27266
diff changeset
152 my $protocol = "prpl-aim";
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
157 $account = Purple::Accounts::find($account_name, $protocol);
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
158
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
159 # Testing a find function: Note Purple::Find not Purple::Buddy:find!
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
161 Purple::Debug::info("testplugin", "Testing: Purple::Find::buddy()...");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
162 $buddy = Purple::Find::buddy($account, "BUDDYNAME");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
163 Purple::Debug::info("", ($buddy ? "ok." : "fail.") . "\n");
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
166 Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::get_handle()...");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
167 $handle = Purple::BuddyList::get_handle();
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
168 Purple::Debug::info("", ($handle ? "ok." : "fail.") . "\n");
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
169
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
170 # This gets the Purple::BuddyList and references it by $blist
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
171 Purple::Debug::info("testplugin", "Testing: Purple::get_blist()...");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
172 $blist = Purple::get_blist();
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
173 Purple::Debug::info("", ($blist ? "ok." : "fail.") . "\n");
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
176 Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::Buddy::new...");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
177 $buddy = Purple::BuddyList::Buddy::new($account, "NEWNAME", "ALIAS");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
178 Purple::Debug::info("", ($buddy ? "ok." : "fail.") . "\n");
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
182 Purple::Debug::info("testplugin", "Testing: Purple::Find::group...");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
183 $group = Purple::Find::group("GROUP");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
184 Purple::Debug::info("", ($group ? "ok." : "fail.") . "\n");
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
188 Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::add_buddy...\n");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
189 Purple::BuddyList::add_buddy($buddy, undef, $group, $group);
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
190
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
191 # The example that follows gives an indication of how an API call that returns a list is handled.
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
194 Purple::Debug::info("testplugin", "Testing: Purple::Find::buddies...\n");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
195 @buddy_array = Purple::Find::buddies($account, undef);
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
196 if (@buddy_array) {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
197 Purple::Debug::info("testplugin", "Buddies in list (" . @buddy_array . "): \n");
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
198 foreach $bud (@buddy_array) {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
199 Purple::Debug::info("testplugin", Purple::BuddyList::Buddy::get_name($bud) . "\n");
15065
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
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
diff changeset
206 for a given account, assign aliases, and further manipulate the structure
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
207 as needed. It is also contains methods for accessing @c Purple::BuddyList::Group
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
208 and @c Purple::BuddyList::Chat types.
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
212 The @c Purple::Connection API is one of the many packages that will not be covered
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
213 in-depth in this tutorial. It is most useful to protocol plugin developers.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
214 However, the entire @c purple_connection_ API has corresponding, functioning perl subroutines.
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
218 The libpurple perl APIs for @c purple_conversation_ and @c pidgin_conv_window_ allow
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
219 plugins to interact with existing conversations, create new conversations, and
15065
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
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
222 example again replaces the @c plugin_load subroutine in the simple plugin
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
223 template. The @c Purple::Conversation::Chat package handles the
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
224 @c purple_conv_chat_ portion of the API very similarly to how the
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
225 Purple::Conversation::IM package is used in the examples that follow.
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
226
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
227 Notice that the interaction with the conversation window is in the @c Pidgin package as it
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
228 is UI-specific code interacting with Pidgin and not libpurple.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
230
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
231
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
232 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
233 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
234 my $plugin = shift;
29730
36379bf98ed6 Update this to use prpl-aim
Mark Doliner <mark@kingant.net>
parents: 27266
diff changeset
235 my $protocol = "prpl-aim";
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
236 my $account_name = "test";
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
237
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
238 $account = Purple::Accounts::find($account_name, $protocol);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
239
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
240 # First we create two new conversations.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
241 print "Testing Purple::Conversation->new()...";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
242 $conv1 = Purple::Conversation->new(1, $account, "Test Conversation 1");
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
243 if ($conv1) { print "ok.\n"; } else { print "fail.\n"; }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
244
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
245 print "Testing Purple::Conversation->new()...";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
246 $conv2 = Purple::Conversation->new(1, $account, "Test Conversation 2");
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
247 if ($conv2) { print "ok.\n"; } else { print "fail.\n"; }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
248
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
249 # Second we create a window to display the conversations in.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
250 # Note that the package here is Pidgin::Conversation::Window
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
251 print "Testing Pidgin::Conversation::Window->new()...\n";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
252 $win = Pidgin::Conversation::Window->new();
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
253
15065
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
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
256 # present in the window.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
257 print "Testing Pidgin::Conversation::Window::add_conversation()...";
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
258 $gtkconv2 = Pidgin::Conversation::get_gtkconv($conv2);
15065
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
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
261 if ($conv_count) {
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
262 print "ok..." . $conv_count . " conversations...\n";
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
263 } else {
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
264 print "fail.\n";
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
265 }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
266
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
267 # Now the window is displayed to the user.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
268 print "Testing Pidgin::Conversation::Window::show()...\n";
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
269 $win->show();
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
270
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
272 print "Testing Purple::Conversation::get_im_data()...\n";
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
273 $im = $conv1->get_im_data();
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
274 if ($im) { print "ok.\n"; } else { print "fail.\n"; }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
275
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
276 # Here we send messages to the conversation
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
277 print "Testing Purple::Conversation::IM::send()...\n";
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
278 $im->send("Message Test.");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
279
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
280 print "Testing Purple::Conversation::IM::write()...\n";
15065
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
282 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
283 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
284
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
285 The next block of code shows how a script can close a known conversation window
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
286 @c $win.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
287
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
288 @code
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
289 print "Testing Pidgin::Conversation::Window::get_gtkconv_count()...\n";
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
290 $conv_count = $win->get_gtkconv_count();
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
291 print "...and it returned $conv_count.\n";
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
292 if ($conv_count > 0) {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
293 print "Testing Pidgin::Conversation::Window::destroy()...\n";
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
294 $win->destroy();
12340
11d14efe7be2 [gaim-migrate @ 14644]
Mark Doliner <mark@kingant.net>
parents: 11501
diff changeset
295 }
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
296 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
297
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
298 @section plugin-pref-api Plugin Preference and Gtk Preference API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
299
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
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: 15065
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: 15065
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: 15065
diff changeset
304 they create plugin preference panes.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
305
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
diff changeset
307 @c prefs_info key/value pair in the @c \%PLUGIN_INFO hash. This specifies the
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
308 name of the perl subroutine that will build and return a @c Purple::Pref::Frame.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
309
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
310 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
311 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
312 ...,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
313 prefs_info => "prefs_info_cb"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
314 };
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
315 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
316
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
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: 15065
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: 15065
diff changeset
320 in the @c plugin_load subroutine, as follows.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
321
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
322 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
323 sub plugin_load {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
324 my $plugin = shift;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
325
27266
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
328 # Here we are adding a set of preferences
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
329 # The second argument is the default value for the preference.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
330 Purple::Prefs::add_bool("/plugins/core/perl_test/bool", 1);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
331 Purple::Prefs::add_string("/plugins/core/perl_test/choice_str", "ch1");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
332 Purple::Prefs::add_int("/plugins/core/perl_test/choice_int", 1);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
333 Purple::Prefs::add_string("/plugins/core/perl_test/text", "Foobar");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
334 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
335 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
336
15933
b449dc6b8a20 A little doxygen love and some tiny gaim->purpleisms
Mark Doliner <mark@kingant.net>
parents: 15069
diff changeset
337 Now we can provide an UI for manipulating these preferences in our @c prefs_info
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
338 function.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
339
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
340 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
341 sub prefs_info_cb {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
342 # The first step is to initialize the Purple::Pref::Frame that will be returned
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
343 $frame = Purple::PluginPref::Frame->new();
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
344
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
345 # Create a new boolean option with a label "Boolean Label" and then add
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
346 # it to the frame
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
347 $ppref = Purple::PluginPref->new_with_label("Boolean Label");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
348 $frame->add($ppref);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
349
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
350 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
351 "/plugins/core/perl_test/bool", "Boolean Preference");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
352 $frame->add($ppref);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
353
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
354 # Create a set of choices. To do so, we must set the type to 1 which is
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
355 # the numerical equivalent of the PurplePrefType for choice.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
356 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
357 "/plugins/core/perl_test/choice_str", "Choice Preference");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
358 $ppref->set_type(1);
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
359 $ppref->add_choice("ch0", "ch0");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
360 # The following will be the default value as set from plugin_load
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
361 $ppref->add_choice("ch1", "ch1");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
362 $frame->add($ppref);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
363
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
365 # the numerical equivalent of the PurplePrefType for choice.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
366 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
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
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
375 # Create a text box. The default value will be "Foobar" as set by
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
376 # plugin_load
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
377 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
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
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
380 $ppref->set_max_length(16);
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
381 $frame->add($ppref);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
382
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
383 return $frame;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
384 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
385 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
386
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
387 <!--
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
389
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
390 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
391 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
392 ...,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
393 # Used to differentiate between a regular and a Gtk preference frame
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
394 GTK_UI => TRUE,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
395 gtk_prefs_info => "gtk_prefs_info_cb",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
396 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
397 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
398
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
400
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
401 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
402 # A simple call back that prints out whatever value it is given as an argument.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
403 sub button_cb {
15065
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
407 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
408
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
409 sub gtk_prefs_info_cb {
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
410 # Create a button that prints a message to the console and places it in the frame.
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
411 use Glib;
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
412 require Gtk2;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
413
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
414 $frame = Gtk2::Frame->new(\'Gtk Test Frame\');
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
415 $button = Gtk2::Button->new(\'Print Message\');
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
416
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
417 $frame->set_border_width(10);
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
418 $button->set_border_width(150);
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
419 $button->signal_connect("clicked" => \&button_cb, "Message Text");
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
420 $frame->add($button);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
421
15065
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
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
424
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
425 return $frame;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
426 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
427 @endcode
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
428 -->
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
429
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
430 @section request-api Request Dialog Box API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
431
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
432 The @c Purple::Request package allows plugins to have interactive dialog boxes
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
433 without the need to directly interact with the UI (e.g. GTK+). This allows core
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
434 (libpurple) plugins to create a UI that can be displayed on whichever UI frontend
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
diff changeset
436 listed below, followed by an example illustrating its use.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
437
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
438 These arguments are the same for each of the three request types:
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
439 @arg @em handle - The plugin handle.
15065
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
449 @arg @em masked - Boolean indicating if the user can edit the text.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
450 @arg @em hint - See source for more information - can be left blank.
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
451 @arg @em filename - String default file name value.
15065
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
453
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
454 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
455 # Create a simple text input box
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
456 Purple::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
457
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
458 # Prompt user to select a file
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
459 Purple::Request::file(handle, title, filename, savedialog, ok_cb, cancel_cb);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
460
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
461 # Create a unique input dialog as shown in the following example
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
462 Purple::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
463 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
464
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
465 The following is an example of a @c Purple::Request::fields() dialog box with a
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
466 callback for the OK button and another for the Cancel Button.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
467
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
468 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
469 sub ok_cb_test{
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
470 # The $fields is passed to the callback function when the button is clicked.
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
471 # To access a specific field, it must be extracted from $fields by name.
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
472 $fields = shift;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
473 $account = Purple::Request::Fields::get_account($fields, "acct_test");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
474 $int = Purple::Request::Fields::get_integer($fields, "int_test");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
475 $choice = Purple::Request::Fields::get_choice($fields, "ch_test");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
476 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
477
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
478 sub cancel_cb_test{
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
481
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
482 sub plugin_load {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
483 my $plugin = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
484
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
485 # Create a group to pool together multiple fields.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
486 $group = Purple::Request::Field::Group::new("Group Name");
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
487
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
488 # Each field is created with Purple::Request::*_new(), is made viewable with Purple::Request::field_*_set_show_all()
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
489 # and is then added to the group with Purple::Request::field_group_add_field()
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
490
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
491 # Add an account combobox containing all active accounts
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
492 $field = Purple::Request::Field::account_new("acct_test", "Account Text", undef);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
493 Purple::Request::Field::account_set_show_all($field, 0);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
494 Purple::Request::Field::Group::add_field($group, $field);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
495
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
496 # Add an integer input box
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
497 $field = Purple::Request::Field::int_new("int_test", "Integer Text", 33);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
498 Purple::Request::Field::Group::add_field($group, $field);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
499
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
500 # Add a list of choices
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
501 $field = Purple::Request::Field::choice_new("ch_test", "Choice Text", 1);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
502 Purple::Request::Field::choice_add($field, "Choice 0");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
503 Purple::Request::Field::choice_add($field, "Choice 1");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
504 Purple::Request::Field::choice_add($field, "Choice 2");
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
505
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
506 Purple::Request::Field::Group::add_field($group, $field);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
507
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
508 # Create a Purple::Request and add the group that was just created.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
509 $request = Purple::Request::Fields::new();
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
510 Purple::Request::Fields::add_group($request, $group);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
511
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
512 # Display the dialog box with the input fields added earlier with the appropriate titles.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
513 Purple::Request::fields(
15065
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
521 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
522 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
523
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
524 @section timeout-cb Misc: Plugin Actions, Timeouts and Callbacks
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
525
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
526 This section of the manual covers some of the important features that can be
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
527 added to libpurple perl Plugins. Plugin actions are callback functions that are
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
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: 15065
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: 15065
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: 15065
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: 15065
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: 15065
diff changeset
534 demonstrate the usage of these features.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
535
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
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: 15065
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: 15065
diff changeset
539 added to the @c \%plugin_actions hash.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
540
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
541 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
542 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
549 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
563 Purple::Debug::info("Test Plugin", "Action 2 activated\n");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
564 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
565 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
566
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
568
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
569 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
570 sub timeout_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
571 my $plugin = shift;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
572 Purple::Debug::info("testplugin", "Timeout occurred.\n");
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
579 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
580
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
581 # Schedule a timeout for ten seconds from now
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
582 Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
583 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
584 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
585
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
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: 15065
diff changeset
587 then attaching the callback to a signal.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
588
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
589 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
590 sub signal_cb {
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
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
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
595
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
596 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
597 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
598
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
599 # User data to be given as an argument to the callback perl subroutine.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
600 $data = "";
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
601
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
603 $accounts_handle = Purple::Accounts::get_handle();
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
604
15065
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
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
606 Purple::Signal::connect($accounts_handle, "account-connecting", $plugin, \&signal_cb, $data);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
607 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
608 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
609
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
610 @section Resources
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
611 @see API Documentation
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
612
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
613 */