1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27
28#ifndef __com_sun_star_form_binding_BindableDataAwareControlModel_idl__
29#define __com_sun_star_form_binding_BindableDataAwareControlModel_idl__
30
31#ifndef __com_sun_star_form_DataAwareControlModel_idl__
32#include <com/sun/star/form/DataAwareControlModel.idl>
33#endif
34
35#ifndef __com_sun_star_form_binding_BindableControlModel_idl__
36#include <com/sun/star/form/binding/BindableControlModel.idl>
37#endif
38
39//=============================================================================
40
41module com {  module sun {  module star {  module form { module binding {
42
43//=============================================================================
44
45/** is a specialization of the <type scope="com::sun::star::form">DataAwareControlModel</type>
46    which additionally supports binding to external value suppliers.
47
48    <p>Control models usually have some kind of value property, which reflects the very current
49    content of the controls associated with this model. For instance, for an
50    <type scope="com::sun::star::form::component">TextField</type>, this would be the
51    <member scope="com::sun::star::awt">UnoControlEditModel::Text</member> property of the base
52    service. Similarily, a <type scope="com::sun::star::form::component">CheckBox</type> has
53    a property <member scope="com::sun::star::awt">UnoControlCheckBoxModel::State</member>, which
54    reflects the current check state.</p>
55
56    <p>Usual <type scope="com::sun::star::form">DataAwareControlModel</type>s can be bound to
57    a column of a <type scope="com::sun::star::form::component">DataForm</type>, and exchange
58    their content with such a column.<br/>
59    In particular, when the <type scope="com::sun::star::form::component">DataForm</type>
60    is moved to a different record, then the bound control model is updated with the value of
61    it's column in this particular row.<br/>
62    On the other hand, when any change in the control model (e.g. resulting from a user entering
63    data in a control associated with the control model) is committed
64    (<member scope="com::sun::star::form">XBoundComponent::commit</member>), then the actual
65    data of the control model is written into the associated
66    <type scope="com::sun::star::form::component">DataForm</type> column.</p>
67
68    <p><type>BindableDataAwareControlModel</type>'s additionally support an alternative value
69    binding, which forces them to exchange their value with another foreign instance.
70    In some sense, they are an abstraction of the data aware control models, which only
71    support a specialized, hard-coded value binding (namely the binding to a
72    <type scope="com::sun::star::form::component">DataForm</type> column).</p>
73
74    <p>For this, they provide the <type>XBindableValue</type> interface which allows to
75    set an external component to exchange the value with.</p>
76
77    <p>The following rules apply when a data aware control model is bound to an external value binding:
78        <ul><li><b>Priority</b><br/>
79                External value bindings overrule any active SQL-column binding. If an external
80                component is bound to a control model which currently has an active SQL binding,
81                this SQL binding is suspended, until the external binding is revoked.
82            </li>
83            <li><b>Activation</b><br/>
84                An external value binding becomes effective as soon as it is set. This is a
85                difference to SQL bindings, which only are effective when the parent form
86                of the control model is loaded (<type scope="com::sun::star::form">XLoadable</type>).
87            </li>
88            <li><b>Immediacy</b><br/>
89                When a <type>BindableDataAwareControlModel</type> is bound to an external value,
90                then every change in the control model's value is <em>immediately</em> reflected
91                in the external binding. This is a difference to SQL bindings of most
92                <type scope="com::sun::star::form">DataAwareControlModel</type>'s, where changes
93                in the control model's value are only propagated to the bound column upon explicit
94                request via <member scope="com::sun::star::form">XBoundComponent::commit</member>.<br/>
95                Note that this restriction is inherited from the <type>BindableControlModel</type>.
96            </li>
97            <li><b>Cloning</b><br/>
98                <type scope="com::sun::star::form">FormControlModel</type>s support cloning themself
99                via the <type scope="com::sun::star::util">XCloneable</type> interface which they
100                inherit from the <type scope="com::sun::star::awt">UnoControlModel</type> service.</br>
101                When a <type>BindableDataAwareControlModel</type> is cloned while it has an active
102                external value binding, then the clone is also bound to the same binding instance.<br/>
103                Note that this restriction is inherited from the <type>BindableControlModel</type>.
104            </li>
105        </ul>
106    </p>
107
108    <p>When a <type>BindableDataAwareControlModel</type> is being bound to an external value,
109    using <member>XBindableValue::setValueBinding</member>,
110    then the control model (it's value property, respectively) and the external value are
111    initially synchronized by setting the external value (<member>XValueBinding::getValue</member>)
112    at the control model.</p>
113
114*/
115service BindableDataAwareControlModel
116{
117    /** specifies the functionality for binding the control model to a
118        column of an SQL <type scope="com::sun::star::form::component">DataForm</type>.
119    */
120	service com::sun::star::form::DataAwareControlModel;
121
122    /** specifies the functionality for <em>alternatively</em> binding the control model
123        to an external value.
124    */
125    service BindableControlModel;
126};
127
128//=============================================================================
129
130}; }; }; }; };
131
132#endif
133