Tool Integration Development
Welcome to the the EiffelStudio tool integration development page. The content held within this page will show you how to develop and integrate an new tool in EiffelStudio.
Contents
Getting Started
We are just getting started so this tutorial will only cover the basics for more advanced tutorials, see Tool_Integration_Advanced_Development and Tool_Integration_Service_Development and Services.
Requirements
The content of this tutorial relates to the working version of EiffelStudio 6.1, current attainable from the open source repository https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel. Please see the pages on attain the EiffelStudio source code from the Repository, Compiling EiffelStudio and Debugging_EiffelStudio.
Once you have EiffelStudio compiled and in a state where it can be debugged then continue reading.
An Implemented Tool Reference
If at any time you need to reference an actually implementation of a tool using the information in these pages, see the implementation of ES_ERRORS_AND_WARNINGS_TOOL
in the EiffelStudio code.
Creating a Tool
Before anything else can be done you need to create a tool. Most tools inside EiffelStudio utilized a class call EB_TOOL
(as of 6.1.) EB_TOOL
is current the most basic tool class and has become a little outdated. In 6.1 a new abstract base class call ES_DOCKABLE_TOOL_WINDOW
was created for the purpose of creating EiffelStudio tools with greater ease. ES_DOCKABLE_TOOL_WINDOW
still derives from EB_TOOL
but this may change in the future if all tools are converted to use ES_DOCKABLE_TOOL_WINDOW
instead.
So to be clear, only use ES_DOCKABLE_TOOL_WINDOW
as your base for tool development.
ES_DOCKABLE_TOOL_WINDOW
requires a generic parameter constrained to EV_WIDGET
. The generic parameter, G
, represents the "user widget". The user widget, defined by the feature user_widget
is the top level widget you tool should interact with. If you tool consists of just a grid, list or tree widget then the user control will be of the respective type.
To start out create a new Eiffel class and inherit ES_DOCKABLE_TOOL_WINDOW
, specifying the generic parameter for your user widget.
Note: Through out this tutorial I'll be creating a tool that uses ES_GRID
, an EiffelVision 2 grid (EV_GRID
widget that has been specialized for use in EiffelStudio.
ES_DOCKABLE_TOOL_WINDOW
has many advantages to being a base class for all tool; simplified implementation, a small number of required to implement features and delayed initialization of the tool itself. This last aspect is important because the more tool that are put into EiffelStudio the more time it takes to start up. Using delayed initialization comes with a few gotcha that'll you run into but it's recommended that it is used, so not to slow down EiffelStudio.
Implementing the Requirements
There is less than a hand full of deferred
features from ES_DOCKABLE_TOOL_WINDOW
to implement.
-
build_tool_interface
-
create_tool_bar_items
-
create_widget
-
tool_icon_buffer
-
tool_title
I'll discuss the rudimentary feature first and move on to the optional implementation.
tool_title
Every tool requires it has a title. The title is the text that is displayed when the tool is first created. Generally the title should be internationalized but I'll discuss this in a further tutorial. Simple return a attached non-empty Eiffel string.
tool_icon_buffer
As well as title, all tools require an icon to distiguish them from other tools. Instead of an EV_PIXMAP
and EV_PIXEL_BUFFER
is require, which retains information related to the alpha channel of a pixmap.
For now, simply use one of the stock EiffelStudio icons available from stock_pixmaps
. I would recommend using stock_pixmaps.tool_objects_icon_buffer
as it is generic enough for now.
If you wish to add your own pixmap matrix and use the Eiffel Matrix Code Generator tool then feel free. The project source root folder contains a file call readme.txt that explains the format of a configuration file.
create_widget
create_widget
is a factory function that must return a widget of the same type as defined for the inherited ES_DOCKABLE_TOOL_WINDOW
's actual generic parameter. Here your tool should only create the widget and do any must-needed initialization. create_widget
will be called the first time the tool requires the user widget and it will only be called once per development window. Any other intialization can be done in build_tool_interface
, but more on this later.