1Padre::Plugin(3)      User Contributed Perl Documentation     Padre::Plugin(3)
2
3
4

NAME

6       Padre::Plugin - Padre plug-in API 2.2
7

SYNOPSIS

9         package Padre::Plugin::Foo;
10
11         use strict;
12         use base 'Padre::Plugin';
13
14         # The plug-in name to show in the Plug-in Manager and menus
15         sub plugin_name {
16             'Example Plug-in';
17         }
18
19         # 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
27         # 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
38         1;
39

STATIC/CLASS METHODS

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
45       The default implementation will generate a name based on the class name
46       of the plug-in.
47
48   "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
52       Returns a path string if the share directory exists, or "undef" if not.
53
54   "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
58       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
64       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
69       That is, Padre__Plugin__Vi-de.po for the German locale of
70       "Padre::Plugin::Vi".
71
72   "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
77       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
80   "plugin_wizards"
81       The "plugin_wizards" method will be called by Padre when it retrieves
82       the wizard list.
83
84       The default implementation returns an empty list
85
86   "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
94       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
98       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
103       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
106       The list of interfaces should be provided as a list of class/version
107       pairs, as shown in the example.
108
109       The padre_interfaces method will be called on the class, not on the
110       plug-in object. By default, this method returns nothing.
111
112       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

CONSTRUCTORS

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
122       A default constructor is provided that creates an empty hash-based
123       object.
124

INSTANCE METHODS

126   "registered_documents"
127         sub registered_documents {
128             'application/javascript' => 'Padre::Plugin::JavaScript::Document',
129             'application/json'       => 'Padre::Plugin::JavaScript::Document',
130         }
131
132       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
137       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
142       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
146       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
150   "provided_highlighters"
151       Default method returning an empty array.
152
153       TO DO. See Padre::Document.
154
155   "highlighting_mime_types"
156       TO DO. See Padre::Document.
157
158   "event_on_context_menu"
159         sub event_on_context_menu {
160           my ($self, $document, $editor, $menu, $event) = (@_);
161
162           # create our own menu section
163           $menu->AppendSeparator;
164
165           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
173       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
181       Parameters retrieved are the objects for the document, the editor, the
182       context menu ("Wx::Menu") and the event.
183
184       Have a look at the implementation in Padre::Document::Perl for a more
185       thorough example, including how to manipulate the active document.
186
187   "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
192       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
196       Please note that Padre will block until this method returns, so you
197       should attempt to complete return as quickly as possible.
198
199       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
202       Returns true if the plug-in started up successfully, or false on
203       failure.
204
205       The default implementation does nothing, and returns true.
206
207   "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
213       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
217       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
222       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
226         require Class::Unload;
227         Class::Unload->unload('My::Extra::Class');
228
229       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
234       Returns true on success, or false if the unloading process failed and
235       your plug-in has been left in an unknown state.
236
237   "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
245       The "config_read" method provides access to host-specific configuration
246       stored in a persistent location by Padre.
247
248       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
252       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
256   "config_write"
257         $self->config_write( { foo => 'bar' } );
258
259       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
263       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
267   "plugin_preferences"
268         $plugin->plugin_preferences($wx_parent);
269
270       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
274       The method is passed a Wx object that should be used as the Wx parent.
275
276   "menu_plugins_simple"
277         sub menu_plugins_simple {
278             'My Plug-in' => [
279                 Submenu  => [
280                     'Do Something' => sub { $self->do_something },
281                 ],
282
283                 # Separator
284                 '---' => undef,
285
286                 # Shorthand for sub { $self->show_about(@_) }
287                 About => 'show_about',
288
289                 # Also use keyboard shortcuts to call sub { $self->show_about(@_) }
290                 "Action\tCtrl+Shift+Z" => 'action',
291             ];
292         }
293
294       The "menu_plugins_simple" method defines a simple menu structure for
295       your plug-in.
296
297       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
301       If the key is a string of three hyphens (i.e. "---") the pair will be
302       rendered as a menu separator.
303
304       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
308       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
311       If the value is a reference to an ARRAY, the pair will be rendered as a
312       sub-menu containing further menu items.
313
314   "menu_plugins"
315         sub menu_plugins {
316             my $self = shift;
317             my $main = shift;
318
319             # 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
327             # Return it and the label for our plug-in
328             return ( $self->plugin_name => $menu );
329
330       The "menu_plugins" method defines a fully-featured mechanism for
331       building your plug-in menu.
332
333       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
337       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
341       If the method return a null list, no menu entry will be created for the
342       plug-in.
343
344   "editor_enable"
345         sub editor_enable {
346             my $self     = shift;
347             my $editor   = shift;
348             my $document = shift;
349
350             # Make changes to the editor here...
351
352             return 1;
353         }
354
355       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
359       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
363       The method is passed two parameters, the fully set up editor object,
364       and the Padre::Document being opened.
365
366       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
370   "editor_disable"
371         sub editor_disable {
372             my $self     = shift;
373             my $editor   = shift;
374             my $document = shift;
375
376             # Undo your changes to the editor here...
377
378         return 1;
379
380       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
384       It provides the plug-in with an opportunity to clean up, remove any GUI
385       customisations, and complete any other shutdown/close processes.
386
387       The method is passed two parameters, the fully set up editor object,
388       and the Padre::Document being closed.
389
390       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
394   "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
399   "main"
400       The "main" convenience method provides direct access to the
401       Padre::Wx::Main (main window) object.
402
403   "current"
404       The "current" convenience method provides a Padre::Current context
405       object for the current plug-in.
406

SEE ALSO

408       Padre
409
411       Copyright 2008-2011 The Padre development team as listed in Padre.pm.
412
413       This program is free software; you can redistribute it and/or modify it
414       under the same terms as Perl 5 itself.
415
416       The full text of the license can be found in the LICENSE file included
417       with this module.
418
419
420
421perl v5.30.0                      2019-07-26                  Padre::Plugin(3)
Impressum