Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Scout/Concepts/Form"

(Description: add link to example)
m (permute screenshot and lifecycle)
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{ScoutPage|cat=Concepts}}
+
{{ScoutPage|cat=Client}}
  
 
A form is both a model structure of a ui concept known as dialog or view and also a model of a {{ScoutLink|Concepts|Wizard|wizard}} page. Wizard {{ScoutLink|Concepts|Button|buttons}} are added automatically to the main box if missing.
 
A form is both a model structure of a ui concept known as dialog or view and also a model of a {{ScoutLink|Concepts|Wizard|wizard}} page. Wizard {{ScoutLink|Concepts|Button|buttons}} are added automatically to the main box if missing.
  
* implements: {{ScoutJavadoc|<TODO:NameOfTheInterface>|I}}
+
* implements: {{ScoutJavadoc|IForm|I}}
* extends: {{ScoutJavadoc|<TODO:NameOfTheAbstractClass>|C}}
+
* extends: {{ScoutJavadoc|AbstractForm|C}}
  
 
== Description ==
 
== Description ==
{{note|TODO|Add a description}}
+
Each form contains:
TODO:
+
* 0..n {{ScoutLink|Concepts|Variable|Variables}}.
* Main Box Field
+
* 0..n {{ScoutLink|Concepts|KeyStroke|Key Strokes}} (inner classes implementing <tt>IKeyStroke</tt>).
* {{ScoutLink|Concepts|Form Handler|Handlers}}: start the form with different behaviors (e.g. startNew and startModify)
+
* exactly 1 MainBox field (inner class implementing <tt>IGroupBox</tt>): this is the root {{ScoutLink|Concepts|GroupBox|GroupBox field}} containing the other {{ScoutLink|Concepts|Field|fields}}
* {{ScoutLink|Concepts|Form/Example|Example of a form}} code of a simple form
+
* 0..n {{ScoutLink|Concepts|ToolButton|Tool Buttons}} (inner classes implementing <tt>IToolButton</tt>),
 +
* 1..n {{ScoutLink|Concepts|Form Handler|Form Handlers}} (usually defined as inner classes implementing <tt>IFormHandler</tt>, but since the handler is set as parameter of <tt>AbstractForm.startInternal(IFormHandler)</tt> the handler can be defined everywhere). The form handler starts the form with different behaviors (e.g. <code>startNew()</code> and <code>startModify()</code>)
 +
 
 +
A Form can be opened as a Dialog or as a View (see {{ScoutLink|HowTo|Open_a_Form_in_a_View|How to open a form in a view}}).
 +
 
 +
{{ScoutLink|Concepts|Form/Example|Java code of a simple form}} as example.
 +
 
 +
See also {{ScoutLink|Concepts|Search_Form|SearchForm}}.
 +
 
  
 
== Screenshot ==
 
== Screenshot ==
{{note|TODO|Add a screenshot (or remove this section, if there is no screenshot to make)}}
+
<gallery>
 +
Image:Scout Form.png|Form as Dialog
 +
Image:Scout Form View.png|Form as View
 +
</gallery>
 +
 
 +
 
 +
== Form lifecycle ==
 +
 
 +
Typically a form will be loaded with data coming from the server (using a FormData as data transfert object) and be displayed to the user. The user can interact with the form and if he makes some modifications that needs to be persisted in the server.
 +
 
 +
In a lot of applications, the flow of data is not the same if the form is used to create a new entity or to modify an existing entity. This is why each form works with Form Handler that precise. By default the SDK creates a ModifyHandle and a NewHandler, but everything is possible depending on your use case. For example a ViewHandler might be useful for the case where the user cannot do any modification, or a WizardHandler might be useful for the special case where the form is embedded as step of a wizard. In a typical scenario the Form Handler will at least load the data during its {{ScoutEvent|Load}} event and store them during its {{ScoutEvent|Store}} event.
 +
 
 +
The state of the form can be checked with different methods:
 +
* isFormOpen()
 +
* isFormLoading()
 +
* isFormStored()
 +
* isFormClosed()
 +
 
 +
=== Unsaved changes ===
 +
Scout handles the notion of unsaved changes in a form. Depending on the rendering UI technology the user gets a visual confirmation that he needs to save the form. For example on SWT a form displayed in a view will have a star character <code>*</code> in its title to indicate that the form needs to be saved. Some developers speak from a “dirty marker” for this char. On Mac OSX, the red closing button is also lightly different when the form needs to be saved.
 +
 
 +
The behavior of the framework will not be the same when the user leaves a form if the form contains unsaved changes or not.
 +
 
 +
Each field can contribute information to determine if the form contains unsaved changes or not. By default the value fields compare the current value with the initial values. But custom logic can be implemented.
 +
 
 +
To check if the form contains unsaved changes the method: <code>IForm.isSaveNeeded()</code> can be called. The state returned by this function might be out of date (for example if the state changes due to some business logic like “wait 5 minutes” and not due to some user input). To be sure to get the correct state, you should call <code>IForm. checkSaveNeeded()</code> before calling <code>IForm.isSaveNeeded()</code>.
 +
 
 +
In addition of asking each fields it is also possible to mark that the form contains unsaved changes with the method <code>IForm.touch()</code>. Do not call this method during the formLoading phase (in other words: call <code>touch()</code> in <code>AbstractFormHandler.execPostLoad()</code> and not during <code>AbstractFormHandler.execLoad()</code>).
 +
<code>IForm.markSaved()</code> is the counter part of <code>IForm.touch()</code>. It will indicate that the form contains no unsaved changes. Concretely the state will be changed in each field (the markedChanged() call is propagated in each field of the form).
 +
 
 +
=== Actions and buttons ===
 +
TODO:
 +
* Ok button
 +
* Cancel Button
 +
* Save Button
 +
*Close Button
 +
*closing icon (“X”)
 +
* execOnCloseRequest
 +
https://www.eclipse.org/forums/index.php/mv/msg/796762/1416232/#msg_1416232
  
 +
=== Confirmation Dialog ===
 +
TODO:
 +
When and how to parameterize the form depending on the goal.
  
 
== Properties ==
 
== Properties ==
Line 33: Line 82:
 
* {{ScoutLink|Concepts|FormData|FormData}}
 
* {{ScoutLink|Concepts|FormData|FormData}}
 
* {{ScoutLink|Concepts|Wizard|Wizard}}
 
* {{ScoutLink|Concepts|Wizard|Wizard}}
 +
* {{ScoutLink|HowTo|Open_a_Form_in_a_View|How to open a form in a view}}
 
* {{ScoutLink|Concepts|Client Plug-In|Client Plug-In}}
 
* {{ScoutLink|Concepts|Client Plug-In|Client Plug-In}}

Revision as of 13:25, 25 September 2014

The Scout documentation has been moved to https://eclipsescout.github.io/.

A form is both a model structure of a ui concept known as dialog or view and also a model of a The Scout documentation has been moved to https://eclipsescout.github.io/. page. Wizard The Scout documentation has been moved to https://eclipsescout.github.io/. are added automatically to the main box if missing.

Description

Each form contains:

  • 0..n The Scout documentation has been moved to https://eclipsescout.github.io/..
  • 0..n The Scout documentation has been moved to https://eclipsescout.github.io/. (inner classes implementing IKeyStroke).
  • exactly 1 MainBox field (inner class implementing IGroupBox): this is the root The Scout documentation has been moved to https://eclipsescout.github.io/. containing the other The Scout documentation has been moved to https://eclipsescout.github.io/.
  • 0..n The Scout documentation has been moved to https://eclipsescout.github.io/. (inner classes implementing IToolButton),
  • 1..n The Scout documentation has been moved to https://eclipsescout.github.io/. (usually defined as inner classes implementing IFormHandler, but since the handler is set as parameter of AbstractForm.startInternal(IFormHandler) the handler can be defined everywhere). The form handler starts the form with different behaviors (e.g. startNew() and startModify())

A Form can be opened as a Dialog or as a View (see The Scout documentation has been moved to https://eclipsescout.github.io/.).

The Scout documentation has been moved to https://eclipsescout.github.io/. as example.

See also The Scout documentation has been moved to https://eclipsescout.github.io/..


Screenshot


Form lifecycle

Typically a form will be loaded with data coming from the server (using a FormData as data transfert object) and be displayed to the user. The user can interact with the form and if he makes some modifications that needs to be persisted in the server.

In a lot of applications, the flow of data is not the same if the form is used to create a new entity or to modify an existing entity. This is why each form works with Form Handler that precise. By default the SDK creates a ModifyHandle and a NewHandler, but everything is possible depending on your use case. For example a ViewHandler might be useful for the case where the user cannot do any modification, or a WizardHandler might be useful for the special case where the form is embedded as step of a wizard. In a typical scenario the Form Handler will at least load the data during its The Scout documentation has been moved to https://eclipsescout.github.io/. event and store them during its The Scout documentation has been moved to https://eclipsescout.github.io/. event.

The state of the form can be checked with different methods:

  • isFormOpen()
  • isFormLoading()
  • isFormStored()
  • isFormClosed()

Unsaved changes

Scout handles the notion of unsaved changes in a form. Depending on the rendering UI technology the user gets a visual confirmation that he needs to save the form. For example on SWT a form displayed in a view will have a star character * in its title to indicate that the form needs to be saved. Some developers speak from a “dirty marker” for this char. On Mac OSX, the red closing button is also lightly different when the form needs to be saved.

The behavior of the framework will not be the same when the user leaves a form if the form contains unsaved changes or not.

Each field can contribute information to determine if the form contains unsaved changes or not. By default the value fields compare the current value with the initial values. But custom logic can be implemented.

To check if the form contains unsaved changes the method: IForm.isSaveNeeded() can be called. The state returned by this function might be out of date (for example if the state changes due to some business logic like “wait 5 minutes” and not due to some user input). To be sure to get the correct state, you should call IForm. checkSaveNeeded() before calling IForm.isSaveNeeded().

In addition of asking each fields it is also possible to mark that the form contains unsaved changes with the method IForm.touch(). Do not call this method during the formLoading phase (in other words: call touch() in AbstractFormHandler.execPostLoad() and not during AbstractFormHandler.execLoad()). IForm.markSaved() is the counter part of IForm.touch(). It will indicate that the form contains no unsaved changes. Concretely the state will be changed in each field (the markedChanged() call is propagated in each field of the form).

Actions and buttons

TODO:

  • Ok button
  • Cancel Button
  • Save Button
  • Close Button
  • closing icon (“X”)
  • execOnCloseRequest

https://www.eclipse.org/forums/index.php/mv/msg/796762/1416232/#msg_1416232

Confirmation Dialog

TODO: When and how to parameterize the form depending on the goal.

Properties

Defined with The Scout documentation has been moved to https://eclipsescout.github.io/. methods.

Note.png
TODO
Add a description of important properties. The idea is not to recreate the JavaDoc of the getConfiguredXxxxxx() methods but to provide explanations, best practice, example... Group the properties by domain.


Events

Defined with The Scout documentation has been moved to https://eclipsescout.github.io/. methods.

Note.png
TODO
Add a description of important events. The idea is not to recreate the JavaDoc of the execXxxxxx() methods but to provide explanations, best practice, example... Group the events by domain.


See Also

Back to the top