Difference between revisions of "Using Dialog Prompts (Basic)"

Latest revision as of 09:18, 14 May 2008

There are two methods of displaying dialog prompts inside EiffelStudio. Firstly there is the simple and effective approach, which requires very little coding but offers very little in the way of customization. The second approach can be simple, but by not means as simple as the first, and can offer a great deal of customization. The information in this page pertains for the former approach. To use the latter please see Using Dialog Prompts (Advanced).

Getting Started

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

You may also want to check out the following pages:

• Tool Dialog Prompts
• Taxonomy of Dialog Prompts
• Dialog Prompt Messages and Formatting

Displaying 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.

For a quick reference, here is the one of the show routines from ES_PROMPT_PROVIDER.

show_error_prompt (a_message: STRING_32; a_window: EV_WINDOW; a_ok_action: PROCEDURE [ANY, TUPLE])
      -- Displays an error prompt to the user with an Ok button only
      --
      -- `a_message': A message to display to the user
      -- `a_window': A parent window, or Void if none is available
      -- `a_ok_action': An option action to perform when the user clicks the 'Ok' button.
    require
      a_message_attached: a_message /= Void
      not_a_message_is_empty: not a_message.is_empty

As you might see from using ES_PROMPT_PROVIDER, the routines provide little means for custom the dialog prompts. Instead its purpose is for the quick creation and display of standard dialog prompts.

An Example

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 dialog prompt on the EiffelStudio 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:

Formatting Dialog Prompt Text

When creating dialog prompt you may feel compelled to insert new-line characters into a dialog prompt's display text to wrap the text correctly. There is no need, and, it's not recommended.

Dialog prompts automatically wrap the text using an internal predefined limit, which may change in the future when screen resolutions increase or the minimum required resolution for EiffelStudio is upped or lowered. Dialog prompt text should not contain any new-line characters unless some explicit formatting is require to separate terse paragraphs or to highlight data by placing it on a new line.

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 classes 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. 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 accomplished 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.