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.

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.

It should be noted that tool_title and title can represent different values. tool_title should remain constant, title is a mutable title of the tool settable via set_title. tool_title is used in the initialization of title and nothing more. Of course you are free to base a new title using tool_title as part of an aggregated 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_output_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.