annotate doc/PERL-HOWTO.dox @ 20425:5048651671e1

Revert a bunch of whitespace changes so reviewing a diff against im.pidgin.pidgin doesn't make my eyes bleed quite as much
author Stu Tomlinson <stu@nosnilmot.com>
date Sat, 26 May 2007 13:59:07 +0000
parents 1414e0e01dc5
children 77dfed554b2b
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
75 # Testing was done using Oscar, but this should work regardless of the protocol chosen
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
76 my $protocol = "prpl-oscar";
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
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
152 my $protocol = "prpl-oscar";
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;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
235 my $protocol = "prpl-oscar";
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
326 # Here we are adding a set of preferences
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
327 # The second argument is the default value for the preference.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
328 Purple::Prefs::add_none("/plugins/core/perl_test");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
329 Purple::Prefs::add_bool("/plugins/core/perl_test/bool", 1);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
330 Purple::Prefs::add_string("/plugins/core/perl_test/choice_str", "ch1");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
331 Purple::Prefs::add_int("/plugins/core/perl_test/choice_int", 1);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
332 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
333 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
334 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
335
15933
b449dc6b8a20 A little doxygen love and some tiny gaim->purpleisms
Mark Doliner <mark@kingant.net>
parents: 15069
diff changeset
336 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
337 function.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
338
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
339 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
340 sub prefs_info_cb {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
341 # 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
342 $frame = Purple::PluginPref::Frame->new();
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
343
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
344 # 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
345 # it to the frame
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
346 $ppref = Purple::PluginPref->new_with_label("Boolean Label");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
347 $frame->add($ppref);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
348
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
349 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
350 "/plugins/core/perl_test/bool", "Boolean Preference");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
351 $frame->add($ppref);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
352
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
353 # 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
354 # the numerical equivalent of the PurplePrefType for choice.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
355 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
356 "/plugins/core/perl_test/choice_str", "Choice Preference");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
357 $ppref->set_type(1);
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
358 $ppref->add_choice("ch0", "ch0");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
359 # 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
360 $ppref->add_choice("ch1", "ch1");
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
361 $frame->add($ppref);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
362
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
363 # 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
364 # the numerical equivalent of the PurplePrefType for choice.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
365 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
366 "/plugins/core/perl_test/choice_int", "Choice Preference 2");
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
367 $ppref->set_type(1);
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
368 $ppref->add_choice("zero", 0);
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
369 # 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
370 $ppref->add_choice("one", 1);
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
371 $frame->add($ppref);
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
372
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
373
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
374 # 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
375 # plugin_load
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
376 $ppref = Purple::PluginPref->new_with_name_and_label(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
377 "/plugins/core/perl_test/text", "Text Box Preference");
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
378 $ppref->set_type(2);
12364
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
379 $ppref->set_max_length(16);
6fd82071a7b8 [gaim-migrate @ 14668]
Mark Doliner <mark@kingant.net>
parents: 12340
diff changeset
380 $frame->add($ppref);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
381
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
382 return $frame;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
383 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
384 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
385
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
386 <!--
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
387 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
388
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
389 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
390 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
391 ...,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
392 # 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
393 GTK_UI => TRUE,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
394 gtk_prefs_info => "gtk_prefs_info_cb",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
395 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
396 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
397
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
398 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
399
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
400 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
401 # 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
402 sub button_cb {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
403 my $widget = shift;
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
404 my $data = shift;
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
405 print "Clicked button with message: " . $data . "\n";
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
406 }
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 sub gtk_prefs_info_cb {
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
409 # 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
410 use Glib;
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
411 require Gtk2;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
412
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
413 $frame = Gtk2::Frame->new(\'Gtk Test Frame\');
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
414 $button = Gtk2::Button->new(\'Print Message\');
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
415
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
416 $frame->set_border_width(10);
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
417 $button->set_border_width(150);
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
418 $button->signal_connect("clicked" => \&button_cb, "Message Text");
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
419 $frame->add($button);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
420
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
421 $button->show();
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
422 $frame->show();
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
423
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
424 return $frame;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
425 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
426 @endcode
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
427 -->
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
428
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
429 @section request-api Request Dialog Box API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
430
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
431 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
432 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
433 (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
434 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
435 listed below, followed by an example illustrating its use.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
436
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
437 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
438 @arg @em handle - The plugin handle.
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
439 @arg @em title - String title for the dialog.
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
440 @arg @em primary - The first sub-heading.
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
441 @arg @em secondary - The second sub-heading.
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
442 @arg @em ok_text - The Text for the OK button.
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
443 @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
444 @arg @em cancel_text - The text for the Cancel button.
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
445 @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
446 @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
447 @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
448 @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
449 @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
450 @arg @em filename - String default file name value.
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
451 @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
452
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
453 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
454 # Create a simple text input box
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
455 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
456
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
457 # Prompt user to select a file
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
458 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
459
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
460 # Create a unique input dialog as shown in the following example
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
461 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
462 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
463
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
464 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
465 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
466
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
467 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
468 sub ok_cb_test{
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
469 # 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
470 # 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
471 $fields = shift;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
472 $account = Purple::Request::Fields::get_account($fields, "acct_test");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
473 $int = Purple::Request::Fields::get_integer($fields, "int_test");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
474 $choice = Purple::Request::Fields::get_choice($fields, "ch_test");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
475 }
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 sub cancel_cb_test{
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
478 # 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
479 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
480
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
481 sub plugin_load {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
482 my $plugin = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
483
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
484 # Create a group to pool together multiple fields.
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
485 $group = Purple::Request::Field::Group::new("Group Name");
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
486
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
487 # 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
488 # 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
489
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
490 # Add an account combobox containing all active accounts
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
491 $field = Purple::Request::Field::account_new("acct_test", "Account Text", undef);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
492 Purple::Request::Field::account_set_show_all($field, 0);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
493 Purple::Request::Field::Group::add_field($group, $field);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
494
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
495 # Add an integer input box
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
496 $field = Purple::Request::Field::int_new("int_test", "Integer Text", 33);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
497 Purple::Request::Field::Group::add_field($group, $field);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
498
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
499 # Add a list of choices
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
500 $field = Purple::Request::Field::choice_new("ch_test", "Choice Text", 1);
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
501 Purple::Request::Field::choice_add($field, "Choice 0");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
502 Purple::Request::Field::choice_add($field, "Choice 1");
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
503 Purple::Request::Field::choice_add($field, "Choice 2");
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
504
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
505 Purple::Request::Field::Group::add_field($group, $field);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
506
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
507 # Create a Purple::Request and add the group that was just created.
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
508 $request = Purple::Request::Fields::new();
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
509 Purple::Request::Fields::add_group($request, $group);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
510
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
511 # 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
512 Purple::Request::fields(
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
513 $plugin,
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
514 "Request Title!",
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
515 "Primary Title",
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
516 "Secondary Title",
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
517 $request,
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
518 "Ok Text", "ok_cb_test",
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
519 "Cancel Text", "cancel_cb_test");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
520 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
521 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
522
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
523 @section timeout-cb Misc: Plugin Actions, Timeouts and Callbacks
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
524
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
525 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
526 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
527 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
528 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
529 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
530 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
531 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
532 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
533 demonstrate the usage of these features.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
534
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
535 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
536 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
537 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
538 added to the @c \%plugin_actions hash.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
539
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
540 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
541 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
542 ...,
13351
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
543 plugin_action_sub => "plugin_actions_cb",
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
544 }
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 sub plugin_actions_cb {
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
547 my @actions = ("Action 1", "Action 2");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
548 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
549
13351
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
550 %plugin_actions = (
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
551 # 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
552 "Action 1" => \&action1_cb,
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
553 # 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
554 "Action 2" => \&action2_cb
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
555 );
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 sub action1_cb {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
558 Purple::Debug::info("Test Plugin", "Action 1 activated\n");
13351
967dd29cc4ae [gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents: 12364
diff changeset
559 }
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 sub action2_cb {
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
562 Purple::Debug::info("Test Plugin", "Action 2 activated\n");
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
563 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
564 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
565
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
566 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
567
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
568 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
569 sub timeout_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
570 my $plugin = shift;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
571 Purple::Debug::info("testplugin", "Timeout occurred.\n");
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
572
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
573 # Reschedule timeout
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
574 Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin);
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
575 }
6603
21084026030b [gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents: 6602
diff changeset
576
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
577 sub plugin_load {
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
578 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
579
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
580 # Schedule a timeout for ten seconds from now
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
581 Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
582 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
583 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
584
15069
3d6f2568457c [gaim-migrate @ 17853]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 15065
diff changeset
585 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
586 then attaching the callback to a signal.
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
587
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
588 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
589 sub signal_cb {
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
590 # 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
591 my ($account, $data) = @_;
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
592 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
593 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
594
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
595 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
596 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
597
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
598 # 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
599 $data = "";
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
600
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
601 # 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
602 $accounts_handle = Purple::Accounts::get_handle();
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
603
15065
e53cceebebb3 [gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents: 14692
diff changeset
604 # Connect the perl subroutine 'signal_cb' to the event 'account-connecting'
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 15933
diff changeset
605 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
606 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
607 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
608
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
609 @section Resources
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
610 @see API Documentation
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
611
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
612 */