annotate doc/PERL-HOWTO.dox @ 12227:b4391f2ae8de

[gaim-migrate @ 14529] Oops. I'm dumb. Bartosz Oler caught my foul-up here as well. committer: Tailor Script <tailor@pidgin.im>
author Richard Laager <rlaager@wiktel.com>
date Fri, 25 Nov 2005 22:45:08 +0000
parents 9563b768e8e2
children 11d14efe7be2
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
4 Gaim Perl Plugins are setup very similarly to their C counterparts. Most of the API calls are implemented and are divided into pacakges. There are some significant differences between the Perl and C API. Much like the C API, the best place to seek guidances is the source located in the plugins/perl/common directory. The tutorial that follows will be example based and attempt to touch on the salient features of the embedded perl interpreter. It is also important to note that some of the C API is missing in Gaim's perl API.
10408
f53c59c95f03 [gaim-migrate @ 11656]
Mark Doliner <mark@kingant.net>
parents: 10161
diff changeset
5
11501
9563b768e8e2 [gaim-migrate @ 13746]
Richard Laager <rlaager@wiktel.com>
parents: 11377
diff changeset
6 It is possible to get Gtk2-Perl to work with Gaim's perl API, however you must not load the module with @c use but with @c require. If you are uninterested in using Gtk with your perl plugins than this still has bearing on you if you would like to use certain perl modules that are dynamically loaded. By always using @c require instead of @c use the problem is avoided.
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
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
10 Let us start with a simple example of a Gaim 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
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
13 use Gaim;
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 = (
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
16 perl_api_version => 2,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
17 name => "Perl Test Plugin",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
18 version => "0.1",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
19 summary => "Test plugin for the Perl interpreter.",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
20 description => "Your description here",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
21 author => "John H. Kelm <johnhkelm\@gmail.com",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
22 url => "http://gaim.sourceforge.net/",
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
23
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
24 load => "plugin_load",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
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 {
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
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 {
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
33 my $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
34 Gaim::debug_info("plugin_load()", "Test Plugin Loaded.");
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 {
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
38 my $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
39 Gaim::debug_info("plugin_unload()", "Test Plugin Unloaded.");
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
43 It is necessary to load the Gaim perl package with the line @code use Gaim; @endcode which will make all the Gaim perl API available to the script. The @c \%PLUGIN_INFO has contains all the information that will be displayed in the Plugin frame of the Preferences dialog. In addition to information needed to describe the plugin to the user, information about how the plugin is to be handled is present. The keys @c load and @c unload specify and action to take when the plugin is loaded and when it is unloaded from the Preferences dialog respectively. There are other key values that may be present in the @c \%PLUGIN_INFO hash that will be covered in the following sections.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
44
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
45 The Perl subroutine @c plugin_init is executed when the plugin is probed by the plugin subsystem. What this means is as soon as Gaim is started, this subroutine is run once, regardless of whether the plugin is loaded or not. The other two subroutines present are those defined by the @c \%PLUGIN_INFO hash and take 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 Gaim::debug_info() Gaim perl API call.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
46
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
47 The last step is to save the script with a .pl file extention in your ~/.gaim/plugins directory. After restarting gaim the plugin "Perl Test Plugin" should now appear under "Tools->Preferences->Plugins". To view the messages make sure you run Gaim from the console with the '-d' flag or open the Debug Window from inside Gaim under "Help". When you enable the checkbox next the plugin you should see a message appear in the Debug Window (or console) and when you disable the checkbox you should see another message appear. You have now created the framework that will allow you to create almost any kind of Gaim plugin you can imagine.
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
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
51 The Account API is in the @c Gaim::Account:: and @c Gaim::Accounts:: packages and both are nearly identical to their C counterparts @c gaim_account_ and @c gaim_accounts_. The Account Option API is in the package @c Gaim::Account::Option and is identical to its C implementation @c gaim_account_option .
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
52
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
53 The Account* APIs allow for scripts to create, remove, and edit accounts of the type GaimAccount. (Note: Gaim type have no real meaning in perl scripts other than the types of the arguments of the perl subroutines need to be of the expected type.) This section will not go into detail about the @c Gaim::Account::Option package for its use in building protocol plugins which are outside the scope of this document. However, most of the API calls for the @c Gaim::Account::Option package should function as expected so if there is a need to access any of the Account Options the function calls necessary are avaialbe in the Gaim perl API.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
54
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
55 To reduce redundant code the following code examples are going to use the template shown in the previous section. To highlight some of the more useful features of the Account API we will be replacing the @c plugin_load perl subroutine. For testing purposes we will display output on the command line by using perl @c print commands.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
56
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
57 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
58 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
59 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
60
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
61 # 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
62 my $protocol = "prpl-oscar";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
63
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
64 # Create a new Account
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
65 print "Testing: Gaim::Account::new()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
66 $account = Gaim::Account::new("TEST_NAME", $protocol);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
67 if ($account) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
68
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
69 # Add a new Account
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
70 print "Testing: Gaim::Account::add()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
71 Gaim::Accounts::add($account);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
72 print "pending find...\n";
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
73
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
74 # Find the account we just added to verify its existence
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
75 print "Testing: Gaim::Accounts::find()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
76 $account = Gaim::Accounts::find("TEST_NAME", $protocol);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
77 if ($account) { print "ok.\n"; } else { print "fail.\n"; }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
78
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
79 # Return the username
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
80 print "Testing: Gaim::Account::get_username()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
81 $user_name = Gaim::Account::get_username($account);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
82 if ($user_name) { print $user_name . "...ok.\n"; } else { print "fail.\n"; }
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 # Verify if the user is connected
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
85 print "Testing: Gaim::Account::is_connected()";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
86 $user_connected = Gaim::Account::is_connected($account);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
87 if (!($user_connected)) { print "...not connected...ok..\n"; } else { print "...connected...ok.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
88
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
89 # The status mechanism is how users are Connected, set Away, Disconnected (status set to Offline), etc
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
90 # $status is now a Gaim::Status perl type.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
91 print "Testing: Gaim::Accounts::get_active_status()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
92 $status = Gaim::Account::get_active_status($account);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
93 if ($status) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
94
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
95 # It follows that to connect a user you mest set the account status to "available"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
96 # similarly we can disconnect a user by setting the account status to "offline"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
97 $account = Gaim::Accounts::find("TEST_NAME", $protocol);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
98 print "Testing: Gaim::Accounts::connect()...pending...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
99
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
100 Gaim::Account::set_status($account, "available", TRUE);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
101 Gaim::Account::connect($account);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
102 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
103 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
104
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
105 For the most part the code listed above is explained by the comments, however there are a few other points to make. The variables above are all specialized Perl types that contain pointers to the actual Gaim types. They can be reasigned at will just like any other variable in Perl. The only way to edit the values of a Gaim type from within perl are through accessor methods such as @c Gaim::Account::get_username(). For arguments that you would make @c NULL in C should be set to @c undef in Perl.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
106
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
107 @section buddylist-api Buddylist, Group and Chat API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
108
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
109 The BuddList, Group and Chat APIs are very similar and whatever is shown for the @c Gaim::BuddlyList API should carry over to @c Gaim::Chat and @c Gaim::Group. Note that there is a @c Gaim::Find pacakge that was created to keep the naming consistent with how these functions are named in the C API.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
110
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
111 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
112 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
113 my $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
114 my $protocol = "prpl-oscar";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
115
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
116 # This is how we get an account to use in the following tests. You should replace the username
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
117 # with an existent user
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
118 $account = Gaim::Accounts::find("USERNAME", $protocol);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
119
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
120 # Testing a find function: Note Gaim::Find not Gaim::Buddy:find!
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
121 # Furthermore, this should work the same for chats and groups
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
122 print "Testing: Gaim::Find::buddy()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
123 $buddy = Gaim::Find::buddy($account, "BUDDYNAME");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
124 if ($buddy) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
125
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
126 # If you should need the handle for some reason, here is how you do it
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
127 print "Testing: Gaim::BuddyList::get_handle()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
128 $handle = Gaim::BuddyList::get_handle();
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
129 if ($handle) { print "ok.\n"; } else { print "fail.\n"; }
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 # This gets the Gaim::BuddyList and references it by $blist
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
132 print "Testing: Gaim::BuddyList::get_blist()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
133 $blist = Gaim::BuddyList::get_blist();
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
134 if ($blist) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
135
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
136 # This is how you would add a buddy named "NEWNAME" with the alias "ALIAS"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
137 print "Testing: Gaim::Buddy::new...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
138 $buddy = Gaim::Buddy::new($account, "NEWNAME", "ALIAS");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
139 if ($buddy) { print "ok.\n"; } else { print "fail.\n"; }
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 # Here we add the new buddy '$buddy' to the group "GROUP"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
142 # so first we must find the group
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
143 print "Testing: Gaim::Find::group...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
144 $group = Gaim::Find::group("GROUP");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
145 if ($group) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
146
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
147 # To add the buddy we need to have the buddy, contact, group and node for insertion.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
148 # For this example we can let contact be undef and set the insertion node as the group
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
149 print "Testing: Gaim::BuddyList::add_buddy...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
150 Gaim::BuddyList::add_buddy($buddy, undef, $group, $group);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
151 if ($buddy) { print "ok.\n"; } else { print "fail.\n"; }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
152
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
153 # The example that follows gives an indiction of how an API call that returns a list is handled.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
154 # In this case the buddies of the account found earlier are retrieved and put in an array '@buddy_array'
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
155 # Further down an accessor method is used, 'get_name()' -- see source for details on the full set of methods
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
156 print "Testing: Gaim::Find::buddies...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
157 @buddy_array = Gaim::Find::buddies($account, "USERNAME");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
158 if (@buddy_array) {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
159 print "Buddies in list (" . @buddy_array . "): \n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
160 foreach $bud (@buddy_array) {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
161 print Gaim::Buddy::get_name($bud) . "\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
162 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
163 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
164 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
165 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
166
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
167 The BuddyList API allows for plugins to edit buddies in the list, find the buddies on a given account, set alias, and manipulate the structer as needed. It is also contains the methods for accessing @c Gaim::Group and @c Gaim::Chat types.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
168
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
169 @section conn-api Connection API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
170
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
171 The @c Gaim::Connection API is one of the many packages that will not be covered in depth in this tutorial. They are more useful to protocol plugin developers. However, the entire @c gaim_connection_ API has corresponding, functioning perl subroutines.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
172
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
173 @section conv-api Conversation API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
174
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
175 The Gaim perl API for @c gaim_conversation_ and @c gaim_conv_window_ allow plugins to interact with open conversations, create new conversations, and modify conversations at will. The following example again replaces the @c plugin_load subroutine. In the example script, a new window is created, displayed and a new conversation instant message is created. The @c Gaim::Conv::Chat package handles the @c gaim_conv_chat_ portion of the API very similarly to the examples that follow.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
176
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
177 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
178 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
179 my $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
180 my $protocol = "prpl-oscar";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
181
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
182 $account = Gaim::Accounts::find("USERNAME", $protocol);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
183
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
184 # First we create two new conversations.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
185 print "Testing Gaim::Conv::new()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
186 $conv1 = Gaim::Conv::new(1, $account, "Test Conv. 1");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
187 if ($conv1) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
188
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
189 print "Testing Gaim::Conv::new()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
190 $conv2 = Gaim::Conv::new(1, $account, "Test Conv. 2");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
191 if ($conv2) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
192
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
193 # Second we create a window to display the conversations in.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
194 # Note that the package here is Gaim::Conv::Window
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
195 print "Testing Gaim::Conv::Window::new()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
196 $win = Gaim::Conv::Window::new();
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
197
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
198 # The third thing to do is to add the two conversations to the windows.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
199 # The subroutine add_conversation() returns the number of conversations present in the window.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
200 print "Testing Gaim::Conv::Window::add_conversation()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
201 $conv_count = Gaim::Conv::Window::add_conversation($win, $conv1);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
202 if ($conv_count) { print "ok..." . $conv_count . " conversations...\n"; } else { print "fail.\n"; }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
203
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
204 print "Testing Gaim::Conv::Window::add_conversation()...";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
205 $conv_count = Gaim::Conv::Window::add_conversation($win, $conv2);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
206 if ($conv_count) { print "ok..." . $conv_count . " conversations...\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
207
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
208 # Now the window is displayed to the user.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
209 print "Testing Gaim::Conv::Window::show()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
210 Gaim::Conv::Window::show($win);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
211
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
212 # Use Gaim::Conv::get_im_data to get a handle for the conversation
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
213 print "Testing Gaim::Conv::get_im_data()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
214 $im = Gaim::Conv::get_im_data($conv1);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
215 if ($im) { print "ok.\n"; } else { print "fail.\n"; }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
216
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
217 # Here we send messages to the conversation
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
218 print "Testing Gaim::Conv::IM::send()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
219 Gaim::Conv::IM::send($im, "Message Test.");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
220
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
221 print "Testing Gaim::Conv::IM::write()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
222 Gaim::Conv::IM::write($im, "SENDER", "<b>Message</b> Test.", 0, 0);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
223 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
224 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
225
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
226 The next block of code shows how a script can close a known conversation window @c $win.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
227
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
228 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
229 print "Testing Gaim::Conv::Window::get_conversation_count()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
230 $conv_count = Gaim::Conv::Window::get_conversation_count($win);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
231 if ($conv_count > 0) {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
232 print "Testing Gaim::Conv::Window::destroy()...\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
233 Gaim::Conv::Window::destroy($win);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
234 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
235 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
236
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
237 @section plugin-pref-api Plugin Preference and Gtk Preference API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
238
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
239 The plugin preference API allows the plugin to display options in a preference pane that the user can change to manipulate the behaviour of the particular perl plugin. The method used for creating the pane in C does not allow a direct mapping into perl. Therefore perl plugin writers must be aware that there will be significant differences in how they create plugin preference panes.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
240
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
241 To first create a standard plugin preference tab we need to add some key/value pairs to the @c \%PLUGIN_INFO hash. The first line contains the perl subroutine that must be provided and will return a @c Gaim::Pref::Frame.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
242
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
243 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
244 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
245 ...,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
246 prefs_info => "prefs_info_cb"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
247 };
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
248 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
249
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
250 The perl subroutine @c prefs_info_cb will be called to create the tab for the perl plugin in the Preferences dialog. An example of this function will explain the details of creating a preference frame. However, it is necessary to first create the preferences from @c plugin_load as follows.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
251
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
252 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
253 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
254 my $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
255
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
256 # Here we are adding a set of preferences
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
257 # The second argument is the default value for the preference.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
258 Gaim::Prefs::add_none("/plugins/core/perl_test");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
259 Gaim::Prefs::add_bool("/plugins/core/perl_test/bool", 1);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
260 Gaim::Prefs::add_string("/plugins/core/perl_test/choice", "ch1");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
261 Gaim::Prefs::add_string("/plugins/core/perl_test/text", "Foobar");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
262 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
263 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
264
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
265 Now we can add these preferences from inside our function specified in @c \%PLUGIN_INFO .
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
266
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
267 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
268 sub prefs_info_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
269 # The first step is to initialize the Gaim::Pref::Frame that will be returned
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
270 $frame = Gaim::Pref::frame_new();
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
271
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
272 # Create a new boolean option with a label "Boolean Label" and then add it to the frame
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
273 $ppref = Gaim::Pref::new_with_label("Boolean Label");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
274 Gaim::Pref::frame_add($frame, $ppref);
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 $ppref = Gaim::Pref::new_with_name_and_label("/plugins/core/perl_test/bool", "Boolean Preference");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
277 Gaim::Pref::frame_add($frame, $ppref);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
279 # Create a set of choices. To do so we must set the type to 1 which is the numerical equivelant of
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
280 # the GaimPrefType for choice.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
281 $ppref = Gaim::Pref::new_with_name_and_label("/plugins/core/perl_test/choice", "Choice Preference");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
282 Gaim::Pref::set_type($ppref, 1);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
283 Gaim::Pref::add_choice($ppref, "ch0", $frame);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
284 # The following will be the default value as set from plugin_load
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
285 Gaim::Pref::add_choice($ppref, "ch1", $frame);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
286 Gaim::Pref::frame_add($frame, $ppref);
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 # Create a text box. The default value will be "Foobar" as set by plugin_load
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
289 $ppref = Gaim::Pref::new_with_name_and_label("/plugins/core/perl_test/text", "Text Box Preference");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
290 Gaim::Pref::set_max_length($ppref, 16);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
291 Gaim::Pref::frame_add($frame, $ppref);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
292
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
293 return $frame;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
294 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
295 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
296
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
297 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
298
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
299 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
300 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
301 ...,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
302 # 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
303 GTK_UI => TRUE,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
304 gtk_prefs_info => "gtk_prefs_info_cb",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
305 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
306 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
307
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
308 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
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 # 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
312 sub button_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
313 my $widget = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
314 my $data = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
315 print "Clicked button with message: " . $data . "\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
316 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
317
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
318 sub gtk_prefs_info_cb {
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
319 # Create a button that prints a message to the console and places it in the frame.
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
320 use Glib;
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
321 require Gtk2;
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
322
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
323 $frame = Gtk2::Frame->new(\'Gtk Test Frame\');
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
324 $button = Gtk2::Button->new(\'Print Message\');
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
325
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
326 $frame->set_border_width(10);
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
327 $button->set_border_width(150);
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
328 $button->signal_connect("clicked" => \&button_cb, "Message Text");
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
329 $frame->add($button);
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
330
11377
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
331 $button->show();
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
332 $frame->show();
5c3a0e641520 [gaim-migrate @ 13603]
John H. Kelm <johnkelm@gmail.com>
parents: 11278
diff changeset
333
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
334 return $frame;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
335 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
336 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
337
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
338 @section request-api Request Dialog Box API
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
339
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
340 The @c Gaim::Request package allows for plugins to have interactive dialog boxes without the need for creating them in Gtk creating a seperation between the user interfaace and the plugin. The portion of the Request API available to perl scripts is listed below followed by an example illustrating their use.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
341
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
342 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
343 @arg @em handle - The plugin handle.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
344 @arg @em title - String title for the dialog.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
345 @arg @em primary - The first sub-heading.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
346 @arg @em secondary - The second sub-heading.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
347 @arg @em ok_text - The Text for the OK button.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
348 @arg @em ok_cb - The string name of the perl subroutine to call when the OK button is clicked.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
349 @arg @em cancel_text - The text for the Cancel button.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
350 @arg @em cancel_cb - The string name of the perl subroutine to call when the Cancel button is clicked.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
351 @arg @em default_value - Default text string to display in the input box.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
352 @arg @em multiline - Boolean where true indicates multiple line input boxes are allowed.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
353 @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
354 @arg @em hint - See source for more information - can be left blank.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
355 @arg @em filename - String defualt file name value.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
356 @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
357
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
358 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
359 # Create a simple text input box
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
360 Gaim::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
361
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
362 # Propt user to select a file
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
363 Gaim::Request::file(handle, title, filename, savedialog, ok_cb, cancel_cb);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
364
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
365 # Create a unique input dialog as shown in the following example
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
366 Gaim::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
367 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
368
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
369 What follows is an example of a @c Gaim::Request::fields() dialog box with two callbacks for an OK button and a Cancel Button.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
370
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
371 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
372 sub ok_cb_test{
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
373 # The $fields is passed to the callback function when the button is clicked.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
374 # To get the values they must be extracted from $fields by name.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
375 $fields = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
376 $account = Gaim::Request::fields_get_account($fields, "acct_test");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
377 $int = Gaim::Request::fields_get_integer($fields, "int_test");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
378 $choice = Gaim::Request::fields_get_choice($fields, "ch_test");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
379 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
380
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
381 sub cancel_cb_test{
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
382 # Cancel does nothing but is symmetric to the ok_cb_test
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
383 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
384
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
385 sub plugin_load {
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
386 my $plugin = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
387
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
388 # Create a group to pool together mutltiple fields.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
389 $group = Gaim::Request::field_group_new("Group Name");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
390
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
391 # Each fields is created with Gaim::Request::*_new(), is made viewable with Gaim::Request::field_*_set_show_all()
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
392 # and is then added to the group with Gaim::Request::field_group_add_field()
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
393
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
394 # Add an account drop down list showing all active accounts
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
395 $field = Gaim::Request::field_account_new("acct_test", "Account Text", undef);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
396 Gaim::Request::field_account_set_show_all($field, 0);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
397 Gaim::Request::field_group_add_field($group, $field);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
398
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
399 # Add an integer input box
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
400 $field = Gaim::Request::field_int_new("int_test", "Integer Text", 33);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
401 Gaim::Request::field_group_add_field($group, $field);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
402
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
403 # Add a list of choices
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
404 $field = Gaim::Request::field_choice_new("ch_test", "Choice Text", 1);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
405 Gaim::Request::field_choice_add($field, "Choice 0");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
406 Gaim::Request::field_choice_add($field, "Choice 1");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
407 Gaim::Request::field_choice_add($field, "Choice 2");
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
408
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
409 Gaim::Request::field_group_add_field($group, $field);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
410
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
411 # Create a Gaim::Request and add the group that was just created.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
412 $request = Gaim::Request::fields_new();
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
413 Gaim::Request::fields_add_group($request, $group);
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
414
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
415 # Display the dialog box with the input fields added earlier with the appropriate titles.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
416 Gaim::Request::fields(
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
417 $plugin,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
418 "Request Title!",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
419 "Primary Title",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
420 "Secondary Title",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
421 $request,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
422 "Ok Text", "ok_cb_test",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
423 "Cancel Text", "cancel_cb_test");
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
424 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
425 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
426
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
427 @section timeout-cb Misc: Plugin Actions, Timeouts and Callbacks
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 This section of the manual covers some of the more important features that can be added to Gaim perl Plugins. Plugin actions are callback functions that are accessible to the user from the Gaim main window under "Tools->Plugin Actions". Timeouts allow a plugin to exectue a perl subroutine after a given period of time. Note that timeouts only occur once, so if the timeout must occur periodically just add a new timeout at the end of the timeout callback function. Callbacks are functions that are called when an event occurs such as a buddy signing-on or a message being received. These three tools will be discussed in the following three examples.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
430
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
431 The Plugin Action requires the @c \%PLUGIN_INFO hash to have two key/value pairs added and a callback perl subroutine defined. Note the difference between the C API that allows for a GList of actions--only one plugin action is allowed in Gaim perl plugins.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
432
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
433 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
434 %PLUGIN_INFO = {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
435 ...,
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
436 # The callback subroutine that is called when "Tools->Plugin Action->Plugin Action Label" is selected
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
437 plugin_action => "plugin_action_cb",
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
438 plugin_action_label => "Plugin Action Label"
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
439 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
440
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
441 sub plugin_action_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
442 # Note the function receives the plugin handle as its argument
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
443 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
444 print "Plugin Action Selected.\n";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
445 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
446 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
447
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
448 Timeouts allow a perl subroutine to be exectued after a specified time. They only occur once, so as stated earlier the timeout must be reregistered after every time it is called.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
449
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
450 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
451 sub timeout_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
452 my $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
453 print "Timeout occured.";
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
454
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
455 # Reschedule timeout
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
456 Gaim::timeout_add($plugin, 10, \&timeout_cb, $plugin);
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
457 }
6603
21084026030b [gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents: 6602
diff changeset
458
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
459 sub plugin_load {
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
460 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
461
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
462 # Schedule a timeout for ten seconds from now
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
463 Gaim::timeout_add($plugin, 10, \&timeout_cb, $plugin);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
464 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
465 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
466
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
467 Callbacks are handled by creating a perl subroutine to serve as the callback and then attaching the callback to a signal. To use callbacks it is necessary to first obtain the plugin handle with the @c Gaim::Plugin::get_handle() subroutine to pass as an argument for the callback.
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
468
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
469 @code
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
470 sub signal_cb {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
471 # The handle and the user data come in as arguments
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
472 my ($handle, $data) = @_;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
473 print "User just connected.";
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
474 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
475
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
476 sub plugin_load {
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
477 $plugin = shift;
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
478
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
479 # 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
480 $data = "";
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
481
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
482 # A pointer to the actual plugin handle needed by the callback function
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
483 $plugin_handle = Gaim::Accounts::get_handle();
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
484
11278
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
485 # Connect the perl subroutine 'signal_cb' to the event 'account-connecting'
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
486 Gaim::signal_connect($plugin_handle, "account-connecting", $plugin, \&signal_cb, $data);
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
487 }
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
488 @endcode
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
489
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
490 @section Resources
93258e8fb6d2 [gaim-migrate @ 13470]
John H. Kelm <johnkelm@gmail.com>
parents: 10814
diff changeset
491 @see API Documentation
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
492
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
493 */