Difference between revisions of "Accessing and Using Tools"

m (Foreword)
m
 
Line 1: Line 1:
 
[[Category:EiffelStudio]]
 
[[Category:EiffelStudio]]
 
[[Category:Extending 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.
 
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.
  
Line 7: Line 7:
 
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.
 
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]].
+
For more information on the constituting notions of a tool, see [[Tool Integration Development#Tool Descriptors|tool descriptor]] and [[Tool Integration Development#Tool Panels|tool panel]].
  
 
== Querying a Tool ==
 
== 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]].
+
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 [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/new_graphical/windows/eb_development_window.e 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:
+
Every instance of [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/new_graphical/windows/eb_development_window.e EB_DEVELOPMENT_WINDOW] contains a reference to [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_shell_tools.e 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>
 
<eiffel>
Line 30: Line 30:
 
=== Querying a Tool Edition ===
 
=== 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>.
+
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 Integration Development#Tool Descriptors|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:
 
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:
Line 67: Line 67:
 
</eiffel>
 
</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]].
+
<eiffel>tool_next_available_edition</eiffel> takes a Boolean to determine if a non-instantiate [[Tool Integration Development#Tool Descriptors|tool descriptor]] 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 Integration Development#Tool Panels|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 ===
 
=== 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]].}}
+
{{Note|Direct access to the [[Tool Integration Development#Tool Panels|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 Integration Development#Tool Descriptors|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 [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/tools/event_list_service/error_list/es_error_list_tool.e ES_ERROR_LIST_TOOL] and [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/tools/event_list_service/error_list/es_errors_and_warnings_tool_panel.e 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.
+
If access to the [[Tool Integration Development#Tool Panels|tool panel]] user interface is required use the [[Tool Integration Development#Tool Descriptors|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 ==
 
== 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.
 
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 a [[Tool Integration Development#Tool Descriptors|tool descriptor]] type.
* Creation of the [[tool descriptor]].
+
* Creation of the [[Tool Integration Development#Tool Descriptors|tool descriptor]].
* Creation and rudimentary initialization of the [[tool user interface panel]].
+
* Creation and rudimentary initialization of the [[Tool Integration Development#Tool Panels|tool panel]] user interface.
* Full initialization of the [[tool panel]] user interface.
+
* Full initialization of the [[Tool Integration Development#Tool Panels|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.
+
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 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.
+
When querying for a [[Tool Integration Development#Tool Descriptors|tool descriptor]] using the tool type, through [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_shell_tools.e 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 new edition of the tool and only one [[Tool Integration Development#Tool Descriptors|tool descriptor]] instance exists per edition.
  
 
== Showing Tools (Quickly) ==
 
== 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.
+
[https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_shell_tools.e 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 Integration Development#Tool Descriptors|tool descriptor]] and call <eiffel>show</eiffel> on it.
  
 
== Show Command Object ==
 
== 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.  
+
For help in creating tool bar buttons or menu items for showing a tool using only a [[Tool Integration Development#Tool Descriptors|tool descriptor]], [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_show_tool_command.e ES_SHOW_TOOL_COMMAND] is available. It does require the retrieval of a [[Tool Integration Development#Tool Descriptors|tool descriptor]] during creation so access to a instance of [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_shell_tools.e ES_SHELL_TOOLS] is required. It's useful to use the [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_show_tool_command.e ES_SHOW_TOOL_COMMAND] as it handles all of the UI element creation as well as the activation of the tool.  
  
 
== Tool Memory Management ==
 
== 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.
+
Tools managed by [https://svn.eiffel.com/eiffelstudio/trunk/Src/Eiffel/interface/graphical/foundations/tools/es_shell_tools.e 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 Panels|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 Integration Development#Tool Descriptors|tool descriptor]] and not via the [[Tool Integration Development#Tool Panels|tool panel]] user interface.
  
 
For more information on tool recycling see, [[User Interface Memory Managment|User Interface Memory Management]].
 
For more information on tool recycling see, [[User Interface Memory Managment|User Interface Memory Management]].

Latest revision as of 15: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

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

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.