| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| |
| #ifndef __com_sun_star_form_runtime_XFormOperations_idl__ |
| #define __com_sun_star_form_runtime_XFormOperations_idl__ |
| |
| #ifndef __com_sun_star_form_runtime_FeatureState_idl__ |
| #include <com/sun/star/form/runtime/FeatureState.idl> |
| #endif |
| |
| #ifndef __com_sun_star_lang_XComponent_idl__ |
| #include <com/sun/star/lang/XComponent.idl> |
| #endif |
| #ifndef __com_sun_star_sdbc_XRowSet_idl__ |
| #include <com/sun/star/sdbc/XRowSet.idl> |
| #endif |
| #ifndef __com_sun_star_sdbc_XResultSetUpdate_idl__ |
| #include <com/sun/star/sdbc/XResultSetUpdate.idl> |
| #endif |
| #ifndef __com_sun_star_form_runtime_XFormController_idl__ |
| #include <com/sun/star/form/runtime/XFormController.idl> |
| #endif |
| #ifndef __com_sun_star_lang_IllegalArgumentException_idl__ |
| #include <com/sun/star/lang/IllegalArgumentException.idl> |
| #endif |
| #ifndef __com_sun_star_lang_WrappedTargetException_idl__ |
| #include <com/sun/star/lang/WrappedTargetException.idl> |
| #endif |
| #ifndef __com_sun_star_beans_NamedValue_idl__ |
| #include <com/sun/star/beans/NamedValue.idl> |
| #endif |
| |
| //============================================================================= |
| |
| 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 <member scope="com:::sun::star::sdbc">XResultSet::next</member> |
| 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 |
| <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> or |
| <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>, depending |
| on the form's <member scope="com::sun::star::sdb">RowSet::IsNew</member> 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 nee 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 <type scope="com::sun::star::form">XConfirmDeleteListener</type>s |
| registered at the <type scope="com::sun::star::form">FormController</type> or the |
| <type scope="com::sun::star::form::component">DataForm</type>.</p> |
| |
| <p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code> |
| is for you. It provides a <member>execute</member> method, which will do all of the above |
| for you; plus some similar convenient wrappers for similar functionality.</p> |
| |
| @see FormFeature |
| |
| @since OpenOffice 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 determimed. Must be one of the <type>FormFeature</type> |
| constants.<br/> |
| An invalid value here will be silently ignored, and simply return a <type>FeatureState</type> |
| 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 <member>getState</member>, and evaluating the |
| <member>FeatureState::Enabled</member> member.</p> |
| |
| @param Feature |
| the feature whose state is to be determimed. Must be one of the <type>FormFeature</type> |
| 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 <type>FormFeature</type> |
| 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 <type scope="com::sun::star::uno">RuntimeException</type> |
| and no <type scope="com::sun::star::sdbc">SQLException</type>. |
| |
| @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 <type>FormFeature</type> |
| constants. |
| |
| @param Arguments |
| the named arguments for the feature to execute. See the <type>FormFeature</type> 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 <type scope="com::sun::star::uno">RuntimeException</type> |
| and no <type scope="com::sun::star::sdbc">SQLException</type>. |
| */ |
| 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 erorr 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 erorr 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 es equivalent to examing the |
| <member scope="com::sun::star::sdb">RowSet::IsNew</member> 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 es equivalent to examing the |
| <member scope="com::sun::star::sdb">RowSet::IsModified</member> 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 <member>execute</member> 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 |
