Difference between revisions of "Accessing and Using Tools"

Revision as of 14:02, 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.

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 tool the function ES_SHELL_TOOLS.tool_edition 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:

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" tools (tools with their user interface created) or all tools. 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 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/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 ES_TOOL [G].tool or EB_DEVELOPMENT_WINDOW.shell_tools.tool ({<tool descriptor type>}).tool. 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 descriptor type.
• Creation of the tool descriptor.
• Creation and rudimentary initialization of the tool user interface panel.
• Full initialization of the tool user interface panel.

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 edition of the tool, but there is only one 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 descriptor and the 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 descriptor and not via the tool user interface panel.