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 #include <span>
  25
  26 namespace com::sun::star
  27 {
  28 namespace beans
  29 {
  30 class XMultiPropertySet;
  31 }
  32 namespace beans
  33 {
  34 class XPropertySet;
  35 }
  36 namespace beans
  37 {
  38 class XPropertySetInfo;
  39 }
  40 }
  41
  42 /**
  43  * The MultiPropertySetHelper performs the following functions:
  44  *
  45  * Given a list of property names (as char** or OUString*), it can
  46  * query an XMultiPropertySet (or XPropertySet) which of these properties
  47  * it supports (method hasProperties(...)). The properties *MUST* be
  48  * sorted alphabetically.
  49  *
  50  * Then, the X(Multi)PropertySet can be queried for values, and only
  51  * the supported properties are queried. (method getValues(...)) The
  52  * values are stored in the helper itself.
  53  *
  54  * Finally, each property can be queried for existence
  55  * (method hasProperty(...)) or its value (method (getValue(...))).
  56  *
  57  * After some initial preparation (hasProperties, getValues) the
  58  * MultiPropertySetHelper can be used similarly to an
  59  * XPropertySet in that you can query the values in the places where you
  60  * need them. However, if an XMultiPropertySet is supplied, the queries
  61  * are more efficient, often significantly so.
  62  */
  63 class MultiPropertySetHelper
  64 {
  65     /// names of all properties
  66     std::span<const OUString> pPropertyNames;
  67
  68     /// the sequence of property names that the current (multi)
  69     /// property set implementation supports
  70     css::uno::Sequence<OUString> aPropertySequence;
  71
  72     /// an array of indices that maps from pPropertyNames indices to
  73     /// aPropertySequence indices
  74     std::unique_ptr<sal_Int16[]> pSequenceIndex;
  75
  76     /// the last set of values retrieved by getValues
  77     css::uno::Sequence<css::uno::Any> aValues;
  78
  79     /// result of aValues.getConstArray()
  80     const css::uno::Any* pValues;
  81
  82     /// an empty Any
  83     css::uno::Any aEmptyAny;
  84
  85 public:
  86     MultiPropertySetHelper(std::span<const OUString> pNames);
  87
  88     ~MultiPropertySetHelper();
  89
  90     /**
  91      * Call hasPropertiesByName for the provided XPropertySetInfo and build
  92      * list of allowed properties.
  93      */
  94     void hasProperties(const css::uno::Reference<css::beans::XPropertySetInfo>&);
  95
  96     /**
  97      * Return whether hasProperties was called
  98      * (i.e. if we are ready to call getValues)
  99      */
 100     bool checkedProperties();
 101
 102     /**
 103      * Get values from the XMultiPropertySet.
 104      *
 105      * May only be called after hasProperties() was called for the
 106      * appropriate XPropertySetInfo.
 107      */
 108     void getValues(const css::uno::Reference<css::beans::XMultiPropertySet>&);
 109
 110     /**
 111      * Get values from the XPropertySet. This can be much slower than
 112      * getValues( const Reference<XMultiPropertySet& ) and hence
 113      * should be avoided.
 114      *
 115      * May only be called after hasProperties() was called for the
 116      * appropriate XPropertySetInfo.
 117      */
 118     void getValues(const css::uno::Reference<css::beans::XPropertySet>&);
 119
 120     /**
 121      * Get a value from the values array.
 122      *
 123      * May only be called after getValues() was called.
 124      */
 125     inline const css::uno::Any& getValue(sal_Int16 nIndex);
 126
 127     /**
 128      * Find out if this property is supported.
 129      *
 130      * May only be called after hasProperties() was called.
 131      */
 132     inline bool hasProperty(sal_Int16 nIndex);
 133
 134     /**
 135      * Get a value from the XPropertySet on demand.
 136      *
 137      * If neither getValues nor getValueOnDemand has been called already
 138      * after the last call to resetValues, the values are retrieved
 139      * using getValues. Otherwise the value already retrieved is returned.
 140      * In case XMultiPropertySet is supported by the XPropertySet and
 141      * bTryMult is set, the XMultiPropertySet is used to get the values.
 142      *
 143      */
 144     const css::uno::Any& getValue(sal_Int16 nIndex,
 145                                   const css::uno::Reference<css::beans::XPropertySet>&,
 146                                   bool bTryMulti = false);
 147
 148     /**
 149      * Get a value from the XMultiPropertySet on demand.
 150      *
 151      * If neither getValues nor getValueOnDemand has been called already
 152      * after the last call to resetValues, the values are retrieved
 153      * using getValues. Otherwise the value already retrieved is returned.
 154      * In case XMultiPropertySet is supported by the XPropertySet,
 155      * XMultiPropertySet is used to get the values.
 156      *
 157      */
 158     const css::uno::Any& getValue(sal_Int16 nIndex,
 159                                   const css::uno::Reference<css::beans::XMultiPropertySet>&);
 160
 161     void resetValues() { pValues = nullptr; }
 162 };
 163
 164 // inline implementations of the often-called methods getValue and hasProperty:
 165
 166 const css::uno::Any& MultiPropertySetHelper::getValue(sal_Int16 nValueNo)
 167 {
 168     assert(pValues && "called getValue() without calling getValues()");
 169     assert(pSequenceIndex && "called getValue() without calling hasProperties()");
 170     assert(o3tl::make_unsigned(nValueNo) < pPropertyNames.size());
 171
 172     sal_Int16 nIndex = pSequenceIndex[nValueNo];
 173     return (nIndex != -1) ? pValues[nIndex] : aEmptyAny;
 174 }
 175
 176 bool MultiPropertySetHelper::hasProperty(sal_Int16 nValueNo)
 177 {
 178     assert(pSequenceIndex && "called hasProperty() without calling hasProperties()");
 179     assert(o3tl::make_unsigned(nValueNo) < pPropertyNames.size());
 180
 181     return pSequenceIndex[nValueNo] != -1;
 182 }
 183
 184 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */