:: com :: sun :: star :: form :: runtime ::

interface XFormOperations
Base Interfaces
XFormOperations
┗ ::com::sun::star::lang::XComponent

::com::sun::star::lang::XComponent
(referenced interface's summary:)

Methods' Summary
getState retrieves the current state of the given feature  
isEnabled determines whether a feature is currently enabled.  
execute executes the operation associated with the given feature  
executeWithArguments executes the operation associated with the given feature, with passing arguments for execution  
commitCurrentRecord commits the current record of the form  
commitCurrentControl commits the current control of our controller  
isInsertionRow determines whether the form is currently positioned on the insertion row  
isModifiedRow determines whether the current row of the form is modified  
Attributes' Summary
Cursor provides access to the cursor of the form the instance is operating on.  
UpdateCursor provides access to the update cursor of the form the instance is operating on.  
Controller provides access to the form controller which the instance is operating on.  
FeatureInvalidation denotes the instance which should be notified about features whose state might have changed.  
Methods' Details
getState
FeatureState
getState( [in] short  Feature );

Description
retrieves the current state of the given feature

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 determined. 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.

isEnabled
boolean
isEnabled( [in] short  Feature );

Description
determines whether a feature is currently enabled.

Calling this is equivalent to calling getState, and evaluating the FeatureState::Enabled member.

Parameter Feature
the feature whose state is to be determined. Must be one of the FormFeature constants.
An invalid value here will be silently ignored, and simply return false.
execute
void
execute( [in] short  Feature )
raises( ::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::sdbc::SQLException,
::com::sun::star::lang::WrappedTargetException );

Description
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 strictly requires arguments to be executed.
Throws
::com::sun::star::sdbc::SQLException if a database access error 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.
See also
executeWithArguments
executeWithArguments
void
executeWithArguments( [in] short  Feature,
[in] sequence< ::com::sun::star::beans::NamedValue >  Arguments )
raises( ::com::sun::star::lang::IllegalArgumentException,
::com::sun::star::sdbc::SQLException,
::com::sun::star::lang::WrappedTargetException );

Description
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 error 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.
commitCurrentRecord
boolean
commitCurrentRecord( [out] boolean  RecordInserted )
raises( ::com::sun::star::sdbc::SQLException );

Description
commits the current record of the form
Parameter RecordInserted
will be true if a record has been inserted, i.e. the form was positioned on the insertion row.
Returns
true if and only if the current record needed being committed. That's the case if the record or the active control of the form were modified.
Throws
::com::sun::star::sdbc::SQLException if a database access error occurs
commitCurrentControl
boolean
commitCurrentControl()
raises( ::com::sun::star::sdbc::SQLException );

Description
commits the current control of our controller
Throws
::com::sun::star::sdbc::SQLException if a database access error occurs
isInsertionRow
boolean
isInsertionRow()
raises( ::com::sun::star::lang::WrappedTargetException );

Description
determines whether the form is currently positioned on the insertion row

This is a convenience method only. Calling it is equivalent to examining the ::com::sun::star::sdb::RowSet::IsNew property of the form.

Throws
::com::sun::star::lang::WrappedTargetException if an error occurs obtaining the form property
isModifiedRow
boolean
isModifiedRow()
raises( ::com::sun::star::lang::WrappedTargetException );

Description
determines whether the current row of the form is modified

This is a convenience method only. Calling it is equivalent to examining the ::com::sun::star::sdb::RowSet::IsModified property of the form.

Throws
::com::sun::star::lang::WrappedTargetException if an error occurs obtaining the form property
Attributes' Details
Cursor
[ readonly ] ::com::sun::star::sdbc::XRowSet Cursor;
Description
provides access to the cursor of the form the instance is operating on.
UpdateCursor
[ readonly ] ::com::sun::star::sdbc::XResultSetUpdate UpdateCursor;
Description
provides access to the update cursor of the form the instance is operating on.
Controller
[ readonly ] XFormController Controller;
Description
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.

FeatureInvalidation
XFeatureInvalidation FeatureInvalidation;
Description
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.

See also
FormFeature
Top of Page