Using Dialog Prompts (Advanced Discardable) - Revision history

Paulb at 18:19, 14 May 2008

2008-05-14T18:19:22Z

Paulb: /* Default Discard Button */

2007-09-06T23:23:36Z

‎Default Discard Button

Paulb: /* Adding Buttons and Button Sets */

2007-09-06T19:56:11Z

‎Adding Buttons and Button Sets

Paulb: /* Adding Graphical Elements */

2007-09-06T19:55:31Z

‎Adding Graphical Elements

Paulb: /* State Preference Persistence */

2007-09-06T19:53:00Z

‎State Preference Persistence

Paulb at 18:53, 6 September 2007

2007-09-06T18:53:38Z

Paulb: /* Extending Discardable Dialog Prompts */

2007-09-06T18:53:22Z

‎Extending Discardable Dialog Prompts

Paulb: /* Avoiding Memory Leaks */

2007-09-06T18:52:19Z

‎Avoiding Memory Leaks

Paulb at 17:55, 6 September 2007

2007-09-06T17:55:17Z

New page

[[Category:Extending EiffelStudio]]
{{UnderConstruction}}
Showing dialog prompts displaying the same messages over and over again can be annoying for most end-user. 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, we even discard them without reading them in some cases. [[:Category:EiffelStudio|EiffelStudio]] another product full of cases where "discardable" dialogs prompts are a necessity, without them we could hinder and annoy end-users.

== Getting Started ==

You should already be familiar with the topics detailed in [[Using Dialog Prompts (Advanced)]] as the information there applies to discardable dialogs prompts also.

Before continuing you may also want to check out the following pages:
* [[Tool Dialog Prompts]]
* [[Tool Dialogs]]
* [[Taxonomy of Dialog Prompts]]
* [[Dialog Prompt Messages and Formatting]]

== The Need For Discardable Dialog Prompts ==

One such example of a need for a discardable dialog 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.

[[Image:Dialog prompts example discard assertions.png|Dialog shown when finalizing an Eiffel project]]

== Introducing Discardable Dialog Prompt Classes ==

There are, as of [[:Category:EiffelStudio|EiffelStudio]] [[EiffelStudio_6.1_Releases|6.1]], three common discardable dialog prompt classes for use which are somewhat self-explanatory.

* [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_warning_prompt.e ES_DISCARDABLE_WARNING_PROMPT]: Used to display a discardable warning
* [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_information_prompt.e ES_DISCARDABLE_INFORMATION_PROMPT]: Used to display a piece of informative text that can be discarded in the future.
* [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_question_prompt.e ES_DISCARDABLE_QUESTION_PROMPT]: Used to ask the user a discardable yes/no question.

All dialog prompt classes are based on an abstract implementation [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_prompt.e ES_DISCARDABLE_PROMPT], which in turn implements parts of [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_prompt.e ES_PROMPT].

{{Note|There is no error variant of a discardable dialog prompt because errors are considered too important to discard. If an error occurs it should always been shown to the user!}}

== Using Discardable Dialog Prompts ==

There are only a couple of few pieces of information required when using a discardable dialog prompt over the non-discardable variant.

=== State Preference Persistence ===

Most importantly is the configuration preference that the discardable states is stored. Upon creation of a discardable dialog prompt you will need to supply the full name of a preference, which is typically in the form ''interface.dialogs.confirm_xxxx'' where ''xxxx'' represents the name of the dialog.

{{Note|For dialog preferences and preference names examine the class [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/preference_tool/parameters/eb_dialogs_data.e EB_DIALOGS_DATA]. For a general overview of adding preferences to [[:Category:EiffelStudio|EiffelStudio]] see [[Adding EiffelStudio Preferences]].}}

Not only does the preference record the state of a user-opted discard but it also permits the user to reactive the dialog prompt via the preferences tool.

=== Default Discard Button ===

Like non-discardable dialog prompts, discardable prompts require setting of a "Discard Button". the discard button is the button who's actions are performed, and dialog result set to when the the dialog prompt is not show becasue it was selected to be discarded on a previous showing. To set the discard button call <eiffel>set_discard_button</eiffel> on the dialog prompt after it has been created, using a button identifier that corresponds to a button that is available on the dialog prompt:

<eiffel>
ask_save_changes
-- Ask user if they want to save the changes before continuing
local
l_prompt: ES_DISCARDABLE_QUESTION_PROMPT
do
create l_prompt.make_standard ("Save changes before continuing?", "", "interface.dialog.confirm_save")
l_prompt.set_discard_button ({ES_DIALOG_BUTTONS}.yes_button)
l_prompt.show_on_active_window
end
</eiffel>

[[Image:Discardable dialog prompts example no message.png|The discard button is set to Yes]]

For all of the predefined, common discardable dialogs as discard button is set by default when creating the dialog prompt using either <eiffel>make_standard</eiffel> or <eiffel>make_standard_with_cancel</eiffel>. Below outlines the dialog prompt type and the default standard discard button for the prompt.

* Warning: '''Ok'''
* Information: '''Ok'''
* Question: '''Yes'''

In addition to being the button who's actions are perform, the discard button also is used to determine if the dialog prompt should save the selected discard state. It is logical to expect that if the user choose to perform an action which is not designated as the the discardable action then the discardable state should never be saved. Imagine the finalization dialog prompt mentioned at the beginning of this page. If the user chose to discard the dialog prompt and selected the '''Keep Assertions''' button, if the discard state was persisted, the next time the user finalizes a project the dialog prompt should not be shown and the assertions would be discarded in the compilation. This is because the '''Discard Assertions''' button is the action performed when the dialog prompt is discarded.

=== Discard Message ===

A discard message is an optional message that can be set on the dialog prompt during creation, through the <eiffel>a_discard_message</eiffel> argument.

By default all discardable dialogs prompt have a check option to discard the dialog in the future. When no discard message is set the check option reads '''Do not show again'''. In the case where a discard message is set (a non-empty string) the message will be placed in parenthesis after the '''Do not show again''' check option text. The discard assertions finalization dialog prompt is an example of this, the discard check option reads '''Do not show again (always discard assertions when finalizing)'''. In this case the discard message is ''always discard assertions when finalizing''.

{{Note|Discard messages should indicate what action will be performed when discarded. The messages should be terse but clear and formatted without an initial capital letter as it's part of a sentence, not a new one.}}

In the section detailing discard buttons the example was created without a discard message but passing <eiffel>""</eiffel> as an argument for parameter <eiffel>a_discard_message</eiffel> of <eiffel>make_standard</eiffel>. The follow example sets a discard message <eiffel>"always save"</eiffel>:

<eiffel>
ask_save_changes
-- Ask user if they want to save the changes before continuing
local
l_prompt: ES_DISCARDABLE_QUESTION_PROMPT
do
create l_prompt.make_standard ("Save changes before continuing?", "always save", "interface.dialog.confirm_save")
l_prompt.set_discard_button ({ES_DIALOG_BUTTONS}.yes_button)
l_prompt.show_on_active_window
end
</eiffel>

[[Image:Discardable dialog prompts example message.png|Setting a discard message to 'always save']]

== Extending Discardable Dialog Prompts ==

Like the regular [[Using Dialog Prompts (Basic)#Extend Dialog Prompts|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. Below shows an extended [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_question_prompt.e ES_DISCARDABLE_QUESTION_PROMPT] class to create a discardable prompt that informs the user about unsaved modifications to one or more classes in the project, prior to a compilation.

[[Image:Dialog prompts example unsaved list.png|Unsaved changes dialog prompt with a subtitle]]

← Older revision		Revision as of 18:19, 14 May 2008
Line 1:		Line 1:
	[[Category:Extending EiffelStudio]]		[[Category:Extending EiffelStudio]]
		+	[[Category:EiffelStudio Foundations]]

	Showing dialog prompts displaying the same messages over and over again can be annoying for most end-user. 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, we even discard them without reading them in some cases. [[:Category:EiffelStudio\|EiffelStudio]] another product full of cases where "discardable" dialogs prompts are a necessity, without them we could hinder and annoy end-users.		Showing dialog prompts displaying the same messages over and over again can be annoying for most end-user. 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, we even discard them without reading them in some cases. [[:Category:EiffelStudio\|EiffelStudio]] another product full of cases where "discardable" dialogs prompts are a necessity, without them we could hinder and annoy end-users.

← Older revision		Revision as of 19:56, 6 September 2007
Line 127:		Line 127:

	=== Adding Buttons and Button Sets ===		=== Adding Buttons and Button Sets ===
−	For information on adding button, buttons identifiers and button set, see [[Using Dialog Prompts (Advanced)#Adding Buttons and Button Sets].	+	For information on adding button, buttons identifiers and button set, see [[Using Dialog Prompts (Advanced)#Adding Buttons and Button Sets]].

@@ Line 124: / Line 124: @@
 === Adding Graphical Elements ===
-Whether you are using [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discarable_prompt.e ES_DISCARDABLE_PROMPT] or a common discardable dialog prompt as your base implementation, you will need to redefine <eiffel>build_prompt_interface</eiffel> to add graphical widgets to the main dialog prompt's area (the area with a white background.) Be sure to call <eiffel>Precursor</eiffel> to ensure the dialog prompt's [[Using Dialog Prompts (Advanced)#Changing the Title, Subtitle and Text| subtitle and text] are displayed correctly.
+Whether you are using [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discarable_prompt.e ES_DISCARDABLE_PROMPT] or a common discardable dialog prompt as your base implementation, you will need to redefine <eiffel>build_prompt_interface</eiffel> to add graphical widgets to the main dialog prompt's area (the area with a white background.) Be sure to call <eiffel>Precursor</eiffel> to ensure the dialog prompt's [[Using Dialog Prompts (Advanced)#Changing the Title, Subtitle and Text| subtitle and text]] are displayed correctly.
 === Adding Buttons and Button Sets ===
 For information on adding button, buttons identifiers and button set, see [[Using Dialog Prompts (Advanced)#Adding Buttons and Button Sets].

@@ Line 113: / Line 113: @@
 == Extending Discardable Dialog Prompts ==
 All discardable dialog prompts are fully extendable, like the regular [[Using Dialog Prompts (Basic)#Extend Dialog Prompts|dialog prompts]]. You may either use one of the existing common discardable dialog prompt as your base implementation or you can use [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discarable_prompt.e ES_DISCARDABLE_PROMPT], although using [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discarable_prompt.e ES_DISCARDABLE_PROMPT] requires a little more (simple) implementation.
 If you are implementing a common discardable dialog prompt you can simply examining the existing common discardable dialog implementation for guides. See [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_question_prompt.e ES_DISCARDABLE_QUESTION_PROMPT] for an example on implement a common discardable dialog prompt.
 === Adding Graphical Elements ===

@@ Line 46: / Line 46: @@
 === Default Discard Button ===
-Like non-discardable dialog prompts, discardable prompts require setting of a "Discard Button". the discard button is the button who's actions are performed, and dialog result set to when the the dialog prompt is not show becasue it was selected to be discarded on a previous showing. To set the discard button call <eiffel>set_discard_button</eiffel> on the dialog prompt after it has been created, using a button identifier that corresponds to a button that is available on the dialog prompt:
+Unlike non-discardable dialog prompts, discardable prompts require setting of a "Discard Button". the discard button is the button who's actions are performed, and dialog result set to when the the dialog prompt is not show becasue it was selected to be discarded on a previous showing. To set the discard button call <eiffel>set_discard_button</eiffel> on the dialog prompt after it has been created, using a button identifier that corresponds to a button that is available on the dialog prompt:
 <eiffel>

@@ Line 38: / Line 38: @@
 === State Preference Persistence ===
-Most importantly is the configuration preference that the discardable states is stored. Upon creation of a discardable dialog prompt you will need to supply the full name of a preference, which is typically in the form ''interface.dialogs.confirm_xxxx'' where ''xxxx'' represents the name of the dialog.
+Most importantly is the configuration preference that the discardable states is stored. Upon creation of a discardable dialog prompt you will need to supply the full name of a preference, which is typically in the form ''interface.dialogs.confirm_show_xxxx'' where ''xxxx'' represents the name of the dialog.
 {{Note|For dialog preferences and preference names examine the class [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/preference_tool/parameters/eb_dialogs_data.e EB_DIALOGS_DATA]. For a general overview of adding preferences to [[:Category:EiffelStudio|EiffelStudio]] see [[Adding EiffelStudio Preferences]].}}

@@ Line 1: / Line 1: @@
 [[Category:Extending EiffelStudio]]
-{{UnderConstruction}}
 Showing dialog prompts displaying the same messages over and over again can be annoying for most end-user. 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, we even discard them without reading them in some cases. [[:Category:EiffelStudio|EiffelStudio]] another product full of cases where "discardable" dialogs prompts are a necessity, without them we could hinder and annoy end-users.

@@ Line 95: / Line 95: @@
 [[Image:Discardable dialog prompts example message.png|Setting a discard message to 'always save']]
 == Extending Discardable Dialog Prompts ==
-Like the regular [[Using Dialog Prompts (Basic)#Extend Dialog Prompts|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. Below shows an extended [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_question_prompt.e ES_DISCARDABLE_QUESTION_PROMPT] class to create a discardable prompt that informs the user about unsaved modifications to one or more classes in the project, prior to a compilation.
+, 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. Below shows an extended [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/Eiffel/interface/new_graphical/dialogs/prompts/es_discardable_question_prompt.e ES_DISCARDABLE_QUESTION_PROMPT] class to create a discardable prompt that informs the user about unsaved modifications to one or more classes in the project, prior to a compilation.
 [[Image:Dialog prompts example unsaved list.png|Unsaved changes dialog prompt with a subtitle]]