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.

It should be noted; just like tool_title, tool_icon_buffer should remain unmodified as it is used only during initialization. icon actually represents the icon pixel buffer used by the tool, which may be changed using set_icon. Of course if you need to reset the tool you can always call set_icon with tool_icon_buffer as an argument and the icon will appear as it did on first show.

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 initialization can be done in build_tool_interface, but more on this later.

build_tool_interface

Briefly mentioned in the description of create_widget, build_tool_interface is implemented to perform the brunt of all tool initialization. Initialization of the tool covers the creation of additional widget objects, setting parameters and extending them to user_widget. When called, build_tool_interface receives the created user widget as an argument a_widget. You are encouraged to use a_widget instead of accessing user_widget directly to avoid any possible, unavoidable future initialization recursion issues.

Tool bars and tool bar buttons need not be created in build_tool_interface because tool bars are created using create_tool_bar_items and other such like factory functions, which will be discussed later.

Note: build_tool_interface is called only when the window is shown for the first time, which can lead to calls being made on Void targets, if you tool is accessed from other parts of EiffelStudio. If you tool is stand-alone then this is not a concern. See the "Gotcha" information below

create_tool_bar_items

Most tools require some form of propriatery tool bar so it's only natural that the base implementation provide a means to add one. By default create_tool_bar_items is deferred because it's more a case to have a tool bar than it is not to have one. create_tool_bar_items can have no implementation so it a tool bar is not require, simply return Void or an empty list.

create_tool_bar_items is called once upon initialization and only requires any implementation to return a list of tool bar items, which can be any item that derives SD_TOOL_BAR_ITEM. Initialization takes car of constructing the tool bar and placing the buttons on it, determined by the order the buttons appear in the Result list. If Void or and empty list is returned then no tool bar will be created.

For the more adventerous, take a look at and even experiment with the following features; is_tool_bar_bottom_aligned, create_right_tool_bar_items and create_mini_tool_bar_items.

A Delayed Initialization Gotcha

build_tool_interface is called only when the window is shown for the first time, which can lead to calls being made on Void targets, if you tool is accessed from other parts of EiffelStudio. If you tool is stand-alone then this is not a concern.

In the example of the Errors and Warnings tool, the event list service pushes error event list items to the tool. When an error item is pushed the UI must respond by enabling tool bar buttons and other commands. The Errors and Warnings tool may still be hidden and so build_tool_interface not yet called. This creates a situation where the UI widgets are held in an unattached state and making calls on them illegal. There are two solutions:

• Protect calls to the widget by testing if it is attached to an object.
• Where access to a widget object, created in build_tool_interface, is required call initialize (respecting the preconditions.)

The Errors and Warnings tool actually uses the latter of these solutions as seen in on_event_added and on_event_removed.

Both of the solution respect the recommended approach fordelaying the initialization of the tool until requested. In the first solution the tool simply ignores any UI manipulation requested, which could be deferred until the tool is show if so applicable. The latter option forces initialization because it is deemed time to initialize. The tool will most likely have already been created and EiffelStudio made visible before any interaction with the tool takes place thereby, in effect, delaying the initialization the tool.

There is another solution, but it is not recommended because it will initialize the tool upon creation, and penalizes start up performance; it is mention for the purpose of an absolute requirement! You can initialize the tool upon creation, when EiffelStudio is starting up, by redefining on_before_initialize and making a call to initialize.