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

m
 
m (Getting Started)
Line 4: Line 4:
  
 
== Getting Started ==
 
== Getting Started ==
 +
If you have ended up here then you are either curious or have decided that you want to use some of the extended features of the [[EiffelStudio]] [[Tool Dialog Prompts]]. The page is given the title "Advanced" and there are more advanced topics here but using the deep level of customization features is for everyone as it's simple enough to use.
  
You may also want to check out the following pages:
+
Before continuing you may also want to check out the following pages:
 
* [[Tool Dialog Prompts]]
 
* [[Tool Dialog Prompts]]
 +
* [[Tool Dialogs]]
 
* [[Taxonomy of Dialog Prompts]]
 
* [[Taxonomy of Dialog Prompts]]
 
* [[Dialog Prompt Messages and Formatting]]
 
* [[Dialog Prompt Messages and Formatting]]
 +
 +
== Introducing the Dialog Prompt Classes ==
 +
 +
There are, as of [[EiffelStudio]] 6.1, four common dialog prompt classes for use which are somewhat self-explanatory.
 +
 +
* <eiffel>ES_ERROR_PROMPT</eiffel>: Used to display a error.
 +
* <eiffel>ES_WARNING_PROMPT</eiffel>: Used to display a warning
 +
* <eiffel>ES_INFORMATION_PROMPT</eiffel>: Used to display a piece of informative text.
 +
* <eiffel>ES_QUESTION_PROMPT</eiffel>: Used to ask the user a yes/no question.
 +
 +
{{Note| There is a running convention in [[EiffelStudio]] (for classes prefixed with <eiffel>ES_</eiffel>) whereby all dialog prompts end in <eiffel>_PROMPT</eiffel>. From this you can determine if there are any specialized dialog prompts available for you to use, as the base implementation in ES_PROMPT is customizable. You can also use the code browsing tools to check for all descendents of ES_PROMPT.}}
 +
 +
Each dialog prompt class provide two or more creation routines; <eiffel>make</eiffel> and <eiffel>make_standard</eiffel>. Some prompt classes also have an addition creation routine, <eiffel>make_standard_with_cancel</eiffel>, to augment the standard button set with a '''Cancel''' button. The creation routine <eiffel>make</eiffel> offers the most control but requires more information to create the dialog and some understanding of the concpt of a [[Dialog Buttons Sets]]. The <eiffel>make_standard</eiffel> creation routines are simpler and only require a dialog prompt message, just like the basic dialog prompt usage detailed in [[Using Dialog Prompts (Basic)]].
 +
 +
== Dialog Prompt Buttons ===
 +
The <eiffel>make_standard</eiffel> 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, <eiffel>make_standard_with_cancel</eiffel>, 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 <eiffel>ES_DIALOG_BUTTONS</eiffel> 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 <eiffel>ES_SHARED_DIALOG_BUTTONS</eiffel> through the base dialog implementation <eiffel>ES_DIALOG</eiffel> (see [[Tool Dialogs]] for more information on <eiffel>ES_DIALOG</eiffel> and dialog button sets.)}}
 +
 +
For information of button set and creating your own button set see [[Dialog Buttons Sets]].
 +
 +
=== 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. In the following dialog prompt the '''No''' button is the default button.
 +
 +
<eiffel>
 +
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 ("If you press yes I'll tell you something...")
 +
    l_prompt.show_on_active_window
 +
  end
 +
</eiffel>
 +
 +
[[Image:Dialog_prompts_example_question.png|No is the default set default button]]
 +
 +
'''No''' was set as the default-default button automatically. Unless set, every dialog prompt uses the least dangerous button as the default button. In the above example ''No'' is actually set as the automatic default button because '''No''' is considered (statically) the least dangerous button for question prompts. If the question prompt was created with <eiffel>make_standard_with_cancel</eiffel> the '''Cancel''' button would actually be the default button because cancel is considered less dangerous than '''No'''.
 +
 +
To override the default behavior you'll need to specify the default button. This has to be a button identifier for a button that exists on the dialog prompt. The following code demonstrates this.
 +
 +
<eiffel>
 +
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 ("If you press yes I'll tell you something...")
 +
    l_prompt.set_default_button ({ES_DIALOG_BUTTONS}.yes_button)
 +
    l_prompt.show_on_active_window
 +
  end
 +
</eiffel>
 +
 +
[[Image:Dialog_prompts_example_question2.png|Yes is now the default button]]

Revision as of 14:57, 5 September 2007

Construction.png Not Ready for Review: This Page is Under Development!

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 latter approach. To use the former please see Using Dialog Prompts (Basic).

Getting Started

If you have ended up here then you are either curious or have decided that you want to use some of the extended features of the EiffelStudio Tool Dialog Prompts. The page is given the title "Advanced" and there are more advanced topics here but using the deep level of customization features is for everyone as it's simple enough to use.

Before continuing you may also want to check out the following pages:

Introducing the Dialog Prompt Classes

There are, as of EiffelStudio 6.1, four common dialog prompt classes for use which are somewhat 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.

Information.png Note: There is a running convention in EiffelStudio (for classes prefixed with ES_) whereby all dialog prompts end in _PROMPT. From this you can determine if there are any specialized dialog prompts available for you to use, as the base implementation in ES_PROMPT is customizable. You can also use the code browsing tools to check for all descendents of ES_PROMPT.

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 and some understanding of the concpt of a Dialog Buttons Sets. The make_standard creation routines are simpler and only require a dialog prompt message, just like the basic dialog prompt usage detailed in Using Dialog Prompts (Basic).

Dialog Prompt Buttons =

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.

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

For information of button set and creating your own button set see Dialog Buttons Sets.

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. In the following dialog prompt the No button is the default button.

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 ("If you press yes I'll tell you something...")
    l_prompt.show_on_active_window
  end

No is the default set default button

No was set as the default-default button automatically. Unless set, every dialog prompt uses the least dangerous button as the default button. In the above example No is actually set as the automatic default button because No is considered (statically) the least dangerous button for question prompts. If the question prompt was created with make_standard_with_cancel the Cancel button would actually be the default button because cancel is considered less dangerous than No.

To override the default behavior you'll need to specify the default button. This has to be a button identifier for a button that exists on the dialog prompt. The following code demonstrates this.

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 ("If you press yes I'll tell you something...")
    l_prompt.set_default_button ({ES_DIALOG_BUTTONS}.yes_button)
    l_prompt.show_on_active_window
  end

Yes is now the default button