specifies a component controlling the interaction between the user and form functionality. More...

import"XFormController.idl";

Inheritance diagram for XFormController:

Exported Interfaces
interface	::com::sun::star::awt::XTabController
	is used for tab controlling and grouping of the controls. More...

interface	::com::sun::star::container::XChild
	allows access to the parent controller. More...

interface	::com::sun::star::container::XIndexAccess
	allows access to the sub controllers. More...

interface	::com::sun::star::container::XEnumerationAccess
	allows enumerating sub controllers More...

interface	::com::sun::star::lang::XComponent
	allows life time control of the controller. More...

interface	::com::sun::star::util::XModifyBroadcaster
	allows to register as listener for modifications in the controls which the controller is responsible for. More...

interface	::com::sun::star::form::XConfirmDeleteBroadcaster
	used to notify deletions of data in the form before they happen. More...

interface	::com::sun::star::sdb::XSQLErrorBroadcaster
	is used to notify errors which happen in the form the controller is responsible for. More...

interface	::com::sun::star::sdb::XRowSetApproveBroadcaster
	is used for multiplexing row set events happening on the form which the controller is responsible for. More...

interface	::com::sun::star::form::XDatabaseParameterBroadcaster2
	is used broadcasting parameter events in the form. More...

interface	::com::sun::star::util::XModeSelector
	allows switching the form controller to different operation modes. More...

interface	XFilterController
	allows controlling the filter mode. More...

Public Member Functions
void	addActivateListener ([in] ::com::sun::star::form::XFormControllerListener Listener)
	adds the specified listener to receive notifications whenever the activation state of the controller changes. More...

void	removeActivateListener ([in] ::com::sun::star::form::XFormControllerListener Listener)
	removes the specified listener from the list of components to receive notifications whenever the activation state of the controller changes. More...

void	addChildController ([in] XFormController ChildController) raises ( ::com::sun::star::lang::IllegalArgumentException )
	adds a controller to the list of child controllers More...

Public Member Functions inherited from XTabController
void	setModel ([in] com::sun::star::awt::XTabControllerModel Model)
	sets the tab controller model. More...

com::sun::star::awt::XTabControllerModel	getModel ()
	returns the tab controller model. More...

void	setContainer ([in] com::sun::star::awt::XControlContainer Container)
	set the control container. More...

com::sun::star::awt::XControlContainer	getContainer ()
	returns the control container. More...

sequence< com::sun::star::awt::XControl >	getControls ()
	returns all controls of the control container. More...

void	autoTabOrder ()
	enables automatic tab order. More...

void	activateTabOrder ()
	activates tab order. More...

void	activateFirst ()
	sets the focus to the first control that can be reached with the TAB key. More...

void	activateLast ()
	sets the focus to the last control that can be reached with the TAB key. More...

Public Member Functions inherited from XInterface
any	queryInterface ([in] type aType)
	queries for a new interface to an existing UNO object. More...

void	acquire ()
	increases the reference counter by one. More...

void	release ()
	decreases the reference counter by one. More...

Public Member Functions inherited from XChild
com::sun::star::uno::XInterface	getParent ()
	grants access to the object containing this content. More...

void	setParent ([in] com::sun::star::uno::XInterface Parent) raises ( com::sun::star::lang::NoSupportException )
	sets the parent to this object. More...

Public Member Functions inherited from XIndexAccess
long	getCount ()

any	getByIndex ([in] long Index) raises ( com::sun::star::lang::IndexOutOfBoundsException, com::sun::star::lang::WrappedTargetException )

Public Member Functions inherited from XElementAccess
type	getElementType ()

boolean	hasElements ()

Public Member Functions inherited from XEnumerationAccess
com::sun::star::container::XEnumeration	createEnumeration ()

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

void	addEventListener ([in] XEventListener xListener)
	adds an event listener to the object. More...

void	removeEventListener ([in] XEventListener aListener)
	removes an event listener from the listener list. More...

Public Member Functions inherited from XModifyBroadcaster
void	addModifyListener ([in] com::sun::star::util::XModifyListener aListener)
	adds the specified listener to receive events "modified." More...

void	removeModifyListener ([in] com::sun::star::util::XModifyListener aListener)
	removes the specified listener. More...

Public Member Functions inherited from XConfirmDeleteBroadcaster
void	addConfirmDeleteListener ([in] com::sun::star::form::XConfirmDeleteListener aListener)
	remembers the specified listener to receive an event for confirming deletions More...

void	removeConfirmDeleteListener ([in] com::sun::star::form::XConfirmDeleteListener aListener)
	removes the specified listener. More...

Public Member Functions inherited from XSQLErrorBroadcaster
void	addSQLErrorListener ([in]XSQLErrorListener Listener)
	adds the specified listener to receive the event "errorOccurred" More...

void	removeSQLErrorListener ([in]XSQLErrorListener Listener)
	removes the specified listener. More...

Public Member Functions inherited from XRowSetApproveBroadcaster
void	addRowSetApproveListener ([in]XRowSetApproveListener listener)
	adds the specified listener to receive the events "approveCursorMove", "approveRowChange", and "approveRowSetChange". More...

void	removeRowSetApproveListener ([in]XRowSetApproveListener listener)
	removes the specified listener. More...

Public Member Functions inherited from XDatabaseParameterBroadcaster2
void	addDatabaseParameterListener ([in] com::sun::star::form::XDatabaseParameterListener aListener)
	registers an XDatabaseParameterListener More...

void	removeDatabaseParameterListener ([in] com::sun::star::form::XDatabaseParameterListener aListener)
	revokes an XDatabaseParameterListener More...

Public Member Functions inherited from XDatabaseParameterBroadcaster
void	addParameterListener ([in] com::sun::star::form::XDatabaseParameterListener aListener)
	adds the specified listener, to allow it to fill in necessary parameter values. More...

void	removeParameterListener ([in] com::sun::star::form::XDatabaseParameterListener aListener)
	removes the specified listener. More...

Public Member Functions inherited from XModeSelector
void	setMode ([in] string aMode) raises ( com::sun::star::lang::NoSupportException )
	sets a new mode for the implementing object. More...

string	getMode ()

sequence< string >	getSupportedModes ()

boolean	supportsMode ([in] string aMode)
	asks whether a mode is supported or not. More...

Public Attributes
XFormOperations	FormOperations
	denotes the instance which is used to implement operations on the form which the controller works for. More...

::com::sun::star::awt::XControl	CurrentControl
	provides access to the currently active control More...

XFormControllerContext	Context
	allows to delegate certain tasks to the context of the form controller More...

::com::sun::star::task::XInteractionHandler	InteractionHandler
	used (if not `NULL`) for user interactions triggered by the form controller. More...

Additional Inherited Members
Protected Member Functions inherited from XFilterController
void	addFilterControllerListener ([in] XFilterControllerListener Listener)
	registers a listener to be notified of certain changes in the form based filter. More...

void	removeFilterControllerListener ([in] XFilterControllerListener Listener)
	revokes a listener which was previously registered to be notified of certain changes in the form based filter. More...

void	setPredicateExpression ([in] long Component, [in] long Term, [in] string PredicateExpression) raises ( ::com::sun::star::lang::IndexOutOfBoundsException )
	sets a given predicate expression More...

::com::sun::star::awt::XControl	getFilterComponent ([in] long Component) raises ( ::com::sun::star::lang::IndexOutOfBoundsException )
	retrieves the filter component with the given index. More...

sequence< sequence< string > >	getPredicateExpressions ()
	retrieves the entirety of the predicate expressions represented by the filter controller. More...

void	removeDisjunctiveTerm ([in] long Term) raises ( ::com::sun::star::lang::IndexOutOfBoundsException )
	removes a given disjunctive term More...

void	appendEmptyDisjunctiveTerm ()
	appends an empty disjunctive term to the list of terms. More...

Protected Attributes inherited from XFilterController
long	FilterComponents
	is the number of filter components, or filter controls, which the filter controller is responsible for. More...

long	DisjunctiveTerms
	is the number of disjunctive terms of the filter expression represented by the form based filter. More...

long	ActiveTerm { set raises(::com::sun::star::lang::IndexOutOfBoundsException); }
	denotes the active term of the filter controller. More...

Detailed Description

specifies a component controlling the interaction between the user and form functionality.

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 n^th child of a controller gives you the same object as retrieving the n^th 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 present 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 semantics. 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 a 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 a 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.

See also: com::sun::star::form::component:Form; com::sun::star::form::binding::BindableControlModel; com::sun::star::sdb::DataSource::Settings

Since: OOo 3.3

Exported Interfaces

◆ ::com::sun::star::awt::XTabController

interface ::com::sun::star::awt::XTabController

is used for tab controlling and grouping of the controls.

The model obtained via com::sun::star::awt::XTabController::getModel() is the form for which the controller is responsible.

◆ ::com::sun::star::container::XChild

interface ::com::sun::star::container::XChild

allows access to the parent controller.

◆ ::com::sun::star::container::XEnumerationAccess

interface ::com::sun::star::container::XEnumerationAccess

allows enumerating sub controllers

◆ ::com::sun::star::container::XIndexAccess

interface ::com::sun::star::container::XIndexAccess

allows access to the sub controllers.

◆ ::com::sun::star::form::XConfirmDeleteBroadcaster

interface ::com::sun::star::form::XConfirmDeleteBroadcaster

used to notify deletions of data in the form before they happen.

A form controller listens for deletion events at the form it is responsible for. If and only if no com::sun::star::form::XConfirmDeleteListener is registered at the controller, it uses an own dialog to ask the user for confirmation.

◆ ::com::sun::star::form::XDatabaseParameterBroadcaster2

interface ::com::sun::star::form::XDatabaseParameterBroadcaster2

is used broadcasting parameter events in the form.

A form controller listens for parameter events at the form it is responsible for. If and only if no com::sun::star::form::XDatabaseParameterListener is registered at the controller, it uses an own dialog to ask the user for parameter values.

◆ ::com::sun::star::lang::XComponent

interface ::com::sun::star::lang::XComponent

allows life time control of the controller.

◆ ::com::sun::star::sdb::XRowSetApproveBroadcaster

interface ::com::sun::star::sdb::XRowSetApproveBroadcaster

is used for multiplexing row set events happening on the form which the controller is responsible for.

◆ ::com::sun::star::sdb::XSQLErrorBroadcaster

interface ::com::sun::star::sdb::XSQLErrorBroadcaster

is used to notify errors which happen in the form the controller is responsible for.

A form controller listens for error events at the form it is responsible for. If and only if no com::sun::star::sdb::XSQLErrorListener is registered at the controller, it uses an own dialog to notify the user of the error.

◆ ::com::sun::star::util::XModeSelector

interface ::com::sun::star::util::XModeSelector

allows switching the form controller to different operation modes.

The two modes usually (but not necessarily) supported by a form controller are the DataMode and the FilterMode, where the former is the usual modus operandi for displaying and modifying data, and the latter is a special mode to enter a filter for the database form which the controller is responsible for.

◆ ::com::sun::star::util::XModifyBroadcaster

interface ::com::sun::star::util::XModifyBroadcaster

allows to register as listener for modifications in the controls which the controller is responsible for.

◆ XFilterController

interface XFilterController

optional

allows controlling the filter mode.

If the form controller supports a form based filter mode, then it shall also support the XFilterController interface, which allows controlling this mode.

Member Function Documentation

◆ addActivateListener()

void addActivateListener ( [in] ::com::sun::star::form::XFormControllerListener Listener )

adds the specified listener to receive notifications whenever the activation state of the controller changes.

◆ addChildController()

void addChildController	(	[in] XFormController	ChildController	)
raises	(	::com::sun::star::lang::IllegalArgumentException
	)

adds a controller to the list of child controllers

Exceptions

com::sun::star::lang::IllegalArgumentException if the given controller is NULL, or cannot rightfully be a child controller. Since controllers mirror the hierarchy of the forms the are responsible for, this means that the form of the given child controller must be a child of the controller at which the method is invoked.

◆ removeActivateListener()

void removeActivateListener ( [in] ::com::sun::star::form::XFormControllerListener Listener )

removes the specified listener from the list of components to receive notifications whenever the activation state of the controller changes.

Member Data Documentation

◆ Context

XFormControllerContext Context

attribute

allows to delegate certain tasks to the context of the form controller

◆ CurrentControl

::com::sun::star::awt::XControl CurrentControl

attributereadonly

provides access to the currently active control

◆ FormOperations

XFormOperations FormOperations

attributereadonly

denotes the instance which is used to implement operations on the form which the controller works for.

This instance can be used, for instance, to determine the current state of certain form features.

◆ InteractionHandler

::com::sun::star::task::XInteractionHandler InteractionHandler

attribute

used (if not NULL) for user interactions triggered by the form controller.

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

com/sun/star/form/runtime/XFormController.idl

Exported Interfaces

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Responsibilities

Exported Interfaces

◆ ::com::sun::star::awt::XTabController

◆ ::com::sun::star::container::XChild

◆ ::com::sun::star::container::XEnumerationAccess

◆ ::com::sun::star::container::XIndexAccess

◆ ::com::sun::star::form::XConfirmDeleteBroadcaster

◆ ::com::sun::star::form::XDatabaseParameterBroadcaster2

◆ ::com::sun::star::lang::XComponent

◆ ::com::sun::star::sdb::XRowSetApproveBroadcaster

◆ ::com::sun::star::sdb::XSQLErrorBroadcaster

◆ ::com::sun::star::util::XModeSelector

◆ ::com::sun::star::util::XModifyBroadcaster

◆ XFilterController

Member Function Documentation

◆ addActivateListener()

◆ addChildController()

◆ removeActivateListener()

Member Data Documentation

◆ Context

◆ CurrentControl

◆ FormOperations

◆ InteractionHandler