forked from amazingfate/loongoffice
fadd18db04
Change-Id: I330886e475af840f97458b9f157db47555a530e2 Reviewed-on: https://gerrit.libreoffice.org/77314 Tested-by: Jenkins Reviewed-by: Julien Nabet <serval2412@yahoo.fr>
258 lines
11 KiB
Plaintext
258 lines
11 KiB
Plaintext
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
|
|
/*
|
|
* This file is part of the LibreOffice project.
|
|
*
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
*
|
|
* This file incorporates work covered by the following license notice:
|
|
*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed
|
|
* with this work for additional information regarding copyright
|
|
* ownership. The ASF licenses this file to you under the Apache
|
|
* License, Version 2.0 (the "License"); you may not use this file
|
|
* except in compliance with the License. You may obtain a copy of
|
|
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
|
|
*/
|
|
|
|
#ifndef __com_sun_star_form_runtime_XFormOperations_idl__
|
|
#define __com_sun_star_form_runtime_XFormOperations_idl__
|
|
|
|
#include <com/sun/star/form/runtime/FeatureState.idl>
|
|
#include <com/sun/star/lang/XComponent.idl>
|
|
#include <com/sun/star/sdbc/XRowSet.idl>
|
|
#include <com/sun/star/sdbc/XResultSetUpdate.idl>
|
|
#include <com/sun/star/form/runtime/XFormController.idl>
|
|
#include <com/sun/star/lang/IllegalArgumentException.idl>
|
|
#include <com/sun/star/lang/WrappedTargetException.idl>
|
|
#include <com/sun/star/beans/NamedValue.idl>
|
|
|
|
|
|
module com { module sun { module star { module form { module runtime {
|
|
|
|
interface XFeatureInvalidation;
|
|
|
|
|
|
/** encapsulates operations on a database form.
|
|
|
|
<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::sdbc::XResultSetUpdate::updateRow() or
|
|
com::sun::star::sdbc::XResultSetUpdate::insertRow(), depending
|
|
on the form's com::sun::star::sdb::RowSet::IsNew 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 need 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::form::XConfirmDeleteListeners
|
|
registered at the com::sun::star::form::FormController or the
|
|
com::sun::star::form::component::DataForm.</p>
|
|
|
|
<p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code>
|
|
is for you. It provides an execute() method, which will do all of the above
|
|
for you; plus some similar convenient wrappers for similar functionality.</p>
|
|
|
|
@see FormFeature
|
|
|
|
@since OOo 2.2
|
|
*/
|
|
interface XFormOperations : ::com::sun::star::lang::XComponent
|
|
{
|
|
/** provides access to the cursor of the form the instance is operating on.
|
|
*/
|
|
[attribute, readonly] ::com::sun::star::sdbc::XRowSet Cursor;
|
|
|
|
/** provides access to the update cursor of the form the instance is operating on.
|
|
*/
|
|
[attribute, readonly] ::com::sun::star::sdbc::XResultSetUpdate UpdateCursor;
|
|
|
|
/** provides access to the form controller which the instance is operating on.
|
|
|
|
<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>
|
|
*/
|
|
[attribute, readonly] ::com::sun::star::form::runtime::XFormController Controller;
|
|
|
|
/** retrieves the current state of the given feature
|
|
|
|
<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 `TRUE`.<p>
|
|
|
|
@param Feature
|
|
the feature whose state is to be determined. Must be one of the FormFeature
|
|
constants.<br/>
|
|
An invalid value here will be silently ignored, and simply return a FeatureState
|
|
indicating <em>disabled</em> with a `NULL` state.</p>
|
|
*/
|
|
FeatureState getState(
|
|
[in] short Feature
|
|
);
|
|
|
|
/** determines whether a feature is currently enabled.
|
|
|
|
<p>Calling this is equivalent to calling getState(), and evaluating the
|
|
FeatureState::Enabled member.</p>
|
|
|
|
@param Feature
|
|
the feature whose state is to be determined. Must be one of the FormFeature
|
|
constants.<br/>
|
|
An invalid value here will be silently ignored, and simply return `FALSE`.
|
|
*/
|
|
boolean isEnabled(
|
|
[in] short Feature
|
|
);
|
|
|
|
/** executes the operation associated with the given feature
|
|
|
|
@param Feature
|
|
the feature which is to be executed. Must be one of the FormFeature
|
|
constants.
|
|
|
|
@throws ::com::sun::star::lang::IllegalArgumentException
|
|
if the given Feature is unknown, not executable, or strictly requires arguments
|
|
to be executed.
|
|
|
|
@throws ::com::sun::star::sdbc::SQLException
|
|
if a database access error occurs
|
|
|
|
@throws ::com::sun::star::lang::WrappedTargetException
|
|
if an exception is caught which is no com::sun::star::uno::RuntimeException
|
|
and no com::sun::star::sdbc::SQLException.
|
|
|
|
@see executeWithArguments
|
|
*/
|
|
void execute(
|
|
[in] short Feature
|
|
)
|
|
raises ( ::com::sun::star::lang::IllegalArgumentException
|
|
, ::com::sun::star::sdbc::SQLException
|
|
, ::com::sun::star::lang::WrappedTargetException
|
|
);
|
|
|
|
/** executes the operation associated with the given feature, with passing arguments for execution
|
|
|
|
@param Feature
|
|
the feature which is to be executed. Must be one of the FormFeature
|
|
constants.
|
|
|
|
@param Arguments
|
|
the named arguments for the feature to execute. See the FormFeature list
|
|
for features which require arguments.
|
|
|
|
@throws ::com::sun::star::lang::IllegalArgumentException
|
|
if the given feature is unknown, or not executable
|
|
|
|
@throws ::com::sun::star::lang::IllegalArgumentException
|
|
if the given arguments are not sufficient to execute the feature
|
|
|
|
@throws ::com::sun::star::sdbc::SQLException
|
|
if a database access error occurs
|
|
|
|
@throws ::com::sun::star::lang::WrappedTargetException
|
|
if an exception is caught which is no com::sun::star::uno::RuntimeException
|
|
and no com::sun::star::sdbc::SQLException.
|
|
*/
|
|
void executeWithArguments(
|
|
[in] short Feature,
|
|
[in] sequence< ::com::sun::star::beans::NamedValue > Arguments
|
|
)
|
|
raises ( ::com::sun::star::lang::IllegalArgumentException
|
|
, ::com::sun::star::sdbc::SQLException
|
|
, ::com::sun::star::lang::WrappedTargetException
|
|
);
|
|
|
|
/** commits the current record of the form
|
|
|
|
@param RecordInserted
|
|
will be `TRUE` if a record has been inserted, i.e. the form was positioned
|
|
on the insertion row.
|
|
|
|
@return
|
|
`TRUE` 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.
|
|
|
|
@throws ::com::sun::star::sdbc::SQLException
|
|
if a database access error occurs
|
|
*/
|
|
boolean commitCurrentRecord(
|
|
[out] boolean RecordInserted
|
|
)
|
|
raises ( ::com::sun::star::sdbc::SQLException );
|
|
|
|
/** commits the current control of our controller
|
|
|
|
@throws ::com::sun::star::sdbc::SQLException
|
|
if a database access error occurs
|
|
*/
|
|
boolean commitCurrentControl(
|
|
)
|
|
raises ( ::com::sun::star::sdbc::SQLException );
|
|
|
|
/** determines whether the form is currently positioned on the insertion row
|
|
|
|
<p>This is a convenience method only. Calling it is equivalent to examining the
|
|
com::sun::star::sdb::RowSet::IsNew property of the form.</p>
|
|
|
|
@throws ::com::sun::star::lang::WrappedTargetException
|
|
if an error occurs obtaining the form property
|
|
*/
|
|
boolean isInsertionRow(
|
|
)
|
|
raises ( ::com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** determines whether the current row of the form is modified
|
|
|
|
<p>This is a convenience method only. Calling it is equivalent to examining the
|
|
com::sun::star::sdb::RowSet::IsModified property of the form.</p>
|
|
|
|
@throws ::com::sun::star::lang::WrappedTargetException
|
|
if an error occurs obtaining the form property
|
|
*/
|
|
boolean isModifiedRow(
|
|
)
|
|
raises ( ::com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** denotes the instance which should be notified about features whose state might have changed.
|
|
|
|
<p>If this attribute is not `NULL`, 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 execute() 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>
|
|
|
|
@see FormFeature
|
|
*/
|
|
[attribute] XFeatureInvalidation FeatureInvalidation;
|
|
};
|
|
|
|
|
|
}; }; }; }; };
|
|
|
|
|
|
#endif
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|