View source for Accessing and Using Tools

You do not have permission to edit this page, for the following reasons:
The action you have requested is limited to users in one of the groups: Autoconfirmed users, emailconfirmed, editors.
You must confirm your email address before editing pages. Please set and validate your email address through your user preferences.
You can view and copy the source of this page:
[[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.

== 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 <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 use tool the function <eiffel>ES_SHELL_TOOLS.tool_edition</eiffel> 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:

<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" tool descriptors (tools with their user interface instantiated) or all tool descriptors. <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 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 <eiffel>True</eiffel> will reuse the unused [[tool descriptor]] and return it to the client. Specifying <eiffel>False</eiffel> 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 <eiffel>panel</eiffel> function or more indirectly through <eiffel>EB_DEVELOPMENT_WINDOW.shell_tools.tool ({<tool descriptor type>}).panel</eiffel>. 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 user interface panel]].
* 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 [[Ttool 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 <eiffel>tool...</eiffel> routines. For every <eiffel>tool...</eiffel> function there is a <eiffel>show...</eiffel> variant used to show the tool without actually have to retain a [[tool descriptor]] and call <eiffel>show</eiffel> 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|tool user interface panel]] 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 Managment|User Interface Memory Management]].
Template used on this page:
Template:Note (view source)
Return to Accessing and Using Tools.
Retrieved from "https://dev.eiffel.com/Accessing_and_Using_Tools"
View source for Accessing and Using Tools

Navigation

Development

Wiki

Search

Tools
