LibreOffice: XFormOperations Interface Reference

LibreOffice LibreOffice 26.8 SDK API Reference

Loading...
Searching...
No Matches
XFormOperations Interface Reference

encapsulates operations on a database form. More...

`import "XFormOperations.idl";`

Inheritance diagram for XFormOperations:

## Public Member Functions
FeatureState | getState ([in] short Feature)
| retrieves the current state of the given feature
boolean | isEnabled ([in] short Feature)
| determines whether a feature is currently enabled.
void | execute ([in] short Feature) raises ( ::com::sun::star::lang::IllegalArgumentException , ::com::sun::star::sdbc::SQLException , ::com::sun::star::lang::WrappedTargetException )
| executes the operation associated with the given feature
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 )
| executes the operation associated with the given feature, with passing arguments for execution
boolean | commitCurrentRecord ([out] boolean RecordInserted) raises ( ::com::sun::star::sdbc::SQLException )
| commits the current record of the form
boolean | commitCurrentControl () raises ( ::com::sun::star::sdbc::SQLException )
| commits the current control of our controller
boolean | isInsertionRow () raises ( ::com::sun::star::lang::WrappedTargetException )
| determines whether the form is currently positioned on the insertion row
boolean | isModifiedRow () raises ( ::com::sun::star::lang::WrappedTargetException )
| determines whether the current row of the form is modified
Public Member Functions inherited from XComponent
void | dispose ()
| The owner of an object calls this method to explicitly free all resources kept by this object and thus break cyclic references.
void | addEventListener ([in] XEventListener xListener)
| adds an event listener to the object.
void | removeEventListener ([in] XEventListener aListener)
| removes an event listener from the listener list.
Public Member Functions inherited from XInterface
any | queryInterface ([in] type aType)
| queries for a new interface to an existing UNO object.
void | acquire ()
| increases the reference counter by one.
void | release ()
| decreases the reference counter by one.

## Public Attributes
::com::sun::star::sdbc::XRowSet | Cursor
| provides access to the cursor of the form the instance is operating on.
::com::sun::star::sdbc::XResultSetUpdate | UpdateCursor
| provides access to the update cursor of the form the instance is operating on.
::com::sun::star::form::runtime::XFormController | Controller
| provides access to the form controller which the instance is operating on.
XFeatureInvalidation | FeatureInvalidation
| denotes the instance which should be notified about features whose state might have changed.

## Detailed 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 need 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 an execute() method, which will do all of the above for you; plus some similar convenient wrappers for similar functionality.

See also
  FormFeature

Since
  OOo 2.2

## Member Function Documentation

## ◆ commitCurrentControl()

boolean commitCurrentControl | ( |  | ) |
raises | ( | ::com::sun::star::sdbc::SQLException ) |  |  |

commits the current control of our controller

Exceptions

  com::sun::star::sdbc::SQLException | if a database access error occurs

## ◆ commitCurrentRecord()

boolean commitCurrentRecord | ( | [out] boolean | RecordInserted | ) |
raises | ( | ::com::sun::star::sdbc::SQLException ) |  |  |

commits the current record of the form

Parameters

  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.

Exceptions

  com::sun::star::sdbc::SQLException | if a database access error occurs

## ◆ execute()

void execute | ( | [in] short | Feature | ) |
raises | ( | ::com::sun::star::lang::IllegalArgumentException ,
|  | ::com::sun::star::sdbc::SQLException ,
|  | ::com::sun::star::lang::WrappedTargetException ) |  |  |

executes the operation associated with the given feature

Parameters

  Feature | the feature which is to be executed. Must be one of the FormFeature constants.

Exceptions

  com::sun::star::lang::IllegalArgumentException | if the given Feature is unknown, not executable, or strictly requires arguments to be executed.
  com::sun::star::sdbc::SQLException | if a database access error occurs
  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 ) |  |  |

executes the operation associated with the given feature, with passing arguments for execution

Parameters

  Feature | the feature which is to be executed. Must be one of the FormFeature constants.
  Arguments | the named arguments for the feature to execute. See the FormFeature list for features which require arguments.

Exceptions

  com::sun::star::lang::IllegalArgumentException | if the given feature is unknown, or not executable
  com::sun::star::lang::IllegalArgumentException | if the given arguments are not sufficient to execute the feature
  com::sun::star::sdbc::SQLException | if a database access error occurs
  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.

## ◆ getState()

FeatureState getState | ( | [in] short | Feature | ) |

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.

Parameters

  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 | ) |

determines whether a feature is currently enabled.

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

Parameters

  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.

## ◆ isInsertionRow()

boolean isInsertionRow | ( |  | ) |
raises | ( | ::com::sun::star::lang::WrappedTargetException ) |  |  |

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.

Exceptions

  com::sun::star::lang::WrappedTargetException | if an error occurs obtaining the form property

## ◆ isModifiedRow()

boolean isModifiedRow | ( |  | ) |
raises | ( | ::com::sun::star::lang::WrappedTargetException ) |  |  |

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.

Exceptions

  com::sun::star::lang::WrappedTargetException | if an error occurs obtaining the form property

## Member Data Documentation

## ◆ Controller

::com::sun::star::form::runtime::XFormController Controller
| attributereadonly

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.

## ◆ Cursor

::com::sun::star::sdbc::XRowSet Cursor
| attributereadonly

provides access to the cursor of the form the instance is operating on.

## ◆ FeatureInvalidation

XFeatureInvalidation FeatureInvalidation
| attribute

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

## ◆ UpdateCursor

::com::sun::star::sdbc::XResultSetUpdate UpdateCursor
| attributereadonly

provides access to the update cursor of the form the instance is operating on.

The documentation for this interface was generated from the following file:

- com/sun/star/form/runtime/XFormOperations.idl