1d1766043SAndrew Rist/************************************************************** 2*0c855477Smseidel * 3d1766043SAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 4d1766043SAndrew Rist * or more contributor license agreements. See the NOTICE file 5d1766043SAndrew Rist * distributed with this work for additional information 6d1766043SAndrew Rist * regarding copyright ownership. The ASF licenses this file 7d1766043SAndrew Rist * to you under the Apache License, Version 2.0 (the 8d1766043SAndrew Rist * "License"); you may not use this file except in compliance 9d1766043SAndrew Rist * with the License. You may obtain a copy of the License at 10*0c855477Smseidel * 11d1766043SAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 12*0c855477Smseidel * 13d1766043SAndrew Rist * Unless required by applicable law or agreed to in writing, 14d1766043SAndrew Rist * software distributed under the License is distributed on an 15d1766043SAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16d1766043SAndrew Rist * KIND, either express or implied. See the License for the 17d1766043SAndrew Rist * specific language governing permissions and limitations 18d1766043SAndrew Rist * under the License. 19*0c855477Smseidel * 20d1766043SAndrew Rist *************************************************************/ 21d1766043SAndrew Rist 22d1766043SAndrew Rist 23*0c855477Smseidel#ifndef __com_sun_star_form_DataAwareControlModel_idl__ 24*0c855477Smseidel#define __com_sun_star_form_DataAwareControlModel_idl__ 25*0c855477Smseidel 26*0c855477Smseidel#ifndef __com_sun_star_form_FormControlModel_idl__ 27*0c855477Smseidel#include <com/sun/star/form/FormControlModel.idl> 28*0c855477Smseidel#endif 29*0c855477Smseidel 30*0c855477Smseidel#ifndef __com_sun_star_form_XBoundComponent_idl__ 31*0c855477Smseidel#include <com/sun/star/form/XBoundComponent.idl> 32*0c855477Smseidel#endif 33*0c855477Smseidel 34*0c855477Smseidel#ifndef __com_sun_star_form_XLoadListener_idl__ 35*0c855477Smseidel#include <com/sun/star/form/XLoadListener.idl> 36*0c855477Smseidel#endif 37*0c855477Smseidel 38*0c855477Smseidel#ifndef __com_sun_star_form_XReset_idl__ 39*0c855477Smseidel#include <com/sun/star/form/XReset.idl> 40*0c855477Smseidel#endif 41*0c855477Smseidel 42*0c855477Smseidel#ifndef __com_sun_star_beans_XPropertySet_idl__ 43*0c855477Smseidel#include <com/sun/star/beans/XPropertySet.idl> 44*0c855477Smseidel#endif 45*0c855477Smseidel 46*0c855477Smseidel//============================================================================= 47*0c855477Smseidel 48*0c855477Smseidel module com { module sun { module star { module form { 49*0c855477Smseidel 50*0c855477Smseidel//============================================================================= 51*0c855477Smseidel 52cdf0e10cSrcweir/** is an abstract service for specialized <type>FormControlModel</type>s 53cdf0e10cSrcweir which are data aware and thus can be bound to a data source. 54cdf0e10cSrcweir 55*0c855477Smseidel <p>The connection between a data-aware control model and a form whose data the 56cdf0e10cSrcweir control should display is made by parentship relations. The parent of a data-aware 57cdf0e10cSrcweir control model (see <type scope="com::sun::star::container">XChild</type>, inherited 58cdf0e10cSrcweir via the <type>FormControlModel</type> and <type>FormComponent</type> services) has 59cdf0e10cSrcweir always to be a <type scope="com::sun::star::form::component">DataForm</type>.</p> 60cdf0e10cSrcweir */ 61cdf0e10cSrcweirpublished service DataAwareControlModel 62*0c855477Smseidel{ 63*0c855477Smseidel service com::sun::star::form::FormControlModel; 64*0c855477Smseidel 65cdf0e10cSrcweir /** makes it possible to transfer the data of the model to the connected data field. 66cdf0e10cSrcweir <p> 67cdf0e10cSrcweir This interface is optional, if a component doesn't support it, it has to forward 68*0c855477Smseidel the changes of its value to the field it is connected to immediately (means whenever a user 69*0c855477Smseidel interaction changes its content). 70cdf0e10cSrcweir </p> 71cdf0e10cSrcweir */ 72*0c855477Smseidel [optional] interface com::sun::star::form::XBoundComponent; 73*0c855477Smseidel 74*0c855477Smseidel 75cdf0e10cSrcweir /** must be implemented in order to recognize when the containing form of the model connects 76*0c855477Smseidel to its data source (loads its data). After loading the form, the model may bind to its 77cdf0e10cSrcweir related field source.<br/> 78cdf0e10cSrcweir This interface will seldom be used directly from outside. 79cdf0e10cSrcweir */ 80*0c855477Smseidel interface com::sun::star::form::XLoadListener; 81*0c855477Smseidel 82*0c855477Smseidel 83*0c855477Smseidel /** Each <type>DataAwareControlModel</type> should be resettable for setting default values. 84cdf0e10cSrcweir 85cdf0e10cSrcweir <p>In the context of a control model which is data-aware, the semantics of <em>default value</em> 86cdf0e10cSrcweir (see <type>XReset</type>) is as follows:<br/> 87*0c855477Smseidel If (and only if) the control is valid bound to a column of its <type scope="com::sun::star::form::component">DataForm</type>, and the form 88cdf0e10cSrcweir is not positioned on a new record (see <member scope="com::sun::star::sdb">RowSet::IsNew</member>), then 89*0c855477Smseidel <member>XReset::reset</member> does not reset the model's value to its default value, but uses the 90cdf0e10cSrcweir underlying column value.<br/> 91cdf0e10cSrcweir In all other cases, the model is reset to the default value as specified by the respective property.</p> 92cdf0e10cSrcweir 93cdf0e10cSrcweir <p>For an example, have a look at the <type scope="com::sun::star::form::component">TextField</type>. It inherites 94cdf0e10cSrcweir the <member scope="com::sun::star::awt">UnoControlEditModel::Text</member> property from the underlying 95cdf0e10cSrcweir service, and additionally specifies the <member scope="com::sun::star::form::component">TextField::DefaultText</member>. 96cdf0e10cSrcweir </p> 97cdf0e10cSrcweir 98cdf0e10cSrcweir <p>In the context of a <type scope="com::sun::star::form::component">DataForm</type>, controls are 99cdf0e10cSrcweir automatically reset when one of the following applies 100*0c855477Smseidel <ul><li>The form is reset by invoking its <type>XReset</type> interface.</li> 101cdf0e10cSrcweir <li>The form moves to a new record.</li> 102cdf0e10cSrcweir <li>The changes in the current record of the form are undone</li> 103cdf0e10cSrcweir </ul> 104cdf0e10cSrcweir </p> 105cdf0e10cSrcweir */ 106*0c855477Smseidel interface com::sun::star::form::XReset; 107*0c855477Smseidel 108*0c855477Smseidel //------------------------------------------------------------------------- 109*0c855477Smseidel 110cdf0e10cSrcweir /** specifies the name of the bound database field. 111cdf0e10cSrcweir 112cdf0e10cSrcweir <p>This property makes sense in the <em>context</em> of the control model only. Normally, a control model 113cdf0e10cSrcweir is a child of a <type scope="com::sun::star::form::component">DataForm</type>, which is bound 114cdf0e10cSrcweir to a higher level object such as a table or query - more general, a result set.<br/> 115cdf0e10cSrcweir This member here describes the column of this result set which the control should act for.</p> 116cdf0e10cSrcweir 117cdf0e10cSrcweir <p>Not every control model can be bound to every database column. Usually, super services of the 118cdf0e10cSrcweir <type>DataAwareControlModel</type> restrict the column types they can be used with.</p> 119cdf0e10cSrcweir 120cdf0e10cSrcweir @see DataAwareControlModel::BoundField 121cdf0e10cSrcweir */ 122*0c855477Smseidel [property] string DataField; 123*0c855477Smseidel 124*0c855477Smseidel /** determines whether or not input into this field is required, when it is actually bound to a database field. 125*0c855477Smseidel 126*0c855477Smseidel <p>If this property is set to <FALSE/>, then the form runtime will not check the control/model for 127*0c855477Smseidel <NULL/> values before submitting data to the database. Usually, if a control model is bound to 128*0c855477Smseidel a database field which cannot be <NULL/>, and the model itself does not have a value, then the database 129*0c855477Smseidel update is prevented, showing an error message to the user. To disable this behavior on a per-control 130*0c855477Smseidel basis, use the <code>InputRequired</code> property.</p> 131*0c855477Smseidel 132*0c855477Smseidel @since OpenOffice 3.1 133*0c855477Smseidel */ 134*0c855477Smseidel [optional, property] boolean InputRequired; 135*0c855477Smseidel 136*0c855477Smseidel //------------------------------------------------------------------------- 137*0c855477Smseidel 138cdf0e10cSrcweir /** references to the cursor field to which the control is bound. 139cdf0e10cSrcweir <p>Applies only if the form the control model belongs to is loaded and the control is valid bound. 140cdf0e10cSrcweir The referenced field supports the <type scope="com::sun::star::sdb">Column</type> service. 141cdf0e10cSrcweir </p> 142cdf0e10cSrcweir @see DataAwareControlModel::DataField 143cdf0e10cSrcweir */ 144*0c855477Smseidel [readonly, property] com::sun::star::beans::XPropertySet BoundField; 145*0c855477Smseidel 146*0c855477Smseidel //------------------------------------------------------------------------- 147cdf0e10cSrcweir 148cdf0e10cSrcweir /** references to a control model within the same document which should be used as a label. 149cdf0e10cSrcweir <p>Any user interface action which needs to refer to the control is assumed to use this 150*0c855477Smseidel property.<br/> 151cdf0e10cSrcweir A very common design method for forms is to group a data aware control with a label control, 152cdf0e10cSrcweir with the latter describing the content of the former. For instance, you may have a 153cdf0e10cSrcweir <type scope="com::sun::star::form::component">TextField</type>, which is bound to the e-mail 154cdf0e10cSrcweir column of your data source. Then you will probably add a 155*0c855477Smseidel <type scope="com::sun::star::form::component">FixedText</type> whose label is "E-Mail", 156cdf0e10cSrcweir and associate it with the TextField by setting it as <member>LabelControl</member>.<br/> 157cdf0e10cSrcweir Now if you imagine a component offering data search in a form, this component will examine 158cdf0e10cSrcweir the <member>LabelControl</member> property, find the <type scope="com::sun::star::form::component">FixedText</type>, 159*0c855477Smseidel examine its label, and use this label to refer to the <type scope="com::sun::star::form::component">TextField</type>. 160cdf0e10cSrcweir </p> 161cdf0e10cSrcweir <p>When setting the property, a number of constraints apply: 162cdf0e10cSrcweir <ul> 163cdf0e10cSrcweir <li>The object which is to be set has to support the following interfaces 164cdf0e10cSrcweir <ul><li><type scope="com::sun::star::awt">XControlModel</type></li> 165cdf0e10cSrcweir <li><type scope="com::sun::star::lang">XServiceInfo</type></li> 166cdf0e10cSrcweir <li><type scope="com::sun::star::beans">XPropertySet</type></li> 167cdf0e10cSrcweir <li><type scope="com::sun::star::container">XChild</type></li> 168cdf0e10cSrcweir </ul> 169cdf0e10cSrcweir </il> 170*0c855477Smseidel <li>It has to be a part of the same document as the model whose property is to be modified.</il> 171cdf0e10cSrcweir <li>Additionally, the support of a special service, indicating that the model is of the right type, 172cdf0e10cSrcweir is required. Which kind of service is in the request depends on the type of the control model.<br/> 173cdf0e10cSrcweir 174cdf0e10cSrcweir For instance, text fields (<type scope="com::sun::star::form::component">TextField</type>) can be 175*0c855477Smseidel labeled by label controls only (<type scope="com::sun::star::form::component">FixedText</type>), 176*0c855477Smseidel and radio buttons (<type scope="com::sun::star::form::component">RadioButton</type>) can be labeled 177cdf0e10cSrcweir by group boxes (<type scope="com::sun::star::form::component">GroupBox</type>) only. 178cdf0e10cSrcweir </li> 179cdf0e10cSrcweir </ul> 180cdf0e10cSrcweir </p> 181cdf0e10cSrcweir */ 182*0c855477Smseidel [property] com::sun::star::beans::XPropertySet LabelControl; 183*0c855477Smseidel 184*0c855477Smseidel}; 185*0c855477Smseidel 186*0c855477Smseidel//============================================================================= 187*0c855477Smseidel 188*0c855477Smseidel}; }; }; }; 189*0c855477Smseidel 190cdf0e10cSrcweir#endif 191