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. If you are using
61 Module::Build version 0.36 and later, please use the "share_dir" new()
62 argument.
63 Your plug-in catalogs should be named $plugin-$locale.po (or .mo for
65 the compiled form) where $plugin is the class name of your plug-in with
66 any character that are illegal in file names (on all file systems)
67 flattened to underscores.
68 That is, Padre__Plugin__Vi-de.po for the German locale of
70 "Padre::Plugin::Vi".
71 "plugin_icon"
73 The "plugin_icon" method will be called by Padre when it needs an icon
74 to display in the user interface. It should return a 16x16 "Wx::Bitmap"
75 object.
76 The default implementation will look for an icon at the path
78 $plugin_directory_share/icons/16x16/logo.png and load it for you.
79 "plugin_wizards"
81 The "plugin_wizards" method will be called by Padre when it retrieves
82 the wizard list.
83 The default implementation returns an empty list
85 "padre_interfaces"
87 sub padre_interfaces {
88 'Padre::Plugin' => 0.43,
89 'Padre::Document::Perl' => 0.35,
90 'Padre::Wx::Main' => 0.43,
91 'Padre::DB' => 0.25,
92 }
93 In Padre, plug-ins are permitted to make relatively deep calls into
95 Padre's internals. This allows a lot of freedom, but comes at the cost
96 of allowing plug-ins to damage or crash the editor.
97 To help compensate for any potential problems, the Plug-in Manager
99 expects each plug-in module to define the Padre classes that the plug-
100 in uses, and the version of Padre that the code was originally written
101 against (for each class).
102 This information will be used by the Plug-in Manager to calculate
104 whether or not the plug-in is still compatible with Padre.
105 The list of interfaces should be provided as a list of class/version
107 pairs, as shown in the example.
108 The padre_interfaces method will be called on the class, not on the
110 plug-in object. By default, this method returns nothing.
111 In future, plug-ins that do not supply compatibility information may be
113 disabled unless the user has specifically allowed experimental plug-
114 ins.
115
117 "new"
118 The new constructor takes no parameters. When a plug-in is loaded,
119 Padre will instantiate one plug-in object for each plug-in, to provide
120 the plug-in with a location to store any private or working data.
121 A default constructor is provided that creates an empty hash-based
123 object.
124
126 "registered_documents"
127 sub registered_documents {
128 'application/javascript' => 'Padre::Plugin::JavaScript::Document',
129 'application/json' => 'Padre::Plugin::JavaScript::Document',
130 }
131 The "registered_documents" methods can be used by a plug-in to define
133 document types for which the plug-in provides a document class (which
134 is used by Padre to enable functionality beyond the level of a plain
135 text file with simple Scintilla highlighting).
136 This method will be called by the Plug-in Manager and the information
138 returned will be used to populate various internal data structures and
139 perform various other tasks. Plug-in authors are expected to provide
140 this information without having to know how or why Padre will use it.
141 This (theoretically at this point) should allow Padre to keep a
143 document open while a plug-in is being enabled or disabled, upgrading
144 or downgrading the document in the process.
145 The method call is made on the plug-in object, and returns a list of
147 MIME type to class pairs. By default the method returns a null list,
148 which indicates that the plug-in does not provide any document types.
149 "provided_highlighters"
151 Default method returning an empty array.
152 TO DO. See Padre::Document.
154 "highlighting_mime_types"
156 TO DO. See Padre::Document.
157 "event_on_context_menu"
159 sub event_on_context_menu {
160 my ($self, $document, $editor, $menu, $event) = (@_);
161 # create our own menu section
163 $menu->AppendSeparator;
164 my $item = $menu->Append( -1, _T('Mutley, do something') );
166 Wx::Event::EVT_MENU(
167 $self->main,
168 $item,
169 sub { Wx::MessageBox('sh sh sh sh', 'Mutley', Wx::wxOK, shift) },
170 );
171 }
172 If implemented in a plug-in, this method will be called when a context
174 menu is about to be displayed either because the user pressed the right
175 mouse button in the editor window ("Wx::MouseEvent") or because the
176 "Right-click" menu entry was selected in the "Window" menu
177 ("Wx::CommandEvent"). The context menu object was created and populated
178 by the Editor and then possibly augmented by the "Padre::Document" type
179 (see "event_on_right_down" in Padre::Document).
180 Parameters retrieved are the objects for the document, the editor, the
182 context menu ("Wx::Menu") and the event.
183 Have a look at the implementation in Padre::Document::Perl for a more
185 thorough example, including how to manipulate the active document.
186 "plugin_enable"
188 The "plugin_enable" object method will be called (at an arbitrary time
189 of Padre's choosing) to allow the plug-in object to initialise and
190 start up the plug-in.
191 This may involve loading any configuration files, hooking into existing
193 documents or editor windows, and otherwise doing anything needed to
194 bootstrap operations.
195 Please note that Padre will block until this method returns, so you
197 should attempt to complete return as quickly as possible.
198 Any modules that you may use should not be loaded during this phase,
200 but should be "require"ed when they are needed, at the last moment.
201 Returns true if the plug-in started up successfully, or false on
203 failure.
204 The default implementation does nothing, and returns true.
206 "plugin_disable"
208 The "plugin_disable" method is called by Padre for various reasons to
209 request the plug-in do whatever tasks are necessary to shut itself
210 down. This also provides an opportunity to save configuration
211 information, save caches to disk, and so on.
212 Most often, this will be when Padre itself is shutting down. Other uses
214 may be when the user wishes to disable the plug-in, when the plug-in is
215 being reloaded, or if the plug-in is about to be upgraded.
216 If you have any private classes other than the standard
218 "Padre::Plugin::Foo", you should unload them as well as the plug-in may
219 be in the process of upgrading and will want those classes freed up for
220 use by the new version.
221 The recommended way of unloading your extra classes is using
223 Class::Unload. Suppose you have "My::Extra::Class" and want to unload
224 it, simply do this in "plugin_disable":
225 require Class::Unload;
227 Class::Unload->unload('My::Extra::Class');
228 Class::Unload takes care of all the tedious bits for you. Note that you
230 should not unload any external "CPAN" dependencies, as these may be
231 needed by other plug-ins or Padre itself. Only classes that are part of
232 your plug-in should be unloaded.
233 Returns true on success, or false if the unloading process failed and
235 your plug-in has been left in an unknown state.
236 "config_read"
238 my $hash = $self->config_read;
239 if ( $hash ) {
240 print "Loaded existing configuration\n";
241 } else {
242 print "No existing configuration";
243 }
244 The "config_read" method provides access to host-specific configuration
246 stored in a persistent location by Padre.
247 At this time, the configuration must be a nested, non-cyclic structure
249 of "HASH" references, "ARRAY" references and simple scalars (the use of
250 "undef" values is permitted) with a "HASH" reference at the root.
251 Returns a nested "HASH"-root structure if there is an existing saved
253 configuration for the plug-in, or "undef" if there is no existing saved
254 configuration for the plug-in.
255 "config_write"
257 $self->config_write( { foo => 'bar' } );
258 The "config_write" method is used to write the host-specific
260 configuration information for the plug-in into the underlying database
261 storage.
262 At this time, the configuration must be a nested, non-cyclic structure
264 of "HASH" references, "ARRAY" references and simple scalars (the use of
265 "undef" values is permitted) with a "HASH" reference at the root.
266 "plugin_preferences"
268 $plugin->plugin_preferences($wx_parent);
269 The "plugin_preferences" method allows a plug-in to define an entry
271 point for the Plug-in Manager dialog to trigger to show a preferences
272 or configuration dialog for the plug-in.
273 The method is passed a Wx object that should be used as the Wx parent.
275 "menu_plugins_simple"
277 sub menu_plugins_simple {
278 'My Plug-in' => [
279 Submenu => [
280 'Do Something' => sub { $self->do_something },
281 ],
282 # Separator
284 '---' => undef,
285 # Shorthand for sub { $self->show_about(@_) }
287 About => 'show_about',
288 # Also use keyboard shortcuts to call sub { $self->show_about(@_) }
290 "Action\tCtrl+Shift+Z" => 'action',
291 ];
292 }
293 The "menu_plugins_simple" method defines a simple menu structure for
295 your plug-in.
296 It returns two values, the label for the menu entry to be used in the
298 top level Plug-ins menu, and a reference to an ARRAY containing an
299 ordered set of key/value pairs that will be turned into menus.
300 If the key is a string of three hyphens (i.e. "---") the pair will be
302 rendered as a menu separator.
303 If the key is a string containing a tab ("\t") and a keyboard shortcut
305 combination the menu action will also be available through a keyboard
306 shortcut.
307 If the value is a Perl identifier, it will be treated as a method name
309 to be called on the plug-in object when the menu entry is triggered.
310 If the value is a reference to an ARRAY, the pair will be rendered as a
312 sub-menu containing further menu items.
313 "menu_plugins"
315 sub menu_plugins {
316 my $self = shift;
317 my $main = shift;
318 # Create a simple menu with a single About entry
320 my $menu = Wx::Menu->new;
321 Wx::Event::EVT_MENU(
322 $main,
323 $menu->Append( -1, 'About', ),
324 sub { $self->show_about },
325 );
326 # Return it and the label for our plug-in
328 return ( $self->plugin_name => $menu );
329 The "menu_plugins" method defines a fully-featured mechanism for
331 building your plug-in menu.
332 It returns two values, the label for the menu entry to be used in the
334 top level Plug-ins menu, and a Wx::Menu object containing the custom-
335 built menu structure.
336 A default implementation of this method is provided which will call
338 "menu_plugins_simple" and implements the expansion of the simple data
339 into a full menu structure.
340 If the method return a null list, no menu entry will be created for the
342 plug-in.
343 "editor_enable"
345 sub editor_enable {
346 my $self = shift;
347 my $editor = shift;
348 my $document = shift;
349 # Make changes to the editor here...
351 return 1;
353 }
354 The "editor_enable" method is called by Padre to provide the plug-in
356 with an opportunity to alter the setup of the editor as it is being
357 loaded.
358 This method is only triggered when new editor windows are opened.
360 Hooking into any existing open documents must be done within the
361 "plugin_enable" method.
362 The method is passed two parameters, the fully set up editor object,
364 and the Padre::Document being opened.
365 At the present time, this method has been provided primarily for the
367 use of the Padre::Plugin::Vi plug-in and other plug-ins that need deep
368 integration with the editor widget.
369 "editor_disable"
371 sub editor_disable {
372 my $self = shift;
373 my $editor = shift;
374 my $document = shift;
375 # Undo your changes to the editor here...
377 return 1;
379 The "editor_disable" method is the twin of the previous "editor_enable"
381 method. It is called as the file in the editor is being closed, after
382 the user has confirmed the file is to be closed.
383 It provides the plug-in with an opportunity to clean up, remove any GUI
385 customisations, and complete any other shutdown/close processes.
386 The method is passed two parameters, the fully set up editor object,
388 and the Padre::Document being closed.
389 At the present time, this method has been provided primarily for the
391 use of the Padre::Plugin::Vi plug-in and other plug-ins that need deep
392 integration with the editor widget.
393 "ide"
395 The "ide" convenience method provides access to the root-level Padre
396 IDE object, preventing the need to go via the global "Padre->ide"
397 method.
398 "main"
400 The "main" convenience method provides direct access to the
401 Padre::Wx::Main (main window) object.
402 "current"
404 The "current" convenience method provides a Padre::Current context
405 object for the current plug-in.
406
408 Padre
409
411 Copyright 2008-2011 The Padre development team as listed in Padre.pm.
412 This program is free software; you can redistribute it and/or modify it
414 under the same terms as Perl 5 itself.
415 The full text of the license can be found in the LICENSE file included
417 with this module.
418perl v5.32.1 2021-01-27 Padre::Plugin(3)