Provided by: padre_0.90.ds1-1_all bug

NAME

       Padre::Plugin - Padre plug-in API 2.2

SYNOPSIS

         package Padre::Plugin::Foo;

         use strict;
         use base 'Padre::Plugin';

         # The plug-in name to show in the Plug-in Manager and menus
         sub plugin_name {
             'Example Plug-in';
         }

         # Declare the Padre interfaces this plug-in uses
         sub padre_interfaces {
             'Padre::Plugin'         => 0.29,
             'Padre::Document::Perl' => 0.29,
             'Padre::Wx::Main'       => 0.29,
             'Padre::DB'             => 0.29,
         }

         # The command structure to show in the Plug-ins menu
         sub menu_plugins_simple {
             my $self = shift;
             return $self->plugin_name => [
                 'About'   => sub { $self->show_about },
                 'Submenu' => [
                     'Do Something' => sub { $self->do_something },
                 ],
             ];
         }

         1;

STATIC/CLASS METHODS

   "plugin_name"
       The "plugin_name" method will be called by Padre when it needs a name to display in the
       user interface.

       The default implementation will generate a name based on the class name of the plug-in.

   "plugin_directory_share"
       The "plugin_directory_share" method finds the location of the shared files directory for
       the plug-in, if one exists.

       Returns a path string if the share directory exists, or "undef" if not.

   "plugin_directory_locale"
       The "plugin_directory_locale()" method will be called by Padre to know where to look for
       your plug-in l10n catalog.

       It defaults to $sharedir/locale (with $sharedir as defined by "File::ShareDir" and thus
       should work as is for your plug-in if you're using the "install_share" command of
       Module::Install. If you are using Module::Build version 0.36 and later, please use the
       "share_dir" new() argument.

       Your plug-in catalogs should be named $plugin-$locale.po (or .mo for the compiled form)
       where $plugin is the class name of your plug-in with any character that are illegal in
       file names (on all file systems) flattened to underscores.

       That is, Padre__Plugin__Vi-de.po for the German locale of "Padre::Plugin::Vi".

   "plugin_icon"
       The "plugin_icon" method will be called by Padre when it needs an icon to display in the
       user interface. It should return a 16x16 "Wx::Bitmap" object.

       The default implementation will look for an icon at the path
       $plugin_directory_share/icons/16x16/logo.png and load it for you.

   "plugin_wizards"
       The "plugin_wizards" method will be called by Padre when it retrieves the wizard list.

       The default implementation returns an empty list

   "padre_interfaces"
         sub padre_interfaces {
             'Padre::Plugin'         => 0.43,
             'Padre::Document::Perl' => 0.35,
             'Padre::Wx::Main'       => 0.43,
             'Padre::DB'             => 0.25,
         }

       In Padre, plug-ins are permitted to make relatively deep calls into Padre's internals.
       This allows a lot of freedom, but comes at the cost of allowing plug-ins to damage or
       crash the editor.

       To help compensate for any potential problems, the Plug-in Manager expects each plug-in
       module to define the Padre classes that the plug-in uses, and the version of Padre that
       the code was originally written against (for each class).

       This information will be used by the Plug-in Manager to calculate whether or not the plug-
       in is still compatible with Padre.

       The list of 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 plug-in object. By
       default, this method returns nothing.

       In future, plug-ins that do not supply compatibility information may be disabled unless
       the user has specifically allowed experimental plug-ins.

CONSTRUCTORS

   "new"
       The new constructor takes no parameters. When a plug-in is loaded, Padre will instantiate
       one plug-in object for each plug-in, to provide the plug-in with a location to store any
       private or working data.

       A default constructor is provided that creates an empty hash-based object.

INSTANCE METHODS

   "registered_documents"
         sub registered_documents {
             'application/javascript' => 'Padre::Plugin::JavaScript::Document',
             'application/json'       => 'Padre::Plugin::JavaScript::Document',
         }

       The "registered_documents" methods can be used by a plug-in to define document types for
       which the plug-in provides a document class (which is used by Padre to enable
       functionality beyond the level of a plain text file with simple Scintilla highlighting).

       This method will be called by the Plug-in Manager and the information returned will be
       used to populate various internal data structures and perform various other tasks. Plug-in
       authors are expected to provide this information without having to know how or why Padre
       will use it.

       This (theoretically at this point) should allow Padre to keep a document open while a
       plug-in is being enabled or disabled, upgrading or downgrading the document in the
       process.

       The method call is made on the plug-in object, and returns a list of MIME type to class
       pairs. By default the method returns a null list, which indicates that the plug-in does
       not provide any document types.

   "provided_highlighters"
       Default method returning an empty array.

       TO DO. See Padre::Document.

   "highlighting_mime_types"
       TO DO. See Padre::Document.

   "event_on_context_menu"
         sub event_on_context_menu {
           my ($self, $document, $editor, $menu, $event) = (@_);

           # create our own menu section
           $menu->AppendSeparator;

           my $item = $menu->Append( -1, _T('Mutley, do something') );
           Wx::Event::EVT_MENU(
               $self->main,
               $item,
               sub { Wx::MessageBox('sh sh sh sh', 'Mutley', Wx::wxOK, shift) },
           );
         }

       If implemented in a plug-in, this method will be called when a context menu is about to be
       displayed either because the user pressed the right mouse button in the editor window
       ("Wx::MouseEvent") or because the "Right-click" menu entry was selected in the "Window"
       menu ("Wx::CommandEvent"). The context menu object was created and populated by the Editor
       and then possibly augmented by the "Padre::Document" type (see "event_on_right_down" in
       Padre::Document).

       Parameters retrieved are the objects for the document, the editor, the context menu
       ("Wx::Menu") and the event.

       Have a look at the implementation in Padre::Document::Perl for a more thorough example,
       including how to manipulate the active document.

   "plugin_enable"
       The "plugin_enable" object method will be called (at an arbitrary time of Padre's
       choosing) to allow the plug-in object to initialise and start up the plug-in.

       This may involve loading any configuration 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
       "require"ed when they are needed, at the last moment.

       Returns true if the plug-in started up successfully, 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 plug-in
       do whatever tasks are necessary 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 plug-in, when the plug-in is being reloaded, or if the plug-in
       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 plug-in 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 should not unload
       any external "CPAN" dependencies, as these may be needed by other plug-ins or Padre
       itself. Only classes that are part of your plug-in should be unloaded.

       Returns true on success, or false if the unloading process failed and your plug-in has
       been left in an unknown state.

   "config_read"
         my $hash = $self->config_read;
         if ( $hash ) {
             print "Loaded existing configuration\n";
         } else {
             print "No existing configuration";
         }

       The "config_read" method provides access to host-specific configuration stored in a
       persistent location by Padre.

       At this time, the configuration must be a nested, non-cyclic structure of "HASH"
       references, "ARRAY" references and simple scalars (the use of "undef" values is permitted)
       with a "HASH" reference at the root.

       Returns a nested "HASH"-root structure if there is an existing saved configuration for the
       plug-in, or "undef" if there is no existing saved configuration for the plug-in.

   "config_write"
         $self->config_write( { foo => 'bar' } );

       The "config_write" method is used to write the host-specific configuration information for
       the plug-in into the underlying database storage.

       At this time, the configuration must be a nested, non-cyclic structure of "HASH"
       references, "ARRAY" references and simple scalars (the use of "undef" values is permitted)
       with a "HASH" reference at the root.

   "plugin_preferences"
         $plugin->plugin_preferences($wx_parent);

       The "plugin_preferences" method allows a plug-in to define an entry point for the Plug-in
       Manager dialog to trigger to show a preferences or configuration dialog for the plug-in.

       The method is passed a Wx object that should be used as the Wx parent.

   "menu_plugins_simple"
         sub menu_plugins_simple {
             'My Plug-in' => [
                 Submenu  => [
                     'Do Something' => sub { $self->do_something },
                 ],

                 # Separator
                 '---' => undef,

                 # Shorthand for sub { $self->show_about(@_) }
                 About => 'show_about',

                 # Also use keyboard shortcuts to call sub { $self->show_about(@_) }
                 "Action\tCtrl+Shift+Z" => 'action',
             ];
         }

       The "menu_plugins_simple" method defines a simple menu structure for your plug-in.

       It returns two values, the label for the menu entry to be used in the top level Plug-ins
       menu, and a reference to an ARRAY containing an ordered set of key/value pairs that will
       be turned into menus.

       If the key is a string of three hyphens (i.e. "---") the pair will be rendered as a menu
       separator.

       If the key is a string containing a tab ("\t") and a keyboard shortcut combination the
       menu action will also be available through a keyboard shortcut.

       If the value is a Perl identifier, it will be treated as a method name to be called on the
       plug-in object when the menu entry is triggered.

       If the value is a reference to an ARRAY, the pair will be rendered as a sub-menu
       containing further menu items.

   "menu_plugins"
         sub menu_plugins {
             my $self = shift;
             my $main = shift;

             # Create a simple menu with a single About entry
             my $menu = Wx::Menu->new;
             Wx::Event::EVT_MENU(
                 $main,
                 $menu->Append( -1, 'About', ),
                 sub { $self->show_about },
             );

             # Return it and the label for our plug-in
             return ( $self->plugin_name => $menu );

       The "menu_plugins" method defines a fully-featured mechanism for building your plug-in
       menu.

       It returns two values, the label for the menu entry to be used in the top level Plug-ins
       menu, and a Wx::Menu object containing the custom-built menu structure.

       A default implementation of this method is provided which will call "menu_plugins_simple"
       and implements the expansion of the simple data into a full menu structure.

       If the method return a null list, no menu entry will be created for the plug-in.

   "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 plug-in 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 plug-in and other plug-ins 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 user has confirmed the file is
       to be closed.

       It provides the plug-in 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 plug-in and other plug-ins that need deep integration with the editor
       widget.

   "ide"
       The "ide" convenience method provides access to the root-level Padre IDE object,
       preventing the need to go via the global "Padre->ide" method.

   "main"
       The "main" convenience method provides direct access to the Padre::Wx::Main (main window)
       object.

   "current"
       The "current" convenience method provides a Padre::Current context object for the current
       plug-in.

SEE ALSO

       Padre

COPYRIGHT

       Copyright 2008-2011 The Padre development team as listed in Padre.pm.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl 5 itself.

       The full text of the license can be found in the LICENSE file included with this module.