allows to exclicitly free resources and break cyclic references.
Usage Restrictions
not published
Description
encapsulates operations on a database form.
This instance allows for operations on a user interface form, by saving its clients
from various tedious and error-prone operations.
As an example, imagine you have a database form, displayed in some user
interface, which you want to move to the next record.
It is as easy as calling com:::sun::star::sdbc::XResultSet::next
on this form, right? Wrong. First, you need to care for saving the current
record, so the user doesn't lose her input. So you need to call
::com::sun::star::sdbc::XResultSetUpdate::updateRow or
::com::sun::star::sdbc::XResultSetUpdate::insertRow, depending
on the form's ::com::sun::star::sdb::RowSet::IsNew property.
But then you're done, right? Wrong, again.
When the user just entered some data into one of the form fields, but did not yet
leave this field, then the data is not yet committed to the form, not to talk
about being committed to the underlying database. So, before everything else,
you would nee to obtain the active control of the form, and commit it. Now you're done ...
As another example, consider that you want to delete the current record from the
form. You have to take into account any ::com::sun::star::form::XConfirmDeleteListeners
registered at the ::com::sun::star::form::FormController or the
::com::sun::star::form::component::DataForm.
If you agree that this is ugly to do and maintain, then XFormOperations
is for you. It provides a execute method, which will do all of the above
for you; plus some similar convenient wrappers for similar functionality.
You would usually use this to update some user interface to reflect this state.
For instance, you could imagine a toolbar button which is associated with a given feature.
This button would be enabled if and only if the respective feature is currently
available, and be checked if and only if the feature state is a boolean
evaluating to true.
Parameter Feature
the feature whose state is to be determimed. Must be one of the FormFeature
constants.
An invalid value here will be silently ignored, and simply return a FeatureState
indicating disabled with a NULL state.
the feature whose state is to be determimed. Must be one of the FormFeature
constants.
An invalid value here will be silently ignored, and simply return false.
executes the operation associated with the given feature
Parameter Feature
the feature which is to be executed. Must be one of the FormFeature
constants.
Throws
::com::sun::star::lang::IllegalArgumentException
if the given Feature is unknown, not executable, or striclty requires arguments
to be executed.
Throws
::com::sun::star::sdbc::SQLException
if a database access erorr occurs
Throws
::com::sun::star::lang::WrappedTargetException
if an exception is caught which is no ::com::sun::star::uno::RuntimeException
and no ::com::sun::star::sdbc::SQLException.
executes the operation associated with the given feature, with passing arguments for execution
Parameter Feature
the feature which is to be executed. Must be one of the FormFeature
constants.
Parameter Arguments
the named arguments for the feature to execute. See the FormFeature list
for features which require arguments.
Throws
::com::sun::star::lang::IllegalArgumentException
if the given feature is unknown, or not executable
Throws
::com::sun::star::lang::IllegalArgumentException
if the given arguments are not sufficient to execute the feature
Throws
::com::sun::star::sdbc::SQLException
if a database access erorr occurs
Throws
::com::sun::star::lang::WrappedTargetException
if an exception is caught which is no ::com::sun::star::uno::RuntimeException
and no ::com::sun::star::sdbc::SQLException.
provides access to the form controller which the instance is operating on.
Note that it is possible to operate on a user interface form without
actually having access to the form controller instance. However, in this
case some functionality will not be available. In particular, every feature
which relies on the active control of the controller might be of limited use.
denotes the instance which should be notified about features whose state might have changed.
If this attribute is not NULL, the instance which it denotes will be notified
whenever the state of any supported feature might have changed.
For instance, imagine a form whose current row has just been moved to another
record, using the execute method. This means that potentially, the state
of all movement-related features might have changed.
Note that the instance does not actually notify changes in the feature states, but only
potential changes: It's up to the callee to react on this appropriately. This is
since OpenOffice.org's application framework features own mechanisms to cache and invalidate
feature states, so we do not burden this implementation here with such mechanisms.
