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