| 1 | package Wrangler::Plugin; | ||
| 2 | |||
| 3 | =pod | ||
| 4 | |||
| 5 | =head1 NAME | ||
| 6 | |||
| 7 | Wrangler::Plugin - Base class for Wrangler Plugins | ||
| 8 | |||
| 9 | =head1 DESCRIPTION | ||
| 10 | |||
| 11 | =head2 new($wrangler) | ||
| 12 | |||
| 13 | Each Plugin must implement a new() constructor, but apart from blessing this shouldn't | ||
| 14 | do much, as it is called on Wrangler startup and would slow down. Plugins should | ||
| 15 | do their init in startup(). | ||
| 16 | |||
| 17 | =head2 plugin_name() | ||
| 18 | |||
| 19 | Must return the name of the Plugin, which must be unique and posssibly short, | ||
| 20 | as it is currently used for internal/config settings mapping. | ||
| 21 | |||
| 22 | =head2 plugin_info() | ||
| 23 | |||
| 24 | Should return a description of what the Plugin does. This value is shown in Settings | ||
| 25 | > Plugins > Info | ||
| 26 | |||
| 27 | =head2 plugin_enable() | ||
| 28 | |||
| 29 | Wrangler calls this at an arbitrary stage, latest when the Plugin is actually put | ||
| 30 | to use. This here is where Plugin authors should do any additional module loading, | ||
| 31 | polling settings, etc. | ||
| 32 | |||
| 33 | =head2 plugin_phases() | ||
| 34 | |||
| 35 | Each Plugin must register itself via this method for any scope the Plugin code should | ||
| 36 | be executed. This method must return a hashref where the keys are the scopes pointing | ||
| 37 | to some true value. | ||
| 38 | |||
| 39 | Currently Wrangler offers these phase hooks: "wrangler_startup", "file_context_menu", | ||
| 40 | "directory_listing", "plugin_settings". | ||
| 41 | |||
| 42 | =head2 wrangler_startup() | ||
| 43 | |||
| 44 | This is called during Wrangler's startup. Plugins usually use it to "register" their | ||
| 45 | needed metadata keys with central $wishlist in Wrangler.pm. | ||
| 46 | |||
| 47 | =head2 plugin_settings($parent) | ||
| 48 | |||
| 49 | Using the $parent that is passed in by Wrangler, the plugin must return a Wx component | ||
| 50 | that will be displayed in Settings > Plugins > <this plugin>. | ||
| 51 | |||
| 52 | =head2 file_context_menu($menu,$selection_ref) | ||
| 53 | |||
| 54 | Only required for "context_menu"-Plugins. This method will be called on each Plugin | ||
| 55 | which has registered itself for the scope "context_menu" via plugin_phases(). Passed | ||
| 56 | values are a Wx::Menu object and a ref to an richitems array of the current selection. | ||
| 57 | |||
| 58 | Plugins are expected to return an arrayref to an array of (1) a Wx::MenuItem, | ||
| 59 | and (2) a coderef { callback }, and optionally (3) a { post-add-callback } ). The | ||
| 60 | post-add-callback is code that is executed after the MenuItem has been added to | ||
| 61 | the Wx::Menu. This is needed for checkboxes which can only be checked after the | ||
| 62 | Wx::MenuItem has been added to the Wx::Menu. | ||
| 63 | |||
| 64 | =head2 directory_listing($filebrowser,$itemId,$richlist_item) | ||
| 65 | |||
| 66 | This is called from within the loop over all items of a directory/collection, in | ||
| 67 | FileBrowser's Populate() method. It allows a Plugin to do per-item manipulations. | ||
| 68 | |||
| 69 | =head1 COPYRIGHT & LICENSE | ||
| 70 | |||
| 71 | This module is part of L<Wrangler>. Please refer to the main module for further | ||
| 72 | information and licensing / usage terms. | ||
| 73 | |||
| 74 | =cut | ||
| 75 | |||
| 76 | use strict; | ||
| 77 | use warnings; | ||
| 78 | |||
| 79 | 1; |