The eric4 plug-in system
The eric4 plug-in system
Version 4.3
Copyright © 2007-2009 Detlev Offenbach <detlev@die-offenbachs.de>
Page 1 of 45
The eric4 plug-in system
Table of contents
1 Introduction......................................................................................................................4
2 Description of the plug-in system.....................................................................................4
3 The plug-in system from a user perspective....................................................................4
3.1 The Plug-ins menu and toolbar................................................................................4
3.2 The Plug-in Infos dialog............................................................................................5
3.3 Installing Plug-ins......................................................................................................8
3.4 Uninstalling Plug-ins...............................................................................................12
3.5 The Plug-ins repository...........................................................................................13
4 Eric4 for plug-in developers...........................................................................................14
5 Anatomy of a plug-in......................................................................................................18
5.1 Plug-in structure......................................................................................................18
5.2 Plug-in header........................................................................................................18
5.3 Plug-in module functions........................................................................................20
5.3.1 moduleSetup().................................................................................................20
5.3.2 prepareUninstall()............................................................................................21
5.3.3 getConfigData()...............................................................................................21
5.3.4 previewPix().....................................................................................................22
5.3.5 exeDisplayData().............................................................................................22
5.3.6 apiFiles(language)...........................................................................................25
5.4 Plug-in object methods...........................................................................................26
5.4.1 __init__(self, ui)...............................................................................................26
5.4.2 activate(self)....................................................................................................26
5.4.3 deactivate(self)................................................................................................27
5.4.4 __loadTranslator(self)......................................................................................28
6 Eric4 hooks....................................................................................................................29
6.1 Hooks of the project browser objects.....................................................................29
6.1.1 Hooks of the ProjectFormsBrowser object......................................................29
6.1.2 Hooks of the ProjectResourcesBrowser object...............................................30
6.1.3 Hooks of the ProjectTranslationsBrowser object............................................30
6.2 Hooks of the Editor object......................................................................................31
7 Eric4 functions available for plug-in development.........................................................32
7.1 The eric4 object registry.........................................................................................32
7.2 The action registries...............................................................................................33
7.3 The getMenu() methods.........................................................................................33
7.4 Methods of the PluginManager object....................................................................36
7.5 Methods of the UserInterface object......................................................................36
7.6 Methods of the E4ToolBarManager object.............................................................36
7.7 Methods of the Project object.................................................................................37
7.8 Methods of the ProjectBrowser object....................................................................38
7.9 Methods of QScintilla.Lexer....................................................................................39
7.10 Signals..................................................................................................................40
8 Special plug-in types......................................................................................................44
8.1 VCS plug-ins...........................................................................................................44
8.2 ViewManager plug-ins............................................................................................45
Page 2 of 45
The eric4 plug-in system
List of figures
Figure 1: eric4 main menu.....................................................................................................4
Figure 2: The Plug-ins menu..................................................................................................4
Figure 3: The Plug-ins toolbar................................................................................................5
Figure 4: Plug-ins Info dialog.................................................................................................6
Figure 5: Plug-ins Info dialog context menu..........................................................................7
Figure 6: Plug-in Details dialog..............................................................................................7
Figure 7: Plug-ins Installation dialog, step 1..........................................................................9
Figure 8: Plug-ins Installation dialog, step 2........................................................................10
Figure 9: Plug-ins Installation dialog, step 3........................................................................11
Figure 10: Plug-ins Installation dialog, step 4......................................................................12
Figure 11: Plug-ins Installation dialog, step 5......................................................................12
Figure 12: Plug-in Uninstallation dialog, step 1...................................................................13
Figure 13: Plug-in Uninstallation dialog, step 2...................................................................13
Figure 14: Plug-in Repository dialog....................................................................................14
Figure 15: Plug-in specific project properties.......................................................................15
Figure 16: Packagers submenu...........................................................................................15
List of listings
Listing 1: Example of a PKGLIST file...................................................................................17
Listing 2: Plug-in header......................................................................................................18
Listing 3: Additional header for on-demand plug-ins...........................................................20
Listing 4: Example for the moduleSetup() function..............................................................21
Listing 5: Example for the prepareUninstall() function.........................................................21
Listing 6: Example for the getConfigData() function............................................................22
Listing 7: Example for the previewPix() function..................................................................22
Listing 8: Example for the exeDisplayData() function returning a dictionary of type 1........24
Listing 9: Example for the exeDisplayData() function returning a dictionary of type 2........25
Listing 10: Example for the apiFiles(language) function......................................................25
Listing 11: Example for the __init__(self, ui) method...........................................................26
Listing 12: Example for the activate(self) method................................................................27
Listing 13: Example for the deactivate(self) method............................................................28
Listing 14: Example for the __loadTranslator(self) method.................................................29
Listing 15: Example for the usage of the object registry......................................................33
Listing 16: Example of the getVcsSystemIndicator() function.............................................44
Page 3 of 45
The eric4 plug-in system
1 Introduction
eric 4.1 introduced a plug-in system, which allows easy extension of the IDE. Every user
can customize the application by installing plug-ins available via the Internet. This
document describes this plug-in system from a user perspective and from a plug-in
developers perspective as well.
2 Description of the plug-in system
The eric4 plug-in system is the extensible part of the eric4 IDE. There are two kinds of
plug-ins. The first kind of plug-ins are automatically activated at startup, the other kind are
activated on demand. The activation of the on-demand plug-ins is controlled by
configuration options. Internally, all plug-ins are managed by the PluginManager object.
Deactivated autoactivate plug-ins are remembered and will not be activated automatically
on the next start of eric4.
Eric4 comes with quite a number of core plug-ins. These are part of the eric4 installation.
In addition to this, there are additional plug-ins available via the internet. Those plug-ins
may be installed and uninstalled using the provided menu or toolbar entries. Installable
plug-ins live in one of two areas. One is the global plug-in area, the other is the user plug-
in area. The later one overrides the global area.
3 The plug-in system from a user perspective
The eric4 plug-in system provides the user with a Plug-ins menu in the main menu bar and
a corresponding toolbar. Through both of them the user is presented with actions to show
information about loaded plug-ins and to install or uninstall plug-ins.
3.1 The Plug-ins menu and toolbar
The plug-ins menu is located under the “Plugins” label in the main menu bar of the eric4
main window. It contains all available user actions and is accompanied by a toolbar
containing the same actions. They are shown in the following figures.
Page 4 of 45
Figure 1: eric4 main menu
Figure 2: The Plug-ins menu
The eric4 plug-in system
The “Plugin Infos...” action is used to show a dialog, that lists all the loaded plug-ins and
there status. The entry labeled “Install Plugins...” opens a wizard like dialog to install new
plug-ins from plug-in archives. The entry, “Uninstall Plugin...”, presents a dialog to uninstall
a plug-in. If a plug-in to be uninstalled is loaded, it is unloaded first. The entry called
“Plugin Repository...” shows a dialog, that displays the official plug-ins available in the
eric4 plug-in repository. The “Configure...” entry opens the eric4 configuration dialog
displaying the Plugin Manager configuration page.
3.2 The Plug-in Infos dialog
The “Plugin Infos” dialog shows information about all loaded plug-ins. Plug-ins, which had
a problem when loaded or activated are highlighted. More details are presented, by double
clicking an entry or selecting the “Show details” context menu entry. An example of the
dialog is show in the following figure.
Page 5 of 45
Figure 3: The Plug-ins toolbar