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