View source for Accessing and Using Tools

[[Category:EiffelStudio]]
[[Category:Extending EiffelStudio]]
{{UnderConstruction}}
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.

== 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 <eiffel>EB_DEVELOPMENT_WINDOW.shell_tools</eiffel>, a managed EiffelStudio core shell tool manager. To retrieve a [[Tool Integration Development#Tool Descriptors|tool descriptor]] simply query <eiffel>ES_SHELL_TOOLS.tool</eiffel> using a [[Tool Integration Development#Tool Descriptors|tool descriptor]] type. For instance, to access the '''Output Tool''' the following code could be used:

<eiffel>
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
</eiffel>

This will return the Output Tool [[Tool Integration Development#Tool Descriptors|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 <eiffel>is_supporting_multiple_instances</eiffel>.

To actually retrieve an edition of the tool the function <eiffel>ES_SHELL_TOOLS.tool_edition</eiffel> supplying the edition index. The edition index cannot be an arbitary index number. I must be an existing edition or the last edition + 1 to fetch a new edition of the tool. If a new edition is what is sought then there are two way of accomplishing this:

<eiffel>
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
</eiffel>

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

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

<eiffel>
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
</eiffel>

<eiffel>tool_next_available_edition</eiffel> takes a [[BOOLEAN]] to determine if a non-instantiate tool should be reused, if available. It makes sense in some cases to make use of a [[Tool Integration Development#Tool Descriptors|tool descriptor]] that was queried but the tool panel user interface was never requested. In this case specifying <eiffel>True</eiffel> will reuse the unused [[Tool Integration Development#Tool Descriptors|tool descriptor]] and return it to the client. Specifying <eiffel>False</eiffel> will always create a new [[Tool Integration Development#Tool Descriptors|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/shim where it can decided whether to forward the interaction to the user interface base on if the user interface has been created and initialized or not. For a example of this kind of 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 <eiffel>ES_TOOL [G].tool</eiffel> or <eiffel>EB_DEVELOPMENT_WINDOW.shell_tools.tool ({<tool descriptor type>}).tool</eiffel>. Please use digressions when using this function as it will create the tool's user interface if it has not already been created.

== Show Command Object ==

== 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 Integration Development#Tool Descriptors|tool descriptor]] type.
* Creation of the [[Tool Integration Development#Tool Descriptors|tool descriptor]].
* Creation and rudimentary initialization of the [[Tool Integration Development#Tool Panel|tool user interface panel]].
* Full initialization of the [[Tool Integration Development#Tool Panel|tool user interface panel]].

In the first stage a [[Tool Integration Development#Tool Descriptors|tool descriptor]] type is created. All tools should be accessed using a [[Tool Integration Development#Tool Descriptors|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 Integration Development#Tool Descriptors|tool descriptor]] using the tool type, through [[ES_SHELL_TOOLS]], a [[Tool Integration Development#Tool Descriptors|tool descriptor]] will be created. When querying, a [[Tool Integration Development#Tool Descriptors|tool descriptor]] is created for every edition of the tool, but there is only one [[Tool Integration Development#Tool Descriptors|tool descriptor]] instance per edition.

For some of the built-in EiffelStudio tools

== Recycling a Tool ==
Tools managed by [[ES_SHELL_TOOLS]] are automatically recycled when the EiffelStudio IDE window is closed. Both the [[Tool Integration Development#Tool Descriptors|tool descriptor]] and the [[Tool Integration Development#Tool Panel|tool user interface panel]] are recycled and the user interface destroyed. If there is a need to explictly recycle the tool then it should be done through the [[Tool Integration Development#Tool Descriptors|tool descriptor]] and not via the [[Tool Integration Development#Tool Panel|tool user interface panel]].