Adding upstream version 4:24.2.0.upstream/4%24.2.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

7 files changed, 453 insertions, 0 deletions

diff --git a/offapi/com/sun/star/form/validation/ValidatableBindableControlModel.idl b/offapi/com/sun/star/form/validation/ValidatableBindableControlModel.idl
new file mode 100644
index 0000000000..87aa9a9019
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/ValidatableBindableControlModel.idl
@@ -0,0 +1,58 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+module com {  module sun {  module star {  module form { module validation {
+
+/** specifies a control model which supports both binding to an external value supplier,
+    and to an external validator.
+
+    <p>There are two methods how the value which is represented by a control model
+    can interact with other components (well, except the trivial ones accessible
+    by using com::sun::star::beans::XPropertySet):
+    <ul><li>binding the value to an external component via com::sun::star::form::binding::XBindableValue</li>
+        <li>validating the current value by an external component, via XValidatable and XValidator</li>
+    </ul></p>
+
+    <p>The ValidatableBindableControlModel services describes the interaction of these concepts
+    for control models which support both of them.</p>
+*/
+service ValidatableBindableControlModel
+{
+    /** specifies support for validating the current value of the control
+    */
+    service ValidatableControlModel;
+
+    /** specifies support for binding the control value to an external component
+
+        <p>If a value binding is established at the control model (by using
+        com::sun::star::form::binding::XBindableValue::setValueBinding() with a non-`NULL`
+        binding), this binding is analyzed for validation support. If it is present (read: if the
+        binding also supports the XValidator interface), the binding is also
+        established as validator, as if it has been passed to XValidatable::setValidator().<br/>
+        If, while this binding is active (in both its roles as value binding and validator),
+        an attempt is made to establish another validator, this is blocked with raising a
+        com::sun::star::util::VetoException upon calling XValidatable::setValidator().</p>
+    */
+    service com::sun::star::form::binding::BindableControlModel;
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/form/validation/ValidatableControlModel.idl b/offapi/com/sun/star/form/validation/ValidatableControlModel.idl
new file mode 100644
index 0000000000..2dcf1ba7e8
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/ValidatableControlModel.idl
@@ -0,0 +1,72 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+
+module com {  module sun {  module star {  module form { module validation {
+
+/** specifies the model of a form control which supports live validation of its
+    input.
+
+    <p>Validatable control models support setting a validator with dynamic
+    validity constraints, and broadcasting changes in their value as well as the
+    validity of their value.</p>
+*/
+service ValidatableControlModel
+{
+    /** specifies the basic functionality for a form control model
+
+        <p>Via this service, validatable control models inherit the
+        com::sun::star::util::XCloneable interface.<br/>
+        If a validatable control model, at which a validator has been set (via
+        XValidatable::setValidator()), is being cloned, then the
+        validator is also set at the clone. Effectively, this means that
+        both control model instances share the same validator instance.</p>
+    */
+    service com::sun::star::form::FormControlModel;
+
+    /** enables support for validating the value of the control model
+
+        <p>Setting and retrieving the current validator of the control model is
+        possible via the XValidatable interface (which
+        XValidatableFormComponent is derived from).</p>
+
+        <p>Easy access to the current value of the control, as well as it's validity
+        (relative to the active validator), is provided by the methods XValidatableFormComponent::isValid()
+        and XValidatableFormComponent::getCurrentValue().</p>
+
+        <p>Note that the type of the value provided by XValidatableFormComponent::getCurrentValue()
+        is not specified here, but depends on the concrete control type.</p>
+    */
+    interface XValidatableFormComponent;
+
+    /** enables support for validators with dynamic validity constraints.
+
+        <p>As soon as a validator is set via XValidatable::setValidator(), the validatable
+        control model registers itself as listener. If the validity constraint of the validator
+        changes, the ValidatableControlModel re-validates its current valid, and
+        broadcasts any resulting changes to all its XFormComponentValidityListener, if
+        necessary.</p>
+    */
+    interface XValidityConstraintListener;
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/form/validation/XFormComponentValidityListener.idl b/offapi/com/sun/star/form/validation/XFormComponentValidityListener.idl
new file mode 100644
index 0000000000..5114f337f6
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/XFormComponentValidityListener.idl
@@ -0,0 +1,41 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+
+module com {  module sun {  module star {  module form { module validation {
+
+
+/** is the listener interface to be notified of changes of a XValidatableFormComponent
+*/
+interface XFormComponentValidityListener : com::sun::star::lang::XEventListener
+{
+    /** called when the validity and/or the value of the form component at which the listener
+        is registered changed.
+
+        @param Source
+            The member com::sun::star::lang::EventObject::Source
+            represents the XValidatableFormComponent whose validity, value, or text changed.
+    */
+    void    componentValidityChanged( [in] com::sun::star::lang::EventObject Source );
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/form/validation/XValidatable.idl b/offapi/com/sun/star/form/validation/XValidatable.idl
new file mode 100644
index 0000000000..be7d27f7a6
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/XValidatable.idl
@@ -0,0 +1,55 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+
+module com {  module sun {  module star {  module form { module validation {
+
+interface XValidator;
+
+
+/** specifies support for validating a component
+
+    @see XValidator
+*/
+interface XValidatable : com::sun::star::uno::XInterface
+{
+    /** sets an external instance which is able to validate the component
+
+        <p>Any previously active validator will be revoked - there can be only one!</p>
+
+        @param Validator
+            the new validator which is to be used by the component. May be `NULL`,
+            in this case only the current validator is revoked.
+
+        @throws com::sun::star::util::VetoException
+            if changing the validator is not allowed in the current component state
+     */
+    void    setValidator( [in] XValidator Validator )
+                raises ( com::sun::star::util::VetoException );
+
+    /** retrieves the external instance which is currently used to validate the component
+    */
+    XValidator
+            getValidator( );
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/form/validation/XValidatableFormComponent.idl b/offapi/com/sun/star/form/validation/XValidatableFormComponent.idl
new file mode 100644
index 0000000000..f797ef2521
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/XValidatableFormComponent.idl
@@ -0,0 +1,100 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+
+module com {  module sun {  module star {  module form { module validation {
+
+interface XFormComponentValidityListener;
+
+
+/** is a convenience interface for accessing several aspects of a form component
+    which supports validation.
+
+    <p>A validatable form component has two aspects which other parties might
+    be interested in:
+    <ul>
+        <li>The pure validity flag: Whatever the user enters in the component, this is
+        either valid (relative to the active validator), or invalid.</li>
+        <li>The current value: Even if the validity flag does not change with the user
+        input (e.g. because the user replaces one invalid value with another invalid
+        value), observers might be interested in the current value, for example to
+        include it in a feedback message to the user.</li>
+    </ul>
+    </p>
+
+    <p>An XValidatableFormComponent allows to easily access both of these aspects.</p>
+
+    <p>Note that all of the information provided at this interface can also obtained by other means,
+    but much more inconveniently.</p>
+
+    @see XValidatable
+    @see XValidator
+*/
+interface XValidatableFormComponent : XValidatable
+{
+    /** determines whether the current value of the component passed the validity test
+        at the validator.
+
+        <p>Calling this is equal to calling XValidator::isValid() with
+        the current value (see getCurrentValue()) of the component, where
+        the validator is obtained via XValidatable::getValidator().</p>
+
+        <p>If no validator has been set (XValidatable::setValidator()), this method
+        returns true.</p>
+    */
+    boolean isValid();
+
+    /** retrieves the current value of the component.
+
+        <p>The type of the current value, as well as it's semantics, depend on the service
+        implementing this interface.</p>
+
+        <p>Again, this is a convenience method. For example, for a com::sun::star::form::component::FormattedField,
+        calling this method is equivalent to retrieving the
+        com::sun::star::awt::UnoControlFormattedFieldModel::EffectiveValue.</p>
+
+        <p>If no validator has been set (XValidatable::setValidator()), the value returned
+        here is defined by the service implementing this interface.</p>
+    */
+    any getCurrentValue();
+
+    /** registers the given listener.
+
+        <p>XFormComponentValidityListeners are called whenever <em>any</em> of the aspects
+        of the validatable form component (the validity flag, or the value) changed.</p>
+
+        @throws com::sun::star::lang::NullPointerException
+            if the given listener is `NULL`
+    */
+    void    addFormComponentValidityListener( [in] XFormComponentValidityListener Listener )
+                raises( com::sun::star::lang::NullPointerException );
+
+    /** registers the given listener.
+
+        @throws com::sun::star::lang::NullPointerException
+            if the given listener is `NULL`
+    */
+    void    removeFormComponentValidityListener( [in] XFormComponentValidityListener Listener )
+                raises( com::sun::star::lang::NullPointerException );
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/form/validation/XValidator.idl b/offapi/com/sun/star/form/validation/XValidator.idl
new file mode 100644
index 0000000000..a46db60045
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/XValidator.idl
@@ -0,0 +1,85 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+
+module com {  module sun {  module star {  module form { module validation {
+
+interface XValidityConstraintListener;
+
+
+/** specifies a component able to validate (the content of) other components
+
+    <p>Validators support simple validity checks and retrieving justifications for
+    invalidity.</p>
+
+    <p>Validators may additionally support dynamic validity constraints. In such a case,
+    the validity of a given value may change, without the value changing itself.<br/>
+    To be notified about this, interested components should register as XValidityConstraintListener.
+
+    @see XValidatable
+*/
+interface XValidator : com::sun::star::uno::XInterface
+{
+    /** determines whether the given value is valid
+
+    @param Value
+        the value to check for validity
+    @return
+        `TRUE` if and only if the value is considered valid.
+    */
+    boolean isValid( [in] any Value );
+
+    /** retrieves a justification for the invalidity of the given value
+
+    @param Value
+        the value which has been recognized as being invalid
+    @return
+        a human-readable string, which explains why the given value is considered invalid.
+    */
+    string explainInvalid( [in] any Value );
+
+    /** registers the given validity listener.
+
+    <p>Usually, an XValidatable instance will also add itself as validity listener,
+    as soon as the validator is introduced to it.</p>
+
+    <p>Implementations which do not support dynamic validity constraints should simply ignore this
+    call.</p>
+
+    @throws com::sun::star::lang::NullPointerException
+        if the given listener is `NULL`
+    @see XValidityConstraintListener
+    */
+    void    addValidityConstraintListener( [in] XValidityConstraintListener Listener )
+                raises( com::sun::star::lang::NullPointerException );
+
+    /** revokes the given validity listener
+
+    @throws com::sun::star::lang::NullPointerException
+        if the given listener is `NULL`
+    @see XValidityConstraintListener
+    */
+    void    removeValidityConstraintListener( [in] XValidityConstraintListener Listener )
+                raises( com::sun::star::lang::NullPointerException );
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/form/validation/XValidityConstraintListener.idl b/offapi/com/sun/star/form/validation/XValidityConstraintListener.idl
new file mode 100644
index 0000000000..dad86ef2eb
--- /dev/null
+++ b/offapi/com/sun/star/form/validation/XValidityConstraintListener.idl
@@ -0,0 +1,42 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+
+module com {  module sun {  module star {  module form { module validation {
+
+
+/** specifies an interface for listening for changes in the validity constraints
+    represented by an XValidator.
+*/
+interface XValidityConstraintListener : com::sun::star::lang::XEventListener
+{
+    /** called when the validity constraint represented by an XValidator,
+        at which the listener is registered, changed.
+
+    @param Source
+        The event source. The member com::sun::star::lang::EventObject::Source
+        represents the validator component whose validity constraint changed.
+    */
+    void    validityConstraintChanged( [in] com::sun::star::lang::EventObject Source );
+};
+
+
+}; }; }; }; };
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */