1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24#ifndef __com_sun_star_form_runtime_XFormOperations_idl__ 25#define __com_sun_star_form_runtime_XFormOperations_idl__ 26 27#ifndef __com_sun_star_form_runtime_FeatureState_idl__ 28#include <com/sun/star/form/runtime/FeatureState.idl> 29#endif 30 31#ifndef __com_sun_star_lang_XComponent_idl__ 32#include <com/sun/star/lang/XComponent.idl> 33#endif 34#ifndef __com_sun_star_sdbc_XRowSet_idl__ 35#include <com/sun/star/sdbc/XRowSet.idl> 36#endif 37#ifndef __com_sun_star_sdbc_XResultSetUpdate_idl__ 38#include <com/sun/star/sdbc/XResultSetUpdate.idl> 39#endif 40#ifndef __com_sun_star_form_runtime_XFormController_idl__ 41#include <com/sun/star/form/runtime/XFormController.idl> 42#endif 43#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ 44#include <com/sun/star/lang/IllegalArgumentException.idl> 45#endif 46#ifndef __com_sun_star_lang_WrappedTargetException_idl__ 47#include <com/sun/star/lang/WrappedTargetException.idl> 48#endif 49#ifndef __com_sun_star_beans_NamedValue_idl__ 50#include <com/sun/star/beans/NamedValue.idl> 51#endif 52 53//============================================================================= 54 55module com { module sun { module star { module form { module runtime { 56 57interface XFeatureInvalidation; 58 59//============================================================================= 60 61/** encapsulates operations on a database form. 62 63 <p>This instance allows for operations on a user interface form, by saving its clients 64 from various tedious and error-prone operations.</p> 65 66 <p>As an example, imagine you have a database form, displayed in some user 67 interface, which you want to move to the next record.<br/> 68 It is as easy as calling <member scope="com:::sun::star::sdbc">XResultSet::next</member> 69 on this form, right? Wrong. First, you need to care for saving the current 70 record, so the user doesn't lose her input. So you need to call 71 <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> or 72 <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>, depending 73 on the form's <member scope="com::sun::star::sdb">RowSet::IsNew</member> property.<br/> 74 But then you're done, right? Wrong, again.<br/> 75 When the user just entered some data into one of the form fields, but did not yet 76 leave this field, then the data is not yet committed to the form, not to talk 77 about being committed to the underlying database. So, before everything else, 78 you would nee to obtain the active control of the form, and commit it.<br/> 79 <em>Now</em> you're done ...</p> 80 81 <p>As another example, consider that you want to delete the current record from the 82 form. You have to take into account any <type scope="com::sun::star::form">XConfirmDeleteListener</type>s 83 registered at the <type scope="com::sun::star::form">FormController</type> or the 84 <type scope="com::sun::star::form::component">DataForm</type>.</p> 85 86 <p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code> 87 is for you. It provides a <member>execute</member> method, which will do all of the above 88 for you; plus some similar convenient wrappers for similar functionality.</p> 89 90 @see FormFeature 91 92 @since OpenOffice 2.2 93 */ 94interface XFormOperations : ::com::sun::star::lang::XComponent 95{ 96 /** provides access to the cursor of the form the instance is operating on. 97 */ 98 [attribute, readonly] ::com::sun::star::sdbc::XRowSet Cursor; 99 100 /** provides access to the update cursor of the form the instance is operating on. 101 */ 102 [attribute, readonly] ::com::sun::star::sdbc::XResultSetUpdate UpdateCursor; 103 104 /** provides access to the form controller which the instance is operating on. 105 106 <p>Note that it is possible to operate on a user interface form without 107 actually having access to the form controller instance. However, in this 108 case some functionality will not be available. In particular, every feature 109 which relies on the active control of the controller might be of limited use.</p> 110 */ 111 [attribute, readonly] ::com::sun::star::form::runtime::XFormController Controller; 112 113 /** retrieves the current state of the given feature 114 115 <p>You would usually use this to update some user interface to reflect this state. 116 For instance, you could imagine a toolbar button which is associated with a given feature. 117 This button would be enabled if and only if the respective feature is currently 118 available, and be checked if and only if the feature state is a <code>boolean</code> 119 evaluating to <TRUE/>.<p> 120 121 @param Feature 122 the feature whose state is to be determimed. Must be one of the <type>FormFeature</type> 123 constants.<br/> 124 An invalid value here will be silently ignored, and simply return a <type>FeatureState</type> 125 indicating <em>disabled</em> with a <NULL/> state.</p> 126 */ 127 FeatureState getState( 128 [in] short Feature 129 ); 130 131 /** determines whether a feature is currently enabled. 132 133 <p>Calling this is equivalent to calling <member>getState</member>, and evaluating the 134 <member>FeatureState::Enabled</member> member.</p> 135 136 @param Feature 137 the feature whose state is to be determimed. Must be one of the <type>FormFeature</type> 138 constants.<br/> 139 An invalid value here will be silently ignored, and simply return <FALSE/>. 140 */ 141 boolean isEnabled( 142 [in] short Feature 143 ); 144 145 /** executes the operation associated with the given feature 146 147 @param Feature 148 the feature which is to be executed. Must be one of the <type>FormFeature</type> 149 constants. 150 151 @throws ::com::sun::star::lang::IllegalArgumentException 152 if the given Feature is unknown, not executable, or striclty requires arguments 153 to be executed. 154 155 @throws ::com::sun::star::sdbc::SQLException 156 if a database access erorr occurs 157 158 @throws ::com::sun::star::lang::WrappedTargetException 159 if an exception is caught which is no <type scope="com::sun::star::uno">RuntimeException</type> 160 and no <type scope="com::sun::star::sdbc">SQLException</type>. 161 162 @see executeWithArguments 163 */ 164 void execute( 165 [in] short Feature 166 ) 167 raises ( ::com::sun::star::lang::IllegalArgumentException 168 , ::com::sun::star::sdbc::SQLException 169 , ::com::sun::star::lang::WrappedTargetException 170 ); 171 172 /** executes the operation associated with the given feature, with passing arguments for execution 173 174 @param Feature 175 the feature which is to be executed. Must be one of the <type>FormFeature</type> 176 constants. 177 178 @param Arguments 179 the named arguments for the feature to execute. See the <type>FormFeature</type> list 180 for features which require arguments. 181 182 @throws ::com::sun::star::lang::IllegalArgumentException 183 if the given feature is unknown, or not executable 184 185 @throws ::com::sun::star::lang::IllegalArgumentException 186 if the given arguments are not sufficient to execute the feature 187 188 @throws ::com::sun::star::sdbc::SQLException 189 if a database access erorr occurs 190 191 @throws ::com::sun::star::lang::WrappedTargetException 192 if an exception is caught which is no <type scope="com::sun::star::uno">RuntimeException</type> 193 and no <type scope="com::sun::star::sdbc">SQLException</type>. 194 */ 195 void executeWithArguments( 196 [in] short Feature, 197 [in] sequence< ::com::sun::star::beans::NamedValue > Arguments 198 ) 199 raises ( ::com::sun::star::lang::IllegalArgumentException 200 , ::com::sun::star::sdbc::SQLException 201 , ::com::sun::star::lang::WrappedTargetException 202 ); 203 204 /** commits the current record of the form 205 206 @param RecordInserted 207 will be <TRUE/> if a record has been inserted, i.e. the form was positioned 208 on the insertion row. 209 210 @return 211 <TRUE/> if and only if the current record needed being committed. That's the 212 case if the record or the active control of the form were modified. 213 214 @throws ::com::sun::star::sdbc::SQLException 215 if a database access erorr occurs 216 */ 217 boolean commitCurrentRecord( 218 [out] boolean RecordInserted 219 ) 220 raises ( ::com::sun::star::sdbc::SQLException ); 221 222 /** commits the current control of our controller 223 224 @throws ::com::sun::star::sdbc::SQLException 225 if a database access erorr occurs 226 */ 227 boolean commitCurrentControl( 228 ) 229 raises ( ::com::sun::star::sdbc::SQLException ); 230 231 /** determines whether the form is currently positioned on the insertion row 232 233 <p>This is a convenience method only. Calling it es equivalent to examing the 234 <member scope="com::sun::star::sdb">RowSet::IsNew</member> property of the form.</p> 235 236 @throws ::com::sun::star::lang::WrappedTargetException 237 if an error occurs obtaining the form property 238 */ 239 boolean isInsertionRow( 240 ) 241 raises ( ::com::sun::star::lang::WrappedTargetException ); 242 243 /** determines whether the current row of the form is modified 244 245 <p>This is a convenience method only. Calling it es equivalent to examing the 246 <member scope="com::sun::star::sdb">RowSet::IsModified</member> property of the form.</p> 247 248 @throws ::com::sun::star::lang::WrappedTargetException 249 if an error occurs obtaining the form property 250 */ 251 boolean isModifiedRow( 252 ) 253 raises ( ::com::sun::star::lang::WrappedTargetException ); 254 255 /** denotes the instance which should be notified about features whose state might have changed. 256 257 <p>If this attribute is not <NULL/>, the instance which it denotes will be notified 258 whenever the state of any supported feature might have changed.</p> 259 260 <p>For instance, imagine a form whose current row has just been moved to another 261 record, using the <member>execute</member> method. This means that potentially, the state 262 of all movement-related features might have changed.</p> 263 264 <p>Note that the instance does not actually notify changes in the feature states, but only 265 <em>potential</em> changes: It's up to the callee to react on this appropriately. This is 266 since OpenOffice.org's application framework features own mechanisms to cache and invalidate 267 feature states, so we do not burden this implementation here with such mechanisms.</p> 268 269 @see FormFeature 270 */ 271 [attribute] XFeatureInvalidation FeatureInvalidation; 272}; 273 274//============================================================================= 275 276}; }; }; }; }; 277 278//============================================================================= 279 280#endif 281