/soc/2013/ankitkv/gobjectification: 423fbe5e5289: Moved *.dox fi...
Ankit Vani
a at nevitus.org
Sun Oct 13 06:19:46 EDT 2013
Changeset: 423fbe5e5289762d8e37a519842caf2521b88818
Author: Ankit Vani <a at nevitus.org>
Date: 2013-10-13 15:41 +0530
Branch: soc.2013.gobjectification.plugins
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/423fbe5e5289
Description:
Moved *.dox files to the reference directory and removed perl, tcl howtos for now
diffstat:
doc/Makefile.am | 31 +--
doc/PERL-HOWTO.dox | 613 -------------------------------------------
doc/TCL-HOWTO.dox | 362 -------------------------
doc/TracFooter.html | 2 -
doc/TracHeader.html | 2 -
doc/C-HOWTO.dox | 0
doc/SIGNAL-HOWTO.dox | 0
doc/account-signals.dox | 0
doc/blist-signals.dox | 0
doc/certificate-signals.dox | 0
doc/cmd-signals.dox | 0
doc/connection-signals.dox | 0
doc/conversation-signals.dox | 0
doc/core-signals.dox | 0
doc/dbus-server-signals.dox | 0
doc/imgstore-signals.dox | 0
doc/jabber-signals.dox | 0
doc/log-signals.dox | 0
doc/notify-signals.dox | 0
doc/plugin-i18n.dox | 0
doc/plugin-ids.dox | 0
doc/plugin-signals.dox | 0
doc/protocol-signals.dox | 0
doc/savedstatus-signals.dox | 0
doc/sound-signals.dox | 0
doc/ui-ops.dox | 0
doc/xfer-signals.dox | 0
doc/gtkaccount-signals.dox | 0
doc/gtkblist-signals.dox | 0
doc/gtkconv-signals.dox | 0
doc/gtkimhtml-signals.dox | 0
doc/gtklog-signals.dox | 0
32 files changed, 1 insertions(+), 1009 deletions(-)
diffs (truncated from 1122 to 300 lines):
diff --git a/doc/Makefile.am b/doc/Makefile.am
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -13,37 +13,8 @@ man_MANS += finch.1
endif
EXTRA_DIST = \
- C-HOWTO.dox \
- PERL-HOWTO.dox \
- SIGNAL-HOWTO.dox \
- TCL-HOWTO.dox \
- TracFooter.html \
- TracHeader.html \
- account-signals.dox \
- blist-signals.dox \
- certificate-signals.dox \
- connection-signals.dox \
- conversation-signals.dox \
- core-signals.dox \
- dbus-server-signals.dox \
funniest_home_convos.txt \
finch.1.in \
- gtkaccount-signals.dox \
- gtkblist-signals.dox \
- gtkconv-signals.dox \
- gtklog-signals.dox \
- gtkimhtml-signals.dox \
gtkrc-2.0 \
- imgstore-signals.dox \
- jabber-signals.dox \
- log-signals.dox \
- notify-signals.dox \
pidgin.1.in \
- plugin-i18n.dox \
- plugin-ids.dox \
- plugin-signals.dox \
- protocol-signals.dox \
- savedstatus-signals.dox \
- sound-signals.dox \
- the_penguin.txt \
- xfer-signals.dox
+ the_penguin.txt
diff --git a/doc/PERL-HOWTO.dox b/doc/PERL-HOWTO.dox
deleted file mode 100644
--- a/doc/PERL-HOWTO.dox
+++ /dev/null
@@ -1,613 +0,0 @@
-/** @page perl-howto Perl Scripting HOWTO
-
- at section Introduction
-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 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.
-
- at section first-script Writing your first script
-
-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.
-
- at code
-use Purple;
-
-%PLUGIN_INFO = (
- perl_api_version => 2,
- name => "Perl Test Plugin",
- version => "0.1",
- summary => "Test plugin for the Perl interpreter.",
- description => "Your description here",
- author => "John H. Kelm <johnhkelm\@gmail.com",
- url => "https://pidgin.im",
-
- load => "plugin_load",
- unload => "plugin_unload"
-);
-
-sub plugin_init {
- return %PLUGIN_INFO;
-}
-
-sub plugin_load {
- my $plugin = shift;
- Purple::Debug::info("testplugin", "plugin_load() - Test Plugin Loaded.\n");
-}
-
-sub plugin_unload {
- my $plugin = shift;
- Purple::Debug::info("testplugin", "plugin_unload() - Test Plugin Unloaded.\n");
-}
- at endcode
-
-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 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 ~/.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.
-
- at section account-api Account and Account Option Functions
-
-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 "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
-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
- at 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
-from the previous section as a template. To highlight some of the more useful
-features of the Account API, we will be replacing the @c plugin_load perl
-subroutine. For testing purposes, we will display output on the command line by
-using perl @c print commands.
-
- at code
-sub plugin_load {
- $plugin = shift;
-
- # Testing was done using AIM, but this should work regardless of the protocol chosen
- my $protocol = "aim";
- my $account_name = "test";
-
- # Create a new Account
- 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: Purple::Account::add()...";
- Purple::Accounts::add($account);
- print "pending find...\n";
-
- # Find the account we just added to verify its existence
- 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: Purple::Account::get_username()... ";
- $user_name = $account->get_username();
- if ($user_name) {
- print "Success: $user_name.\n";
- } else {
- print "Failed!\n";
- }
- # Verify if the user is connected
- print "Testing: Purple::Account::is_connected()";
- if ($account->is_connected()) {
- print " Connected.\n";
- } else {
- print " Disconnected.\n";
- }
-
- # The status mechanism is how users are Connected, set Away,
- # Disconnected (status set to Offline), etc
- # $status is now a Purple::Status perl type.
- print "Testing: Purple::Accounts::get_active_status()... ";
- if ($account->get_active_status()) {
- print "Okay.\n";
- } else {
- print "Failed!\n";
- }
-
- # It follows that to connect a user you must set the account status to
- # "available" similarly we can disconnect a user by setting the account
- # status to "offline"
-
- print "Testing: Purple::Accounts::connect()...pending...\n";
-
- $account->set_status("available", TRUE);
- $account->set_enabled(Purple::Core::get_ui(), TRUE);
- $account->connect();
-
-}
- at endcode
-
-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 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
-Purple type from within perl is to use the accessor methods, e.g.
- at c Purple::Account::get_username(). If you would like to assign a C @c NULL value,
-simply use @c undef.
-
- at section buddylist-api Buddylist, Group and Chat API
-
-The BuddyList, Group and Chat APIs are very similar and whatever is shown for
-the @c Purple::BuddyList API should carry over to @c Purple::BuddyList::Chat and
- at c Purple::BuddyList::Group. Note that a @c Purple::Find package was created to
-keep the naming consistent with the C API.
-
- at code
-sub plugin_load {
- my $plugin = shift;
-
- my $protocol = "aim";
- my $account_name = "test";
-
- # This is how we get an account to use in the following tests. You should replace the username
- # with an existing user
- $account = Purple::Accounts::find($account_name, $protocol);
-
- # Testing a find function: Note Purple::Find not Purple::Buddy:find!
- # Furthermore, this should work the same for chats and groups
- 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
- Purple::Debug::info("testplugin", "Testing: Purple::BuddyList::get_handle()...");
- $handle = Purple::BuddyList::get_handle();
- Purple::Debug::info("", ($handle ? "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"
- 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
- 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
- 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
- Purple::Debug::info("testplugin", "Testing: Purple::Find::buddies...\n");
- @buddy_array = Purple::Find::buddies($account, undef);
- if (@buddy_array) {
- Purple::Debug::info("testplugin", "Buddies in list (" . @buddy_array . "): \n");
- foreach $bud (@buddy_array) {
- Purple::Debug::info("testplugin", Purple::BuddyList::Buddy::get_name($bud) . "\n");
- }
- }
-}
- at endcode
-
-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 Purple::BuddyList::Group
-and @c Purple::BuddyList::Chat types.
-
- at section conn-api Connection API
-
-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 purple_connection_ API has corresponding, functioning perl subroutines.
-
- at section conv-api Conversation API
-
-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 Purple::Conversation::Chat package handles the
- at 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 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
-
-
- at code
-sub plugin_load {
- my $plugin = shift;
- my $protocol = "aim";
- my $account_name = "test";
-
- $account = Purple::Accounts::find($account_name, $protocol);
-
- # First we create two new conversations.
- 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 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 Pidgin::Conversation::Window
- print "Testing Pidgin::Conversation::Window->new()...\n";
- $win = Pidgin::Conversation::Window->new();
-
More information about the Commits
mailing list