110 lines
5.6 KiB
Text
110 lines
5.6 KiB
Text
/* -*- 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 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;
|
|
};
|
|
|
|
|
|
}; }; }; }; };
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|