comparison doc/PERL-HOWTO.dox @ 12364:6fd82071a7b8

[gaim-migrate @ 14668] sf patch #1373688, from Will Thompson "Make the Perl bindings more Perl-ish" committer: Tailor Script <[e-mail]>

12363:f758af0373cb

The last step is to save the script with a .pl file extention in your ~/.gaim/plugins directory.  After restarting gaim the plugin "Perl Test Plugin" should now appear under "Tools->Preferences->Plugins".  To view the messages make sure you run Gaim from the console with the '-d' flag or open the Debug Window from inside Gaim under "Help".  When you enable the checkbox next the plugin you should see a message appear in the Debug Window (or console) and when you disable the checkbox you should see another message appear.  You have now created the framework that will allow you to create almost any kind of Gaim plugin you can imagine.

@section account-api Account and Account Option Functions

The Account API is in the @c Gaim::Account:: and @c Gaim::Accounts:: packages and both are nearly identical to their C counterparts @c gaim_account_ and @c gaim_accounts_.  The Account Option API is in the package @c Gaim::Account::Option and is identical to its C implementation @c gaim_account_option .  

The Account* APIs allow for scripts to create, remove, and edit accounts of the type GaimAccount. (Note: Gaim type have no real meaning in perl scripts other than the types of the arguments of the perl subroutines need to be of the expected type.)  This section will not go into detail about the @c Gaim::Account::Option package for its use in building protocol plugins which are outside the scope of this document.  However, most of the API calls for the @c Gaim::Account::Option package should function as expected so if there is a need to access any of the Account Options the function calls necessary are avaialbe in the Gaim perl API.

To reduce redundant code the following code examples are going to use the template shown in the previous section.  To highlight some of the more useful features of the Account API we will be replacing the @c plugin_load perl subroutine.  For testing purposes we will display output on the command line by using perl @c print commands.   

@code
sub plugin_load {
	$plugin = shift;

	# Testing was done using Oscar, but this should work regardless of the protocol chosen
	my $protocol = "prpl-oscar";

	# Create a new Account
        print "Testing: Gaim::Account::new()...";
        $account = Gaim::Account::new("TEST_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 "pending find...\n";

        print "Testing: Gaim::Accounts::find()...";
        $account = Gaim::Accounts::find("TEST_NAME", $protocol);
        if ($account) { print "ok.\n"; } else { print "fail.\n"; }

	# Return the username 
        print "Testing: Gaim::Account::get_username()...";
        $user_name = Gaim::Account::get_username($account);
        if ($user_name) { print $user_name . "...ok.\n"; } else { print "fail.\n"; }

	# Verify if the user is connected
        print "Testing: Gaim::Account::is_connected()";
        $user_connected = Gaim::Account::is_connected($account);
        if (!($user_connected)) { print "...not connected...ok..\n"; } else { print "...connected...ok.\n"; }

	# 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 = Gaim::Account::get_active_status($account);
        if ($status) { print "ok.\n"; } else { print "fail.\n"; }

	# It follows that to connect a user you mest set the account status to "available"
	#  similarly we can disconnect a user by setting the account status to "offline"
        $account = Gaim::Accounts::find("TEST_NAME", $protocol);
        print "Testing: Gaim::Accounts::connect()...pending...\n";

        Gaim::Account::set_status($account, "available", TRUE);
        Gaim::Account::connect($account);
}
@endcode

For the most part the code listed above is explained by the comments, however there are a few other points to make.  The variables above are all specialized Perl types that contain pointers to the actual Gaim types.  They can be reasigned at will just like any other variable in Perl.  The only way to edit the values of a Gaim type from within perl are through accessor methods such as @c Gaim::Account::get_username().  For arguments that you would make @c NULL in C should be set to @c undef in Perl.  

@section buddylist-api Buddylist, Group and Chat API

The BuddList, Group and Chat APIs are very similar and whatever is shown for the @c Gaim::BuddlyList API should carry over to @c Gaim::Chat and @c Gaim::Group.  Note that there is a @c Gaim::Find pacakge that was created to keep the naming consistent with how these functions are named in the C API.

Now we can add these preferences from inside our function specified in @c \%PLUGIN_INFO .

@code
sub prefs_info_cb {
	# The first step is to initialize the Gaim::Pref::Frame that will be returned
        $frame = Gaim::Pref::frame_new();

	# Create a new boolean option with a label "Boolean Label" and then add it to the frame
        $ppref = Gaim::Pref::new_with_label("Boolean Label");
        Gaim::Pref::frame_add($frame, $ppref);

        $ppref = Gaim::Pref::new_with_name_and_label("/plugins/core/perl_test/bool", "Boolean Preference");
        Gaim::Pref::frame_add($frame, $ppref);

	# Create a set of choices.  To do so we must set the type to 1 which is the numerical equivelant of 
	#  the GaimPrefType for choice.
        $ppref = Gaim::Pref::new_with_name_and_label("/plugins/core/perl_test/choice", "Choice Preference");
        Gaim::Pref::set_type($ppref, 1);
        Gaim::Pref::add_choice($ppref, "ch0", $frame);
	# The following will be the default value as set from plugin_load
        Gaim::Pref::add_choice($ppref, "ch1", $frame);
        Gaim::Pref::frame_add($frame, $ppref);

	# Create a text box.  The default value will be "Foobar" as set by plugin_load
        $ppref = Gaim::Pref::new_with_name_and_label("/plugins/core/perl_test/text", "Text Box Preference");
        Gaim::Pref::set_max_length($ppref, 16);
        Gaim::Pref::frame_add($frame, $ppref);

        return $frame;
}
@endcode

12364:6fd82071a7b8

The last step is to save the script with a .pl file extention in your ~/.gaim/plugins directory.  After restarting gaim the plugin "Perl Test Plugin" should now appear under "Tools->Preferences->Plugins".  To view the messages make sure you run Gaim from the console with the '-d' flag or open the Debug Window from inside Gaim under "Help".  When you enable the checkbox next the plugin you should see a message appear in the Debug Window (or console) and when you disable the checkbox you should see another message appear.  You have now created the framework that will allow you to create almost any kind of Gaim plugin you can imagine.

@section account-api Account and Account Option Functions

The Account API is in the @c Gaim::Account:: and @c Gaim::Accounts:: packages
and both are nearly identical to their C counterparts @c gaim_account_ and @c
gaim_accounts_.  The Account Option API is in the package @c
Gaim::Account::Option and is identical to its C implementation @c
gaim_account_option.

The Account* APIs allow for scripts to create, remove, and edit accounts of the
type GaimAccount. (Note: Gaim types have no real meaning in perl scripts other
than the types of the arguments of the perl subroutines need to be of the
expected type.)  This section will not go into detail about the @c
Gaim::Account::Option package for its use in building protocol plugins which
are outside the scope of this document.  However, most of the API calls for the
@c Gaim::Account::Option package should function as expected so if there is a
need to access any of the Account Options the function calls necessary are
avaialbe in the Gaim perl API.

To reduce redundant code the following code examples are going to use the
template shown in the previous section.  To highlight some of the more useful
features of the Account API we will be replacing the @c plugin_load perl
subroutine.  For testing purposes we will display output on the command line by
using perl @c print commands.

@code
sub plugin_load {
	$plugin = shift;

	# Testing was done using Oscar, but this should work regardless of the protocol chosen
	my $protocol = "prpl-oscar";

	# Create a new Account
	print "Testing: Gaim::Account::new()... ";
	$account = Gaim::Account->new($TEST_NAME, $PROTOCOL_ID);
	if ($account) { print "ok.\n"; } else { print "fail.\n"; }

	# Add a new Account
        print "Testing: Gaim::Account::add()...";
        Gaim::Accounts::add($account);
                print "pending find...\n";

        print "Testing: Gaim::Accounts::find()...";
        $account = Gaim::Accounts::find("TEST_NAME", $protocol);
        if ($account) { print "ok.\n"; } else { print "fail.\n"; }

	# Return the username 
	print "Testing: Gaim::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: Gaim::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 Gaim::Status perl type.
	print "Testing: Gaim::Accounts::get_active_status()... ";
	if ($account->get_active_status()) {
		print "Okay.\n";
	} else {
		print "Failed!\n";
	}

	# It follows that to connect a user you mest set the account status to
	# "available" similarly we can disconnect a user by setting the account
	# status to "offline"

        $account = Gaim::Accounts::find("TEST_NAME", $protocol);
        print "Testing: Gaim::Accounts::connect()...pending...\n";

	$account->set_status("available", TRUE);
	$account->connect();

}
@endcode

For the most part the code listed above is explained by the comments, however
there are a few other points to make.  The variables above are all specialized
Perl types that contain pointers to the actual Gaim types.  They can be
reasigned at will just like any other variable in Perl.  The only way to edit
the values of a Gaim type from within perl are through accessor methods such as
@c Gaim::Account::get_username().  For arguments that you would make @c NULL in
C should be set to @c undef in Perl.

@section buddylist-api Buddylist, Group and Chat API

The BuddList, Group and Chat APIs are very similar and whatever is shown for the @c Gaim::BuddlyList API should carry over to @c Gaim::Chat and @c Gaim::Group.  Note that there is a @c Gaim::Find pacakge that was created to keep the naming consistent with how these functions are named in the C API.

Now we can add these preferences from inside our function specified in @c \%PLUGIN_INFO .

@code
sub prefs_info_cb {
	# The first step is to initialize the Gaim::Pref::Frame that will be returned
        $frame = Gaim::PluginPref::Frame->new();

	# Create a new boolean option with a label "Boolean Label" and then add
	# it to the frame
        $ppref = Gaim::Pref->new_with_label("Boolean Label");
	$frame->add($ppref);

	$ppref = Gaim::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 equivelant of the GaimPrefType for choice.
	$ppref = Gaim::PluginPref->new_with_name_and_label(
	    "/plugins/core/perl_test/choice", "Choice Preference");
	$ppref->set_type(1);
	$ppref->add_choice("ch0", $frame);
	# The following will be the default value as set from plugin_load
	$ppref->add_choice("ch1", $frame);
	$frame->add($ppref);

	# Create a text box.  The default value will be "Foobar" as set by
	# plugin_load
	$ppref = Gaim::PluginPref->new_with_name_and_label(
	    "/plugins/core/perl_test/text", "Text Box Preference");
	$ppref->set_max_length(16);
	$frame->add($ppref);

        return $frame;
}
@endcode