1*d1766043SAndrew Rist/************************************************************** 2cdf0e10cSrcweir * 3*d1766043SAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 4*d1766043SAndrew Rist * or more contributor license agreements. See the NOTICE file 5*d1766043SAndrew Rist * distributed with this work for additional information 6*d1766043SAndrew Rist * regarding copyright ownership. The ASF licenses this file 7*d1766043SAndrew Rist * to you under the Apache License, Version 2.0 (the 8*d1766043SAndrew Rist * "License"); you may not use this file except in compliance 9*d1766043SAndrew Rist * with the License. You may obtain a copy of the License at 10*d1766043SAndrew Rist * 11*d1766043SAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 12*d1766043SAndrew Rist * 13*d1766043SAndrew Rist * Unless required by applicable law or agreed to in writing, 14*d1766043SAndrew Rist * software distributed under the License is distributed on an 15*d1766043SAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16*d1766043SAndrew Rist * KIND, either express or implied. See the License for the 17*d1766043SAndrew Rist * specific language governing permissions and limitations 18*d1766043SAndrew Rist * under the License. 19*d1766043SAndrew Rist * 20*d1766043SAndrew Rist *************************************************************/ 21*d1766043SAndrew Rist 22*d1766043SAndrew Rist 23cdf0e10cSrcweir 24cdf0e10cSrcweir#ifndef __com_sun_star_form_binding_BindableDataAwareControlModel_idl__ 25cdf0e10cSrcweir#define __com_sun_star_form_binding_BindableDataAwareControlModel_idl__ 26cdf0e10cSrcweir 27cdf0e10cSrcweir#ifndef __com_sun_star_form_DataAwareControlModel_idl__ 28cdf0e10cSrcweir#include <com/sun/star/form/DataAwareControlModel.idl> 29cdf0e10cSrcweir#endif 30cdf0e10cSrcweir 31cdf0e10cSrcweir#ifndef __com_sun_star_form_binding_BindableControlModel_idl__ 32cdf0e10cSrcweir#include <com/sun/star/form/binding/BindableControlModel.idl> 33cdf0e10cSrcweir#endif 34cdf0e10cSrcweir 35cdf0e10cSrcweir//============================================================================= 36cdf0e10cSrcweir 37cdf0e10cSrcweirmodule com { module sun { module star { module form { module binding { 38cdf0e10cSrcweir 39cdf0e10cSrcweir//============================================================================= 40cdf0e10cSrcweir 41cdf0e10cSrcweir/** is a specialization of the <type scope="com::sun::star::form">DataAwareControlModel</type> 42cdf0e10cSrcweir which additionally supports binding to external value suppliers. 43cdf0e10cSrcweir 44cdf0e10cSrcweir <p>Control models usually have some kind of value property, which reflects the very current 45cdf0e10cSrcweir content of the controls associated with this model. For instance, for an 46cdf0e10cSrcweir <type scope="com::sun::star::form::component">TextField</type>, this would be the 47cdf0e10cSrcweir <member scope="com::sun::star::awt">UnoControlEditModel::Text</member> property of the base 48cdf0e10cSrcweir service. Similarily, a <type scope="com::sun::star::form::component">CheckBox</type> has 49cdf0e10cSrcweir a property <member scope="com::sun::star::awt">UnoControlCheckBoxModel::State</member>, which 50cdf0e10cSrcweir reflects the current check state.</p> 51cdf0e10cSrcweir 52cdf0e10cSrcweir <p>Usual <type scope="com::sun::star::form">DataAwareControlModel</type>s can be bound to 53cdf0e10cSrcweir a column of a <type scope="com::sun::star::form::component">DataForm</type>, and exchange 54cdf0e10cSrcweir their content with such a column.<br/> 55cdf0e10cSrcweir In particular, when the <type scope="com::sun::star::form::component">DataForm</type> 56cdf0e10cSrcweir is moved to a different record, then the bound control model is updated with the value of 57cdf0e10cSrcweir it's column in this particular row.<br/> 58cdf0e10cSrcweir On the other hand, when any change in the control model (e.g. resulting from a user entering 59cdf0e10cSrcweir data in a control associated with the control model) is committed 60cdf0e10cSrcweir (<member scope="com::sun::star::form">XBoundComponent::commit</member>), then the actual 61cdf0e10cSrcweir data of the control model is written into the associated 62cdf0e10cSrcweir <type scope="com::sun::star::form::component">DataForm</type> column.</p> 63cdf0e10cSrcweir 64cdf0e10cSrcweir <p><type>BindableDataAwareControlModel</type>'s additionally support an alternative value 65cdf0e10cSrcweir binding, which forces them to exchange their value with another foreign instance. 66cdf0e10cSrcweir In some sense, they are an abstraction of the data aware control models, which only 67cdf0e10cSrcweir support a specialized, hard-coded value binding (namely the binding to a 68cdf0e10cSrcweir <type scope="com::sun::star::form::component">DataForm</type> column).</p> 69cdf0e10cSrcweir 70cdf0e10cSrcweir <p>For this, they provide the <type>XBindableValue</type> interface which allows to 71cdf0e10cSrcweir set an external component to exchange the value with.</p> 72cdf0e10cSrcweir 73cdf0e10cSrcweir <p>The following rules apply when a data aware control model is bound to an external value binding: 74cdf0e10cSrcweir <ul><li><b>Priority</b><br/> 75cdf0e10cSrcweir External value bindings overrule any active SQL-column binding. If an external 76cdf0e10cSrcweir component is bound to a control model which currently has an active SQL binding, 77cdf0e10cSrcweir this SQL binding is suspended, until the external binding is revoked. 78cdf0e10cSrcweir </li> 79cdf0e10cSrcweir <li><b>Activation</b><br/> 80cdf0e10cSrcweir An external value binding becomes effective as soon as it is set. This is a 81cdf0e10cSrcweir difference to SQL bindings, which only are effective when the parent form 82cdf0e10cSrcweir of the control model is loaded (<type scope="com::sun::star::form">XLoadable</type>). 83cdf0e10cSrcweir </li> 84cdf0e10cSrcweir <li><b>Immediacy</b><br/> 85cdf0e10cSrcweir When a <type>BindableDataAwareControlModel</type> is bound to an external value, 86cdf0e10cSrcweir then every change in the control model's value is <em>immediately</em> reflected 87cdf0e10cSrcweir in the external binding. This is a difference to SQL bindings of most 88cdf0e10cSrcweir <type scope="com::sun::star::form">DataAwareControlModel</type>'s, where changes 89cdf0e10cSrcweir in the control model's value are only propagated to the bound column upon explicit 90cdf0e10cSrcweir request via <member scope="com::sun::star::form">XBoundComponent::commit</member>.<br/> 91cdf0e10cSrcweir Note that this restriction is inherited from the <type>BindableControlModel</type>. 92cdf0e10cSrcweir </li> 93cdf0e10cSrcweir <li><b>Cloning</b><br/> 94cdf0e10cSrcweir <type scope="com::sun::star::form">FormControlModel</type>s support cloning themself 95cdf0e10cSrcweir via the <type scope="com::sun::star::util">XCloneable</type> interface which they 96cdf0e10cSrcweir inherit from the <type scope="com::sun::star::awt">UnoControlModel</type> service.</br> 97cdf0e10cSrcweir When a <type>BindableDataAwareControlModel</type> is cloned while it has an active 98cdf0e10cSrcweir external value binding, then the clone is also bound to the same binding instance.<br/> 99cdf0e10cSrcweir Note that this restriction is inherited from the <type>BindableControlModel</type>. 100cdf0e10cSrcweir </li> 101cdf0e10cSrcweir </ul> 102cdf0e10cSrcweir </p> 103cdf0e10cSrcweir 104cdf0e10cSrcweir <p>When a <type>BindableDataAwareControlModel</type> is being bound to an external value, 105cdf0e10cSrcweir using <member>XBindableValue::setValueBinding</member>, 106cdf0e10cSrcweir then the control model (it's value property, respectively) and the external value are 107cdf0e10cSrcweir initially synchronized by setting the external value (<member>XValueBinding::getValue</member>) 108cdf0e10cSrcweir at the control model.</p> 109cdf0e10cSrcweir 110cdf0e10cSrcweir*/ 111cdf0e10cSrcweirservice BindableDataAwareControlModel 112cdf0e10cSrcweir{ 113cdf0e10cSrcweir /** specifies the functionality for binding the control model to a 114cdf0e10cSrcweir column of an SQL <type scope="com::sun::star::form::component">DataForm</type>. 115cdf0e10cSrcweir */ 116cdf0e10cSrcweir service com::sun::star::form::DataAwareControlModel; 117cdf0e10cSrcweir 118cdf0e10cSrcweir /** specifies the functionality for <em>alternatively</em> binding the control model 119cdf0e10cSrcweir to an external value. 120cdf0e10cSrcweir */ 121cdf0e10cSrcweir service BindableControlModel; 122cdf0e10cSrcweir}; 123cdf0e10cSrcweir 124cdf0e10cSrcweir//============================================================================= 125cdf0e10cSrcweir 126cdf0e10cSrcweir}; }; }; }; }; 127cdf0e10cSrcweir 128cdf0e10cSrcweir#endif 129