offapi/com/sun/star/form/runtime/XFormOperations.idl

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