|
|
| (15 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| | [[Category:EiffelStudio]] | | [[Category:EiffelStudio]] |
| − | [[Category:Extending_EiffelStudio]] | + | [[Category:Extending EiffelStudio]] |
| − | {{UnderConstruction}}
| + | [[Category:EiffelStudio Foundations]] |
| | | | |
| | 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. | | 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 == | | == 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. | + | As of [[:Category:EiffelStudio|EiffelStudio]] [[EiffelStudio_6.1_Releases|6.1]], [[:Category:EiffelStudio|EiffelStudio]] uses custom dialog prompts that come in a flavor of presentation that stands above the stock dialog prompts found in [[:Category:EiffelVision2|EiffelVision2]]. As such all dialog prompts in EiffelStudio should be using the new prompt classes instead of those found in [[:Category:EiffelVision2|EiffelVision2]] or the slightly specialized versions found in previous versions of [[:Category:EiffelStudio|EiffelStudio]]. |
| | | | |
| | Just to get an idea of what the new prompts look like, here’s an example: | | Just to get an idea of what the new prompts look like, here’s an example: |
| | | | |
| | [[Image:Dialog_prompts_example_question.png|New prompts in EiffelStudio]] | | [[Image:Dialog_prompts_example_question.png|New prompts in EiffelStudio]] |
| | + | |
| | + | For more examples of the new dialog prompts in [[:Category:EiffelStudio|EiffelStudio]] [[EiffelStudio_6.1_Releases|6.1]] see [[Taxonomy of Dialog Prompts]]. |
| | | | |
| | == New Features == | | == New Features == |
| Line 20: |
Line 22: |
| | * Dual-model; providing agent actions to perform on button presses and/or retrieval of the dialog result code. | | * 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. | | * Simplified interfaces with less code to write. |
| − | * Extendable (see <eiffel>ES_DISCARDABLE_COMPILE_SAVE_FILES_PROMPT</eiffel>.) | + | * Extendable (see [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_compile_save_files_prompt.e ES_DISCARDABLE_COMPILE_SAVE_PROMPT].) |
| | * Provides both standard and advanced creation routines for quick or complex creation. | | * 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. | | * 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. | | * 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 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'', ...) | + | * Automatic key navigation binding; Use of {{key|TAB}}, {{key|LEFT}} or {{key|RIGHT}} cursor keys and button first(or next)-character key ('''Yes''' => {{key|Y}}, '''Create''' => {{key|C}}, ...) |
| | * Ability to set a default active button. | | * Ability to set a default active button. |
| | | | |
| Line 32: |
Line 34: |
| | | | |
| | == Displaying Dialog Prompts, the Easy Way == | | == Displaying Dialog Prompts, the Easy Way == |
| − | Instead of creating dialog prompts and displaying them using the <eiffel>ES_XXX_PROMPT</eiffel> classes directly you can use a help class <eiffel>ES_PROMPT_PROVIDER</eiffel> (or inherit the shared class <eiffel>ES_SHARED_PROMPT_PROVIDER</eiffel> and access <eiffel>prompts</eiffel>.) Of course, the easy way does limit functionality but for the vast majority of cases the routines of <eiffel>ES_PROMPT_PROVIDER</eiffel> provide all that is needed.
| + | For the simplest way to show dialog prompts inside [[:Category:EiffelStudio|EiffelStudio]] or to use dialog prompts in the Eiffel [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/ framework library] see [[Using Dialog Prompts (Basic)]]. |
| − | | + | |
| − | Note: For tool and dialog development <eiffel>ES_DOCKABLE_TOOL_WINDOW</eiffel> and <eiffel>ES_DIALOG</eiffel> both inherit <eiffel>ES_SHARED_PROMPT_PROVIDER</eiffel> and provide access to a shared instance of <eiffel>ES_PROMPT_PROVIDER</eiffel> through a feature <eiffel>prompts</eiffel>.
| + | |
| − | | + | |
| − | <eiffel>ES_PROMPT_PROVIDER</eiffel> 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, <eiffel>show_error_prompt</eiffel> will show an error prompt, <eiffel>show_warning_prompt</eiffel> shows an warning prompt, <eiffel>show_info_prompt</eiffel> shows an information prompt and finally, show_question_prompt show a prompt designated for asking the user a question.
| + | |
| − | | + | |
| − | There are the <eiffel>show_xxx_with_cancel</eiffel> variants, which includes a cancel button along with the standard set of buttons.
| + | |
| − | | + | |
| − | === Prompt Arguments ===
| + | |
| − | Using <eiffel>ES_PROMPT_PROVIDER</eiffel> 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 <eiffel>show_xxx_prompt</eiffel> routine requires a message string through the parameter <eiffel>a_message</eiffel>, which relates to the message the user is shown.
| + | |
| − | | + | |
| − | The argument specifying the parent window, through the parameter <eiffel>a_window</eiffel>, to display the prompt to is optional. If <eiffel>Void</eiffel> 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 <eiffel>Void</eiffel> to specify no action. There is a parameter for each of the standard buttons.
| + | |
| − | | + | |
| − | === An Example, the Easy Way ===
| + | |
| − | | + | |
| − | To simply demonstrate the use of <eiffel>ES_PROMPT_PROVIDER</eiffel> by inheriting the shared class <eiffel>ES_SHARED_PROMPT_PROVIDER</eiffel>, the code below is all that is needed to show an Error prompt on the IDE window, with the message <eiffel>"This is an Error prompt"</eiffel>.
| + | |
| − | | + | |
| − | <eiffel>
| + | |
| − | prompts.show_error_prompt ("This is an Error prompt", Void, Void) | + | |
| − | </eiffel>
| + | |
| − | | + | |
| − | The result of executing the above code results in a dialog prompt like the one below:
| + | |
| − | | + | |
| − | [[Image:Dialog_prompts_example_error.png]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | <eiffel>
| + | |
| − | 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
| + | |
| − | )
| + | |
| − | </eiffel>
| + | |
| − | | + | |
| − | The result of executing the above code results in a dialog prompt like the one below:
| + | |
| − | | + | |
| − | [[Image:Dialog_prompts_example_question.png]]
| + | |
| − | | + | |
| − | Pressing the '''Yes''' button on the question dialog prompt produces the dialog prompt:
| + | |
| − | | + | |
| − | [[Image:Dialog_prompts_example_question_info.png]]
| + | |
| − | | + | |
| − | Pressing the '''No''' button on the question dialog prompt produces the dialog prompt:
| + | |
| − | | + | |
| − | [[Image:Dialog_prompts_example_question_error.png]]
| + | |
| − | | + | |
| − | === Using Dialog Prompts In the Eiffel Framework ===
| + | |
| − | | + | |
| − | <eiffel>ES_PROMPT_PROVIDER</eiffel> and <eiffel>ES_SHARED_PROMPT_PROVIDER</eiffel> are accessible from the Eiffel framework library, however the underlying implementation in the framework library actually uses the older <eiffel>EB_XXX_DIALOG</eiffel>s instead of the new <eiffel>ES_XXX_PROMPT</eiffel> classes.
| + | |
| − | | + | |
| − | The new <eiffel>ES_XXX_PROMPT</eiffel> rely on classes found in the EiffelStudio IDE so for the sake of compatibility the old <eiffel>EB_XXX_DIALOG</eiffel> 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 <eiffel>EB_XXX_DIALOG</eiffel> dialog prompt classes directly, please use the routines of <eiffel>ES_PROMPT_PROVIDER</eiffel>.
| + | |
| − | | + | |
| − | 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 <eiffel>ES_PROMPT_PROVIDER</eiffel> and not any of the <eiffel>EB_XXX_DIALOG</eiffel> classes! If you use the <eiffel>EB_XXX_PROMPT</eiffel> classes directly you will see no change with integrating you code. All the <eiffel>EB_XXX_PROMPT</eiffel> classes have been marked obsolete so the only obsolete warnings you should see if those from <eiffel>ES_PROMPT_PROVIDER</eiffel>.
| + | |
| | | | |
| | == Displaying Dialog Prompts, the Other Way == | | == Displaying Dialog Prompts, the Other Way == |
| − | If more control is what you are after then using the <eiffel>ES_PROMPT_PROVIDER</eiffel> may not be of any use. As such you can instantiate, use and display the EiffelStudio prompt classes directly.
| + | For more control over the way dialog prompts are display and how users interact with them, see [[Using Dialog Prompts (Advanced)]]. |
| − | | + | |
| − | There are, as of EiffelStudio 6.1, four common dialog prompt classes for use which are 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.
| + | |
| − | | + | |
| − | 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. The <eiffel>make_standard</eiffel> creation routines are simpler and only require a dialog prompt message.
| + | |
| − | | + | |
| − | 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.)}}
| + | |
| − | | + | |
| − | === Two Consequence Models ===
| + | |
| − | As stated above in the New Features section the <eiffel>ES_XXX_PROMPT</eiffel> 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 [http://docs.eiffel.com/eiffelstudio/general/guided_tour/language/tutorial-12.html agents], assigning them to a button using a button identifier.
| + | |
| − | | + | |
| − | After creating a prompt you may associate an agent to a button using <eiffel>ES_PROMPT.set_button_action</eiffel>. The routine takes a button identifier, which must be an identifier of a button on the prompt, as well as an agent action.
| + | |
| − | | + | |
| − | <eiffel>
| + | |
| − | ask_save_changed
| + | |
| − | -- 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
| + | |
| − | </eiffel>
| + | |
| − | | + | |
| − | 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 <eiffel>set_button_action</eiffel>. <eiffel>set_button_action</eiffel> is passed the button identifier <eiffel>yes_button</eiffel>, which is statically accessed from <eiffel>ES_DIALOG_BUTTONS</eiffel>. <eiffel>yes_button</eiffel> could have just as easily been accessed from the <eiffel>dialog_buttons</eiffel> function exported on the prompt class:
| + | |
| − | | + | |
| − | <eiffel>
| + | |
| − | l_prompt.set_button_action (l_prompt.dialog_buttons.yes_button, agent save_changes)
| + | |
| − | </eiffel>
| + | |
| − | | + | |
| − | 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 <eiffel>dialog_result</eiffel>. Like button identifiers, <eiffel>dialog_result</eiffel> is an <eiffel>INTEGER</eiffel>
| + | |
| − | | + | |
| − | == 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 [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_compile_save_files_prompt.e ES_DISCARDABLE_COMPILE_SAVE_PROMPT] class.
| + | == Displaying Discardable Dialog Prompts == |
| | + | The final set of dialog prompts are discardable dialog prompt. Discardable dialog prompts allows the user to opt out of seeing the dialog prompt subsequent showings. For information on using discardable dialog prompts, see [[Using Dialog Prompts (Advanced Discardable)]]. |
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:
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.
For more control over the way dialog prompts are display and how users interact with them, see Using Dialog Prompts (Advanced).
The final set of dialog prompts are discardable dialog prompt. Discardable dialog prompts allows the user to opt out of seeing the dialog prompt subsequent showings. For information on using discardable dialog prompts, see Using Dialog Prompts (Advanced Discardable).
