diff options
Diffstat (limited to 'offapi/com/sun/star/form/runtime')
| -rw-r--r-- | offapi/com/sun/star/form/runtime/FeatureState.idl | 62 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/FilterEvent.idl | 65 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/FormController.idl | 52 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/FormFeature.idl | 155 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/FormOperations.idl | 91 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFeatureInvalidation.idl | 76 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFilterController.idl | 181 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFilterControllerListener.idl | 85 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFormController.idl | 374 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFormControllerContext.idl | 58 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/XFormOperations.idl | 284 | ||||
| -rw-r--r-- | offapi/com/sun/star/form/runtime/makefile.mk | 56 |
12 files changed, 1539 insertions, 0 deletions
diff --git a/offapi/com/sun/star/form/runtime/FeatureState.idl b/offapi/com/sun/star/form/runtime/FeatureState.idl new file mode 100644 index 000000000000..996aff1e8076 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/FeatureState.idl @@ -0,0 +1,62 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_form_runtime_FeatureState_idl__ +#define __com_sun_star_form_runtime_FeatureState_idl__ + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** encapsulates the state of a FormFeature + + @see XFormOperations + + @since OpenOffice.org 2.2.0 + */ +struct FeatureState +{ + /** determines whether the respective feature is enabled (i.e. available) + in the current state of the form. + */ + boolean Enabled; + + /** determines the state of the feature. The concrete semantics depends + on the concrete <type>FormFeature</type>. + */ + any State; +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif + diff --git a/offapi/com/sun/star/form/runtime/FilterEvent.idl b/offapi/com/sun/star/form/runtime/FilterEvent.idl new file mode 100644 index 000000000000..b7cc035113cb --- /dev/null +++ b/offapi/com/sun/star/form/runtime/FilterEvent.idl @@ -0,0 +1,65 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * +************************************************************************/ + +#ifndef __com_sun_star_form_runtime_FilterEvent_idl__ +#define __com_sun_star_form_runtime_FilterEvent_idl__ + +#include <com/sun/star/lang/EventObject.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** is an event fired by a filter controller, when the filter managed by the controller changes. + + @see XFilterController + + @since OpenOffice.org 3.3 + */ +struct FilterEvent : ::com::sun::star::lang::EventObject +{ + /** denotes the index of the <em>disjunctive term</em> to which the event applies, if any. + */ + long DisjunctiveTerm; + + /** denotes the index of the <em>filter component</em> to which the event applies, if any. + */ + long FilterComponent; + + /** denotes the <em>predicate expression</em> associated with the event. + */ + string PredicateExpression; +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/FormController.idl b/offapi/com/sun/star/form/runtime/FormController.idl new file mode 100644 index 000000000000..6a03270a1b52 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/FormController.idl @@ -0,0 +1,52 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * +************************************************************************/ + +#ifndef __offapi_com_sun_star_form_runtime_FormController_idl__ +#define __offapi_com_sun_star_form_runtime_FormController_idl__ + +#include <com/sun/star/form/runtime/XFormController.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** specifies a component controlling the interaction between the user and multiple + form controls belonging to a single form. + */ +service FormController +{ + interface XFormController; +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/FormFeature.idl b/offapi/com/sun/star/form/runtime/FormFeature.idl new file mode 100644 index 000000000000..57ebcc8ef7b7 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/FormFeature.idl @@ -0,0 +1,155 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_form_runtime_FormFeature_idl__ +#define __com_sun_star_form_runtime_FormFeature_idl__ + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** specifies the operations on a user interface form, as supported by the + <type>XFormOperations</type> interface. + + @since OpenOffice.org 2.2.0 +*/ +constants FormFeature +{ + /** moves the form to a record given by absolute position. + + <p>This operation cannot be executed without arguments. When executing it (i.e. + when calling <member scope="com::sun::star::form::runtime">XFormOperations::executeWithArguments</member>), + you need to specify a parameter named <em>Position</em> of type <code>long</code>, which + denotes the position to move the form to.</p> + */ + const short MoveAbsolute = 1; + + /** determines the number of total records in the form, + including the potentially active insertion row. + + <p>This is not strictly an operation you can do on a form, but rather a + state you can retrieve (and display to the user) using the <type>XFormOperations</type>' + respective methods.</p> + + <p>The state obtained here is a string, not a number. This is because in an UI + form, the fact that the current record count is not yet known (since not all + records have been visited, yet) is indicated by an asterik (<code>*</code>) besides + the record count.</p> + */ + const short TotalRecords = 2; + + /// moves the form to the first record + const short MoveToFirst = 3; + + /// moves the form to the record before the current record, if there is any + const short MoveToPrevious = 4; + + /// moves the form to the record after the current record, if there is any + const short MoveToNext = 5; + + /// moves the form to the last record + const short MoveToLast = 6; + + /// moves the form to the insertion row, if privileges allow + const short MoveToInsertRow = 7; + + /** saves all changes in the form's current record, including changes in the current + control which had not yet been committed to the form + */ + const short SaveRecordChanges = 8; + + /** revertsall changes in the form's current record, including changes in the current + control which had not yet been committed to the form + */ + const short UndoRecordChanges = 9; + + /** deletes the current record, while honoring any registered + <type scope="com::sun::star::form">XConfirmDeleteListener</type>s + */ + const short DeleteRecord = 10; + + /// reloads the form content + const short ReloadForm = 11; + + /// sorts the form ascending by the field which the active form control is bound to. + const short SortAscending = 12; + + /// sorts the form descending by the field which the active form control is bound to. + const short SortDescending = 13; + + /// opens a dialog which allows the user to interactively specify a form sorting order + const short InteractiveSort = 14; + + /** adds a filter to the form, which is defined by the active form control and its + current value + + <p>For instance, if the currently active form control is bound to a table field + named <code>Price</code>, and currently has a value of <code>100</code>, then invoking + the <code>AutoFilter</code> operation will put an additional filter <code>Price = 100</code> + on the form.</p> + */ + const short AutoFilter = 15; + + /// opens a dialog which allows the user to interactively specify a form filter + const short InteractiveFilter = 16; + + /** toggles the <member scope="com::sun::star::sdb">RowSet::ApplyFilter</member> property + of a the form. + */ + const short ToggleApplyFilter = 17; + + /** removes all filter and sort criterions put on the form. + + <p>Note that this does not apply to criterios which are part of the form's + data source. That is, if you bind the form to the SQL command <code>SELECT * FROM + Articles WHERE Price > 100</code>, then the <code>Price > 100</code> filter + will not be removed.</p> + + <p>Effectively, this operation resets the <member scope="com::sun::star::sdb">RowSet::Filter</member> + and <member scope="com::sun::star::sdb">RowSet::Order</member> properties of the form.</p> + */ + const short RemoveFilterAndSort = 18; + + /** refreshs the current control + + <p>Basically, this means calling XRefreshable::refresh on the current control, if it supports + this interface.</p> + + @since OOo 3.1 + */ + const short RefreshCurrentControl = 19; +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/FormOperations.idl b/offapi/com/sun/star/form/runtime/FormOperations.idl new file mode 100644 index 000000000000..aa4b7e825c8c --- /dev/null +++ b/offapi/com/sun/star/form/runtime/FormOperations.idl @@ -0,0 +1,91 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_form_runtime_FormOperations_idl__ +#define __com_sun_star_form_runtime_FormOperations_idl__ + +#ifndef __com_sun_star_form_runtime_XFormOperations_idl__ +#include <com/sun/star/form/runtime/XFormOperations.idl> +#endif +#ifndef __com_sun_star_form_runtime_XFormController_idl__ +#include <com/sun/star/form/runtime/XFormController.idl> +#endif +#ifndef __com_sun_star_form_XForm_idl__ +#include <com/sun/star/form/XForm.idl> +#endif +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** encapsulates operations on a database form which has a UI representation, + and is interacting with the user. + + @since OpenOffice.org 2.2.0 + */ +service FormOperations : XFormOperations +{ + /** creates a <code>FormOperations</code> instance which works on a <type scope="com::sun::star::form">FormController</type> + instance. + @throws IllegalArgumentException + if the given form controller is <NULL/>, or does not have a model denoting a valid + <type scope="com::sun::star::form::component">DataForm</type> instance. + */ + createWithFormController( + [in] XFormController Controller + ) + raises( + ::com::sun::star::lang::IllegalArgumentException + ); + + /** creates a <code>FormOperations</code> instance which works on a <type scope="com::sun::star::form::component">DataForm</type> + instance. + + @throws IllegalArgumentException + if the given form is <NULL/>, or does not support the <type scope="com::sun::star::form::component">DataForm</type> + service. + */ + createWithForm( + [in] XForm Form + ) + raises( + ::com::sun::star::lang::IllegalArgumentException + ); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFeatureInvalidation.idl b/offapi/com/sun/star/form/runtime/XFeatureInvalidation.idl new file mode 100644 index 000000000000..b435e64a6d81 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFeatureInvalidation.idl @@ -0,0 +1,76 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_form_runtime_XFeatureInvalidation_idl__ +#define __com_sun_star_form_runtime_XFeatureInvalidation_idl__ + +#ifndef __com_sun_star_uno_XInterface_idl__ +#include <com/sun/star/uno/XInterface.idl> +#endif + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** implements a callback for a <type>XFormOperations</type> instance, which is called + when the state of one or more <type>FormFeature</type>s might have changed. + + @see XFormOperations + + @since OpenOffice.org 2.2.0 +*/ +interface XFeatureInvalidation +{ + /** invalidates the given <type>FormFeature</type>s + + <p>Invalidation means that any user interface representation (such as toolbox buttons), or + any dispatches associated with the features in question are potentially out-of-date, and + need to be updated.</p> + + @param Features + The set of features whose state might have changed. + */ + void invalidateFeatures( [in] sequence< short > Features ); + + /** invalidates all features + + <p>This method is used of it cannot be exactly and reliably determined + which features might actually have changed their state. In this case, the callee + should assume all features it is interested in must be requeried.</p> + */ + void invalidateAllFeatures(); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFilterController.idl b/offapi/com/sun/star/form/runtime/XFilterController.idl new file mode 100644 index 000000000000..8f3fded592d9 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFilterController.idl @@ -0,0 +1,181 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * +************************************************************************/ + +#ifndef __offapi_com_sun_star_form_runtime_XFilterController_idl__ +#define __offapi_com_sun_star_form_runtime_XFilterController_idl__ + +#include <com/sun/star/awt/XControl.idl> +#include <com/sun/star/lang/IndexOutOfBoundsException.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +interface XFilterControllerListener; + +/** provides access to a form based filter for a database form + + <p>In a form based filter, form controls bound to a searchable database field are replaced with a control + which allows entering a search expression. This so-called <em>predicate expression</em> is basically a part of an + SQL <code>WHERE</code> clause, but without the the part denoting the database column. For instance, if you + have a form control bound to a table column named <code>Name</code>, then entering the string + <q>LIKE '%Smith%'</q> effectively consitutes a SQL <code>WHERE</code> clause <code>"Name" LIKE '%Smith%'</code>.</p> + + <p>In the actual document view, there are usually some relaxations to this. For instance, keywords such as + <code>LIKE</code> might be localized, according to OpenOffice.org's UI locale. Also, for an equality criterion, + the equality sign <code>=</code> is usually omitted. However, this interface here provides programmatic access + to the form based filter, so those relaxations are not considered here.</p> + + <p>The filter maintained by a filter controller is, logically, a disjunctive normal form of an SQL <code>WHERE</code> + class. That is, it is a disjunction of <em>m</em> terms, where each term is a conjunction of <em>n</em> clauses + of the form <code><column> <predicate> <literal></code> or of the form <code><em><column> + IS [NOT] NULL</em></code>.</p> + + <p><em>n</em> equals the number of filter controls which the filter controller is responsible for. This number + doesn't change during one session of the form based filter. On the other hand, <em>m</em>, the number of disjunctive + terms, is dynamic.</p> + + <a name="active_term"></a> + <p>With the above, there are potentially <em>m * n</em> <em>predicate expressions</em> (though usually only a fraction + of those will actually exist). Since in a form based filter, there are only <em>n</em> filter controls, and each + filter control displays exactly one <em>predicate expression</em>, this means that only a part of the complete + filter can be displayed, in particular, only one <em>disjunctive term</em> can be displayed at a time. Thus, + the filter controller knows the concept of an <em>active term</em>, denoted by the <member>ActiveTerm</member> + attribute, controls which of the terms is currently displayed in the form controls.</p> + + @see XFormController + @see com::sun::star::sdbc::XResultSetMetaData::isSearchable + @see com::sun::star::sdb::XSingleSelectQueryAnalyzer::getStructuredFilter + @see com::sun::star::sdb::SQLFilterOperator + + @since OpenOffice.org 3.3 + */ +interface XFilterController +{ + /** registers a listener to be notified of certain changes in the form based filter. + + <p>Registering the same listener multiple times results in multiple notifications of the same event, + and also requires multiple revocations of the listener. + */ + void addFilterControllerListener( [in] XFilterControllerListener _Listener ); + + /** revokes a listener which was previously registered to be notified of certain changes in the form based filter. + */ + void removeFilterControllerListener( [in] XFilterControllerListener _Listener ); + + /** is the number of <em>filter components</em>, or filter controls, which the filter controller is responsible + for. + + <p>This number is constant during one session of the form based filter.</p> + */ + [attribute, readonly] long FilterComponents; + + /** is the number of <em>disjunctive terms</em> of the filter expression represented by the form based filter. + */ + [attribute, readonly] long DisjunctiveTerms; + + /** denotes the <a href="#active_term"><em>active term</em></a> of the filter controller. + */ + [attribute] long ActiveTerm + { + set raises ( ::com::sun::star::lang::IndexOutOfBoundsException ); + }; + + /** sets a given <em>predicate expression</em> + + @param _Component + denotes the filter component whose expression is to be set. Must be greater than or equal to 0, and smaller than + <member>FilterComponents</member>. + + @param _Term + denotes the <em>disjunctive term</em> in which the expression is to be set. Must be greater than or equal to 0, + and smaller than <member>DisjunctiveTerms</member>. + + @param _PredicateExpression + denotes the <em>predicate expression</em> to set for the given filter component in the given term. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if one of the indexes is out of the allowed range + */ + void + setPredicateExpression( [in] long _Component, [in] long _Term, [in] string _PredicateExpression ) + raises( ::com::sun::star::lang::IndexOutOfBoundsException ); + + /** retrieves the filter component with the given index. + + <p>The filter control has the same control model as the control which it stands in for. Consequently, you can use this method + to obtain the database column which the filter control works on, by examining the control model's <code>BoundField</code> + property.</p> + + @param _Component + denotes the index of the filter component whose control should be obtained. Must be greater than or equal to 0, + and smaller than <member>FilterComponents</member>. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if <arg>_Component</arg> is out of the allowed range. + + @see ::com::sun::star::form::component::DataAwareControlModel::BoundField + */ + ::com::sun::star::awt::XControl + getFilterComponent( [in] long _Component ) + raises( ::com::sun::star::lang::IndexOutOfBoundsException ); + + /** retrieves the entirety of the <em>predicate expressions</em> represented by the filter controller. + + <p>Each element of the returned sequence is a <em>disjunctive term</em>, having exactly <member>FilterComponents</member> + elements, which denote the single <em>predicate expressions</em> of this term.</p> + */ + sequence< sequence< string > > + getPredicateExpressions(); + + /** removes a given <em>disjunctive term</em> + + @param _Term + the index of the term to remove. Must be greater than or equal to 0, and smaller than + <member>DisjunctiveTerms</member>. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if <arg>_Term</arg> is out of the allowed range. + */ + void + removeDisjunctiveTerm( [in] long _Term ) + raises( ::com::sun::star::lang::IndexOutOfBoundsException ); + + /** appends an empty disjunctive term to the list of terms. + */ + void + appendEmptyDisjunctiveTerm(); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFilterControllerListener.idl b/offapi/com/sun/star/form/runtime/XFilterControllerListener.idl new file mode 100644 index 000000000000..c737f9b24c70 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFilterControllerListener.idl @@ -0,0 +1,85 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * +************************************************************************/ + +#ifndef __com_sun_star_form_runtime_XFilterControllerListener_idl__ +#define __com_sun_star_form_runtime_XFilterControllerListener_idl__ + +#include <com/sun/star/lang/XEventListener.idl> +#include <com/sun/star/form/runtime/FilterEvent.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** is implemented by components listening for events fired by an <type>XFilterController</type>. + + @since OpenOffice.org 3.3 +*/ +interface XFilterControllerListener : ::com::sun::star::lang::XEventListener +{ + /** is fired when a single <em>predicate expression</em> of the filter represented by the filter + controller changed. + + <p><member>FilterEvent::DisjunctiveTerm</member> is the index of the <em>disjunctive term</em> in which the + expression changed. This usually equals <member>XFilterController::ActiveTerm</member>.</p> + + <p><member>FilterEvent::FilterComponent</member> denotes the index of the filter component whose + <em>predicate expression</em> changed.</p> + + <p><member>FilterEvent::PredicateExpression</member> is the new <em>predicate expressions</em>.</p> + */ + void predicateExpressionChanged( [in] FilterEvent _Event ); + + /** is fired when a <em>disjunctive term</em> was removed from the filter of the filter controller. + + <p><member>FilterEvent::DisjunctiveTerm</member> is the index of the <em>disjunctive term</em> which was + removed.</p> + + <p><member>FilterEvent::FilterComponent</member> and <member>FilterEvent::PredicateExpression</member> are not + used for this event type.</p> + */ + void disjunctiveTermRemoved( [in] FilterEvent _Event ); + + /** is fired when a <em>disjunctive term</em> was added to the filter of the filter controller. + + <p><member>FilterEvent::DisjunctiveTerm</member> is the index of the <em>disjunctive term</em> which was + added.</p> + + <p><member>FilterEvent::FilterComponent</member> and <member>FilterEvent::PredicateExpression</member> are not + used for this event type.</p> + */ + void disjunctiveTermAdded( [in] FilterEvent _Event ); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFormController.idl b/offapi/com/sun/star/form/runtime/XFormController.idl new file mode 100644 index 000000000000..983b0bd61f07 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFormController.idl @@ -0,0 +1,374 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * +************************************************************************/ + +#ifndef __offapi_com_sun_star_form_runtime_XFormController_idl__ +#define __offapi_com_sun_star_form_runtime_XFormController_idl__ + +#include <com/sun/star/awt/XTabController.idl> +#include <com/sun/star/container/XChild.idl> +#include <com/sun/star/lang/XComponent.idl> +#include <com/sun/star/container/XIndexAccess.idl> +#include <com/sun/star/container/XEnumerationAccess.idl> +#include <com/sun/star/util/XModifyBroadcaster.idl> +#include <com/sun/star/util/XModeSelector.idl> +#include <com/sun/star/form/XConfirmDeleteBroadcaster.idl> +#include <com/sun/star/sdb/XSQLErrorBroadcaster.idl> +#include <com/sun/star/sdb/XRowSetApproveBroadcaster.idl> +#include <com/sun/star/form/XDatabaseParameterBroadcaster2.idl> +#include <com/sun/star/form/XFormControllerListener.idl> +#include <com/sun/star/task/XInteractionHandler.idl> +#include <com/sun/star/lang/IllegalArgumentException.idl> +#include <com/sun/star/form/runtime/XFilterController.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +interface XFormOperations; +interface XFormControllerContext; + +//============================================================================= + +/** specifies a component controlling the interaction between the user and form functionality. + + <p>As soon as a form (containing controls) is to be presented to the user, + there is a need for an instance controlling the user interaction.<br/> + Such a <code>FormController</code> is responsible for dialog processing, + like controlling the tab order and the grouping of controls.</p> + + <p>As a form may contain one or many subforms, a <type>FormController</type> may + contain one or more other <type>FormController</type>s, so the form model structure or hierarchy + is reflected in the structure of <type>FormController</type>s. That is, retrieving the parent of + the model of a controller will give you the same object as retrieving the model of the parent of + the controller. Similarly, retrieving the model of the <code>n</code><sup>th</sup> child of + a controller gives you the same object as retrieving the <code>n</code><sup>th</sup> child of + the model of the controller.</p> + + <p>A controller is called <em>active</em> if one of the controls it is responsible for has the focus, + else inactive. To be notified whenever this activation state of a given controller changes, you can + add listeners.</p> + + <p>This interface supersedes the <type scope="com::sun::star::form">FormController</type>.</p> + + <h3>Responsibilities</h3> + <p>A <type>FormController</type> is responsible for a <type scope="com::sun::star::awt">UnoControlContainer</type>, + and all controls therein.</p> + + <p>Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form + contains controls bound to a database, or to an external validator, then the form controller will + check their current value when the current record is to be saved to the database.</p> + + <p>First, it will check whether any controls with an external validator exist. If so, those validators + will be asked to validate the current control content. If this fails, the message provided by the validator + is displayed to the user, the control is focused, and the update of the record is vetoed.</p> + + <p>Second, the controls are examined for NULL values. If a control is bound to a database field which + is declared to be <code>NOT NULL</code>, no auto-increment field, but still <NULL/>, then an error + message is shown to the user saying that input is required, the respective control is focused, and + the update of the record is vetoed.</p> + + <p>Note that you can precent the second check - for database fields containing <NULL/> values - on + a per-form and a per-database basis.<br/> + For the former, you need to add a boolean property <code>FormsCheckRequiredFields</code> to the form + (aka the <code>FormController</code>'s model), using its + <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member> method, with a value + of <FALSE/>.<br/> + For the latter, you need to set the respective property of the data source's <code>Settings</code> + (also named <code>FormsCheckRequiredFields</code>) to <FALSE/>.</p> + + <p>Alternatively, you can prevent the check on a per-control basis, using the + <member>DataAwareControlModel::InputRequired</member> property of a single control model.</p> + + <p>If a control which the controller is responsible for supports the <type scope="com::sun::star::frame">XDispatchProviderInterception</type> + interface, the controller registers a dispatch interceptor. Then, the control can try to delegate part of its + functionality to the controller by querying the dispatch interceptor for it.</p> + + <p>Below, there's a list of URLs which have a defined meaning - if an implementation supports one of them, + there must be a guaranteed semantices. However, concrete implementations may support an arbitrary sub or super + set of these URLs.</p> + + <p>In general, all URLs start with the same prefix, namely <em>.uno:FormController/</em>. To this, a suffix is + appended which describes the requested functionality.<br/> + Example: The URL suffix for deleting the current record is <em>deleteRecord</em>, so the complete URL for + requesting a dispatcher for this functionality is <em>.uno:FormController/deleteRecord</em>.</p> + + <p>Some URLs may require parameters. For this, the sequence of <type scope="com::sun::star::beans">PropertyValue</type>s + passed to the <member scope="com::sun::star::frame">XDispatch::dispatch</member> call is used - every property value is + used as one named parameter.</p> + + <p>For all URLs, interested parties can register as status listeners (<type scope="com::sun::star::frame">XStatusListener</type>) + at the dispatchers, and be notified whenever the functionality associated with the URL becomes enabled or + disabled.<br/> + For instance, the URL with the suffix <em>moveToFirst</em> is associated with moving the form to the first + record, and it will be disabled in case the form is already positioned on the first record.</p> + + <table style="width:100%;" border="0" cellpadding="2" cellspacing="2"><tbody> + + <tr style="vertical-align: top;"> + <td><b>URL suffix</b></td> + <td><b>functionality</b></td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>positionForm</em></td> + <td>positions the form on a record given by absolute number.<br/> + There's one parameter for this functionality, named <em>Position</em>, which must be a long + value specifying the absolute position to which the form should be moved</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>RecordCount</em></td> + <td>This is a passive functionality: It cannot be dispatched, instead, interested parties may + use the dispatcher to add as <type scope="com::sun::star::frame">XStatusListener</type>, and be + notified when the record count changes.<br/> + The status value which is being notified (<member scope="com::sun::star::frame">FeatureStateEvent::State</member>) + is a string which can be used to display the record count. In particular, if the record count is not yet known + (<member scope="com::sun::star::sdb">RowSet::IsRowCountFinal</member> is <FALSE/>), this is indicated in the + string, too.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToFirst</em></td> + <td>moves the form to the first record</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToPrev</em></td> + <td>moves the form to the record preceding the current one</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToNext</em></td> + <td>moves the form to the record after the current one</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToLast</em></td> + <td>moves the form to the last record</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>moveToNew</em></td> + <td>moves the form to the virtual "insert row", where new records can be inserted</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>saveRecord</em></td> + <td>Commits any potentially pending changes in the current control, and saves the current record to + the database, or inserts a new record if the form is currently positioned on the virtual insertion row.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>undoRecord</em></td> + <td>reverts the changes done to the current record. Basically, this means refreshing the + current row from the database, and updating all controls with the new content.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>deleteRecord</em></td> + <td>deletes the current record, after asking the user for confirmation.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>refreshForm</em></td> + <td>reloads the complete form. After this, the form is positioned on the first record</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>sortUp</em></td> + <td>Adds an order clause to the form, to sort it ascending by the field which the current control is bound to, + and then reloads the form.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>sortDown</em></td> + <td>Adds an order clause to the form, to sort it descending by the field which the current control is bound to, + and then reloads the form.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>sort</em></td> + <td>opens an dialog, which allows the user to manipulate the current sorting order of the form. If the dialog + is closed with OK, the form is reloaded after setting the new sorting order.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>autoFilter</em></td> + <td>creates, from the current control, a filter for the form. This is, if the current control is bound to + the field, say, "customer", and contains the value "Furs, Inc.", then a filter "customer = 'Furs, Inc.'" + is created and set at the form. After this, the form is reloaded.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>filter</em></td> + <td>opens an dialog, which allows the user to manipulate the current filter of the form. If the dialog + is closed with OK, the form is reloaded after setting the new filter.</td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>applyFilter</em></td> + <td><p>Toggles the <member scope="com::sun::star::sdb">RowSet::ApplyFilter</member> property + of the form.</p> + <p>Additionally, status listeners will be provided with the current (boolean) state of this property + in the <member scope="com::sun::star::frame">FeatureStateEvent::State</member> member of the event + notified by the dispatcher.</p></td> + </tr> + + <tr style="vertical-align: top;"> + <td><em>removeFilterOrder</em></td> + <td>completely removes any filter and sorting order from the form, and reloads it.</td> + </tr> + + </tbody></table> + + @see ::com::sun::star::form::component:Form + @see ::com::sun::star::form::binding::BindableControlModel + @see ::com::sun::star::sdb::DataSource::Settings + + @since OpenOffice.org 3.3 + */ +interface XFormController +{ + /** is used for tab controlling and grouping of the controls. + + <p>The model obtained via <member scope="com::sun::star::awt">XTabController::getModel</member> is the form for which the + controller is responsible.</p> + */ + interface ::com::sun::star::awt::XTabController; + + /** allows access to the parent controller. + */ + interface ::com::sun::star::container::XChild; + + /** allows access to the sub controllers. + */ + interface ::com::sun::star::container::XIndexAccess; + + /** allows enumerating sub controllers + */ + interface ::com::sun::star::container::XEnumerationAccess; + + /** allows life time control of the controller. + */ + interface ::com::sun::star::lang::XComponent; + + /** allows to register as listener for modifications in the controls which the controller is responsible + for. + */ + interface ::com::sun::star::util::XModifyBroadcaster; + + /** used to notify deletions of data in the form before they happen. + + <p>A form controller listens for deletion events at the form it is responsible for. If and only if no + <type scope="com::sun::star::form">XConfirmDeleteListener</type> is registered at + the controller, it uses an own dialog to ask the user for confirmation.</p> + */ + interface ::com::sun::star::form::XConfirmDeleteBroadcaster; + + /** is used to notify errors which happen in the form the controller is responsible for. + + <p>A form controller listens for error events at the form it is responsible for. If and only if no + <type scope="com::sun::star::sdb">XSQLErrorListener</type> is registered at the controller, it + uses an own dialog to notify the user of the error.</p> + + */ + interface ::com::sun::star::sdb::XSQLErrorBroadcaster; + + /** is used for multiplexing row set events happening on the form which the controller is responsible for. + */ + interface ::com::sun::star::sdb::XRowSetApproveBroadcaster; + + /** is used broadcasting parameter events in the form. + + <p>A form controller listens for parameter events at the form it is responsible for. If and only if no + <type scope="com::sun::star::form">XDatabaseParameterListener</type> is registered at the controller, it + uses an own dialog to ask the user for parameter values.</p> + */ + interface ::com::sun::star::form::XDatabaseParameterBroadcaster2; + + /** allows switching the form controller to different operation modes. + + <a name="mode_selector"></a> + <p>The two modes usually (but not necessarily) supported by a form controller are the <code>DataMode</code> + and the <code>FilterMode</code>, where the former is the usual modus operandi for displaying and modifying + data, and the latter is a special mode to enter a filter for the database form which the controller is + responsible for.</p> + */ + interface ::com::sun::star::util::XModeSelector; + + /** allows controlling the filter mode. + + <p>If the form controller supports a <a href="#mode_selector">form based filter mode</a>, then it shall also + support the <type>XFilterController</type> interface, which allows controlling this mode.</p> + */ + [optional] interface XFilterController; + + /** denotes the instance which is used to implement operations on the form which the controller + works for. + + <p>This instance can be used, for instance, to determine the current state of certain form features.</p> + */ + [attribute, readonly] XFormOperations FormOperations; + + /** provicdes access to the currently active control + */ + [attribute, readonly] ::com::sun::star::awt::XControl CurrentControl; + + /** allows to delegate certain tasks to the context of the form controller + */ + [attribute] XFormControllerContext Context; + + /** used (if not <NULL/>) for user interactions triggered by the form controller. + */ + [attribute] ::com::sun::star::task::XInteractionHandler InteractionHandler; + + /** adds the specified listener to receive notifications whenever the activation state of + the controller changes. + */ + void addActivateListener( [in] ::com::sun::star::form::XFormControllerListener _Listener ); + + /** removes the specified listener from the list of components to receive notifications whenever the activation + state of the controller changes. + */ + void removeActivateListener( [in] ::com::sun::star::form::XFormControllerListener _Listener ); + + /** adds a controller to the list of child controllers + @throws ::com::sun::star::lang::IllegalArgumentException + if the given controller is <NULL/>, or cannot rightfully be a child controller. Since controllers + mirror the hierarchy of the forms the are responsible for, this means that the form of the given + child controller must be a child of the controller at which the method is invoked. + */ + void addChildController( [in] XFormController _ChildController ) + raises ( ::com::sun::star::lang::IllegalArgumentException ); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFormControllerContext.idl b/offapi/com/sun/star/form/runtime/XFormControllerContext.idl new file mode 100644 index 000000000000..434faba18288 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFormControllerContext.idl @@ -0,0 +1,58 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * +************************************************************************/ + +#ifndef __offapi_com_sun_star_form_runtime_XFormControllerContext_idl__ +#define __offapi_com_sun_star_form_runtime_XFormControllerContext_idl__ + +#include <com/sun/star/awt/XControl.idl> + +//============================================================================= + +module com { module sun { module star { module form { module runtime { + +//============================================================================= + +/** provides a context for a <type>FormController</type> + +<p>A <type>FormController</type> knows about the controls it is responsible + for, and about the control container which those controls live in. However, it doesn't know + about a possible larger context, like a scrollable view which the controls are embedded into. + To compensate this, it can be provided a <code>XFormControllerContext</code>.</p> + */ +interface XFormControllerContext +{ + /** ensures the given control is visible, by scrolling the view if necessary. + */ + void makeVisible( [in] ::com::sun::star::awt::XControl _Control ); +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/form/runtime/XFormOperations.idl b/offapi/com/sun/star/form/runtime/XFormOperations.idl new file mode 100644 index 000000000000..f6f040ccc199 --- /dev/null +++ b/offapi/com/sun/star/form/runtime/XFormOperations.idl @@ -0,0 +1,284 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_form_runtime_XFormOperations_idl__ +#define __com_sun_star_form_runtime_XFormOperations_idl__ + +#ifndef __com_sun_star_form_runtime_FeatureState_idl__ +#include <com/sun/star/form/runtime/FeatureState.idl> +#endif + +#ifndef __com_sun_star_lang_XComponent_idl__ +#include <com/sun/star/lang/XComponent.idl> +#endif +#ifndef __com_sun_star_sdbc_XRowSet_idl__ +#include <com/sun/star/sdbc/XRowSet.idl> +#endif +#ifndef __com_sun_star_sdbc_XResultSetUpdate_idl__ +#include <com/sun/star/sdbc/XResultSetUpdate.idl> +#endif +#ifndef __com_sun_star_form_runtime_XFormController_idl__ +#include <com/sun/star/form/runtime/XFormController.idl> +#endif +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif +#ifndef __com_sun_star_lang_WrappedTargetException_idl__ +#include <com/sun/star/lang/WrappedTargetException.idl> +#endif +#ifndef __com_sun_star_beans_NamedValue_idl__ +#include <com/sun/star/beans/NamedValue.idl> +#endif + +//============================================================================= + +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 <member scope="com:::sun::star::sdbc">XResultSet::next</member> + 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 + <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> or + <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>, depending + on the form's <member scope="com::sun::star::sdb">RowSet::IsNew</member> 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 <type scope="com::sun::star::form">XConfirmDeleteListener</type>s + registered at the <type scope="com::sun::star::form">FormController</type> or the + <type scope="com::sun::star::form::component">DataForm</type>.</p> + + <p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code> + is for you. It provides a <member>execute</member> method, which will do all of the above + for you; plus some similar convenient wrappers for similar functionality.</p> + + @see FormFeature + + @since OpenOffice.org 2.2.0 + */ +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 determimed. Must be one of the <type>FormFeature</type> + constants.<br/> + An invalid value here will be silently ignored, and simply return a <type>FeatureState</type> + 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 <member>getState</member>, and evaluating the + <member>FeatureState::Enabled</member> member.</p> + + @param Feature + the feature whose state is to be determimed. Must be one of the <type>FormFeature</type> + 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 <type>FormFeature</type> + constants. + + @throws ::com::sun::star::lang::IllegalArgumentException + if the given Feature is unknown, not executable, or striclty requires arguments + to be executed. + + @throws ::com::sun::star::sdbc::SQLException + if a database access erorr occurs + + @throws ::com::sun::star::lang::WrappedTargetException + if an exception is caught which is no <type scope="com::sun::star::uno">RuntimeException</type> + and no <type scope="com::sun::star::sdbc">SQLException</type>. + + @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 <type>FormFeature</type> + constants. + + @param Arguments + the named arguments for the feature to execute. See the <type>FormFeature</type> 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 erorr occurs + + @throws ::com::sun::star::lang::WrappedTargetException + if an exception is caught which is no <type scope="com::sun::star::uno">RuntimeException</type> + and no <type scope="com::sun::star::sdbc">SQLException</type>. + */ + 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 erorr 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 erorr 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 es equivalent to examing the + <member scope="com::sun::star::sdb">RowSet::IsNew</member> 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 es equivalent to examing the + <member scope="com::sun::star::sdb">RowSet::IsModified</member> 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 <member>execute</member> 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 diff --git a/offapi/com/sun/star/form/runtime/makefile.mk b/offapi/com/sun/star/form/runtime/makefile.mk new file mode 100644 index 000000000000..4b34b28cae9a --- /dev/null +++ b/offapi/com/sun/star/form/runtime/makefile.mk @@ -0,0 +1,56 @@ +#************************************************************************* +# +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +# +# Copyright 2000, 2010 Oracle and/or its affiliates. +# +# OpenOffice.org - a multi-platform office productivity suite +# +# This file is part of OpenOffice.org. +# +# OpenOffice.org is free software: you can redistribute it and/or modify +# it under the terms of the GNU Lesser General Public License version 3 +# only, as published by the Free Software Foundation. +# +# OpenOffice.org is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Lesser General Public License version 3 for more details +# (a copy is included in the LICENSE file that accompanied this code). +# +# You should have received a copy of the GNU Lesser General Public License +# version 3 along with OpenOffice.org. If not, see +# <http://www.openoffice.org/license.html> +# for a copy of the LGPLv3 License. +# +#************************************************************************* + +PRJ=..$/..$/..$/..$/.. + +PRJNAME=offapi + +TARGET=cssfrunt +PACKAGE=com$/sun$/star$/form$/runtime + +# --- Settings ----------------------------------------------------- +.INCLUDE : $(PRJ)$/util$/makefile.pmk + +# ------------------------------------------------------------------------ + +IDLFILES=\ + FeatureState.idl \ + FilterEvent.idl \ + FormFeature.idl \ + FormOperations.idl \ + FormController.idl \ + XFeatureInvalidation.idl \ + XFilterController.idl \ + XFilterControllerListener.idl \ + XFormController.idl \ + XFormControllerContext.idl \ + XFormOperations.idl \ + +# ------------------------------------------------------------------ + +.INCLUDE : target.mk +.INCLUDE : $(PRJ)$/util$/target.pmk |