Difference between revisions of "Tool Dialog Prompts"

Revision as of 14:21, 4 September 2007

Dialog prompts are an essential part of Tool Integration Development and Services in EiffelStudio. As such we have provide a number of EiffelStudio specific classes for creating and displaying EiffelStudio dialog prompts.

Consistent Look and Feel

As of EiffelStudio 6.1 (EiffelStudio 6.1 Releases), EiffelStudio uses custom dialog prompts that come in a flavor of presentation that stands above the stock dialog prompts found in EiffelVision2. As such all dialog prompts in EiffelStudio should be using the new prompt classes instead of those found in EiffelVision2 or the slightly specialized versions found in previous versions of EiffelStudio.

Just to get an idea of what the new prompts look like, here’s an example:

New Features

The new dialog prompts in EiffelStudio no only have an update look and feel to them but the come with a number of added benefits for both end-users and EiffelStudio tool developers:

• Brand new look.
• Automatic layout of widgets and other text.
• Button layouts are platform-dependent (Ok|Cancel on Windows, Cancel|Ok on Mac OSX.)
• Dual-model; providing agent actions to perform on button presses and/or retrieval of the dialog result code.
• Simplified interfaces with less code to write.
• Extendable (see ES_DISCARDABLE_COMPILE_SAVE_FILES_PROMPT.)
• Provides both standard and advanced creation routines for quick or complex creation.
• An abstraction that makes it easy to replace the prompts in the future, updating the look etc.
• Dialog prompts are always modal to the parent window.
• Automatic location of the last active EiffelStudio window so tools need not worry about window management.
• Automatic key navigation binding; Use of TAB, LEFT or RIGHT cursor keys and button first(or next)-character key (Yes => Y, Create => C, ...)

Displaying Dialog Prompts, the Easy Way

Instead of creating dialog prompts and displaying them using the ES_XXX_PROMPT classes directly you can use a help class ES_PROMPT_PROVIDER (or inherit the shared class ES_SHARED_PROMPT_PROVIDER and access prompts.) Of course, the easy way does limit functionality but for the vast majority of cases the routines of ES_PROMPT_PROVIDER provide all that is needed.

Note: For tool and dialog development ES_DOCKABLE_TOOL_WINDOW and ES_DIALOG both inherit ES_SHARED_PROMPT_PROVIDER and provide access to a shared instance of ES_PROMPT_PROVIDER through a feature prompts.

ES_PROMPT_PROVIDER provides a quick means to display dialog prompts and associate any actions with the default buttons created on the prompts. The routine are self explanatory, Each routine shows the prompt specific to the situation, show_error_prompt will show an error prompt, show_warning_prompt shows an warning prompt, show_info_prompt shows an information prompt and finally, show_question_prompt show a prompt designated for asking the user a question.

There are the show_xxx_with_cancel variants, which includes a cancel button along with the standard set of buttons.

Prompt Arguments

Using ES_PROMPT_PROVIDER does not provide any means to custom the dialog prompts instead its purpose is for the quick creation and display of standard dialog prompts.

Every show_xxx_prompt routine requires a message string, which relates to the message the user is shown.

The argument specifying the parent window to display the prompt to is optional. If Void is passed for this argument then the last focused window/dialog is used as the parent window or the last active EiffelStudio IDE main window.

The other routine arguments are for any actions that should be associated with a button press in the prompt. Simply pass an appropriate agent or Void to specify no action.

Using Dialog Prompts In the Eiffel Framework

ES_PROMPT_PROVIDER and ES_SHARED_PROMPT_PROVIDER are accessible from the Eiffel framework library, however the underlying implementation in the framework library actually uses the older EB_XXX_DIALOGs instead of the new ES_XXX_PROMPT classes.

The new ES_XXX_PROMPT rely on classes found in the EiffelStudio IDE so for the sake of compatibility the old EB_XXX_DIALOG classes have not been removed from the framework. This means when you are developing with the framework library outside of the EiffelStudio (target bench) project you will see the older dialog prompts, this is normal. Once your code is integrated into the EiffelStudio project, even if it is referenced as a library by the project, you code will automatically use the new dialog prompts for EiffelStudio. Under no circumstances should you be using the EB_XXX_DIALOG dialog prompt classes directly, please use the routines of ES_PROMPT_PROVIDER.

This transparent switching of implementation is accomplished by using an override cluster in the EiffelStudio (target bench) project, overriding the default implementation in the framework library with the EiffelStudio specific implementation.

Note: The transparent switching is done through overriding the default implementation of ES_PROMPT_PROVIDER and not any of the EB_XXX_DIALOG classes! If you use the EB_XXX_PROMPT classes directly you will see no change with integrating you code. All the EB_XXX_PROMPT classes have been marked obsolete so the only obsolete warnings you should see if those from ES_PROMPT_PROVIDER.

An Example, the Easy Way

To simply demonstrate the use of ES_PROMPT_PROVIDER by inheriting the shared class ES_SHARED_PROMPT_PROVIDER, the code below is all that is needed to show an Error prompt on the IDE window, with the message "This is an Error prompt".

prompts.show_error_prompt ("This is an Error prompt", Void, Void)

The result of executing the above code results in a dialog prompt like the one below:

To get a little more into prompts, here's a confirmation prompt that performs actions when pressing a button. Note, inline agents are used here just for the purpose of brevity.

prompts.show_question_prompt ("If you press Yes, I'll tell you something...", Void,
  agent
    do
        -- Agent action for 'Yes' button.
      prompts.show_info_prompt ("You pressed Yes!", Void, Void)
    end,
  agent
    do
        -- Agent action for 'No' button.
      prompts.show_error_prompt ("You should have pressed Yes!", Void, Void)
    end
  )

The result of executing the above code results in a dialog prompt like the one below:

Pressing the Yes button on the question dialog prompt produces the dialog prompt:

Pressing the No button on the question dialog prompt produces the dialog prompt: