Difference between revisions of "Tool Dialog Prompts"

Revision as of 13:25, 5 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, ...)
• Ability to set a default active button.

Choosing a Dialog Prompt

Making the correct choice as to which dialog prompt to display is crucial, and is not as easy as you think. There is a page dedicate to deciding what dialog prompt is best suited for the need of a particular message - Taxonomy of Dialog Prompts. For help on choosing and formatting dialog prompt messages, see Dialog Prompt Messages and Formatting.

Displaying Dialog Prompts, the Easy Way

For the simplest way to show dialog prompts inside EiffelStudio or to use dialog prompts in the Eiffel framework library see Using Dialog Prompts (Basic)

Displaying Dialog Prompts, the Other Way

If more control is what you are after then using the ES_PROMPT_PROVIDER may not be of any use. As such you can instantiate, use and display the EiffelStudio prompt classes directly.

There are, as of EiffelStudio 6.1, four common dialog prompt classes for use which are self-explanatory.

• ES_ERROR_PROMPT: Used to display a error.
• ES_WARNING_PROMPT: Used to display a warning
• ES_INFORMATION_PROMPT: Used to display a piece of informative text.
• ES_QUESTION_PROMPT: Used to ask the user a yes/no question.

Each dialog prompt class provide two or more creation routines; make and make_standard. Some prompt classes also have an addition creation routine, make_standard_with_cancel, to augment the standard button set with a Cancel button. The creation routine make offers the most control but requires more information to create the dialog. The make_standard creation routines are simpler and only require a dialog prompt message.

The make_standard creation routines initialize the dialog prompt using a standard set of dialog buttons in the order dictated by the executing platform. The standard dialog buttons are as follows (ordering representative on Windows):

• Error: Ok
• Warning: Ok
• Information: Ok
• Question: Yes|No

As mentioned, some of the prompts come with a third creation routine, make_standard_with_cancel, augmenting the existing dialog prompt's button set with a Cancel button. The only dialog prompt not to have a third creation routine is the Error prompt as an error is usual considered an exception case and general there is no recourse action. The standard dialog buttons "with cancel" are as follows (ordering representative on Windows):

• Warning: Ok|Cancel
• Information: Ok|Cancel
• Question: Yes|No|Cancel

Button Sets

Most dialog prompts have a standard set of buttons and being so ES_DIALOG_BUTTONS provides access to the well-known and commonly used button sets, such as Ok|Cancel, Yes|No and even Abort|Retry|Ignore.

Note: All dialog prompts inherit ES_SHARED_DIALOG_BUTTONS through the base dialog implementation ES_DIALOG (see Tool Dialogs for more information on ES_DIALOG and dialog button sets.)

Responding to User Interactions

As stated above in the New Features section the ES_XXX_PROMPT classes proffer two models based on the consequence of a user's interaction with the dialog prompt.

Agent Assignment

The primary model is the use of agents, assigning them to a button using a button identifier.

After creating a prompt you may associate an agent to a button using ES_PROMPT.set_button_action. The routine takes a button identifier, which must be an identifier of a button on the prompt, as well as an agent action.

ask_save_changes
    -- Ask user if they want to save the changes before continuing
  local
    l_prompt: ES_QUESTION_PROMPT
  do
    create l_prompt.make_standard ("Save changes before continuing?")
    l_prompt.set_button_action ({ES_DIALOG_BUTTONS}.yes_button, agent save_changes)
    l_prompt.show_on_active_window
  end
 
save_changes
    -- Save all changes
  do
    ...
  end

In the example a question prompt was created using the standard set of buttons for question prompts, which in this case are Yes and No buttons. Post-creation and initialization the Yes button is assigned an agent through the call to set_button_action. set_button_action is passed the button identifier yes_button, which is statically accessed from ES_DIALOG_BUTTONS. yes_button could have just as easily been accessed from the dialog_buttons function exported on the prompt class:

l_prompt.set_button_action (l_prompt.dialog_buttons.yes_button, agent save_changes)

However, static access if preferred if appropriate for the situation.

Using Dialog Result

The second model of processing actions or changing execution flow, based on the user's interaction with the dialog prompt, is through the result dialog_result. Like button identifiers, dialog_result is an INTEGER and is set once the dialog has been closed buy the result of a user's interaction.

Here is the same example written using the dialog result model.

ask_save_changes
    -- Ask user if they want to save the changes before continuing
  local
    l_prompt: ES_QUESTION_PROMPT
  do
    create l_prompt.make_standard ("Save changes before continuing?")
    l_prompt.show_on_active_window
 
    if l_prompt.dialog_result = {ES_DIALOG_BUTTONS}.yes_button then
      save_changes
    end
  end
 
save_changes
    -- Save all changes
  do
    ...
  end

Using static access for the dialog button identifiers also allows you to opt to use the Eiffel inspect construct instead of using if...then...elseif...then...end:

inspect l_prompt.dialog_result
when {ES_DIALOG_BUTTONS}.yes_button then
  save_changes
when {ES_DIALOG_BUTTONS}.no_button then
  do_something_else
end

Changing Button Labels

There are times when a dialog prompt's button labels are not adequate enough to get the full message over to the user, or simply that you want a dialog prompt's buttons to show an extremely terse explaination of their action. Once such dialog in EiffelStudio is the Discard Assertions question prompt:

File:Dialog prompt example finalization.png

The discard assertion dialog prompt is a question prompt that has had it's Yes button label set to Discard Assertions and No button label set to Keep Assertions. There was no need to subclass ES_QUESTION_PROMPT (well actually ES_DISCARDABLE_QUESTION_PROMPT but we have not gotten to discardable dialog prompts yet) and redefine dialog_button_label. Instead set_button_text can be used, in a similar manner as set_button_action is.

ask_save_changes
    -- Ask user if they want to save the changes before continuing
  local
    l_prompt: ES_QUESTION_PROMPT
  do
    create l_prompt.make_standard ("Save changes before continuing?")
    l_prompt.set_button_text ({ES_DIALOG_BUTTONS}.yes_button, "Save Changes")
    l_prompt.set_button_action ({ES_DIALOG_BUTTONS}.yes_button, agent save_changes)
    l_prompt.set_button_text ({ES_DIALOG_BUTTONS}.no_button, "Continue Without Save")
    l_prompt.show_on_active_window
  end

File:Dialog prompt example button text.png

Not only has the text been changed on the dialog prompt but the buttons have also been resized and both resized to match each width, as per the general user interface guidelines related to dialog buttons. This is just one of the new features of the new dialog implementation in 6.1.

In addition the resizing the key bindings have also been altered. On regular question prompts with Yes and No buttons pressing the Y key will select the Yes button and pressing N will select the No button. With the buttons relabeled from their defaults new key bindings are introduced. Save Changes can be select by pressing S and Continue Without Save selected by pressing C.

Setting Default Buttons

Every prompt has a default active button, also known as the "Default Button". This is the button that will have the focus when the dialog is shown.

Discardable Dialog Prompts

Showing dialog prompts showing the same messages over and over again can be annoying for some, if not most. Take the security or alert notifications in your browser, most of us just turn them off after we have read them after they have been shown for the first time. EiffelStudio is full of cases where "discardable" dialog prompts are useful as not to hinder or annoy end-users. One such prime example is performing a finalization compilation. Finalization asks the end-user if they want to discard or keep assertions. For the most part (95%-99% of cases) assertions are always discarded. It makes sense to offer a way to suppress the dialog in the future and perform a default, commonly used, pre-defined action (discarding assertions in this case) when performing a finalization in the future.

Like the regular dialog prompts, discardable dialog prompts can also be extended. For an example of extension inside EiffelStudio, see the ES_DISCARDABLE_COMPILE_SAVE_PROMPT class.