<html> <head> <title>Interface XFormOperations</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../../idl.css"> </head> <body> <div id="adc-idlref"> <a name="_top_"> </a><table class="navimain" border="0" cellpadding="3"> <tr> <td class="navimain"><a href="../../module-ix.html" class="navimain">Overview</a></td> <td class="navimain"><a href="module-ix.html" class="navimain">Module</a></td> <td class="navimain"><a href="XFormOperations-xref.html" class="navimain">Use</a></td> <td class="navimainnone">Devguide</td> <td class="navimain"><a href="../../../../../index-files/index-1.html" class="navimain">Index</a></td> </tr> </table> <table class="navisub" border="0" cellpadding="0"> <tr> <td class="navisub"><a href="#MethodsSummary" class="navisub">Methods' Summary</a></td> <td class="navisub"><a href="#MethodsDetails" class="navisub">Methods' Details</a></td> <td class="navisub"><a href="#AttributesSummary" class="navisub">Attributes' Summary</a></td> <td class="navisub"><a href="#AttributesDetails" class="navisub">Attributes' Details</a></td> </tr> </table> <hr> <table border="0" width="100%" cellpadding="5" cellspacing="3" class="title-table" style="margin-bottom:6pt;"> <tr> <td><p class="namechain"><a href="../../../../../module-ix.html" class="namechain">::</a> <a href="../../../../module-ix.html" class="namechain">com</a> :: <a href="../../../module-ix.html" class="namechain">sun</a> :: <a href="../../module-ix.html" class="namechain">star</a> :: <a href="../module-ix.html" class="namechain">form</a> :: <a href="module-ix.html" class="namechain">runtime</a> :: </p> </td> </tr> <tr> <td class="title"><table class="title-table" width="99%"> <tr> <td width="25%" class="title2">unpublished </td> <td width="50%" class="title">interface XFormOperations</td> <td width="*"/></tr> </table> </td> </tr> <tr> <td><dl> <dt><b>Base Interfaces</b></dt> <dd><pre style="font-family:monospace;"><strong>XFormOperations</strong> ┗ ::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/XComponent.html">XComponent</a> </pre></dd> <dd><a name/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="crosstitle"> <tr> <td class="imsum_left">::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/XComponent.html">XComponent</a></td> <td class="imsum_right"><dl> <dt>(referenced interface's summary:)</dt> <dd>allows to exclicitly free resources and break cyclic references. </dd> </dl> </td> </tr> </table> </dd> </dl> </td> </tr> <tr> <td><dl> <dt><b>Description</b></dt> <dd>encapsulates operations on a database form. </dd> <dd><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::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/XResultSetUpdate.html">XResultSetUpdate</a>::<a href="../../sdbc/XResultSetUpdate.html#updateRow">updateRow</a> or ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/XResultSetUpdate.html">XResultSetUpdate</a>::<a href="../../sdbc/XResultSetUpdate.html#insertRow">insertRow</a>, depending on the form's ::com::sun::star::<a href="../../sdb/module-ix.html">sdb</a>::<a href="../../sdb/RowSet.html">RowSet</a>::<a href="../../sdb/RowSet.html#IsNew">IsNew</a> 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 ::com::sun::star::<a href="../module-ix.html">form</a>::<a href="../XConfirmDeleteListener.html">XConfirmDeleteListener</a>s registered at the ::com::sun::star::<a href="../module-ix.html">form</a>::<a href="../FormController.html">FormController</a> or the ::com::sun::star::form::<a href="../component/module-ix.html">component</a>::<a href="../component/DataForm.html">DataForm</a>.</p> <p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code> is for you. It provides a <a href="XFormOperations.html#execute">execute</a> method, which will do all of the above for you; plus some similar convenient wrappers for similar functionality.</p> </dd> <dt><b/></dt> <dd/><dt><b>See also</b></dt> <dd><a href="FormFeature.html">FormFeature</a></dd> </dl> </td> </tr> </table> <hr> <a name="MethodsSummary"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle" colspan="2">Methods' Summary</td> </tr> <tr> <td class="imsum_left"><a href="#getState">getState</a></td> <td class="imsum_right">retrieves the current state of the given feature </td> </tr> <tr> <td class="imsum_left"><a href="#isEnabled">isEnabled</a></td> <td class="imsum_right">determines whether a feature is currently enabled. </td> </tr> <tr> <td class="imsum_left"><a href="#execute">execute</a></td> <td class="imsum_right">executes the operation associated with the given feature </td> </tr> <tr> <td class="imsum_left"><a href="#executeWithArguments">executeWithArguments</a></td> <td class="imsum_right">executes the operation associated with the given feature, with passing arguments for execution </td> </tr> <tr> <td class="imsum_left"><a href="#commitCurrentRecord">commitCurrentRecord</a></td> <td class="imsum_right">commits the current record of the form </td> </tr> <tr> <td class="imsum_left"><a href="#commitCurrentControl">commitCurrentControl</a></td> <td class="imsum_right">commits the current control of our controller </td> </tr> <tr> <td class="imsum_left"><a href="#isInsertionRow">isInsertionRow</a></td> <td class="imsum_right">determines whether the form is currently positioned on the insertion row </td> </tr> <tr> <td class="imsum_left"><a href="#isModifiedRow">isModifiedRow</a></td> <td class="imsum_right">determines whether the current row of the form is modified </td> </tr> </table> <a name="MethodsDetails"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle">Methods' Details</td> </tr> <tr> <td class="imdetail"><a name="getState" class="membertitle">getState</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3"><a href="FeatureState.html">FeatureState</a></td> </tr> <tr> <td valign="top"><b>getState</b>(</td> <td valign="top">[in] short</td> <td valign="bottom"> Feature );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>retrieves the current state of the given feature </dd> <dd><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 <b>true</b>.<p> </dd> <dt><b>Parameter Feature</b></dt> <dd>the feature whose state is to be determimed. Must be one of the <a href="FormFeature.html">FormFeature</a> constants.<br/> An invalid value here will be silently ignored, and simply return a <a href="FeatureState.html">FeatureState</a> indicating <em>disabled</em> with a <b>NULL</b> state.</p> </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="isEnabled" class="membertitle">isEnabled</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">boolean</td> </tr> <tr> <td valign="top"><b>isEnabled</b>(</td> <td valign="top">[in] short</td> <td valign="bottom"> Feature );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>determines whether a feature is currently enabled. </dd> <dd><p>Calling this is equivalent to calling <a href="#getState">getState</a>, and evaluating the <a href="FeatureState.html">FeatureState</a>::<a href="FeatureState.html#Enabled">Enabled</a> member.</p> </dd> <dt><b>Parameter Feature</b></dt> <dd>the feature whose state is to be determimed. Must be one of the <a href="FormFeature.html">FormFeature</a> constants.<br/> An invalid value here will be silently ignored, and simply return <b>false</b>. </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="execute" class="membertitle">execute</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>execute</b>(</td> <td valign="top">[in] short</td> <td valign="bottom"> Feature )</td> </tr> <tr> <td valign="top" align="right">raises( </td> <td valign="top" colspan="2">::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/IllegalArgumentException.html">IllegalArgumentException</a>,<br> ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/SQLException.html">SQLException</a>,<br> ::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/WrappedTargetException.html">WrappedTargetException</a> );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>executes the operation associated with the given feature </dd> <dt><b>Parameter Feature</b></dt> <dd>the feature which is to be executed. Must be one of the <a href="FormFeature.html">FormFeature</a> constants. </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::IllegalArgumentException if the given Feature is unknown, not executable, or striclty requires arguments to be executed. </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::sdbc::SQLException if a database access erorr occurs </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::WrappedTargetException if an exception is caught which is no ::com::sun::star::<a href="../../uno/module-ix.html">uno</a>::<a href="../../uno/RuntimeException.html">RuntimeException</a> and no ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/SQLException.html">SQLException</a>. </dd> <dt><b>See also</b></dt> <dd><a href="#executeWithArguments">executeWithArguments</a></dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="executeWithArguments" class="membertitle">executeWithArguments</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>executeWithArguments</b>(</td> <td valign="top">[in] short</td> <td valign="bottom"> Feature,</td> </tr> <tr> <td/><td valign="top">[in] sequence< ::com::sun::star::<a href="../../beans/module-ix.html">beans</a>::<a href="../../beans/NamedValue.html">NamedValue</a> ></td> <td valign="bottom"> Arguments )</td> </tr> <tr> <td valign="top" align="right">raises( </td> <td valign="top" colspan="2">::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/IllegalArgumentException.html">IllegalArgumentException</a>,<br> ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/SQLException.html">SQLException</a>,<br> ::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/WrappedTargetException.html">WrappedTargetException</a> );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>executes the operation associated with the given feature, with passing arguments for execution </dd> <dt><b>Parameter Feature</b></dt> <dd>the feature which is to be executed. Must be one of the <a href="FormFeature.html">FormFeature</a> constants. </dd> <dt><b>Parameter Arguments</b></dt> <dd>the named arguments for the feature to execute. See the <a href="FormFeature.html">FormFeature</a> list for features which require arguments. </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::IllegalArgumentException if the given feature is unknown, or not executable </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::IllegalArgumentException if the given arguments are not sufficient to execute the feature </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::sdbc::SQLException if a database access erorr occurs </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::WrappedTargetException if an exception is caught which is no ::com::sun::star::<a href="../../uno/module-ix.html">uno</a>::<a href="../../uno/RuntimeException.html">RuntimeException</a> and no ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/SQLException.html">SQLException</a>. </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="commitCurrentRecord" class="membertitle">commitCurrentRecord</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">boolean</td> </tr> <tr> <td valign="top"><b>commitCurrentRecord</b>(</td> <td valign="top">[out] boolean</td> <td valign="bottom"> RecordInserted )</td> </tr> <tr> <td valign="top" align="right">raises( </td> <td valign="top" colspan="2">::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/SQLException.html">SQLException</a> );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>commits the current record of the form </dd> <dt><b>Parameter RecordInserted</b></dt> <dd>will be <b>true</b> if a record has been inserted, i.e. the form was positioned on the insertion row. </dd> <dt><b>Returns</b></dt> <dd><b>true</b> 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. </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::sdbc::SQLException if a database access erorr occurs </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="commitCurrentControl" class="membertitle">commitCurrentControl</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">boolean</td> </tr> <tr> <td valign="top"><b>commitCurrentControl</b>()</td> </tr> <tr> <td valign="top" align="right">raises( </td> <td valign="top" colspan="2">::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/SQLException.html">SQLException</a> );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>commits the current control of our controller </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::sdbc::SQLException if a database access erorr occurs </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="isInsertionRow" class="membertitle">isInsertionRow</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">boolean</td> </tr> <tr> <td valign="top"><b>isInsertionRow</b>()</td> </tr> <tr> <td valign="top" align="right">raises( </td> <td valign="top" colspan="2">::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/WrappedTargetException.html">WrappedTargetException</a> );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>determines whether the form is currently positioned on the insertion row </dd> <dd><p>This is a convenience method only. Calling it es equivalent to examing the ::com::sun::star::<a href="../../sdb/module-ix.html">sdb</a>::<a href="../../sdb/RowSet.html">RowSet</a>::<a href="../../sdb/RowSet.html#IsNew">IsNew</a> property of the form.</p> </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::WrappedTargetException if an error occurs obtaining the form property </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="isModifiedRow" class="membertitle">isModifiedRow</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">boolean</td> </tr> <tr> <td valign="top"><b>isModifiedRow</b>()</td> </tr> <tr> <td valign="top" align="right">raises( </td> <td valign="top" colspan="2">::com::sun::star::<a href="../../lang/module-ix.html">lang</a>::<a href="../../lang/WrappedTargetException.html">WrappedTargetException</a> );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>determines whether the current row of the form is modified </dd> <dd><p>This is a convenience method only. Calling it es equivalent to examing the ::com::sun::star::<a href="../../sdb/module-ix.html">sdb</a>::<a href="../../sdb/RowSet.html">RowSet</a>::<a href="../../sdb/RowSet.html#IsModified">IsModified</a> property of the form.</p> </dd> <dt><b>Throws</b></dt> <dd>::com::sun::star::lang::WrappedTargetException if an error occurs obtaining the form property </dd> </dl> </td> </tr> </table> </td> </tr> </table> <a name="AttributesSummary"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle" colspan="2">Attributes' Summary</td> </tr> <tr> <td class="imsum_left"><a href="#Cursor">Cursor</a></td> <td class="imsum_right">provides access to the cursor of the form the instance is operating on. </td> </tr> <tr> <td class="imsum_left"><a href="#UpdateCursor">UpdateCursor</a></td> <td class="imsum_right">provides access to the update cursor of the form the instance is operating on. </td> </tr> <tr> <td class="imsum_left"><a href="#Controller">Controller</a></td> <td class="imsum_right">provides access to the form controller which the instance is operating on. </td> </tr> <tr> <td class="imsum_left"><a href="#FeatureInvalidation">FeatureInvalidation</a></td> <td class="imsum_right">denotes the instance which should be notified about features whose state might have changed. </td> </tr> </table> <a name="AttributesDetails"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle">Attributes' Details</td> </tr> <tr> <td class="imdetail"><a name="Cursor" class="membertitle">Cursor</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-data" bgcolor="#ffffff" align="center"> <tr> <td>[ readonly ] ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/XRowSet.html">XRowSet</a> <b>Cursor</b>;<hr> <dl> <dt><b>Description</b></dt> <dd>provides access to the cursor of the form the instance is operating on. </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="UpdateCursor" class="membertitle">UpdateCursor</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-data" bgcolor="#ffffff" align="center"> <tr> <td>[ readonly ] ::com::sun::star::<a href="../../sdbc/module-ix.html">sdbc</a>::<a href="../../sdbc/XResultSetUpdate.html">XResultSetUpdate</a> <b>UpdateCursor</b>;<hr> <dl> <dt><b>Description</b></dt> <dd>provides access to the update cursor of the form the instance is operating on. </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="Controller" class="membertitle">Controller</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-data" bgcolor="#ffffff" align="center"> <tr> <td>[ readonly ] ::com::sun::star::<a href="../module-ix.html">form</a>::<a href="../XFormController.html">XFormController</a> <b>Controller</b>;<hr> <dl> <dt><b>Description</b></dt> <dd>provides access to the form controller which the instance is operating on. </dd> <dd><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> </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="FeatureInvalidation" class="membertitle">FeatureInvalidation</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-data" bgcolor="#ffffff" align="center"> <tr> <td><a href="XFeatureInvalidation.html">XFeatureInvalidation</a> <b>FeatureInvalidation</b>;<hr> <dl> <dt><b>Description</b></dt> <dd>denotes the instance which should be notified about features whose state might have changed. </dd> <dd><p>If this attribute is not <b>NULL</b>, 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 <a href="#execute">execute</a> 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> </dd> <dt><b>See also</b></dt> <dd><a href="FormFeature.html">FormFeature</a></dd> </dl> </td> </tr> </table> </td> </tr> </table> <a href="#_top_">Top of Page</a><hr size="3"><p class="copyright" align="center">Copyright © 2008 Sun Microsystems, Inc.</p> </div> <!-- id="adc-idlref" --> </body> </html>