NAME
Padre::Plugin - Padre Plugin API
SYNOPSIS
package Padre::Plugin::Foo;
use strict;
use base 'Padre::Plugin';
# Declare the Padre classes we use and Padre version the code was written to
sub padre_interfaces {
'Padre::Document::Perl' => 0.16,
'Padre::Wx::MainWindow' => 0.16,
'Padre::DB' => 0.16,
}
# The plugin name to show in the Plugins menu
# The command structure to show in the Plugins menu
sub menu_plugins_simple {
'My Plugin' => [
About => sub { $self->show_about },
Deep => [
'Do Something' => sub { $self->do_something },
],
];
}
1;METHODS
padre_interfaces
sub padre_interfaces {
'Padre::Document::Perl' => 0.16,
'Padre::Wx::MainWindow' => 0.16,
'Padre::DB' => 0.16,
}In Padre, plugins are permitted to make relatively deep calls into Padre's internals.
To compensate for any potential problems with API compatibility, the second generation Padre Plugin Manager will will look for each Plugin module to define the Padre classes that the Plugin uses, and the version of Padre that the code was originally written against.
This information will be used by the plugin manager to calculate whether or not the Plugin is still compatible with Padre.
The list of used interfaces should be provided as a list of class/version pairs, as shown in the example.
The padre_interfaces method will be called on the class, not on the plugin object. By default, this method returns nothing.
In future, plugins that do NOT supply compatibility information may be disabled unless the user has specifically allowed experimental plugins.
new
The new constructor takes no parameters. When a plugin is loaded, Padre will instantiate one plugin object for each plugin, to provide the plugin with a location to store any private or working data.
A default constructor is provided that creates an empty HASH-based object.
plugin_enable
The plugin_enable object method will be called (at an arbitrary time of Padre's choosing) to allow the plugin object to initialise and start up the Plugin.
This may involve loading any config files, hooking into existing documents or editor windows, and otherwise doing anything needed to bootstrap operations.
Please note that Padre will block until this method returns, so you should attempt to complete return as quickly as possible.
Any modules that you may use should NOT be loaded during this phase, but should be requireed when they are needed, at the last moment.
Returns true if the plugin started up ok, or false on failure.
The default implementation does nothing, and returns true.
plugin_disable
The plugin_disable method is called by Padre for various reasons to request the plugin do whatever tasks are necesary to shut itself down. This also provides an opportunity to save configuration information, save caches to disk, and so on.
Most often, this will be when Padre itself is shutting down. Other uses may be when the user wishes to disable the plugin, when the plugin is being reloaded, or if the plugin is about to be upgraded.
If you have any private classes other than the standard Padre::Plugin::Foo, you should unload them as well as the plugin may be in the process of upgrading and will want those classes freed up for use by the new version.
The recommended way of unloading your extra classes is using Class::Unload. Suppose you have My::Extra::Class and want to unload it, simply do this in plugin_disable:
require Class::Unload;
Class::Unload->unload( "My::Extra::Class" );Class::Unload takes care of all the tedious bits for you. Note that you shouldn't unload any extra, external CPAN dependencies at this point since they might be required by other plugins.
Returns true on success, or false if the unloading process failed.
menu_plugins_simple
sub menu_plugins_simple {
'My Plugin' => [
About => sub { $self->show_about },
Deep => [
'Do Something' => sub { $self->do_something },
],
];
}The menu_plugins_simple method defines a simple menu structure for your plugin.
It returns two values, the label for the menu entry to be used in the top level Plugins menu, and a reference to an ARRAY containing an ordered set of key/value pairs that will be turned into menus.
More complex plugins that need full control over the menu will be addressed in the next release.
If the method return a null list, no menu entry will be created for the plugin.
editor_enable
sub editor_enable {
my $self = shift;
my $editor = shift;
my $document = shift;
# Make changes to the editor here...
return 1;
}The editor_enable method is called by Padre to provide the plugin with an opportunity to alter the setup of the editor as it is being loaded.
This method is only triggered when new editor windows are opened. Hooking into any existing open documents must be done within the plugin_enable method.
The method is passed two parameters, the fully set up editor object, and the Padre::Document being opened.
At the present time, this method has been provided primarily for the use of the Padre::Plugin::Vi plugin and other plugins that need deep integration with the editor widget.
editor_disable
sub editor_disable {
my $self = shift;
my $editor = shift;
my $document = shift;
# Undo your changes to the editor here...
return 1;The editor_disable method is the twin of the previous editor_enable method. It is called as the file in the editor is being closed, AFTER the used has confirmed the file is to be closed.
It provides the plugin with an opportunity to clean up, remove any gui customisations, and complete any other shutdown/close processes.
The method is passed two parameters, the fully set up editor object, and the Padre::Document being closed.
At the present time, this method has been provided primarily for the use of the Padre::Plugin::Vi plugin and other plugins that need deep integration with the editor widget.
AUTHOR
Adam Kennedy adamk@cpan.org
SEE ALSO
COPYRIGHT
Copyright 2008 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.