Difference between revisions of "Tool Integration Development"

m
 
m
Line 23: Line 23:
  
 
{{Note| Through out this tutorial I'll be creating a tool that uses <eiffel>ES_GRID</eiffel>, an EiffelVision 2 grid (<eiffel>EV_GRID</eiffel> widget that has been specialized for use in EiffelStudio.}}
 
{{Note| Through out this tutorial I'll be creating a tool that uses <eiffel>ES_GRID</eiffel>, an EiffelVision 2 grid (<eiffel>EV_GRID</eiffel> widget that has been specialized for use in EiffelStudio.}}
 +
 +
<eiffel>ES_DOCKABLE_TOOL_WINDOW</eiffel> 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 <eiffel>deferred</eiffel> features from <eiffel>ES_DOCKABLE_TOOL_WINDOW</eiffel> to implement.
 +
* <eiffel>build_tool_interface</eiffel>
 +
* <eiffel>create_tool_bar_items</eiffel>
 +
* <eiffel>create_widget</eiffel>
 +
* <eiffel>tool_icon_buffer</eiffel>
 +
* <eiffel>tool_title</eiffel>
 +
 +
I'll discuss the rudimentary feature first and move on to the optional implementation.
 +
 +
=== <eiffel>tool_title</eiffel> ===
 +
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.
 +
 +
=== <eiffel>tool_icon_buffer</eiffel> ===
 +
As well as title, all tools require an icon to distiguish them from other tools. Instead of an <eiffel>EV_PIXMAP</eiffel> and <eiffel>EV_PIXEL_BUFFER</eiffel> 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 <eiffel>stock_pixmaps</eiffel>. I would recommend using <eiffel>stock_pixmaps.tool_objects_icon_buffer</eiffel> 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.
 +
 +
=== <eiffel>create_widget</eiffel> ===
 +
<eiffel>create_widget</eiffel> is a factory function that must return a widget of the same type as defined for the inherited <eiffel>ES_DOCKABLE_TOOL_WINDOW</eiffel>'s actual generic parameter. Here your tool should '''only''' create the widget and do any '''must'''-needed initialization. <eiffel>create_widget</eiffel> 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 <eiffel>build_tool_interface</eiffel>, but more on this later.

Revision as of 15:46, 10 August 2007


Construction.png Not Ready for Review: This Page is Under 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.

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.

Information.png 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.