diff options
Diffstat (limited to 'offapi/com/sun/star/form/runtime/XFormOperations.idl')
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFormOperations.idl | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/offapi/com/sun/star/form/runtime/XFormOperations.idl b/offapi/com/sun/star/form/runtime/XFormOperations.idl new file mode 100644 index 000000000..a3c4f9e04 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFormOperations.idl @@ -0,0 +1,257 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ + +#ifndef __com_sun_star_form_runtime_XFormOperations_idl__ +#define __com_sun_star_form_runtime_XFormOperations_idl__ + +#include <com/sun/star/form/runtime/FeatureState.idl> +#include <com/sun/star/lang/XComponent.idl> +#include <com/sun/star/sdbc/XRowSet.idl> +#include <com/sun/star/sdbc/XResultSetUpdate.idl> +#include <com/sun/star/form/runtime/XFormController.idl> +#include <com/sun/star/lang/IllegalArgumentException.idl> +#include <com/sun/star/lang/WrappedTargetException.idl> +#include <com/sun/star/beans/NamedValue.idl> + + +module com { module sun { module star { module form { module runtime { + +interface XFeatureInvalidation; + + +/** encapsulates operations on a database form. + + <p>This instance allows for operations on a user interface form, by saving its clients + from various tedious and error-prone operations.</p> + + <p>As an example, imagine you have a database form, displayed in some user + interface, which you want to move to the next record.<br/> + 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.<br/> + But then you're done, right? Wrong, again.<br/> + 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.<br/> + <em>Now</em> you're done ...</p> + + <p>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.</p> + + <p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code> + 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.</p> + + @see FormFeature + + @since OOo 2.2 + */ +interface XFormOperations : ::com::sun::star::lang::XComponent +{ + /** provides access to the cursor of the form the instance is operating on. + */ + [attribute, readonly] ::com::sun::star::sdbc::XRowSet Cursor; + + /** provides access to the update cursor of the form the instance is operating on. + */ + [attribute, readonly] ::com::sun::star::sdbc::XResultSetUpdate UpdateCursor; + + /** provides access to the form controller which the instance is operating on. + + <p>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.</p> + */ + [attribute, readonly] ::com::sun::star::form::runtime::XFormController Controller; + + /** retrieves the current state of the given feature + + <p>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 <code>boolean</code> + evaluating to `TRUE`.<p> + + @param Feature + the feature whose state is to be determined. Must be one of the FormFeature + constants.<br/> + An invalid value here will be silently ignored, and simply return a FeatureState + indicating <em>disabled</em> with a `NULL` state.</p> + */ + FeatureState getState( + [in] short Feature + ); + + /** determines whether a feature is currently enabled. + + <p>Calling this is equivalent to calling getState(), and evaluating the + FeatureState::Enabled member.</p> + + @param Feature + the feature whose state is to be determined. Must be one of the FormFeature + constants.<br/> + An invalid value here will be silently ignored, and simply return `FALSE`. + */ + boolean isEnabled( + [in] short Feature + ); + + /** executes the operation associated with the given feature + + @param 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 executeWithArguments + */ + 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, with passing arguments for execution + + @param Feature + the feature which is to be executed. Must be one of the FormFeature + constants. + + @param 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. + */ + 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 + ); + + /** commits the current record of the form + + @param RecordInserted + will be `TRUE` if a record has been inserted, i.e. the form was positioned + on the insertion row. + + @return + `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 + */ + boolean commitCurrentRecord( + [out] boolean RecordInserted + ) + raises ( ::com::sun::star::sdbc::SQLException ); + + /** commits the current control of our controller + + @throws ::com::sun::star::sdbc::SQLException + if a database access error occurs + */ + boolean commitCurrentControl( + ) + raises ( ::com::sun::star::sdbc::SQLException ); + + /** determines whether the form is currently positioned on the insertion row + + <p>This is a convenience method only. Calling it is equivalent to examining the + com::sun::star::sdb::RowSet::IsNew property of the form.</p> + + @throws ::com::sun::star::lang::WrappedTargetException + if an error occurs obtaining the form property + */ + boolean isInsertionRow( + ) + raises ( ::com::sun::star::lang::WrappedTargetException ); + + /** determines whether the current row of the form is modified + + <p>This is a convenience method only. Calling it is equivalent to examining the + com::sun::star::sdb::RowSet::IsModified property of the form.</p> + + @throws ::com::sun::star::lang::WrappedTargetException + if an error occurs obtaining the form property + */ + boolean isModifiedRow( + ) + raises ( ::com::sun::star::lang::WrappedTargetException ); + + /** denotes the instance which should be notified about features whose state might have changed. + + <p>If this attribute is not `NULL`, the instance which it denotes will be notified + whenever the state of any supported feature might have changed.</p> + + <p>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.</p> + + <p>Note that the instance does not actually notify changes in the feature states, but only + <em>potential</em> 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.</p> + + @see FormFeature + */ + [attribute] XFeatureInvalidation FeatureInvalidation; +}; + + +}; }; }; }; }; + + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |