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