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 __com_sun_star_form_validation_XValidatableFormComponent_idl__
25#define __com_sun_star_form_validation_XValidatableFormComponent_idl__
26
27#ifndef __com_sun_star_form_validation_XValidatable_idl__
28#include <com/sun/star/form/validation/XValidatable.idl>
29#endif
30
31#ifndef __com_sun_star_lang_NoSupportException_idl__
32#include <com/sun/star/lang/NoSupportException.idl>
33#endif
34
35#ifndef __com_sun_star_lang_NullPointerException_idl__
36#include <com/sun/star/lang/NullPointerException.idl>
37#endif
38
39//=============================================================================
40
41module com {  module sun {  module star {  module form { module validation {
42
43interface XFormComponentValidityListener;
44
45//=============================================================================
46
47/** is a convenience interface for accessing several aspects of a form component
48    which supports validation.
49
50    <p>A validatable form component has two aspects which other parties might
51    be interested in:
52    <ul>
53        <li>The pure validity flag: Whatever the user enters in the component, this is
54        either valid (relative to the active validator), or invalid.</li>
55        <li>The current value: Even if the validity flag does not change with the user
56        input (e.g. because the user replaces one invalid value with another invalid
57        value), observers might be interested in the current value, for example to
58        include it in a feedback message to the user.</li>
59    </ul>
60    </p>
61
62    <p>An <type>XValidatableFormComponent</type> allows to easily access both of these aspects.</p>
63
64    <p>Note that all of the information provided at this interface can also obtained by other means,
65    but much more inconviniently.</p>
66
67    @see XValidatable
68    @see XValidator
69*/
70interface XValidatableFormComponent : XValidatable
71{
72    /** determines whether the current value of the component passed the validity test
73        at the validator.
74
75        <p>Calling this is equal to calling <member>XValidator::isValid</member> with
76        the current value (see <member>getCurrentValue</member>) of the component, where
77        the validator is obtained via <member>XValidatable::getValidator</member>.</p>
78
79        <p>If no validator has been set (<member>XValidatable::setValidator</member>), this method
80        returns true.</p>
81    */
82    boolean isValid();
83
84    /** retrieves the current value of the component.
85
86        <p>The type of the current value, as well as it's semantics, depend on the service
87        implementing this interface.</p>
88
89        <p>Again, this is a convenience method. For example, for a <type scope="com::sun::star::form::component">FormattedField</type>,
90        calling this method is equivalent to retrieving the
91        <member scope="com::sun::star::awt">UnoControlFormattedFieldModel::EffectiveValue</member>.</p>
92
93        <p>If no validator has been set (<member>XValidatable::setValidator</member>), the value returned
94        here is defined by the service implementing this interface.</p>
95    */
96    any getCurrentValue();
97
98    /** registers the given listener.
99
100        <p><type>XFormComponentValidityListener</type>s are called whenever <em>any</em> of the aspects
101        of the validatable form component (the validity flag, or the value) changed.</p>
102
103        @throws <type scope="com::sun::star::lang">NullPointerException</type>
104            if the given listener is <NULL/>
105    */
106    void    addFormComponentValidityListener( [in] XFormComponentValidityListener Listener )
107                raises( com::sun::star::lang::NullPointerException );
108
109    /** registers the given listener.
110
111        @throws <type scope="com::sun::star::lang">NullPointerException</type>
112            if the given listener is <NULL/>
113    */
114    void    removeFormComponentValidityListener( [in] XFormComponentValidityListener Listener )
115                raises( com::sun::star::lang::NullPointerException );
116};
117
118//=============================================================================
119
120}; }; }; }; };
121
122#endif
123