Back to DrPython Help
Plugins
Plugins provide a method of adding optional features to DrPython.
Configuring Plugins:
Note: All changes to a plugin take effect the next time DrPython
loads.
The exceptions are shortcuts and the pop up menu.
If a plugin is not loaded, you can still edit shortcuts and the pop up
menu,
but you will be unable to access the plugin functions unless the plugin
is loaded.
To Install:
You have two options for installing a plugin.
You can just install the plugin from "Configure Plugins".
The plugin is
automatically loaded on startup.
If the plugin comes with an index file, you can install that.
And index file (*.idx) is a list of plugins.
When you "Load From Index", all of the plugins in the file are
installed.
This is especially useful if you have a group of plugins you load when
you work on certain kinds of projects.
A plugin installed via index file is only loaded when you select the
plugin index
from the "Load From Index" menu.
The order in which plugins are loaded can be controlled via the "Up"
and "Down" buttons.
When you install a plugin, it is copied to your home directory, under
the subdirectory
plugins. It is also added to the master index file "plugins.dat".
When you install an index, all of the plugins listed in the index file,
plus the file itself,
are copied your home directory, under the subdirectory plugins.
To Remove:
Removing a plugin removes the plugin files (.py, .pyc) from your plugin
directory.
It also removes the entry from plugins.dat.
If the file is referenced in an index, you must remove the index
yourself.
Removing an index file removes the index file, and all plugins listed
within.
However, if any of the plugins listed in the index file are listed in
another index file,
or in the main plugins.dat index, they will not be removed.
To Configure Plugin Loading:
Selecting "Configure Plugins" allows you to
add or remove plugins to the main plugins.dat file,
or to an index file. You can also create your own index files.
If you list the same plugin in more than one index file,
removing one of the index files will not remove that plugin.
If a plugin is only listed in one index file, removing the index file
removes that plugin.
If a plugin is unlisted, it is never loaded. However
it still exists.
You can also directly edit a plugin, or,
if the plugin supports it,
edit shortcuts and/or preferences for
that plugin.
To Create Your Own:
NOTE: If you write your own plugin, please note that
you can access the entire DrPython application (via the DrFrame
instance).
This means a plugin can make stuff not work right, or
can access an internal function that may be changed in
a future release. If you are adding a new component
(such as a new menu item, and a new dialog), you should
be fine.
the first thing you need to do is import the relevant wxWidgets modules
(usually just "wx"):
import wx
Next, you need to define the "Plugin" function:
def Plugin(DrFrame):
DrFrame is the variable for the DrFrame in the DrPython program.
It is the same variable as in DrScript.
Now you can add something to the interface simply by using the
underlying code in DrPython.
To bind a function to an event, there are two ways. Let's take a
look at the following code:
#Example
Plugin
import wx
def Plugin(DrFrame):
idum =
DrFrame.GetNewId()
DrFrame.viewmenu.Append(idum, "Lookit!"," I said Lookit!")
def exampleFunction(event):
DrFrame.ShowPrompt()
DrFrame.txtPrompt.SetText("I'm looking.... Now what?")
DrFrame.Bind(wx.EVT_MENU,
exampleFunction,
id=idum)
DrFrame.AddToPopUpMenu("Lookit!", exampleFunction, 0)
DrFrame.AddSeparatorToPopUpMenu(1)
Now what this code does is the following:
It adds an item to the viewmenu (you can grab the menu names by looking
in the DrPython source: drpython.py).
DrFrame.GetNewId() makes sure a unique id number is returned.
(You only need an id number if the wx Component you are adding requires
one.
You need one for menus).
Now the second step to adding a menu is to use the DrFrame function.
There are two necessary steps.
The first is to define a function. Now if this function is going
to access DrFrame,
it must be defined within the Plugin function(which is only called
once, when the plugin
is loaded).
The function you add must take one argument,
"event". You can name them whatever you want
For example, "(MenuEvent)".
the second will hold the wx Menu Event.
Next, you must use the wxPython method Bind() to bind that function to
the
component you want. Consult the wxPython documentation for usage.
Here is a brief summary of Bind()
wxPythonWidget.Bind(wx.EVT_EVENTTYPE, Function, id=IdNumber).
The idNumber argument is optional (recommended if the eventtype in
question
allows it, check the wxWidgets documentation for that info).
wx.EVT_EVENTTYPE is the event type (wxWidgets Documentation for a list).
Function is the function you are binding to the widget.
*****************************************
To Tell DrPython to let a user acess a function from
keyboard shortcuts, the pop up menu, or the toolbar, you have several
options.
You can specify each separately (or choose only one or two methods),
or you can specify all at once:
DrFrame.AddPluginFunction(NameOfTheCurrentPlugin,
FunctionLabel, FunctionYouWantToAdd)
Here is a brief code example:
DrFrame.AddPluginShortcutFunction("SearchInFiles",
"Find In Files",
OnFindInFiles)
This will let the user add the function OnFindInFiles to keyboard
shortcuts, the pop up menu,
or the toolbar.
For more info on what this means for each method, see below.
*****************************************
To add a keyboard shortcut, you have two options.
You can simply use "AddKeyEvent".
It takes the following arguments:
DrFrame.AddKeyEvent(FunctionYouWantToAdd,
Keycode, Control, Shift, Alt, Meta)
The default for all modifier keys (Control, Shift, Alt, Meta) is 0 (do
not use).
Keycodes can be tricky. For both lowercase and
uppercase, use the python
function "ord()" plus the uppercase letter. Add Shift=1 if you
want to use
uppercase:
Target: Uppercase 'A'
DrFrame.AddKeyEvent(FunctionYouWantToAdd,
ord('A'), 0, 1)
Target: Lowercase 'a'
DrFrame.AddKeyEvent(FunctionYouWantToAdd,
ord('A'))
This will make the shortcut set in stone.
If you want to let the user configure the shortcut:
DrFrame.AddPluginShortcutFunction(NameOfTheCurrentPlugin,
FunctionLabel, FunctionYouWantToAdd)
For example:
#Example
Plugin
#This file is called "examplenumber2.py"
import wx
def Plugin(DrFrame):
idum =
DrFrame.GetNewId()
DrFrame.viewmenu.Append(idum, "Lookit!"," I said Lookit!")
def exampleFunction(event):
DrFrame.ShowMessage("I'm
Looking Already!", "Result:")
DrFrame.Bind(wx.EVT_MENU,
exampleFunction,
id=idum)
DrFrame.AddPluginShortcutFunction("examplenumber2",
"Example Function",
exampleFunction)
Now, you can open the customize shortcuts dialog, and select the
"examplenumber2" plugin,
to set the shortcut for the function "exampleFunction" you just added.
Note the use of the ShowMessage function.
Show message calls the drScrolledMessageDialog.
DrFrameShowMessage(message,
title)
The drScrolledMessageDialog automatically displays a traceback
if one exists.
*****************************************
To allow the user to add to the pop up menu, use
"AddPluginPopUpMenuFunction"
AddPluginPopUpMenuFunction(NameOfTheCurrentPlugin,
FunctionLabel,
FunctionYouWantToAdd)
The NameOfTheCurrentPlugin is straightforward.
This will allow the user to, via the PopUpMenu Dialog, add a Plugin
Function
to the PopUpMenu (with the label "FunctionLabel").
Notes: If you uninstall the plugin, you have to manually remove
the item
from the PopUpMenu list via the PopUpMenu Dialog.
Each Plugin Item on the PopUpMenu is only loaded if that plugin is
loaded.
So if the plugin is loaded via index, when you load the plugin, the
relevant
item will show up on the PopUpMenu. Even if the plugin is not
loaded,
the item is on the PopUpMenu List.
*****************************************
To allow the user to add to the ToolBar, use
"AddPluginToolBarFunction"
AddPluginToolBarFunction(FunctionLabel,
FunctionYouWantToAdd)
This will allow the user to, via the Customize ToolBar Dialog, add a
Plugin
Function
to the ToolBar (with the label "FunctionLabel").
Notes: If you uninstall the plugin, you have to manually remove
the item
from the ToolBar list via the ToolBar Dialog.
Each Plugin Item on the ToolBar will be loaded no matter what, so be
sure to remove the entry if you remove the plugin (if not, nothing will
happen when you click the button.)
To set icons, you have two options. One is to write an install
script
that installs the icons onto the user's harddrive, and then adds
entries for each icon into the custom icon data file in
the user's drpython preferences directory.
The other is to let the user set the icons manually.
To add entries, you can either do so manually,
or use the following built in functions:
AddPluginIcon(Label,
LocationOf16x16File, LocationOf24x24File)
RemovePluginIcon(Label)
Here is an example:
plugindir = DrFrame.GetPluginDirectory()
DrFrame.AddPluginIcon("Find In Files", "", plugindir
+ "/bitmaps/24/Find In Files.png")
Assuming you have copied the icon file to the proper location
(In this case, in the plugin directory: plugindir/bitmaps/24/)
This will add an entry into the user's custom icon data file,
so that if they have their toolbar set to 24x24, and they add
the Find In Files item, it will display the "Find In Files.png" icon.
This function is best called in a ".install" script.
RemovePluginIcon is best called in the "Uninstall" function,
and removes the entry in question from the custom icon data file.
DrFrame.RemovePluginIcon("Find In Files")
Note:
AddPluginIcon will overwrite any entries in the custom icon
data file with the same label.
*****************************************
If the you want to set and load preferences in your plugin,
all you have to do to edit those preferences is define a function:
def OnPreferences(DrFrame):
This function will be called (with DrFrame as the argument)
from the Options Menu. You can make your own Preferences
Dialog, and have it launched from this function.
*****************************************
If the you want to have an about dialog,
or a help dialog, use:
def OnAbout(DrFrame):
def OnHelp(DrFrame):
This function will be called (with DrFrame as the argument)
from the Help Menu. You can make your own Dialog,
and have it launched from this function.
*****************************************
Install/Uninstall Scripts:
DrPython provides a method for automatic install script execution.
if you have a plugin named "example.py", a file named
"example.py.install"
in the same directory will be automatically run on install.
Install Script:
An install script is especially useful if you have files you want
to install to a specific location on the user's hard drive
(eg, bitmaps for the toolbar).
Here is an example:
#Example
Plugin Install Script
#This file is called "example.py.install"
import wx, shutil, os, os.path
def Install(DrFrame):
d = wx.MessageDialog(DrFrame, "This will install some bitmaps for the
Example \
plugin.\nAre you sure you want to
proceed?", \
"Install Search In Files",
wx.YES_NO | wx.ICON_QUESTION)
answer = d.ShowModal()
d.Destroy()
if (answer
== wx.ID_YES):
cwd = os.getcwd()
plugindir =
DrFrame.GetPluginDirectory()
if not
os.path.exists(plugindir + "/bitmaps"):
os.mkdir(plugindir + "/bitmaps")
if not
os.path.exists(plugindir + "/bitmaps/16"):
os.mkdir(plugindir + "/bitmaps/16")
if not
os.path.exists(plugindir + "/bitmaps/24"):
os.mkdir(plugindir + "/bitmaps/24")
shutil.copyfile(cwd + "/bitmaps/16/Example.png",
plugindir + "/bitmaps/16/Example.png")
shutil.copyfile(cwd + "/bitmaps/24/Example.png",
plugindir + "/bitmaps/24/Example.png")
DrFrame.AddPluginIcon("Example", plugindir + "/bitmaps/16/Example.png", plugindir
+ \
"/bitmaps/24/Example.png")
return
True
Note the return statement. This determines the behaviour after
your
plugin isntall script exits. If you return True, drpython will
continue to
install the plugin. This is good if you just want to install some
bitmaps,
but otherwise want drpython to handle the rest.
Returning False will tell drpython to halt the installation. This
is good if
you want to let the user cancel, or if you want to manually install the
plugin
yourself. Also note GetPluginDirectory(). This returns the
user directory
where plugins are stored once they are installed.
UnInstall Script:
If you want specific behaviour on uninstall,
write a method in your plugin file called
"UnInstall"
#Example
Plugin
import wx, os, os.path
def UnInstall(DrFrame):
plugindir = DrFrame.GetPluginDirectory()
if os.path.exists(plugindir
+ "/bitmaps/16/Example.png"):
os.remove(plugindir + "/bitmaps/16/Example.png")
if os.path.exists(plugindir
+ "/bitmaps/24/Example.png"):
os.remove(plugindir + "/bitmaps/24/Example.png")
DrFrame.RemovePluginIcon("Example")
return True
def Plugin(DrFrame):
yadda yadda yadda.....
Again, note the return. UnInstall must take a DrFrame as the only
argument.
If this function returns True, drpython will continue with the rest of
the uninstall
process. If the function returns False, drpython will halt the
uninstall.
Back to DrPython Help