Mercurial > pidgin.yaz
annotate doc/PERL-HOWTO.dox @ 15069:c8228e154e24
[gaim-migrate @ 17852]
(00:55:14) rekkanoryo: sadrul: don't forget to update the man page :-P
Well, :-P to JOO
committer: Tailor Script <tailor@pidgin.im>
author | Sadrul Habib Chowdhury <imadil@gmail.com> |
---|---|
date | Thu, 30 Nov 2006 05:54:37 +0000 |
parents | e53cceebebb3 |
children | 3d6f2568457c |
rev | line source |
---|---|
6598 | 1 /** @page perl-howto Perl Scripting HOWTO |
2 | |
11278 | 3 @section Introduction |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
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 | 5 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
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 | 8 @section first-script Writing your first script |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
9 |
11278 | 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 | 12 @code |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
13 use Gaim; |
6598 | 14 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
15 %PLUGIN_INFO = ( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
16 perl_api_version => 2, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
17 name => "Perl Test Plugin", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
18 version => "0.1", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
19 summary => "Test plugin for the Perl interpreter.", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
20 description => "Your description here", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
21 author => "John H. Kelm <johnhkelm\@gmail.com", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
22 url => "http://gaim.sourceforge.net/", |
6598 | 23 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
24 load => "plugin_load", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
25 unload => "plugin_unload" |
7182
65acffe70a6d
[gaim-migrate @ 7750]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
26 ); |
6598 | 27 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
28 sub plugin_init { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
29 return %PLUGIN_INFO; |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
30 } |
6598 | 31 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
32 sub plugin_load { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
33 my $plugin = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
34 Gaim::Debug::info("testplugin", "plugin_load() - Test Plugin Loaded.\n"); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
35 } |
6598 | 36 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
37 sub plugin_unload { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
38 my $plugin = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
39 Gaim::Debug::info("testplugin", "plugin_unload() - Test Plugin Unloaded.\n"); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
40 } |
11278 | 41 @endcode |
42 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
43 It is necessary to load the libgaim perl package with the line @code use Gaim; @endcode which will make all the libgaim 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. |
11278 | 44 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
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. |
11278 | 46 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
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 -> 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. |
11278 | 48 |
49 @section account-api Account and Account Option Functions | |
50 | |
12364 | 51 The Account API is in the @c Gaim::Account:: and @c Gaim::Accounts:: packages |
52 and both are nearly identical to their C counterparts @c gaim_account_ and @c | |
53 gaim_accounts_. The Account Option API is in the package @c | |
54 Gaim::Account::Option and is identical to its C implementation @c | |
55 gaim_account_option. | |
11278 | 56 |
12364 | 57 The Account* APIs allow for scripts to create, remove, and edit accounts of the |
58 type GaimAccount. (Note: Gaim types have no real meaning in perl scripts other | |
59 than the types of the arguments of the perl subroutines need to be of the | |
60 expected type.) This section will not go into detail about the @c | |
61 Gaim::Account::Option package for its use in building protocol plugins which | |
62 are outside the scope of this document. However, most of the API calls for the | |
63 @c Gaim::Account::Option package should function as expected so if there is a | |
64 need to access any of the Account Options the function calls necessary are | |
65 avaialbe in the Gaim perl API. | |
11278 | 66 |
12364 | 67 To reduce redundant code the following code examples are going to use the |
68 template shown in the previous section. To highlight some of the more useful | |
69 features of the Account API we will be replacing the @c plugin_load perl | |
70 subroutine. For testing purposes we will display output on the command line by | |
71 using perl @c print commands. | |
11278 | 72 |
73 @code | |
74 sub plugin_load { | |
75 $plugin = shift; | |
76 | |
77 # Testing was done using Oscar, but this should work regardless of the protocol chosen | |
78 my $protocol = "prpl-oscar"; | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
79 my $account_name = "test"; |
11278 | 80 |
81 # Create a new Account | |
12364 | 82 print "Testing: Gaim::Account::new()... "; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
83 $account = Gaim::Account->new($account_name, $protocol); |
12364 | 84 if ($account) { print "ok.\n"; } else { print "fail.\n"; } |
11278 | 85 |
86 # Add a new Account | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
87 print "Testing: Gaim::Account::add()..."; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
88 Gaim::Accounts::add($account); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
89 print "pending find...\n"; |
6598 | 90 |
11278 | 91 # Find the account we just added to verify its existence |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
92 print "Testing: Gaim::Accounts::find()..."; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
93 $account = Gaim::Accounts::find($account_name, $protocol); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
94 if ($account) { print "ok.\n"; } else { print "fail.\n"; } |
6598 | 95 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
96 # Return the username |
12364 | 97 print "Testing: Gaim::Account::get_username()... "; |
98 $user_name = $account->get_username(); | |
99 if ($user_name) { | |
100 print "Success: $user_name.\n"; | |
101 } else { | |
102 print "Failed!\n"; | |
103 } | |
11278 | 104 # Verify if the user is connected |
12364 | 105 print "Testing: Gaim::Account::is_connected()"; |
106 if ($account->is_connected()) { | |
107 print " Connected.\n"; | |
108 } else { | |
109 print " Disconnected.\n"; | |
110 } | |
11278 | 111 |
12364 | 112 # The status mechanism is how users are Connected, set Away, |
113 # Disconnected (status set to Offline), etc | |
11278 | 114 # $status is now a Gaim::Status perl type. |
12364 | 115 print "Testing: Gaim::Accounts::get_active_status()... "; |
116 if ($account->get_active_status()) { | |
117 print "Okay.\n"; | |
118 } else { | |
119 print "Failed!\n"; | |
120 } | |
11278 | 121 |
12364 | 122 # It follows that to connect a user you mest set the account status to |
123 # "available" similarly we can disconnect a user by setting the account | |
124 # status to "offline" | |
125 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
126 print "Testing: Gaim::Accounts::connect()...pending...\n"; |
11278 | 127 |
12364 | 128 $account->set_status("available", TRUE); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
129 $account->set_enabled(Gaim::Core::get_ui(), TRUE); |
12364 | 130 $account->connect(); |
131 | |
11278 | 132 } |
133 @endcode | |
134 | |
12364 | 135 For the most part the code listed above is explained by the comments, however |
136 there are a few other points to make. The variables above are all specialized | |
137 Perl types that contain pointers to the actual Gaim types. They can be | |
138 reasigned at will just like any other variable in Perl. The only way to edit | |
139 the values of a Gaim type from within perl are through accessor methods such as | |
140 @c Gaim::Account::get_username(). For arguments that you would make @c NULL in | |
141 C should be set to @c undef in Perl. | |
11278 | 142 |
143 @section buddylist-api Buddylist, Group and Chat API | |
144 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
145 The BuddyList, Group and Chat APIs are very similar and whatever is shown for the @c Gaim::BuddyList API should carry over to @c Gaim::BuddyList::Chat and @c Gaim::BuddyList::Group. Note that there is a @c Gaim::Find package that was created to keep the naming consistent with how these functions are named in the C API. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
146 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
147 @code |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
148 sub plugin_load { |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
149 my $plugin = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
150 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
151 my $protocol = "prpl-oscar"; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
152 my $account_name = "test"; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
153 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
154 # 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
|
155 # with an existing user |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
156 $account = Gaim::Accounts::find($account_name, $protocol); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
157 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
158 # Testing a find function: Note Gaim::Find not Gaim::Buddy:find! |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
159 # Furthermore, this should work the same for chats and groups |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
160 Gaim::Debug::info("testplugin", "Testing: Gaim::Find::buddy()..."); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
161 $buddy = Gaim::Find::buddy($account, "BUDDYNAME"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
162 Gaim::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
163 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
164 # If you should need the handle for some reason, here is how you do it |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
165 Gaim::Debug::info("testplugin", "Testing: Gaim::BuddyList::get_handle()..."); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
166 $handle = Gaim::BuddyList::get_handle(); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
167 Gaim::Debug::info("", ($handle ? "ok." : "fail.") . "\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
168 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
169 # This gets the Gaim::BuddyList and references it by $blist |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
170 Gaim::Debug::info("testplugin", "Testing: Gaim::get_blist()..."); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
171 $blist = Gaim::get_blist(); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
172 Gaim::Debug::info("", ($blist ? "ok." : "fail.") . "\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
173 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
174 # This is how you would add a buddy named "NEWNAME" with the alias "ALIAS" |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
175 Gaim::Debug::info("testplugin", "Testing: Gaim::BuddyList::Buddy::new..."); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
176 $buddy = Gaim::BuddyList::Buddy::new($account, "NEWNAME", "ALIAS"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
177 Gaim::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
178 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
179 # 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
|
180 # so first we must find the group |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
181 Gaim::Debug::info("testplugin", "Testing: Gaim::Find::group..."); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
182 $group = Gaim::Find::group("GROUP"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
183 Gaim::Debug::info("", ($group ? "ok." : "fail.") . "\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
184 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
185 # 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
|
186 # For this example we can let contact be undef and set the insertion node as the group |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
187 Gaim::Debug::info("testplugin", "Testing: Gaim::BuddyList::add_buddy...\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
188 Gaim::BuddyList::add_buddy($buddy, undef, $group, $group); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
189 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
190 # The example that follows gives an indiction of how an API call that returns a list is handled. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
191 # 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
|
192 # Further down an accessor method is used, 'get_name()' -- see source for details on the full set of methods |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
193 Gaim::Debug::info("testplugin", "Testing: Gaim::Find::buddies...\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
194 @buddy_array = Gaim::Find::buddies($account, undef); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
195 if (@buddy_array) { |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
196 Gaim::Debug::info("testplugin", "Buddies in list (" . @buddy_array . "): \n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
197 foreach $bud (@buddy_array) { |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
198 Gaim::Debug::info("testplugin", Gaim::BuddyList::Buddy::get_name($bud) . "\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
199 } |
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 @endcode |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
203 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
204 The BuddyList API allows for plugins to edit buddies in the list, find the buddies on a given account, set alias, and manipulate the structure as needed. It is also contains the methods for accessing @c Gaim::BuddyList::Group and @c Gaim::BuddyList::Chat types. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
205 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
206 @section conn-api Connection API |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
207 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
208 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. |
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 conv-api Conversation API |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
211 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
212 The Gaim perl API for @c gaim_conversation_ and @c gaim_conv_window_ allow |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
213 plugins to interact with open conversations, create new conversations, and |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
214 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
|
215 displayed and a new conversation instant message is created. The following |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
216 example again replaces the @c plugin_load subroutine. The |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
217 @c Gaim::Conversation::Chat package handles the @c gaim_conv_chat_ portion of |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
218 the API very similarly to the examples that follow. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
219 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
220 Notice that the interaction with the conversation window is in the @c Gaim::GtkUI package as it |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
221 is UI-specific code interacting with gtkgaim and not libgaim. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
222 To use any of the Gaim::GtkUI functionality, you will need to add the following to the top of your script: @code use Gaim::GtkUI; @endcode |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
223 |
11278 | 224 |
225 @code | |
226 sub plugin_load { | |
227 my $plugin = shift; | |
228 my $protocol = "prpl-oscar"; | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
229 my $account_name = "test"; |
11278 | 230 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
231 $account = Gaim::Accounts::find($account_name, $protocol); |
11278 | 232 |
233 # First we create two new conversations. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
234 print "Testing Gaim::Conversation->new()..."; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
235 $conv1 = Gaim::Conversation->new(1, $account, "Test Conversation 1"); |
12340 | 236 if ($conv1) { print "ok.\n"; } else { print "fail.\n"; } |
11278 | 237 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
238 print "Testing Gaim::Conversation->new()..."; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
239 $conv2 = Gaim::Conversation->new(1, $account, "Test Conversation 2"); |
12340 | 240 if ($conv2) { print "ok.\n"; } else { print "fail.\n"; } |
11278 | 241 |
242 # Second we create a window to display the conversations in. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
243 # Note that the package here is Gaim::GtkUI::Conversation::Window |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
244 print "Testing Gaim::GtkUI::Conversation::Window->new()...\n"; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
245 $win = Gaim::GtkUI::Conversation::Window->new(); |
11278 | 246 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
247 # 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
|
248 # The subroutine add_gtkconv() returns the number of conversations |
12340 | 249 # present in the window. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
250 print "Testing Gaim::GtkUI::Conversation::Window::add_conversation()..."; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
251 $gtkconv2 = Gaim::GtkUI::Conversation::get_gtkconv($conv2); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
252 $gtkconv2->get_window()->remove_gtkconv($gtkconv2); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
253 $conv_count = $win->add_gtkconv($gtkconv2); |
12340 | 254 if ($conv_count) { |
255 print "ok..." . $conv_count . " conversations...\n"; | |
256 } else { | |
257 print "fail.\n"; | |
258 } | |
11278 | 259 |
260 # Now the window is displayed to the user. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
261 print "Testing Gaim::GtkUI::Conversation::Window::show()...\n"; |
12340 | 262 $win->show(); |
11278 | 263 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
264 # Use get_im_data() to get a handle for the conversation |
12340 | 265 print "Testing Gaim::Conversation::get_im_data()...\n"; |
266 $im = $conv1->get_im_data(); | |
267 if ($im) { print "ok.\n"; } else { print "fail.\n"; } | |
11278 | 268 |
269 # Here we send messages to the conversation | |
12340 | 270 print "Testing Gaim::Conversation::IM::send()...\n"; |
271 $im->send("Message Test."); | |
11278 | 272 |
12340 | 273 print "Testing Gaim::Conversation::IM::write()...\n"; |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
274 $conv2->get_im_data()->write("SENDER", "<b>Message</b> Test.", 0, 0); |
11278 | 275 } |
276 @endcode | |
277 | |
12340 | 278 The next block of code shows how a script can close a known conversation window |
279 @c $win. | |
11278 | 280 |
281 @code | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
282 print "Testing Gaim::GtkUI::Conversation::Window::get_gtkconv_count()...\n"; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
283 $conv_count = $win->get_gtkconv_count(); |
12340 | 284 print "...and it returned $conv_count.\n"; |
285 if ($conv_count > 0) { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
286 print "Testing Gaim::GtkUI::Conversation::Window::destroy()...\n"; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
287 $win->destroy(); |
12340 | 288 } |
11278 | 289 @endcode |
290 | |
291 @section plugin-pref-api Plugin Preference and Gtk Preference API | |
292 | |
293 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. | |
294 | |
295 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 | 296 |
11278 | 297 @code |
298 %PLUGIN_INFO = { | |
299 ..., | |
300 prefs_info => "prefs_info_cb" | |
301 }; | |
302 @endcode | |
303 | |
304 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. | |
305 | |
306 @code | |
307 sub plugin_load { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
308 my $plugin = shift; |
11278 | 309 |
310 # Here we are adding a set of preferences | |
311 # The second argument is the default value for the preference. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
312 Gaim::Prefs::add_none("/plugins/core/perl_test"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
313 Gaim::Prefs::add_bool("/plugins/core/perl_test/bool", 1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
314 Gaim::Prefs::add_string("/plugins/core/perl_test/choice_str", "ch1"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
315 Gaim::Prefs::add_int("/plugins/core/perl_test/choice_int", 1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
316 Gaim::Prefs::add_string("/plugins/core/perl_test/text", "Foobar"); |
11278 | 317 } |
318 @endcode | |
319 | |
320 Now we can add these preferences from inside our function specified in @c \%PLUGIN_INFO . | |
6598 | 321 |
11278 | 322 @code |
323 sub prefs_info_cb { | |
324 # The first step is to initialize the Gaim::Pref::Frame that will be returned | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
325 $frame = Gaim::PluginPref::Frame->new(); |
11278 | 326 |
12364 | 327 # Create a new boolean option with a label "Boolean Label" and then add |
328 # it to the frame | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
329 $ppref = Gaim::PluginPref->new_with_label("Boolean Label"); |
12364 | 330 $frame->add($ppref); |
11278 | 331 |
12364 | 332 $ppref = Gaim::PluginPref->new_with_name_and_label( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
333 "/plugins/core/perl_test/bool", "Boolean Preference"); |
12364 | 334 $frame->add($ppref); |
11278 | 335 |
12364 | 336 # Create a set of choices. To do so we must set the type to 1 which is |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
337 # the numerical equivalent of the GaimPrefType for choice. |
12364 | 338 $ppref = Gaim::PluginPref->new_with_name_and_label( |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
339 "/plugins/core/perl_test/choice_str", "Choice Preference"); |
12364 | 340 $ppref->set_type(1); |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
341 $ppref->add_choice("ch0", "ch0"); |
11278 | 342 # The following will be the default value as set from plugin_load |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
343 $ppref->add_choice("ch1", "ch1"); |
12364 | 344 $frame->add($ppref); |
11278 | 345 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
346 # Create a set of choices. To do so we must set the type to 1 which is |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
347 # the numerical equivalent of the GaimPrefType for choice. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
348 $ppref = Gaim::PluginPref->new_with_name_and_label( |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
349 "/plugins/core/perl_test/choice_int", "Choice Preference 2"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
350 $ppref->set_type(1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
351 $ppref->add_choice("zero", 0); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
352 # 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
|
353 $ppref->add_choice("one", 1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
354 $frame->add($ppref); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
355 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
356 |
12364 | 357 # Create a text box. The default value will be "Foobar" as set by |
358 # plugin_load | |
359 $ppref = Gaim::PluginPref->new_with_name_and_label( | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
360 "/plugins/core/perl_test/text", "Text Box Preference"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
361 $ppref->set_type(2); |
12364 | 362 $ppref->set_max_length(16); |
363 $frame->add($ppref); | |
6598 | 364 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
365 return $frame; |
11278 | 366 } |
367 @endcode | |
368 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
369 <!-- |
11377 | 370 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 | 371 |
372 @code | |
373 %PLUGIN_INFO = { | |
374 ..., | |
375 # Used to differentiate between a regular and a Gtk preference frame | |
376 GTK_UI => TRUE, | |
377 gtk_prefs_info => "gtk_prefs_info_cb", | |
378 } | |
379 @endcode | |
380 | |
381 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 | 382 |
11278 | 383 @code |
384 # A simple call back that prints out whatever value it is given as an argument. | |
385 sub button_cb { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
386 my $widget = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
387 my $data = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
388 print "Clicked button with message: " . $data . "\n"; |
11278 | 389 } |
390 | |
391 sub gtk_prefs_info_cb { | |
11377 | 392 # Create a button that prints a message to the console and places it in the frame. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
393 use Glib; |
11377 | 394 require Gtk2; |
11278 | 395 |
11377 | 396 $frame = Gtk2::Frame->new(\'Gtk Test Frame\'); |
397 $button = Gtk2::Button->new(\'Print Message\'); | |
11278 | 398 |
11377 | 399 $frame->set_border_width(10); |
400 $button->set_border_width(150); | |
401 $button->signal_connect("clicked" => \&button_cb, "Message Text"); | |
402 $frame->add($button); | |
11278 | 403 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
404 $button->show(); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
405 $frame->show(); |
11377 | 406 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
407 return $frame; |
11278 | 408 } |
409 @endcode | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
410 --> |
6598 | 411 |
11278 | 412 @section request-api Request Dialog Box API |
413 | |
414 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. | |
415 | |
416 These arguments are the same for each of the three request types: | |
417 @arg @em handle - The plugin handle. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
418 @arg @em title - String title for the dialog. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
419 @arg @em primary - The first sub-heading. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
420 @arg @em secondary - The second sub-heading. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
421 @arg @em ok_text - The Text for the OK button. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
422 @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
|
423 @arg @em cancel_text - The text for the Cancel button. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
424 @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
|
425 @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
|
426 @arg @em multiline - Boolean where true indicates multiple line input boxes are allowed. |
11278 | 427 @arg @em masked - Boolean indicating if the user can edit the text. |
428 @arg @em hint - See source for more information - can be left blank. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
429 @arg @em filename - String defualt file name value. |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
430 @arg @em savedialog - Boolean where true indicates use as a save file dialog and false indicates an open file dialog. |
6598 | 431 |
11278 | 432 @code |
433 # Create a simple text input box | |
434 Gaim::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb); | |
435 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
436 # Prompt user to select a file |
11278 | 437 Gaim::Request::file(handle, title, filename, savedialog, ok_cb, cancel_cb); |
438 | |
439 # Create a unique input dialog as shown in the following example | |
440 Gaim::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb); | |
441 @endcode | |
442 | |
443 What follows is an example of a @c Gaim::Request::fields() dialog box with two callbacks for an OK button and a Cancel Button. | |
444 | |
445 @code | |
446 sub ok_cb_test{ | |
447 # The $fields is passed to the callback function when the button is clicked. | |
448 # To get the values they must be extracted from $fields by name. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
449 $fields = shift; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
450 $account = Gaim::Request::Fields::get_account($fields, "acct_test"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
451 $int = Gaim::Request::Fields::get_integer($fields, "int_test"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
452 $choice = Gaim::Request::Fields::get_choice($fields, "ch_test"); |
11278 | 453 } |
454 | |
455 sub cancel_cb_test{ | |
456 # 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
|
457 } |
6598 | 458 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
459 sub plugin_load { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
460 my $plugin = shift; |
6598 | 461 |
11278 | 462 # Create a group to pool together mutltiple fields. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
463 $group = Gaim::Request::Field::Group::new("Group Name"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
464 |
11278 | 465 # Each fields is created with Gaim::Request::*_new(), is made viewable with Gaim::Request::field_*_set_show_all() |
466 # and is then added to the group with Gaim::Request::field_group_add_field() | |
6598 | 467 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
468 # Add an account drop down list showing all active accounts |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
469 $field = Gaim::Request::Field::account_new("acct_test", "Account Text", undef); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
470 Gaim::Request::Field::account_set_show_all($field, 0); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
471 Gaim::Request::Field::Group::add_field($group, $field); |
6598 | 472 |
11278 | 473 # Add an integer input box |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
474 $field = Gaim::Request::Field::int_new("int_test", "Integer Text", 33); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
475 Gaim::Request::Field::Group::add_field($group, $field); |
6598 | 476 |
11278 | 477 # Add a list of choices |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
478 $field = Gaim::Request::Field::choice_new("ch_test", "Choice Text", 1); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
479 Gaim::Request::Field::choice_add($field, "Choice 0"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
480 Gaim::Request::Field::choice_add($field, "Choice 1"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
481 Gaim::Request::Field::choice_add($field, "Choice 2"); |
6598 | 482 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
483 Gaim::Request::Field::Group::add_field($group, $field); |
11278 | 484 |
485 # Create a Gaim::Request and add the group that was just created. | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
486 $request = Gaim::Request::Fields::new(); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
487 Gaim::Request::Fields::add_group($request, $group); |
6598 | 488 |
11278 | 489 # Display the dialog box with the input fields added earlier with the appropriate titles. |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
490 Gaim::Request::fields( |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
491 $plugin, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
492 "Request Title!", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
493 "Primary Title", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
494 "Secondary Title", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
495 $request, |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
496 "Ok Text", "ok_cb_test", |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
497 "Cancel Text", "cancel_cb_test"); |
11278 | 498 } |
499 @endcode | |
6598 | 500 |
11278 | 501 @section timeout-cb Misc: Plugin Actions, Timeouts and Callbacks |
6598 | 502 |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
503 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 Name]". 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. |
11278 | 504 |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
505 Plugin actions require the @c \%PLUGIN_INFO hash to have a key/value pair added and a callback perl subroutine defined to list the available actions, as well as one callback subroutine for each action. Also, a @c \%plugin_actions hash needs to be defined relating the action names returned by the callback to the appropriate callback subroutines for each action. |
6598 | 506 |
11278 | 507 @code |
508 %PLUGIN_INFO = { | |
509 ..., | |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
510 plugin_action_sub => "plugin_actions_cb", |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
511 } |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
512 |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
513 sub plugin_actions_cb { |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
514 my @actions = ("Action 1", "Action 2"); |
11278 | 515 } |
6598 | 516 |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
517 %plugin_actions = ( |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
518 # 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
|
519 "Action 1" => \&action1_cb, |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
520 # 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
|
521 "Action 2" => \&action2_cb |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
522 ); |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
523 |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
524 sub action1_cb { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
525 Gaim::Debug::info("Test Plugin", "Action 1 activated\n"); |
13351
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
526 } |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
527 |
967dd29cc4ae
[gaim-migrate @ 15723]
Richard Laager <rlaager@wiktel.com>
parents:
12364
diff
changeset
|
528 sub action2_cb { |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
529 Gaim::Debug::info("Test Plugin", "Action 2 activated\n"); |
11278 | 530 } |
531 @endcode | |
6598 | 532 |
11278 | 533 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. |
534 | |
535 @code | |
536 sub timeout_cb { | |
537 my $plugin = shift; | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
538 Gaim::Debug::info("testplugin", "Timeout occurred.\n"); |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
539 |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
540 # Reschedule timeout |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
541 Gaim::timeout_add($plugin, 10, \&timeout_cb, $plugin); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
542 } |
6603
21084026030b
[gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents:
6602
diff
changeset
|
543 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
544 sub plugin_load { |
11278 | 545 $plugin = shift; |
546 | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
547 # Schedule a timeout for ten seconds from now |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
548 Gaim::timeout_add($plugin, 10, \&timeout_cb, $plugin); |
11278 | 549 } |
550 @endcode | |
6598 | 551 |
11278 | 552 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. |
553 | |
554 @code | |
555 sub signal_cb { | |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
556 # 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
|
557 my ($account, $data) = @_; |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
558 Gaim::Debug::info("testplugin", "Account \"" . $account->get_username() . "\" just connected.\n"); |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
559 } |
6598 | 560 |
11278 | 561 sub plugin_load { |
562 $plugin = shift; | |
563 | |
564 # User data to be given as an argument to the callback perl subroutine. | |
565 $data = ""; | |
6598 | 566 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
567 # A pointer to the handle to which the signal belongs needed by the callback function |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
568 $accounts_handle = Gaim::Accounts::get_handle(); |
6598 | 569 |
15066
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
570 # Connect the perl subroutine 'signal_cb' to the event 'account-connecting' |
e53cceebebb3
[gaim-migrate @ 17849]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
14692
diff
changeset
|
571 Gaim::Signal::connect($accounts_handle, "account-connecting", $plugin, \&signal_cb, $data); |
11278 | 572 } |
573 @endcode | |
574 | |
575 @section Resources | |
576 @see API Documentation | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
577 |
6598 | 578 */ |