Difference between revisions of "Accessing and Using Tools"

Latest revision as of 14:47, 31 October 2007

EiffelStudio's tools are, for the most part, created on an as-needed basis using a mechanism to dynamically create editions of a tool upon request. This prevents unnecessary objects from being created using up memory and delaying the appearance of the EiffelStudio IDE when launched. As such referencing an EiffelStudio tool directly is not recommended as a reference incurs the creation of the tool itself.

Foreword

Through out this page the term tool is used to describe a classes/objects that form the actual EiffelStudio tool. When talking explicitly of the constituting parts of a tool; tool descriptor and it's user interface the terms tool descriptor and tool panel are used respectively.

For more information on the constituting notions of a tool, see tool descriptor and tool panel.

Querying a Tool

Tools can be queried for on a per-IDE window basis so in order to access a tool, there has to access to an instance of EB_DEVELOPMENT_WINDOW.

Every instance of EB_DEVELOPMENT_WINDOW contains a reference to ES_SHELL_TOOLS via EB_DEVELOPMENT_WINDOW.shell_tools, a managed EiffelStudio core shell tool manager. To retrieve a tool descriptor simply query ES_SHELL_TOOLS.tool using a tool descriptor type. For instance, to access the Output Tool the following code could be used:

output_tool_for_window (a_window: EB_DEVELOPMENT_WINDOW): ES_OUTPUT_TOOL
  require
    a_window_attached: a_window /= Void
    not_a_window_is_recycled: not a_window.is_recycled
  do
    Result ?= a_window.shell_tools.tool ({ES_OUTPUT_TOOL})
  ensure
    result_attached: Result /= Void
  end

This will return the Output Tool tool descriptor for a supplied EiffelStudio IDE window.

Querying a Tool Edition

Some EiffelStudio tools or third party tools support multiple editions. Every multi-edition tool actually has a mini tool bar button to create a new edition of the current tool, for quick access. Apart from the graphically cue the only way to tell if a tool supports multiple editions is via the tool descriptor code to find the result of is_supporting_multiple_instances.

To actually retrieve an edition of the use tool the function ES_SHELL_TOOLS.tool_edition supplying the edition index. The edition index cannot just be an arbitrary index number. It must be an existing edition or the last edition + 1, which is used to fetch a new edition of the tool. If a new edition is what is sought then there are two way of accomplishing this:

new_watch_tool (a_window: EB_DEVELOPMENT_WINDOW): ES_WATCH_TOOL
  require
    a_window_attached: a_window /= Void
    not_a_window_is_recycled: not a_window.is_recycled
  local
    l_tools: ES_SHELL_TOOLS
  do
    l_tools := a_window.shell_tools 
    Result ?= l_tools.tool_edition ({ES_WATCH_TOOL}, l_tools.editions_of_tool ({ES_WATCH_TOOL}, False) + 1)
  ensure
    result_attached: Result /= Void
    not_result_is_recycled: not Result.is_recycled
  end

The code above uses the tool_edition function along with the editions_of_tool query to specify the next available edition. The last BOOLEAN parameter of editions_of_tool specifies if the edition count should return the number of "active" tool descriptors (tools with their user interface instantiated) or all tool descriptors. True to retrieve only the active tools, False to retrieve all.

A much easier way to retrieve a new edition is to use the ES_SHELL_TOOLS.tool_next_available_edition:

new_watch_tool (a_window: EB_DEVELOPMENT_WINDOW): ES_DEBUGGER_WATCH_TOOL
  require
    a_window_attached: a_window /= Void
    not_a_window_is_recycled: not a_window.is_recycled
  do
    Result ?= a_window.shell_tools.tool_next_available_edition ({ES_DEBUGGER_WATCH_TOOL}, False)
  ensure
    result_attached: Result /= Void
    not_result_is_recycled: not Result.is_recycled
  end

tool_next_available_edition takes a Boolean to determine if a non-instantiate tool descriptor should be reused, if available. It makes sense in some cases to make use of a tool descriptor that was queried but the tool panel user interface was never requested. In this case specifying True will reuse the unused tool descriptor and return it to the client. Specifying False will always create a new tool descriptor.

Fetching the Tool Panel User Interface

Note: Direct access to the tool panel user interface is not recommend! The user interface should not be interacted with by other parts of EiffelStudio. Instead interaction should be processed through the tool descriptor where it can decided whether to forward the interaction to the user interface base on if the user interface has been instantiated and initialized. For a example of this kind of vetted, proxy interaction see ES_ERROR_LIST_TOOL and ES_ERRORS_AND_WARNINGS_TOOL_PANEL.

If access to the tool panel user interface is required use the tool descriptor's panel function or more indirectly through EB_DEVELOPMENT_WINDOW.shell_tools.tool ({<tool descriptor type>}).panel. Please use digressions when using this function as it will create the tool's user interface if it has not already been created.

Stages of Tool Initialization

To delay any tool initialization until the absolute critical moment of when a tool user interface is actually visible, the internal of EiffelStudio instantiate and initialize the tool in different stages.

• Creation of a tool descriptor type.
• Creation of the tool descriptor.
• Creation and rudimentary initialization of the tool panel user interface.
• Full initialization of the tool panel user interface.

In the first stage a tool descriptor type is created. All tools should be accessed using a tool descriptor type so it means a type has to be created. For the ultimate in delayed-initialization a part of EiffelStudio should retain only the type and query the tool only when needed.

When querying for a tool descriptor using the tool type, through ES_SHELL_TOOLS, a tool descriptor will be created. When querying, a tool descriptor is created for every new edition of the tool and only one tool descriptor instance exists per edition.

Showing Tools (Quickly)

ES_SHELL_TOOLS provides sister routines to all the tool... routines. For every tool... function there is a show... variant used to show the tool without actually have to retain a tool descriptor and call show on it.

Show Command Object

For help in creating tool bar buttons or menu items for showing a tool using only a tool descriptor, ES_SHOW_TOOL_COMMAND is available. It does require the retrieval of a tool descriptor during creation so access to a instance of ES_SHELL_TOOLS is required. It's useful to use the ES_SHOW_TOOL_COMMAND as it handles all of the UI element creation as well as the activation of the tool.

Tool Memory Management

Tools managed by ES_SHELL_TOOLS are automatically recycled when the EiffelStudio IDE window is closed. Both the tool descriptor and the tool panel user interface are recycled and the user interface destroyed. If there is a need to explicitly recycle the tool then it should be done through the tool descriptor and not via the tool panel user interface.

For more information on tool recycling see, User Interface Memory Management.