1Padre::Plugin(3) User Contributed Perl Documentation Padre::Plugin(3)
2
6 Padre::Plugin - Padre plug-in API 2.2
7
9 package Padre::Plugin::Foo;
10 use strict;
12 use base 'Padre::Plugin';
13 # The plug-in name to show in the Plug-in Manager and menus
15 sub plugin_name {
16 'Example Plug-in';
17 }
18 # Declare the Padre interfaces this plug-in uses
20 sub padre_interfaces {
21 'Padre::Plugin' => 0.29,
22 'Padre::Document::Perl' => 0.29,
23 'Padre::Wx::Main' => 0.29,
24 'Padre::DB' => 0.29,
25 }
26 # The command structure to show in the Plug-ins menu
28 sub menu_plugins_simple {
29 my $self = shift;
30 return $self->plugin_name => [
31 'About' => sub { $self->show_about },
32 'Submenu' => [
33 'Do Something' => sub { $self->do_something },
34 ],
35 ];
36 }
37 1;
39
41 "plugin_name"
42 The "plugin_name" method will be called by Padre when it needs a name
43 to display in the user interface.
44 The default implementation will generate a name based on the class name
46 of the plug-in.
47 "plugin_directory_share"
49 The "plugin_directory_share" method finds the location of the shared
50 files directory for the plug-in, if one exists.
51 Returns a path string if the share directory exists, or "undef" if not.
53 "plugin_directory_locale"
55 The "plugin_directory_locale()" method will be called by Padre to know
56 where to look for your plug-in l10n catalog.
57 It defaults to $sharedir/locale (with $sharedir as defined by
59 "File::ShareDir" and thus should work as is for your plug-in if you're
60 using the "install_share" command of Module::Install.
61 Your plug-in catalogs should be named $plugin-$locale.po (or .mo for
63 the compiled form) where $plugin is the class name of your plug-in with
64 any character that are illegal in file names (on all file systems)
65 flattened to underscores.
66 That is, Padre__Plugin__Vi-de.po for the German locale of
68 "Padre::Plugin::Vi".
69 "plugin_icon"
71 The "plugin_icon" method will be called by Padre when it needs an icon
72 to display in the user interface. It should return a 16x16 "Wx::Bitmap"
73 object.
74 The default implementation will look for an icon at the path
76 $plugin_directory_share/icons/16x16/logo.png and load it for you.
77 "padre_interfaces"
79 sub padre_interfaces {
80 'Padre::Plugin' => 0.43,
81 'Padre::Document::Perl' => 0.35,
82 'Padre::Wx::Main' => 0.43,
83 'Padre::DB' => 0.25,
84 }
85 In Padre, plug-ins are permitted to make relatively deep calls into
87 Padre's internals. This allows a lot of freedom, but comes at the cost
88 of allowing plug-ins to damage or crash the editor.
89 To help compensate for any potential problems, the Plug-in Manager
91 expects each plug-in module to define the Padre classes that the plug-
92 in uses, and the version of Padre that the code was originally written
93 against (for each class).
94 This information will be used by the Plug-in Manager to calculate
96 whether or not the plug-in is still compatible with Padre.
97 The list of interfaces should be provided as a list of class/version
99 pairs, as shown in the example.
100 The padre_interfaces method will be called on the class, not on the
102 plug-in object. By default, this method returns nothing.
103 In future, plug-ins that do not supply compatibility information may be
105 disabled unless the user has specifically allowed experimental plug-
106 ins.
107
109 "new"
110 The new constructor takes no parameters. When a plug-in is loaded,
111 Padre will instantiate one plug-in object for each plug-in, to provide
112 the plug-in with a location to store any private or working data.
113 A default constructor is provided that creates an empty hash-based
115 object.
116
118 "registered_documents"
119 sub registered_documents {
120 'application/javascript' => 'Padre::Plugin::JavaScript::Document',
121 'application/json' => 'Padre::Plugin::JavaScript::Document',
122 }
123 The "registered_documents" methods can be used by a plug-in to define
125 document types for which the plug-in provides a document class (which
126 is used by Padre to enable functionality beyond the level of a plain
127 text file with simple Scintilla highlighting).
128 This method will be called by the Plug-in Manager and the information
130 returned will be used to populate various internal data structures and
131 perform various other tasks. Plug-in authors are expected to provide
132 this information without having to know how or why Padre will use it.
133 This (theoretically at this point) should allow Padre to keep a
135 document open while a plug-in is being enabled or disabled, upgrading
136 or downgrading the document in the process.
137 The method call is made on the plug-in object, and returns a list of
139 MIME type to class pairs. By default the method returns a null list,
140 which indicates that the plug-in does not provide any document types.
141 "provided_highlighters"
143 Default method returning an empty array.
144 TO DO. See Padre::Document.
146 "highlighting_mime_types"
148 TO DO. See Padre::Document.
149 "event_on_context_menu"
151 sub event_on_context_menu {
152 my ($self, $document, $editor, $menu, $event) = (@_);
153 # create our own menu section
155 $menu->AppendSeparator;
156 my $item = $menu->Append( -1, _T('Mutley, do something') );
158 Wx::Event::EVT_MENU(
159 $self->main,
160 $item,
161 sub { Wx::MessageBox('sh sh sh sh', 'Mutley', Wx::wxOK, shift) },
162 );
163 }
164 If implemented in a plug-in, this method will be called when a context
166 menu is about to be displayed either because the user pressed the right
167 mouse button in the editor window ("Wx::MouseEvent") or because the
168 "Right-click" menu entry was selected in the "Window" menu
169 ("Wx::CommandEvent"). The context menu object was created and populated
170 by the Editor and then possibly augmented by the "Padre::Document" type
171 (see "event_on_right_down" in Padre::Document).
172 Parameters retrieved are the objects for the document, the editor, the
174 context menu ("Wx::Menu") and the event.
175 Have a look at the implementation in Padre::Document::Perl for a more
177 thorough example, including how to manipulate the active document.
178 "plugin_enable"
180 The "plugin_enable" object method will be called (at an arbitrary time
181 of Padre's choosing) to allow the plug-in object to initialise and
182 start up the plug-in.
183 This may involve loading any configuration files, hooking into existing
185 documents or editor windows, and otherwise doing anything needed to
186 bootstrap operations.
187 Please note that Padre will block until this method returns, so you
189 should attempt to complete return as quickly as possible.
190 Any modules that you may use should not be loaded during this phase,
192 but should be "require"ed when they are needed, at the last moment.
193 Returns true if the plug-in started up successfully, or false on
195 failure.
196 The default implementation does nothing, and returns true.
198 "plugin_disable"
200 The "plugin_disable" method is called by Padre for various reasons to
201 request the plug-in do whatever tasks are necessary to shut itself
202 down. This also provides an opportunity to save configuration
203 information, save caches to disk, and so on.
204 Most often, this will be when Padre itself is shutting down. Other uses
206 may be when the user wishes to disable the plug-in, when the plug-in is
207 being reloaded, or if the plug-in is about to be upgraded.
208 If you have any private classes other than the standard
210 "Padre::Plugin::Foo", you should unload them as well as the plug-in may
211 be in the process of upgrading and will want those classes freed up for
212 use by the new version.
213 The recommended way of unloading your extra classes is using
215 Class::Unload. Suppose you have "My::Extra::Class" and want to unload
216 it, simply do this in "plugin_disable":
217 require Class::Unload;
219 Class::Unload->unload('My::Extra::Class');
220 Class::Unload takes care of all the tedious bits for you. Note that you
222 should not unload any external "CPAN" dependencies, as these may be
223 needed by other plug-ins or Padre itself. Only classes that are part of
224 your plug-in should be unloaded.
225 Returns true on success, or false if the unloading process failed and
227 your plug-in has been left in an unknown state.
228 "config_read"
230 my $hash = $self->config_read;
231 if ( $hash ) {
232 print "Loaded existing configuration\n";
233 } else {
234 print "No existing configuration";
235 }
236 The "config_read" method provides access to host-specific configuration
238 stored in a persistent location by Padre.
239 At this time, the configuration must be a nested, non-cyclic structure
241 of "HASH" references, "ARRAY" references and simple scalars (the use of
242 "undef" values is permitted) with a "HASH" reference at the root.
243 Returns a nested "HASH"-root structure if there is an existing saved
245 configuration for the plug-in, or "undef" if there is no existing saved
246 configuration for the plug-in.
247 "config_write"
249 $self->config_write( { foo => 'bar' } );
250 The "config_write" method is used to write the host-specific
252 configuration information for the plug-in into the underlying database
253 storage.
254 At this time, the configuration must be a nested, non-cyclic structure
256 of "HASH" references, "ARRAY" references and simple scalars (the use of
257 "undef" values is permitted) with a "HASH" reference at the root.
258 "plugin_preferences"
260 $plugin->plugin_preferences($wx_parent);
261 The "plugin_preferences" method allows a plug-in to define an entry
263 point for the Plug-in Manager dialog to trigger to show a preferences
264 or configuration dialog for the plug-in.
265 The method is passed a Wx object that should be used as the Wx parent.
267 "menu_plugins_simple"
269 sub menu_plugins_simple {
270 'My Plug-in' => [
271 Submenu => [
272 'Do Something' => sub { $self->do_something },
273 ],
274 '---' => undef, # Separator
275 About => 'show_about', # Shorthand for sub { $self->show_about(@_) }
276 "Action\tCtrl+Shift+Z" => 'action', # Also use keyboard shortcuts
277 # to call sub { $self->show_about(@_) }
278 ];
279 }
280 The "menu_plugins_simple" method defines a simple menu structure for
282 your plug-in.
283 It returns two values, the label for the menu entry to be used in the
285 top level Plug-ins menu, and a reference to an ARRAY containing an
286 ordered set of key/value pairs that will be turned into menus.
287 If the key is a string of three hyphens (i.e. "---") the pair will be
289 rendered as a menu separator.
290 If the key is a string containing a tab ("\t") and a keyboard shortcut
292 combination the menu action will also be available through a keyboard
293 shortcut.
294 If the value is a Perl identifier, it will be treated as a method name
296 to be called on the plug-in object when the menu entry is triggered.
297 If the value is a reference to an ARRAY, the pair will be rendered as a
299 sub-menu containing further menu items.
300 "menu_plugins"
302 sub menu_plugins {
303 my $self = shift;
304 my $main = shift;
305 # Create a simple menu with a single About entry
307 my $menu = Wx::Menu->new;
308 Wx::Event::EVT_MENU(
309 $main,
310 $menu->Append( -1, 'About', ),
311 sub { $self->show_about },
312 );
313 # Return it and the label for our plug-in
315 return ( $self->plugin_name => $menu );
316 The "menu_plugins" method defines a fully-featured mechanism for
318 building your plug-in menu.
319 It returns two values, the label for the menu entry to be used in the
321 top level Plug-ins menu, and a Wx::Menu object containing the custom-
322 built menu structure.
323 A default implementation of this method is provided which will call
325 "menu_plugins_simple" and implements the expansion of the simple data
326 into a full menu structure.
327 If the method return a null list, no menu entry will be created for the
329 plug-in.
330 "editor_enable"
332 sub editor_enable {
333 my $self = shift;
334 my $editor = shift;
335 my $document = shift;
336 # Make changes to the editor here...
338 return 1;
340 }
341 The "editor_enable" method is called by Padre to provide the plug-in
343 with an opportunity to alter the setup of the editor as it is being
344 loaded.
345 This method is only triggered when new editor windows are opened.
347 Hooking into any existing open documents must be done within the
348 "plugin_enable" method.
349 The method is passed two parameters, the fully set up editor object,
351 and the Padre::Document being opened.
352 At the present time, this method has been provided primarily for the
354 use of the Padre::Plugin::Vi plug-in and other plug-ins that need deep
355 integration with the editor widget.
356 "editor_disable"
358 sub editor_disable {
359 my $self = shift;
360 my $editor = shift;
361 my $document = shift;
362 # Undo your changes to the editor here...
364 return 1;
366 The "editor_disable" method is the twin of the previous "editor_enable"
368 method. It is called as the file in the editor is being closed, after
369 the user has confirmed the file is to be closed.
370 It provides the plug-in with an opportunity to clean up, remove any GUI
372 customisations, and complete any other shutdown/close processes.
373 The method is passed two parameters, the fully set up editor object,
375 and the Padre::Document being closed.
376 At the present time, this method has been provided primarily for the
378 use of the Padre::Plugin::Vi plug-in and other plug-ins that need deep
379 integration with the editor widget.
380 "ide"
382 The "ide" convenience method provides access to the root-level Padre
383 IDE object, preventing the need to go via the global "Padre->ide"
384 method.
385 "main"
387 The "main" convenience method provides direct access to the
388 Padre::Wx::Main (main window) object.
389 "current"
391 The "current" convenience method provides a Padre::Current context
392 object for the current plug-in.
393
395 Padre
396
398 Copyright 2008-2010 The Padre development team as listed in Padre.pm.
399 This program is free software; you can redistribute it and/or modify it
401 under the same terms as Perl itself.
402 The full text of the license can be found in the LICENSE file included
404 with this module.
405perl v5.12.1 2010-06-11 Padre::Plugin(3)