From 8eb40998c7db6bd232968070aa60cb6955361ef7 Mon Sep 17 00:00:00 2001 From: Rüdiger Timm Date: Tue, 24 Jul 2007 10:58:45 +0000 Subject: INTEGRATION: CWS dba23b (1.15.168); FILE MERGED 2007/07/07 20:29:49 fs 1.15.168.1: #i78593# more extensive documentation of the Settings property --- offapi/com/sun/star/sdb/DataSource.idl | 40 +++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 6 deletions(-) (limited to 'offapi') diff --git a/offapi/com/sun/star/sdb/DataSource.idl b/offapi/com/sun/star/sdb/DataSource.idl index 6ee5c1a626b8..2bdbca8dd1bb 100644 --- a/offapi/com/sun/star/sdb/DataSource.idl +++ b/offapi/com/sun/star/sdb/DataSource.idl @@ -4,9 +4,9 @@ * * $RCSfile: DataSource.idl,v $ * - * $Revision: 1.15 $ + * $Revision: 1.16 $ * - * last change: $Author: hr $ $Date: 2006-08-15 10:34:35 $ + * last change: $Author: rt $ $Date: 2007-07-24 11:58:45 $ * * The Contents of this file are made available subject to * the terms of GNU Lesser General Public License Version 2.1. @@ -162,16 +162,44 @@ published service DataSource of an existing value), the Settings property wraps the Info property for easier single-value access.

+

You should use the Setting property if you need to access a few properties only, + and the Info property if you need access to all existent settings at once.

+

The object represented by this property supports the PropertyBag service. That is, you can at runtime add arbitrary new properties to the bag.

Additionally, the property bag supports default values of properties, and thus the XPropertyState interface. If you add an own property to the bag using XPropertyContainer::addProperty, you need - to specifiy an initial value, which is also used as default value.

- -

You should use the Setting property if you need to access a few properties only, - and the Info property if you need access to all existent settings at once.

+ to specifiy an initial value, which is also used as default value (exceptions see below).

+ +

Effectively, the property bag represented by Settings contains two classes of properties: + Pre-defined ones and user-defined ones.

+ +

Pre-defined properties are properties which are potentially used by the data source, the + application UI for the data source, or a particular backend driver employed by the data source. There's + a large set of such properties, no all of them are effectively used for a concrete data source, nonetheless, + they're all present in the Settings.
+ Such properties are not removeable from the bag, that is, their + PropertyAttribute::REMOVEABLE attribute is not set.
+ Usually, you'll find that all of this properties have the + PropertyState::PropertyState_DEFAULT_VALUE state.

+ +

User-defined properties are the ones which are added at runtime by any instance. They might or might + not be removeable, this depends on whether or not the code adding them specifies the + PropertyAttribute::REMOVEABLE attribute. Also, they might + or might not have a default value, determined by the + PropertyAttribute::MAYBEDEFAULT attribute at the time they're added + to the bag.

+ +

When a data source is made persistent, then properties which are not removeable (which are assumed to be the + pre-defined properties) are ignored when they are in DEFAULT state. All other properties are + always made persistent, except when an explicit + PropertyAttribute::TRANSIENT attribute prohibits this.

+ +

Similar, when you obtain the Info property of a DataSource, the + Settings bag is asked for all its property values, and the ones which are removeable and + in state default are stripped, and not returned in the Info sequence.

*/ [property, readonly, optional] com::sun::star::beans::XPropertySet Settings; -- cgit