diff options
Diffstat (limited to 'offapi/com/sun/star/form/binding/BindableDataAwareControlModel.idl')
| -rw-r--r-- | offapi/com/sun/star/form/binding/BindableDataAwareControlModel.idl | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/offapi/com/sun/star/form/binding/BindableDataAwareControlModel.idl b/offapi/com/sun/star/form/binding/BindableDataAwareControlModel.idl new file mode 100644 index 000000000..4c16e55c1 --- /dev/null +++ b/offapi/com/sun/star/form/binding/BindableDataAwareControlModel.idl @@ -0,0 +1,118 @@ +/* -*- 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 . + */ + +#ifndef __com_sun_star_form_binding_BindableDataAwareControlModel_idl__ +#define __com_sun_star_form_binding_BindableDataAwareControlModel_idl__ + +#include <com/sun/star/form/DataAwareControlModel.idl> +#include <com/sun/star/form/binding/BindableControlModel.idl> + + +module com { module sun { module star { module form { module binding { + + +/** is a specialization of the com::sun::star::form::DataAwareControlModel + which additionally supports binding to external value suppliers. + + <p>Control models usually have some kind of value property, which reflects the very current + content of the controls associated with this model. For instance, for an + com::sun::star::form::component::TextField, this would be the + com::sun::star::awt::UnoControlEditModel::Text property of the base + service. Similarly, a com::sun::star::form::component::CheckBox has + a property com::sun::star::awt::UnoControlCheckBoxModel::State, which + reflects the current check state.</p> + + <p>Usual com::sun::star::form::DataAwareControlModels can be bound to + a column of a com::sun::star::form::component::DataForm, and exchange + their content with such a column.<br/> + In particular, when the com::sun::star::form::component::DataForm + is moved to a different record, then the bound control model is updated with the value of + it's column in this particular row.<br/> + On the other hand, when any change in the control model (e.g. resulting from a user entering + data in a control associated with the control model) is committed + (com::sun::star::form::XBoundComponent::commit()), then the actual + data of the control model is written into the associated + com::sun::star::form::component::DataForm column.</p> + + <p>BindableDataAwareControlModel's additionally support an alternative value + binding, which forces them to exchange their value with another foreign instance. + In some sense, they are an abstraction of the data aware control models, which only + support a specialized, hard-coded value binding (namely the binding to a + com::sun::star::form::component::DataForm column).</p> + + <p>For this, they provide the XBindableValue interface which allows to + set an external component to exchange the value with.</p> + + <p>The following rules apply when a data aware control model is bound to an external value binding: + <ul><li><b>Priority</b><br/> + External value bindings overrule any active SQL-column binding. If an external + component is bound to a control model which currently has an active SQL binding, + this SQL binding is suspended, until the external binding is revoked. + </li> + <li><b>Activation</b><br/> + An external value binding becomes effective as soon as it is set. This is a + difference to SQL bindings, which only are effective when the parent form + of the control model is loaded (com::sun::star::form::XLoadable). + </li> + <li><b>Immediacy</b><br/> + When a BindableDataAwareControlModel is bound to an external value, + then every change in the control model's value is <em>immediately</em> reflected + in the external binding. This is a difference to SQL bindings of most + com::sun::star::form::DataAwareControlModel's, where changes + in the control model's value are only propagated to the bound column upon explicit + request via com::sun::star::form::XBoundComponent::commit().<br/> + Note that this restriction is inherited from the BindableControlModel. + </li> + <li><b>Cloning</b><br/> + com::sun::star::form::FormControlModels support cloning themselves + via the com::sun::star::util::XCloneable interface which they + inherit from the com::sun::star::awt::UnoControlModel service.<br> + When a BindableDataAwareControlModel is cloned while it has an active + external value binding, then the clone is also bound to the same binding instance.<br/> + Note that this restriction is inherited from the BindableControlModel. + </li> + </ul> + </p> + + <p>When a BindableDataAwareControlModel is being bound to an external value, + using XBindableValue::setValueBinding(), + then the control model (its value property, respectively) and the external value are + initially synchronized by setting the external value (XValueBinding::getValue()) + at the control model.</p> + +*/ +service BindableDataAwareControlModel +{ + /** specifies the functionality for binding the control model to a + column of an SQL com::sun::star::form::component::DataForm. + */ + service com::sun::star::form::DataAwareControlModel; + + /** specifies the functionality for <em>alternatively</em> binding the control model + to an external value. + */ + service BindableControlModel; +}; + + +}; }; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |