step 2 of the FormController UNOization: UNOized all the incoming and outgoing calls, now the interface is completely UNO-based

5 files changed, 355 insertions, 3 deletions

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..8ec7b202e175
--- /dev/null
+++ b/offapi/com/sun/star/form/runtime/FilterEvent.idl
@@ -0,0 +1,64 @@
+/*************************************************************************
+* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+*
+* Copyright 2009 by Sun Microsystems, Inc.
+*
+* 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/XFilterController.idl b/offapi/com/sun/star/form/runtime/XFilterController.idl
new file mode 100644
index 000000000000..5ee9bab57540
--- /dev/null
+++ b/offapi/com/sun/star/form/runtime/XFilterController.idl
@@ -0,0 +1,180 @@
+/*************************************************************************
+* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+*
+* Copyright 2009 by Sun Microsystems, Inc.
+*
+* 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>&lt;column&gt; &lt;predicate&gt; &lt;literal&gt;</code> or of the form <code><em>&lt;column&gt;
+    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..230ba9656d81
--- /dev/null
+++ b/offapi/com/sun/star/form/runtime/XFilterControllerListener.idl
@@ -0,0 +1,84 @@
+/*************************************************************************
+* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+*
+* Copyright 2009 by Sun Microsystems, Inc.
+*
+* 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
index 9c306eeb7857..f0573383860a 100644
--- a/offapi/com/sun/star/form/runtime/XFormController.idl
+++ b/offapi/com/sun/star/form/runtime/XFormController.idl
@@ -39,6 +39,8 @@
 #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>
 
 //=============================================================================
 
@@ -244,6 +246,8 @@ interface XFormControllerContext;
     @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
 {
@@ -306,6 +310,7 @@ interface XFormController
 
     /** 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
@@ -313,6 +318,13 @@ interface XFormController
     */
     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.
 
@@ -335,12 +347,21 @@ interface XFormController
     /** adds the specified listener to receive notifications whenever the activation state of
         the controller changes.
      */
-    void addActivateListener( [in] com::sun::star::form::XFormControllerListener _Listener );
+    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 );
+    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 );
 };
 
 //=============================================================================
diff --git a/offapi/com/sun/star/form/runtime/makefile.mk b/offapi/com/sun/star/form/runtime/makefile.mk
index b13879e1f65a..97c4451edf40 100644
--- a/offapi/com/sun/star/form/runtime/makefile.mk
+++ b/offapi/com/sun/star/form/runtime/makefile.mk
@@ -42,11 +42,14 @@ PACKAGE=com$/sun$/star$/form$/runtime
 # ------------------------------------------------------------------------
 
 IDLFILES=\
-    FeatureState.idl\
+    FeatureState.idl \
+    FilterEvent.idl \
     FormFeature.idl \
     FormOperations.idl \
     FormController.idl \
     XFeatureInvalidation.idl \
+    XFilterController.idl \
+    XFilterControllerListener.idl \
     XFormController.idl \
     XFormControllerContext.idl \
     XFormOperations.idl \