Mercurial > pidgin
changeset 16196:1414e0e01dc5
More renaming.
| author | Richard Laager <rlaager@wiktel.com> |
|---|---|
| date | Mon, 16 Apr 2007 02:08:42 +0000 |
| parents | 7517e6289bc9 |
| children | 30557aad1951 |
| files | doc/PERL-HOWTO.dox doc/TCL-HOWTO.dox doc/core-signals.dox doc/plugin-i18n.dox doc/plugin-ids.dox doc/sound-signals.dox doc/xfer-signals.dox |
| diffstat | 7 files changed, 149 insertions(+), 149 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/PERL-HOWTO.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/PERL-HOWTO.dox Mon Apr 16 02:08:42 2007 +0000 @@ -1,16 +1,16 @@ /** @page perl-howto Perl Scripting HOWTO @section Introduction -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. +libpurple Perl Plugins are set up very similarly to their C counterparts. Most of the API calls are implemented and are divided into packages. There are some significant differences between the Perl and C API. Much like the C API, the best place to seek guidance is the source, which is located in the *.xs files in the [libpurple|pidgin]/plugins/perl/common directories. The tutorial that follows will be example based and attempt to touch on some of the notable features of the embedded perl interpreter. It is also important to note that some of the C API is missing in libpurple's perl API. -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. +It is possible to get Gtk2-Perl to work with libpurple's Perl API, however you must not load the module with @c use, but rather with @c require. Keep this in mind if you would like to use other perl modules that are dynamically loaded. You can avoid the problem by always using @c require instead of @c use. @section first-script Writing your first script -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. +Let us start with a simple example of a perl plugin. The following code sample is a complete plugin that can be copied and used as-is. @code -use Gaim; +use Purple; %PLUGIN_INFO = ( perl_api_version => 2, @@ -19,7 +19,7 @@ summary => "Test plugin for the Perl interpreter.", description => "Your description here", author => "John H. Kelm <johnhkelm\@gmail.com", - url => "http://gaim.sourceforge.net/", + url => "http://pidgin.im", load => "plugin_load", unload => "plugin_unload" @@ -31,35 +31,35 @@ sub plugin_load { my $plugin = shift; - Gaim::Debug::info("testplugin", "plugin_load() - Test Plugin Loaded.\n"); + Purple::Debug::info("testplugin", "plugin_load() - Test Plugin Loaded.\n"); } sub plugin_unload { my $plugin = shift; - Gaim::Debug::info("testplugin", "plugin_unload() - Test Plugin Unloaded.\n"); + Purple::Debug::info("testplugin", "plugin_unload() - Test Plugin Unloaded.\n"); } @endcode -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. +It is necessary to load the libpurple perl package with the @code use Purple; @endcode line; this makes all the libpurple perl API available to the script. The @c \%PLUGIN_INFO hash contains all the information that will be displayed in the Plugin frame of the Preferences dialog, it also contains information about how the plugin is to be handled. The @c load and @c unload keys specify subroutines to be called when the plugin is loaded and unloaded. There are other key values that may be present in the @c \%PLUGIN_INFO hash; some of those will be covered in the following sections. -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. +The Perl subroutine @c plugin_init is executed when the plugin is probed by the plugin subsystem. What this means is that as soon as Pidgin or Finch is started, this subroutine is run once, regardless of whether or not the plugin is actually loaded. The other two subroutines present are the @c load and @c unload routines specified in the @c \%PLUGIN_INFO hash and will receive the plugin handle as an argument. When the plugin is loaded and subsequently unloaded, it will print a message to the debug window using the @c Purple::Debug::info() API call. -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. +In order to use this simple plugin, save the script text in a file with a @c .pl extension in your ~/.purple/plugins directory. After restarting Pidgin, you should see the plugin ("Perl Test Plugin") listed in the plugin list under "Tools -> Plugins". To view the debug output, make sure you run Pidgin from the console with the '-d' flag or open the Debug Window which is available in the "Help" menu. When you check the checkbox next the plugin, you should see a message appear in the Debug Window (or console); similarly, when you uncheck the checkbox you should see another message appear. You have now created a framework that will allow you to create almost any kind of libpurple plugin you can imagine. @section account-api Account and Account Option Functions -The Account API is in the @c Gaim::Account:: and @c Gaim::Accounts:: packages; -both are nearly identical to their C counterparts, @c gaim_account_ and @c -gaim_accounts_. The Account Option API is in the @c Gaim::Account::Option -package and is identical to the C implementation, @c gaim_account_option. +The Account API is in the @c Purple::Account:: and @c Purple::Accounts:: packages; +both are nearly identical to their C counterparts, @c purple_account_ and @c +purple_accounts_. The Account Option API is in the @c Purple::Account::Option +package and is identical to the C implementation, @c purple_account_option. The Account* APIs allow scripts to create, remove, and edit accounts. An -account will have the Perl type of "GaimAccount". (Note: Gaim types have no real +account will have the Perl type of "PurpleAccount". (Note: Purple types have no real meaning in perl scripts, other than that the types passed to perl subroutines need to be correct.) This section will not go into detail about the @c -Gaim::Account::Option package since its use is mainly in building protocol +Purple::Account::Option package since its use is mainly in building protocol plugins, which are outside the scope of this document. However, the API for the -@c Gaim::Account::Option package should function as expected, should you need to +@c Purple::Account::Option package should function as expected, should you need to use it. To reduce redundant code, the following code examples will use the simple plugin @@ -77,22 +77,22 @@ my $account_name = "test"; # Create a new Account - print "Testing: Gaim::Account::new()... "; - $account = Gaim::Account->new($account_name, $protocol); + print "Testing: Purple::Account::new()... "; + $account = Purple::Account->new($account_name, $protocol); if ($account) { print "ok.\n"; } else { print "fail.\n"; } # Add a new Account - print "Testing: Gaim::Account::add()..."; - Gaim::Accounts::add($account); + print "Testing: Purple::Account::add()..."; + Purple::Accounts::add($account); print "pending find...\n"; # Find the account we just added to verify its existence - print "Testing: Gaim::Accounts::find()..."; - $account = Gaim::Accounts::find($account_name, $protocol); + print "Testing: Purple::Accounts::find()..."; + $account = Purple::Accounts::find($account_name, $protocol); if ($account) { print "ok.\n"; } else { print "fail.\n"; } # Return the username - print "Testing: Gaim::Account::get_username()... "; + print "Testing: Purple::Account::get_username()... "; $user_name = $account->get_username(); if ($user_name) { print "Success: $user_name.\n"; @@ -100,7 +100,7 @@ print "Failed!\n"; } # Verify if the user is connected - print "Testing: Gaim::Account::is_connected()"; + print "Testing: Purple::Account::is_connected()"; if ($account->is_connected()) { print " Connected.\n"; } else { @@ -109,8 +109,8 @@ # The status mechanism is how users are Connected, set Away, # Disconnected (status set to Offline), etc - # $status is now a Gaim::Status perl type. - print "Testing: Gaim::Accounts::get_active_status()... "; + # $status is now a Purple::Status perl type. + print "Testing: Purple::Accounts::get_active_status()... "; if ($account->get_active_status()) { print "Okay.\n"; } else { @@ -121,10 +121,10 @@ # "available" similarly we can disconnect a user by setting the account # status to "offline" - print "Testing: Gaim::Accounts::connect()...pending...\n"; + print "Testing: Purple::Accounts::connect()...pending...\n"; $account->set_status("available", TRUE); - $account->set_enabled(Gaim::Core::get_ui(), TRUE); + $account->set_enabled(Purple::Core::get_ui(), TRUE); $account->connect(); } @@ -132,17 +132,17 @@ The above code is mostly explained in the comments, however there are a few notable points to make. The variables above are all specialized Perl types that -contain pointers to the actual Gaim types. They can be reassigned at will, just +contain pointers to the actual Purple types. They can be reassigned at will, just like any other variable in Perl. The only way to edit the internal values of a -Gaim type from within perl is to use the accessor methods, e.g. -@c Gaim::Account::get_username(). If you would like to assign a C @c NULL value, +Purple type from within perl is to use the accessor methods, e.g. +@c Purple::Account::get_username(). If you would like to assign a C @c NULL value, simply use @c undef. @section buddylist-api Buddylist, Group and Chat API 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 a @c Gaim::Find package was created to +the @c Purple::BuddyList API should carry over to @c Purple::BuddyList::Chat and +@c Purple::BuddyList::Group. Note that a @c Purple::Find package was created to keep the naming consistent with the C API. @code @@ -154,49 +154,49 @@ # This is how we get an account to use in the following tests. You should replace the username # with an existing user - $account = Gaim::Accounts::find($account_name, $protocol); + $account = Purple::Accounts::find($account_name, $protocol); - # Testing a find function: Note Gaim::Find not Gaim::Buddy:find! + # Testing a find function: Note Purple::Find not Purple::Buddy:find! # Furthermore, this should work the same for chats and groups - Gaim::Debug::info("testplugin", "Testing: Gaim::Find::buddy()..."); - $buddy = Gaim::Find::buddy($account, "BUDDYNAME"); - Gaim::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); + Purple::Debug::info("testplugin", "Testing: Purple::Find::buddy()..."); + $buddy = Purple::Find::buddy($account, "BUDDYNAME"); + Purple::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); # If you should need the handle for some reason, here is how you do it - Gaim::Debug::info("testplugin", "Testing: Gaim::BuddyList::get_handle()..."); - $handle = Gaim::BuddyList::get_handle(); - Gaim::Debug::info("", ($handle ? "ok." : "fail.") . "\n"); + Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::get_handle()..."); + $handle = Purple::BuddyList::get_handle(); + Purple::Debug::info("", ($handle ? "ok." : "fail.") . "\n"); - # This gets the Gaim::BuddyList and references it by $blist - Gaim::Debug::info("testplugin", "Testing: Gaim::get_blist()..."); - $blist = Gaim::get_blist(); - Gaim::Debug::info("", ($blist ? "ok." : "fail.") . "\n"); + # This gets the Purple::BuddyList and references it by $blist + Purple::Debug::info("testplugin", "Testing: Purple::get_blist()..."); + $blist = Purple::get_blist(); + Purple::Debug::info("", ($blist ? "ok." : "fail.") . "\n"); # This is how you would add a buddy named "NEWNAME" with the alias "ALIAS" - Gaim::Debug::info("testplugin", "Testing: Gaim::BuddyList::Buddy::new..."); - $buddy = Gaim::BuddyList::Buddy::new($account, "NEWNAME", "ALIAS"); - Gaim::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); + Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::Buddy::new..."); + $buddy = Purple::BuddyList::Buddy::new($account, "NEWNAME", "ALIAS"); + Purple::Debug::info("", ($buddy ? "ok." : "fail.") . "\n"); # Here we add the new buddy '$buddy' to the group "GROUP" # so first we must find the group - Gaim::Debug::info("testplugin", "Testing: Gaim::Find::group..."); - $group = Gaim::Find::group("GROUP"); - Gaim::Debug::info("", ($group ? "ok." : "fail.") . "\n"); + Purple::Debug::info("testplugin", "Testing: Purple::Find::group..."); + $group = Purple::Find::group("GROUP"); + Purple::Debug::info("", ($group ? "ok." : "fail.") . "\n"); # To add the buddy we need to have the buddy, contact, group and node for insertion. # For this example we can let contact be undef and set the insertion node as the group - Gaim::Debug::info("testplugin", "Testing: Gaim::BuddyList::add_buddy...\n"); - Gaim::BuddyList::add_buddy($buddy, undef, $group, $group); + Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::add_buddy...\n"); + Purple::BuddyList::add_buddy($buddy, undef, $group, $group); # The example that follows gives an indication of how an API call that returns a list is handled. # In this case the buddies of the account found earlier are retrieved and put in an array '@buddy_array' # Further down an accessor method is used, 'get_name()' -- see source for details on the full set of methods - Gaim::Debug::info("testplugin", "Testing: Gaim::Find::buddies...\n"); - @buddy_array = Gaim::Find::buddies($account, undef); + Purple::Debug::info("testplugin", "Testing: Purple::Find::buddies...\n"); + @buddy_array = Purple::Find::buddies($account, undef); if (@buddy_array) { - Gaim::Debug::info("testplugin", "Buddies in list (" . @buddy_array . "): \n"); + Purple::Debug::info("testplugin", "Buddies in list (" . @buddy_array . "): \n"); foreach $bud (@buddy_array) { - Gaim::Debug::info("testplugin", Gaim::BuddyList::Buddy::get_name($bud) . "\n"); + Purple::Debug::info("testplugin", Purple::BuddyList::Buddy::get_name($bud) . "\n"); } } } @@ -204,29 +204,29 @@ The BuddyList API allows plugins to edit buddies in the list, find the buddies for a given account, assign aliases, and further manipulate the structure -as needed. It is also contains methods for accessing @c Gaim::BuddyList::Group -and @c Gaim::BuddyList::Chat types. +as needed. It is also contains methods for accessing @c Purple::BuddyList::Group +and @c Purple::BuddyList::Chat types. @section conn-api Connection API -The @c Gaim::Connection API is one of the many packages that will not be covered +The @c Purple::Connection API is one of the many packages that will not be covered in-depth in this tutorial. It is most useful to protocol plugin developers. -However, the entire @c gaim_connection_ API has corresponding, functioning perl subroutines. +However, the entire @c purple_connection_ API has corresponding, functioning perl subroutines. @section conv-api Conversation API -The Gaim perl APIs for @c gaim_conversation_ and @c gaim_conv_window_ allow +The libpurple perl APIs for @c purple_conversation_ and @c pidgin_conv_window_ allow plugins to interact with existing conversations, create new conversations, and modify conversations at will. In the example script, a new window is created, displayed and a new conversation instant message is created. The following example again replaces the @c plugin_load subroutine in the simple plugin -template. The @c Gaim::Conversation::Chat package handles the -@c gaim_conv_chat_ portion of the API very similarly to how the -Gaim::Conversation::IM package is used in the examples that follow. +template. The @c Purple::Conversation::Chat package handles the +@c purple_conv_chat_ portion of the API very similarly to how the +Purple::Conversation::IM package is used in the examples that follow. -Notice that the interaction with the conversation window is in the @c Gaim::GtkUI package as it -is UI-specific code interacting with gtkgaim and not libgaim. -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 +Notice that the interaction with the conversation window is in the @c Pidgin package as it +is UI-specific code interacting with Pidgin and not libpurple. +To use any of the Pidgin:: functionality, you will need to add the following to the top of your script: @code use Pidgin; @endcode @code @@ -235,27 +235,27 @@ my $protocol = "prpl-oscar"; my $account_name = "test"; - $account = Gaim::Accounts::find($account_name, $protocol); + $account = Purple::Accounts::find($account_name, $protocol); # First we create two new conversations. - print "Testing Gaim::Conversation->new()..."; - $conv1 = Gaim::Conversation->new(1, $account, "Test Conversation 1"); + print "Testing Purple::Conversation->new()..."; + $conv1 = Purple::Conversation->new(1, $account, "Test Conversation 1"); if ($conv1) { print "ok.\n"; } else { print "fail.\n"; } - print "Testing Gaim::Conversation->new()..."; - $conv2 = Gaim::Conversation->new(1, $account, "Test Conversation 2"); + print "Testing Purple::Conversation->new()..."; + $conv2 = Purple::Conversation->new(1, $account, "Test Conversation 2"); if ($conv2) { print "ok.\n"; } else { print "fail.\n"; } # Second we create a window to display the conversations in. - # Note that the package here is Gaim::GtkUI::Conversation::Window - print "Testing Gaim::GtkUI::Conversation::Window->new()...\n"; - $win = Gaim::GtkUI::Conversation::Window->new(); + # Note that the package here is Pidgin::Conversation::Window + print "Testing Pidgin::Conversation::Window->new()...\n"; + $win = Pidgin::Conversation::Window->new(); # The third thing to do is to move second the conversation to a new window. # The subroutine add_gtkconv() returns the number of conversations # present in the window. - print "Testing Gaim::GtkUI::Conversation::Window::add_conversation()..."; - $gtkconv2 = Gaim::GtkUI::Conversation::get_gtkconv($conv2); + print "Testing Pidgin::Conversation::Window::add_conversation()..."; + $gtkconv2 = Pidgin::Conversation::get_gtkconv($conv2); $gtkconv2->get_window()->remove_gtkconv($gtkconv2); $conv_count = $win->add_gtkconv($gtkconv2); if ($conv_count) { @@ -265,19 +265,19 @@ } # Now the window is displayed to the user. - print "Testing Gaim::GtkUI::Conversation::Window::show()...\n"; + print "Testing Pidgin::Conversation::Window::show()...\n"; $win->show(); # Use get_im_data() to get a handle for the conversation - print "Testing Gaim::Conversation::get_im_data()...\n"; + print "Testing Purple::Conversation::get_im_data()...\n"; $im = $conv1->get_im_data(); if ($im) { print "ok.\n"; } else { print "fail.\n"; } # Here we send messages to the conversation - print "Testing Gaim::Conversation::IM::send()...\n"; + print "Testing Purple::Conversation::IM::send()...\n"; $im->send("Message Test."); - print "Testing Gaim::Conversation::IM::write()...\n"; + print "Testing Purple::Conversation::IM::write()...\n"; $conv2->get_im_data()->write("SENDER", "<b>Message</b> Test.", 0, 0); } @endcode @@ -286,11 +286,11 @@ @c $win. @code - print "Testing Gaim::GtkUI::Conversation::Window::get_gtkconv_count()...\n"; + print "Testing Pidgin::Conversation::Window::get_gtkconv_count()...\n"; $conv_count = $win->get_gtkconv_count(); print "...and it returned $conv_count.\n"; if ($conv_count > 0) { - print "Testing Gaim::GtkUI::Conversation::Window::destroy()...\n"; + print "Testing Pidgin::Conversation::Window::destroy()...\n"; $win->destroy(); } @endcode @@ -305,7 +305,7 @@ To first create a standard plugin preference tab, we need specify the @c prefs_info key/value pair in the @c \%PLUGIN_INFO hash. This specifies the -name of the perl subroutine that will build and return a @c Gaim::Pref::Frame. +name of the perl subroutine that will build and return a @c Purple::Pref::Frame. @code %PLUGIN_INFO = { @@ -325,11 +325,11 @@ # Here we are adding a set of preferences # The second argument is the default value for the preference. - Gaim::Prefs::add_none("/plugins/core/perl_test"); - Gaim::Prefs::add_bool("/plugins/core/perl_test/bool", 1); - Gaim::Prefs::add_string("/plugins/core/perl_test/choice_str", "ch1"); - Gaim::Prefs::add_int("/plugins/core/perl_test/choice_int", 1); - Gaim::Prefs::add_string("/plugins/core/perl_test/text", "Foobar"); + Purple::Prefs::add_none("/plugins/core/perl_test"); + Purple::Prefs::add_bool("/plugins/core/perl_test/bool", 1); + Purple::Prefs::add_string("/plugins/core/perl_test/choice_str", "ch1"); + Purple::Prefs::add_int("/plugins/core/perl_test/choice_int", 1); + Purple::Prefs::add_string("/plugins/core/perl_test/text", "Foobar"); } @endcode @@ -338,21 +338,21 @@ @code sub prefs_info_cb { - # The first step is to initialize the Gaim::Pref::Frame that will be returned - $frame = Gaim::PluginPref::Frame->new(); + # The first step is to initialize the Purple::Pref::Frame that will be returned + $frame = Purple::PluginPref::Frame->new(); # Create a new boolean option with a label "Boolean Label" and then add # it to the frame - $ppref = Gaim::PluginPref->new_with_label("Boolean Label"); + $ppref = Purple::PluginPref->new_with_label("Boolean Label"); $frame->add($ppref); - $ppref = Gaim::PluginPref->new_with_name_and_label( + $ppref = Purple::PluginPref->new_with_name_and_label( "/plugins/core/perl_test/bool", "Boolean Preference"); $frame->add($ppref); # Create a set of choices. To do so, we must set the type to 1 which is - # the numerical equivalent of the GaimPrefType for choice. - $ppref = Gaim::PluginPref->new_with_name_and_label( + # the numerical equivalent of the PurplePrefType for choice. + $ppref = Purple::PluginPref->new_with_name_and_label( "/plugins/core/perl_test/choice_str", "Choice Preference"); $ppref->set_type(1); $ppref->add_choice("ch0", "ch0"); @@ -361,8 +361,8 @@ $frame->add($ppref); # Create a set of choices. To do so we must set the type to 1 which is - # the numerical equivalent of the GaimPrefType for choice. - $ppref = Gaim::PluginPref->new_with_name_and_label( + # the numerical equivalent of the PurplePrefType for choice. + $ppref = Purple::PluginPref->new_with_name_and_label( "/plugins/core/perl_test/choice_int", "Choice Preference 2"); $ppref->set_type(1); $ppref->add_choice("zero", 0); @@ -373,7 +373,7 @@ # Create a text box. The default value will be "Foobar" as set by # plugin_load - $ppref = Gaim::PluginPref->new_with_name_and_label( + $ppref = Purple::PluginPref->new_with_name_and_label( "/plugins/core/perl_test/text", "Text Box Preference"); $ppref->set_type(2); $ppref->set_max_length(16); @@ -428,9 +428,9 @@ @section request-api Request Dialog Box API -The @c Gaim::Request package allows plugins to have interactive dialog boxes +The @c Purple::Request package allows plugins to have interactive dialog boxes without the need to directly interact with the UI (e.g. GTK+). This allows core -(libgaim) plugins to create a UI that can be displayed on whichever UI frontend +(libpurple) plugins to create a UI that can be displayed on whichever UI frontend is being used. The portion of the Request API available to perl scripts is listed below, followed by an example illustrating its use. @@ -452,16 +452,16 @@ @code # Create a simple text input box -Gaim::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb); +Purple::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb); # Prompt user to select a file -Gaim::Request::file(handle, title, filename, savedialog, ok_cb, cancel_cb); +Purple::Request::file(handle, title, filename, savedialog, ok_cb, cancel_cb); # Create a unique input dialog as shown in the following example -Gaim::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb); +Purple::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb); @endcode -The following is an example of a @c Gaim::Request::fields() dialog box with a +The following is an example of a @c Purple::Request::fields() dialog box with a callback for the OK button and another for the Cancel Button. @code @@ -469,9 +469,9 @@ # The $fields is passed to the callback function when the button is clicked. # To access a specific field, it must be extracted from $fields by name. $fields = shift; - $account = Gaim::Request::Fields::get_account($fields, "acct_test"); - $int = Gaim::Request::Fields::get_integer($fields, "int_test"); - $choice = Gaim::Request::Fields::get_choice($fields, "ch_test"); + $account = Purple::Request::Fields::get_account($fields, "acct_test"); + $int = Purple::Request::Fields::get_integer($fields, "int_test"); + $choice = Purple::Request::Fields::get_choice($fields, "ch_test"); } sub cancel_cb_test{ @@ -482,34 +482,34 @@ my $plugin = shift; # Create a group to pool together multiple fields. - $group = Gaim::Request::Field::Group::new("Group Name"); + $group = Purple::Request::Field::Group::new("Group Name"); - # Each field is created with Gaim::Request::*_new(), is made viewable with Gaim::Request::field_*_set_show_all() - # and is then added to the group with Gaim::Request::field_group_add_field() + # Each field is created with Purple::Request::*_new(), is made viewable with Purple::Request::field_*_set_show_all() + # and is then added to the group with Purple::Request::field_group_add_field() # Add an account combobox containing all active accounts - $field = Gaim::Request::Field::account_new("acct_test", "Account Text", undef); - Gaim::Request::Field::account_set_show_all($field, 0); - Gaim::Request::Field::Group::add_field($group, $field); + $field = Purple::Request::Field::account_new("acct_test", "Account Text", undef); + Purple::Request::Field::account_set_show_all($field, 0); + Purple::Request::Field::Group::add_field($group, $field); # Add an integer input box - $field = Gaim::Request::Field::int_new("int_test", "Integer Text", 33); - Gaim::Request::Field::Group::add_field($group, $field); + $field = Purple::Request::Field::int_new("int_test", "Integer Text", 33); + Purple::Request::Field::Group::add_field($group, $field); # Add a list of choices - $field = Gaim::Request::Field::choice_new("ch_test", "Choice Text", 1); - Gaim::Request::Field::choice_add($field, "Choice 0"); - Gaim::Request::Field::choice_add($field, "Choice 1"); - Gaim::Request::Field::choice_add($field, "Choice 2"); + $field = Purple::Request::Field::choice_new("ch_test", "Choice Text", 1); + Purple::Request::Field::choice_add($field, "Choice 0"); + Purple::Request::Field::choice_add($field, "Choice 1"); + Purple::Request::Field::choice_add($field, "Choice 2"); - Gaim::Request::Field::Group::add_field($group, $field); + Purple::Request::Field::Group::add_field($group, $field); - # Create a Gaim::Request and add the group that was just created. - $request = Gaim::Request::Fields::new(); - Gaim::Request::Fields::add_group($request, $group); + # Create a Purple::Request and add the group that was just created. + $request = Purple::Request::Fields::new(); + Purple::Request::Fields::add_group($request, $group); # Display the dialog box with the input fields added earlier with the appropriate titles. - Gaim::Request::fields( + Purple::Request::fields( $plugin, "Request Title!", "Primary Title", @@ -523,7 +523,7 @@ @section timeout-cb Misc: Plugin Actions, Timeouts and Callbacks This section of the manual covers some of the important features that can be -added to Gaim perl Plugins. Plugin actions are callback functions that are +added to libpurple perl Plugins. Plugin actions are callback functions that are accessible to the user from the Buddy List window under "Tools -> [Plugin Name]". Timeouts allow a plugin to execute a perl subroutine after a given period of time. Note that timeouts only occur once, so if the timeout must occur periodically, @@ -555,11 +555,11 @@ ); sub action1_cb { - Gaim::Debug::info("Test Plugin", "Action 1 activated\n"); + Purple::Debug::info("Test Plugin", "Action 1 activated\n"); } sub action2_cb { - Gaim::Debug::info("Test Plugin", "Action 2 activated\n"); + Purple::Debug::info("Test Plugin", "Action 2 activated\n"); } @endcode @@ -568,17 +568,17 @@ @code sub timeout_cb { my $plugin = shift; - Gaim::Debug::info("testplugin", "Timeout occurred.\n"); + Purple::Debug::info("testplugin", "Timeout occurred.\n"); # Reschedule timeout - Gaim::timeout_add($plugin, 10, \&timeout_cb, $plugin); + Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin); } sub plugin_load { $plugin = shift; # Schedule a timeout for ten seconds from now - Gaim::timeout_add($plugin, 10, \&timeout_cb, $plugin); + Purple::timeout_add($plugin, 10, \&timeout_cb, $plugin); } @endcode @@ -589,7 +589,7 @@ sub signal_cb { # The signal data and the user data come in as arguments my ($account, $data) = @_; - Gaim::Debug::info("testplugin", "Account \"" . $account->get_username() . "\" just connected.\n"); + Purple::Debug::info("testplugin", "Account \"" . $account->get_username() . "\" just connected.\n"); } sub plugin_load { @@ -599,10 +599,10 @@ $data = ""; # A pointer to the handle to which the signal belongs needed by the callback function - $accounts_handle = Gaim::Accounts::get_handle(); + $accounts_handle = Purple::Accounts::get_handle(); # Connect the perl subroutine 'signal_cb' to the event 'account-connecting' - Gaim::Signal::connect($accounts_handle, "account-connecting", $plugin, \&signal_cb, $data); + Purple::Signal::connect($accounts_handle, "account-connecting", $plugin, \&signal_cb, $data); } @endcode
--- a/doc/TCL-HOWTO.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/TCL-HOWTO.dox Mon Apr 16 02:08:42 2007 +0000 @@ -37,7 +37,7 @@ "Example plugin registration" \ "Example of how to register a plugin for the Tcl HOWTO" \ "Ethan Blanton <eblanton@cs.purdue.edu>" \ - "http://gaim.sf.net/" ] + "http://pidgin.im/" ] } @endcode
--- a/doc/core-signals.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/core-signals.dox Mon Apr 16 02:08:42 2007 +0000 @@ -11,7 +11,7 @@ void (*quitting)(); @endsignalproto @signaldesc - Emitted when gaim is quitting. + Emitted when libpurple is quitting. @endsignaldef */
--- a/doc/plugin-i18n.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/plugin-i18n.dox Mon Apr 16 02:08:42 2007 +0000 @@ -33,7 +33,7 @@ AM_GLIB_GNU_GETTEXT @endcode The position of these macros in the file don't really matter, but if you - have issues either play around with it or feel free to ask one of the Gaim + have issues either play around with it or feel free to ask one of the Pidgin developers. Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command. - Now create a directory named 'po'. - 'cd' into the 'po' directory. @@ -52,7 +52,7 @@ we're done with the autotools part. - When you're ready, 'cd' into the directory with the source files for your plugin. - - Open the file containing the GaimPluginInfo structure. + - Open the file containing the PurplePluginInfo structure. - If you're not already, please make sure that you are including the 'config.h' file for you plugin. Note that 'config.h' could be whatever you told autohead to use with AM_CONFIG_HEADER. Also add the following: @@ -61,13 +61,13 @@ @endcode Make sure that this include is after you include of your 'config.h', otherwise you will break your build. - - This is where things get a bit goofy. Gaim is going to try and translate - our strings using the Gaim gettext package. So we have to convert them - before Gaim attempts to. + - This is where things get a bit goofy. libpurple is going to try and + translate our strings using the libpurple gettext package. So we have to + convert them before libpurple attempts to. - To do this, we're going to change the entries for name, summary, and description to NULL. - Next, locate your 'init_plugin' function. Your name for this function - may vary, but it's the second parameter to 'GAIM_INIT_PLUGIN'. + may vary, but it's the second parameter to 'PURPLE_INIT_PLUGIN'. - Now add the following within your 'init_plugin' function: @code #ifdef ENABLE_NLS
--- a/doc/plugin-ids.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/plugin-ids.dox Mon Apr 16 02:08:42 2007 +0000 @@ -16,7 +16,7 @@ of the following: - core - Core plugin, capable of being loaded in any program using - libgaim. It must not use any UI-specific code. + libpurple. It must not use any UI-specific code. - prpl - Protocol plugin, providing additional protocols to connect to. - lopl - Loader plugin, which loads scripts as plugins (like Perl @@ -34,12 +34,12 @@ The @em pluginname is the name of your plugin. It can be whatever you like, though it's common to keep it all lowercase. Do not use spaces! If you want a space, use a '-'. Please do not put a version indicator in the ID. - The GaimPlugin structure already has a field for this. + The PurplePlugin structure already has a field for this. @section plugin-db Plugin Database Although it doesn't exist yet, in time there will be a plugin database - on the Gaim website, where users can download and install new plugins. + on the Pidgin website, where users can download and install new plugins. Plugins will be accessed by your plugin ID, which is one reason why it must be unique.
--- a/doc/sound-signals.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/sound-signals.dox Mon Apr 16 02:08:42 2007 +0000 @@ -11,7 +11,7 @@ gboolean (*playing_sound_event)(PurpleSoundEventID event, PurpleAccount *account); @endsignalproto @signaldesc - Emitted when gaim is going to play a sound event. This can be used to cancel playing sound by returning TRUE. + Emitted when libpurple is going to play a sound event. This can be used to cancel playing sound by returning TRUE. @param event The event this sound represents. @param account The account the sound is being played for. @return @c TRUE if the sound should not be played, or @c FALSE otherwise.
--- a/doc/xfer-signals.dox Mon Apr 16 02:08:18 2007 +0000 +++ b/doc/xfer-signals.dox Mon Apr 16 02:08:42 2007 +0000 @@ -62,8 +62,8 @@ Emitted before the user is prompted for an incoming file-transfer. Plugins can intercept the signal to auto-accept/auto-reject the requests. To auto-accept the file transfer, use - gaim_xfer_request_accepted(). To auto-reject, set the status of the - xfer to GAIM_XFER_STATUS_CANCEL_LOCAL. + purple_xfer_request_accepted(). To auto-reject, set the status of the + xfer to PURPLE_XFER_STATUS_CANCEL_LOCAL. @param xfer The file transfer @param data User data @endsignaldef