1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24#ifndef __offapi_com_sun_star_form_runtime_XFilterController_idl__ 25#define __offapi_com_sun_star_form_runtime_XFilterController_idl__ 26 27#include <com/sun/star/awt/XControl.idl> 28#include <com/sun/star/lang/IndexOutOfBoundsException.idl> 29 30//============================================================================= 31 32module com { module sun { module star { module form { module runtime { 33 34//============================================================================= 35 36interface XFilterControllerListener; 37 38/** provides access to a form based filter for a database form 39 40 <p>In a form based filter, form controls bound to a searchable database field are replaced with a control 41 which allows entering a search expression. This so-called <em>predicate expression</em> is basically a part of an 42 SQL <code>WHERE</code> clause, but without the the part denoting the database column. For instance, if you 43 have a form control bound to a table column named <code>Name</code>, then entering the string 44 <q>LIKE '%Smith%'</q> effectively consitutes a SQL <code>WHERE</code> clause <code>"Name" LIKE '%Smith%'</code>.</p> 45 46 <p>In the actual document view, there are usually some relaxations to this. For instance, keywords such as 47 <code>LIKE</code> might be localized, according to OpenOffice.org's UI locale. Also, for an equality criterion, 48 the equality sign <code>=</code> is usually omitted. However, this interface here provides programmatic access 49 to the form based filter, so those relaxations are not considered here.</p> 50 51 <p>The filter maintained by a filter controller is, logically, a disjunctive normal form of an SQL <code>WHERE</code> 52 class. That is, it is a disjunction of <em>m</em> terms, where each term is a conjunction of <em>n</em> clauses 53 of the form <code><column> <predicate> <literal></code> or of the form <code><em><column> 54 IS [NOT] NULL</em></code>.</p> 55 56 <p><em>n</em> equals the number of filter controls which the filter controller is responsible for. This number 57 doesn't change during one session of the form based filter. On the other hand, <em>m</em>, the number of disjunctive 58 terms, is dynamic.</p> 59 60 <a name="active_term"></a> 61 <p>With the above, there are potentially <em>m * n</em> <em>predicate expressions</em> (though usually only a fraction 62 of those will actually exist). Since in a form based filter, there are only <em>n</em> filter controls, and each 63 filter control displays exactly one <em>predicate expression</em>, this means that only a part of the complete 64 filter can be displayed, in particular, only one <em>disjunctive term</em> can be displayed at a time. Thus, 65 the filter controller knows the concept of an <em>active term</em>, denoted by the <member>ActiveTerm</member> 66 attribute, controls which of the terms is currently displayed in the form controls.</p> 67 68 @see XFormController 69 @see com::sun::star::sdbc::XResultSetMetaData::isSearchable 70 @see com::sun::star::sdb::XSingleSelectQueryAnalyzer::getStructuredFilter 71 @see com::sun::star::sdb::SQLFilterOperator 72 73 @since OpenOffice 3.3 74 */ 75interface XFilterController 76{ 77 /** registers a listener to be notified of certain changes in the form based filter. 78 79 <p>Registering the same listener multiple times results in multiple notifications of the same event, 80 and also requires multiple revocations of the listener. 81 */ 82 void addFilterControllerListener( [in] XFilterControllerListener _Listener ); 83 84 /** revokes a listener which was previously registered to be notified of certain changes in the form based filter. 85 */ 86 void removeFilterControllerListener( [in] XFilterControllerListener _Listener ); 87 88 /** is the number of <em>filter components</em>, or filter controls, which the filter controller is responsible 89 for. 90 91 <p>This number is constant during one session of the form based filter.</p> 92 */ 93 [attribute, readonly] long FilterComponents; 94 95 /** is the number of <em>disjunctive terms</em> of the filter expression represented by the form based filter. 96 */ 97 [attribute, readonly] long DisjunctiveTerms; 98 99 /** denotes the <a href="#active_term"><em>active term</em></a> of the filter controller. 100 */ 101 [attribute] long ActiveTerm 102 { 103 set raises ( ::com::sun::star::lang::IndexOutOfBoundsException ); 104 }; 105 106 /** sets a given <em>predicate expression</em> 107 108 @param _Component 109 denotes the filter component whose expression is to be set. Must be greater than or equal to 0, and smaller than 110 <member>FilterComponents</member>. 111 112 @param _Term 113 denotes the <em>disjunctive term</em> in which the expression is to be set. Must be greater than or equal to 0, 114 and smaller than <member>DisjunctiveTerms</member>. 115 116 @param _PredicateExpression 117 denotes the <em>predicate expression</em> to set for the given filter component in the given term. 118 119 @throws ::com::sun::star::lang::IndexOutOfBoundsException 120 if one of the indexes is out of the allowed range 121 */ 122 void 123 setPredicateExpression( [in] long _Component, [in] long _Term, [in] string _PredicateExpression ) 124 raises( ::com::sun::star::lang::IndexOutOfBoundsException ); 125 126 /** retrieves the filter component with the given index. 127 128 <p>The filter control has the same control model as the control which it stands in for. Consequently, you can use this method 129 to obtain the database column which the filter control works on, by examining the control model's <code>BoundField</code> 130 property.</p> 131 132 @param _Component 133 denotes the index of the filter component whose control should be obtained. Must be greater than or equal to 0, 134 and smaller than <member>FilterComponents</member>. 135 136 @throws ::com::sun::star::lang::IndexOutOfBoundsException 137 if <arg>_Component</arg> is out of the allowed range. 138 139 @see ::com::sun::star::form::component::DataAwareControlModel::BoundField 140 */ 141 ::com::sun::star::awt::XControl 142 getFilterComponent( [in] long _Component ) 143 raises( ::com::sun::star::lang::IndexOutOfBoundsException ); 144 145 /** retrieves the entirety of the <em>predicate expressions</em> represented by the filter controller. 146 147 <p>Each element of the returned sequence is a <em>disjunctive term</em>, having exactly <member>FilterComponents</member> 148 elements, which denote the single <em>predicate expressions</em> of this term.</p> 149 */ 150 sequence< sequence< string > > 151 getPredicateExpressions(); 152 153 /** removes a given <em>disjunctive term</em> 154 155 @param _Term 156 the index of the term to remove. Must be greater than or equal to 0, and smaller than 157 <member>DisjunctiveTerms</member>. 158 159 @throws ::com::sun::star::lang::IndexOutOfBoundsException 160 if <arg>_Term</arg> is out of the allowed range. 161 */ 162 void 163 removeDisjunctiveTerm( [in] long _Term ) 164 raises( ::com::sun::star::lang::IndexOutOfBoundsException ); 165 166 /** appends an empty disjunctive term to the list of terms. 167 */ 168 void 169 appendEmptyDisjunctiveTerm(); 170}; 171 172//============================================================================= 173 174}; }; }; }; }; 175 176//============================================================================= 177 178#endif 179