Scout/Concepts/Form
| Scout |
| Wiki Home |
| Website |
| Download • Git |
| Community |
| Forums • Blog • Twitter • G+ |
| Bugzilla |
| Bugzilla |
A form is both a model structure of a ui concept known as dialog or view and also a model of a wizard page. Wizard buttons are added automatically to the main box if missing.
- implements:
IForm - extends:
AbstractForm
Contents
Description
Each form contains:
- 0..n Variables.
- 0..n Key Strokes (inner classes implementing IKeyStroke).
- exactly 1 MainBox field (inner class implementing IGroupBox): this is the root GroupBox field containing the other fields
- 0..n Tool Buttons (inner classes implementing IToolButton),
- 1..n Form Handlers (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()andstartModify())
A Form can be opened as a Dialog or as a View (see How to open a form in a view).
Java code of a simple form as example.
See also SearchForm.
Screenshot
Form as Dialog
Form as View
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 Load event and store them during its 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 * 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 getConfiguredXxxxxx() methods.
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 execXxxxxx() methods.
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.