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.
|Download • Git
|Forums • Blog • Twitter • G+
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.
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.
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:
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
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
AbstractFormHandler.execPostLoad() and not during
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).
- Ok button
- Cancel Button
- Save Button
- Close Button
- closing icon (“X”)
TODO: When and how to parameterize the form depending on the goal.
Defined with getConfiguredXxxxxx() methods.
Defined with execXxxxxx() methods.