From 940b4d1848e8c70ab7642901a68594e8016caffc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 18:51:28 +0200 Subject: Adding upstream version 1:7.0.4. Signed-off-by: Daniel Baumann --- offapi/com/sun/star/form/DataAwareControlModel.idl | 173 +++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 offapi/com/sun/star/form/DataAwareControlModel.idl (limited to 'offapi/com/sun/star/form/DataAwareControlModel.idl') diff --git a/offapi/com/sun/star/form/DataAwareControlModel.idl b/offapi/com/sun/star/form/DataAwareControlModel.idl new file mode 100644 index 000000000..d2d40017f --- /dev/null +++ b/offapi/com/sun/star/form/DataAwareControlModel.idl @@ -0,0 +1,173 @@ +/* -*- 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_DataAwareControlModel_idl__ +#define __com_sun_star_form_DataAwareControlModel_idl__ + +#include + +#include + +#include + +#include + +#include + + + + module com { module sun { module star { module form { + + +/** is an abstract service for specialized FormControlModels + which are data aware and thus can be bound to a data source. + +

The connection between a data-aware control model and a form whose data the + control should display is made by parentship relations. The parent of a data-aware + control model (see com::sun::star::container::XChild, inherited + via the FormControlModel and FormComponent services) has + always to be a com::sun::star::form::component::DataForm.

+ */ +published service DataAwareControlModel +{ + service com::sun::star::form::FormControlModel; + + /** makes it possible to transfer the data of the model to the connected data field. +

+ This interface is optional, if a component doesn't support it, it has to forward + the changes of its value to the field it is connected to immediately (means whenever a user + interaction changes it's content). +

+ */ + [optional] interface com::sun::star::form::XBoundComponent; + + + /** must be implemented in order to recognize when the containing form of the model connects + to its data source (loads its data). After loading the form, the model may bind to its + related field source.
+ This interface will seldom be used directly from outside. + */ + interface com::sun::star::form::XLoadListener; + + + /** Each DataAwareControlModel should be resettable for setting default values. + +

In the context of a control model which is data-aware, the semantics of default value + (see XReset) is as follows:
+ If (and only if) the control is valid bound to a column of its com::sun::star::form::component::DataForm, and the form + is not positioned on a new record (see com::sun::star::sdb::RowSet::IsNew), then + XReset::reset() does not reset the model's value to its default value, but uses the + underlying column value.
+ In all other cases, the model is reset to the default value as specified by the respective property.

+ +

For an example, have a look at the com::sun::star::form::component::TextField. It inherits + the com::sun::star::awt::UnoControlEditModel::Text property from the underlying + service, and additionally specifies the com::sun::star::form::component::TextField::DefaultText. +

+ +

In the context of a com::sun::star::form::component::DataForm, controls are + automatically reset when one of the following applies +

  • The form is reset by invoking its XReset interface.
    • +
  • The form moves to a new record.
    • +
  • The changes in the current record of the form are undone
    • +
+

+ */ + interface com::sun::star::form::XReset; + + + /** specifies the name of the bound database field. + +

This property makes sense in the context of the control model only. Normally, a control model + is a child of a com::sun::star::form::component::DataForm, which is bound + to a higher level object such as a table or query - more general, a result set.
+ This member here describes the column of this result set which the control should act for.

+ +

Not every control model can be bound to every database column. Usually, super services of the + DataAwareControlModel restrict the column types they can be used with.

+ + @see DataAwareControlModel::BoundField + */ + [property] string DataField; + + /** determines whether or not input into this field is required, when it is actually bound to a database field. + +

If this property is set to `FALSE`, then the form runtime will not check the control/model for + `NULL` values before submitting data to the database. Usually, if a control model is bound to + a database field which cannot be `NULL`, and the model itself does not have a value, then the database + update is prevented, showing an error message to the user. To disable this behavior on a per-control + basis, use the InputRequired property.

+ + @since OOo 3.1 + */ + [optional, property] boolean InputRequired; + + + /** references to the cursor field to which the control is bound. +

Applies only if the form the control model belongs to is loaded and the control is valid bound. + The referenced field supports the com::sun::star::sdb::Column service. +

+ @see DataAwareControlModel::DataField + */ + [readonly, property] com::sun::star::beans::XPropertySet BoundField; + + + /** references to a control model within the same document which should be used as a label. +

Any user interface action which needs to refer to the control is assumed to use this + property.
+ A very common design method for forms is to group a data aware control with a label control, + with the latter describing the content of the former. For instance, you may have a + com::sun::star::form::component::TextField, which is bound to the e-mail + column of your data source. Then you will probably add a + com::sun::star::form::component::FixedText whose label is "E-Mail", + and associate it with the TextField by setting it as #LabelControl.
+ Now if you imagine a component offering data search in a form, this component will examine + the #LabelControl property, find the com::sun::star::form::component::FixedText, + examine it's label, and use this label to refer to the com::sun::star::form::component::TextField. +

+

When setting the property, a number of constraints apply: +

    +
  • The object which is to be set has to support the following interfaces +
    • com::sun::star::awt::XControlModel
      • +
    • com::sun::star::lang::XServiceInfo
      • +
    • com::sun::star::beans::XPropertySet
      • +
    • com::sun::star::container::XChild
      • +
    +
    • +
  • It has to be a part of the same document as the model who's property is to be modified.
    • +
  • Additionally, the support of a special service, indicating that the model is of the right type, + is required. Which kind of service is in the request depends on the type of the control model.
    + + For instance, text fields (com::sun::star::form::component::TextField) can be + labeled by label controls only (com::sun::star::form::component::FixedText), + and radio buttons (com::sun::star::form::component::RadioButton) can be labeled + by group boxes (com::sun::star::form::component::GroupBox) only. +
    • +
+

+ */ + [property] com::sun::star::beans::XPropertySet LabelControl; + +}; + + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ -- cgit v1.2.3