As soon as a form (containing controls) is to be presented to the user,
there is a need for an instance controlling the user interaction.
Such a FormController is responsible for dialog processing,
like controlling the tab order and the grouping of controls.
As a form may contain one or many subforms, a FormController may
contain one or more other FormControllers, so the form model structure or hierarchy
is reflected in the structure of FormControllers. That is, retrieving the parent of
the model of a controller will give you the same object as retrieving the model of the parent of
the controller. Similarly, retrieving the model of the nth child of
a controller gives you the same object as retrieving the nth child of
the model of the controller.
A controller is called active if one of the controls it is responsible for has the focus,
else inactive. To be notified whenever this activation state of a given controller changes, you can
add listeners.
This interface supersedes the ::com::sun::star::form::FormController.
Responsibilities
A FormController is responsible for a ::com::sun::star::awt::UnoControlContainer,
and all controls therein.
Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form
contains controls bound to a database, or to an external validator, then the form controller will
check their current value when the current record is to be saved to the database.
First, it will check whether any controls with an external validator exist. If so, those validators
will be asked to validate the current control content. If this fails, the message provided by the validator
is displayed to the user, the control is focused, and the update of the record is vetoed.
Second, the controls are examined for NULL values. If a control is bound to a database field which
is declared to be NOT NULL, no auto-increment field, but still NULL, then an error
message is shown to the user saying that input is required, the respective control is focused, and
the update of the record is vetoed.
Note that you can precent the second check - for database fields containing NULL values - on
a per-form and a per-database basis.
For the former, you need to add a boolean property FormsCheckRequiredFields to the form
(aka the FormController's model), using its
::com::sun::star::beans::XPropertyContainer::addProperty method, with a value
of false.
For the latter, you need to set the respective property of the data source's Settings
(also named FormsCheckRequiredFields) to false.
Alternatively, you can prevent the check on a per-control basis, using the
::DataAwareControlModel::InputRequired property of a single control model.
If a control which the controller is responsible for supports the ::com::sun::star::frame::XDispatchProviderInterception
interface, the controller registers a dispatch interceptor. Then, the control can try to delegate part of its
functionality to the controller by querying the dispatch interceptor for it.
Below, there's a list of URLs which have a defined meaning - if an implementation supports one of them,
there must be a guaranteed semantices. However, concrete implementations may support an arbitrary sub or super
set of these URLs.
In general, all URLs start with the same prefix, namely .uno:FormController/. To this, a suffix is
appended which describes the requested functionality.
Example: The URL suffix for deleting the current record is deleteRecord, so the complete URL for
requesting a dispatcher for this functionality is .uno:FormController/deleteRecord.
Some URLs may require parameters. For this, the sequence of ::com::sun::star::beans::PropertyValues
passed to the ::com::sun::star::frame::XDispatch::dispatch call is used - every property value is
used as one named parameter.
For all URLs, interested parties can register as status listeners (::com::sun::star::frame::XStatusListener)
at the dispatchers, and be notified whenever the functionality associated with the URL becomes enabled or
disabled.
For instance, the URL with the suffix moveToFirst is associated with moving the form to the first
record, and it will be disabled in case the form is already positioned on the first record.
| URL suffix |
functionality |
| positionForm |
positions the form on a record given by absolute number.
There's one parameter for this functionality, named Position, which must be a long
value specifying the absolute position to which the form should be moved |
| RecordCount |
This is a passive functionality: It cannot be dispatched, instead, interested parties may
use the dispatcher to add as ::com::sun::star::frame::XStatusListener, and be
notified when the record count changes.
The status value which is being notified (::com::sun::star::frame::FeatureStateEvent::State)
is a string which can be used to display the record count. In particular, if the record count is not yet known
(::com::sun::star::sdb::RowSet::IsRowCountFinal is false), this is indicated in the
string, too. |
| moveToFirst |
moves the form to the first record |
| moveToPrev |
moves the form to the record preceding the current one |
| moveToNext |
moves the form to the record after the current one |
| moveToLast |
moves the form to the last record |
| moveToNew |
moves the form to the virtual "insert row", where new records can be inserted |
| saveRecord |
Commits any potentially pending changes in the current control, and saves the current record to
the database, or inserts a new record if the form is currently positioned on the virtual insertion row. |
| undoRecord |
reverts the changes done to the current record. Basically, this means refreshing the
current row from the database, and updating all controls with the new content. |
| deleteRecord |
deletes the current record, after asking the user for confirmation. |
| refreshForm |
reloads the complete form. After this, the form is positioned on the first record |
| sortUp |
Adds an order clause to the form, to sort it ascending by the field which the current control is bound to,
and then reloads the form. |
| sortDown |
Adds an order clause to the form, to sort it descending by the field which the current control is bound to,
and then reloads the form. |
| sort |
opens an dialog, which allows the user to manipulate the current sorting order of the form. If the dialog
is closed with OK, the form is reloaded after setting the new sorting order. |
| autoFilter |
creates, from the current control, a filter for the form. This is, if the current control is bound to
the field, say, "customer", and contains the value "Furs, Inc.", then a filter "customer = 'Furs, Inc.'"
is created and set at the form. After this, the form is reloaded. |
| filter |
opens an dialog, which allows the user to manipulate the current filter of the form. If the dialog
is closed with OK, the form is reloaded after setting the new filter. |
| applyFilter |
Toggles the ::com::sun::star::sdb::RowSet::ApplyFilter property
of the form.
Additionally, status listeners will be provided with the current (boolean) state of this property
in the ::com::sun::star::frame::FeatureStateEvent::State member of the event
notified by the dispatcher. |
| removeFilterOrder |
completely removes any filter and sorting order from the form, and reloads it. |
