xmloff/inc/MultiPropertySetHelper.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #pragma once
  20
  21 #include <rtl/ustring.hxx>
  22 #include <com/sun/star/uno/Sequence.hxx>
  23 #include <memory>
  24
  25 namespace com::sun::star
  26 {
  27 namespace beans
  28 {
  29 class XMultiPropertySet;
  30 }
  31 namespace beans
  32 {
  33 class XPropertySet;
  34 }
  35 namespace beans
  36 {
  37 class XPropertySetInfo;
  38 }
  39 }
  40
  41 /**
  42  * The MultiPropertySetHelper performs the following functions:
  43  *
  44  * Given a list of property names (as char** or OUString*), it can
  45  * query an XMultiPropertySet (or XPropertySet) which of these properties
  46  * it supports (method hasProperties(...)). The properties *MUST* be
  47  * sorted alphabetically.
  48  *
  49  * Then, the X(Multi)PropertySet can be queried for values, and only
  50  * the supported properties are queried. (method getValues(...)) The
  51  * values are stored in the helper itself.
  52  *
  53  * Finally, each property can be queried for existence
  54  * (method hasProperty(...)) or its value (method (getValue(...))).
  55  *
  56  * After some initial preparation (hasProperties, getValues) the
  57  * MultiPropertySetHelper can be used similarly to an
  58  * XPropertySet in that you can query the values in the places where you
  59  * need them. However, if an XMultiPropertySet is supplied, the queries
  60  * are more efficient, often significantly so.
  61  */
  62 class MultiPropertySetHelper
  63 {
  64     /// names of all properties
  65     std::unique_ptr<OUString[]> pPropertyNames;
  66
  67     /// length of pPropertyNames array
  68     sal_Int16 nLength;
  69
  70     /// the sequence of property names that the current (multi)
  71     /// property set implementation supports
  72     css::uno::Sequence<OUString> aPropertySequence;
  73
  74     /// an array of indices that maps from pPropertyNames indices to
  75     /// aPropertySequence indices
  76     std::unique_ptr<sal_Int16[]> pSequenceIndex;
  77
  78     /// the last set of values retrieved by getValues
  79     css::uno::Sequence<css::uno::Any> aValues;
  80
  81     /// result of aValues.getConstArray()
  82     const css::uno::Any* pValues;
  83
  84     /// an empty Any
  85     css::uno::Any aEmptyAny;
  86
  87 public:
  88     MultiPropertySetHelper(const char** pNames);
  89
  90     ~MultiPropertySetHelper();
  91
  92     /**
  93      * Call hasPropertiesByName for the provided XPropertySetInfo and build
  94      * list of allowed properties.
  95      */
  96     void hasProperties(const css::uno::Reference<css::beans::XPropertySetInfo>&);
  97
  98     /**
  99      * Return whether hasProperties was called
 100      * (i.e. if we are ready to call getValues)
 101      */
 102     bool checkedProperties();
 103
 104     /**
 105      * Get values from the XMultiPropertySet.
 106      *
 107      * May only be called after hasProperties() was called for the
 108      * appropriate XPropertySetInfo.
 109      */
 110     void getValues(const css::uno::Reference<css::beans::XMultiPropertySet>&);
 111
 112     /**
 113      * Get values from the XPropertySet. This can be much slower than
 114      * getValues( const Reference<XMultiPropertySet& ) and hence
 115      * should be avoided.
 116      *
 117      * May only be called after hasProperties() was called for the
 118      * appropriate XPropertySetInfo.
 119      */
 120     void getValues(const css::uno::Reference<css::beans::XPropertySet>&);
 121
 122     /**
 123      * Get a value from the values array.
 124      *
 125      * May only be called after getValues() was called.
 126      */
 127     inline const css::uno::Any& getValue(sal_Int16 nIndex);
 128
 129     /**
 130      * Find out if this property is supported.
 131      *
 132      * May only be called after hasProperties() was called.
 133      */
 134     inline bool hasProperty(sal_Int16 nIndex);
 135
 136     /**
 137      * Get a value from the XPropertySet on demand.
 138      *
 139      * If neither getValues nor getValueOnDemand has been called already
 140      * after the last call to resetValues, the values are retrieved
 141      * using getValues. Otherwise the value already retrieved is returned.
 142      * In case XMultiPropertySet is supported by the XPropertySet and
 143      * bTryMult is set, the XMultiPropertySet is used to get the values.
 144      *
 145      */
 146     const css::uno::Any& getValue(sal_Int16 nIndex,
 147                                   const css::uno::Reference<css::beans::XPropertySet>&,
 148                                   bool bTryMulti = false);
 149
 150     /**
 151      * Get a value from the XMultiPropertySet on demand.
 152      *
 153      * If neither getValues nor getValueOnDemand has been called already
 154      * after the last call to resetValues, the values are retrieved
 155      * using getValues. Otherwise the value already retrieved is returned.
 156      * In case XMultiPropertySet is supported by the XPropertySet,
 157      * XMultiPropertySet is used to get the values.
 158      *
 159      */
 160     const css::uno::Any& getValue(sal_Int16 nIndex,
 161                                   const css::uno::Reference<css::beans::XMultiPropertySet>&);
 162
 163     void resetValues() { pValues = nullptr; }
 164 };
 165
 166 // inline implementations of the often-called methods getValue and hasProperty:
 167
 168 const css::uno::Any& MultiPropertySetHelper::getValue(sal_Int16 nValueNo)
 169 {
 170     assert(pValues && "called getValue() without calling getValues()");
 171     assert(pSequenceIndex && "called getValue() without calling hasProperties()");
 172     assert(nValueNo < nLength);
 173
 174     sal_Int16 nIndex = pSequenceIndex[nValueNo];
 175     return (nIndex != -1) ? pValues[nIndex] : aEmptyAny;
 176 }
 177
 178 bool MultiPropertySetHelper::hasProperty(sal_Int16 nValueNo)
 179 {
 180     assert(pSequenceIndex && "called hasProperty() without calling hasProperties()");
 181     assert(nValueNo < nLength);
 182
 183     return pSequenceIndex[nValueNo] != -1;
 184 }
 185
 186 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */