sc/source/filter/inc/fapihelper.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
  20 #ifndef INCLUDED_SC_SOURCE_FILTER_INC_FAPIHELPER_HXX
  21 #define INCLUDED_SC_SOURCE_FILTER_INC_FAPIHELPER_HXX
  22
  23 #include <com/sun/star/uno/Any.hxx>
  24 #include <com/sun/star/uno/Reference.hxx>
  25 #include <com/sun/star/uno/Sequence.hxx>
  26 #include <com/sun/star/beans/XPropertySet.hpp>
  27 #include <com/sun/star/beans/XMultiPropertySet.hpp>
  28 #include <com/sun/star/beans/NamedValue.hpp>
  29 #include <osl/diagnose.h>
  30 #include <tools/color.hxx>
  31 #include <comphelper/types.hxx>
  32 #include "ftools.hxx"
  33 #include "scdllapi.h"
  34
  35 namespace com { namespace sun { namespace star {
  36     namespace lang { class XMultiServiceFactory; }
  37 } } }
  38
  39 namespace comphelper { class IDocPasswordVerifier; }
  40
  41 // Static helper functions ====================================================
  42
  43 class SfxMedium;
  44 class SfxObjectShell;
  45
  46 /** Static API helper functions. */
  47 class ScfApiHelper
  48 {
  49 public:
  50     /** Converts a tools color to a UNO color value. */
  51     inline static sal_Int32 ConvertToApiColor( const Color& rColor )
  52                             { return static_cast< sal_Int32 >( rColor.GetColor() ); }
  53     /** Converts a UNO color value to a tools color. */
  54     inline static Color ConvertFromApiColor( sal_Int32 nApiColor )
  55                             { return Color( static_cast< ColorData >( nApiColor ) ); }
  56
  57     /** Converts a non-empty vector into a UNO sequence containing elements of the same type. */
  58     template< typename Type >
  59     static ::com::sun::star::uno::Sequence< Type >
  60                             VectorToSequence( const ::std::vector< Type >& rVector );
  61
  62     /** Returns the service name provided via the XServiceName interface, or an empty string on error. */
  63     static OUString GetServiceName( const css::uno::Reference< css::uno::XInterface >& xInt );
  64
  65     /** Returns the multi service factory from a document shell. */
  66     static css::uno::Reference< css::lang::XMultiServiceFactory > GetServiceFactory( SfxObjectShell* pShell );
  67
  68     /** Creates an instance from the passed service name, using the passed service factory. */
  69     static css::uno::Reference< css::uno::XInterface > CreateInstance(
  70                             const css::uno::Reference< css::lang::XMultiServiceFactory >& xFactory,
  71                             const OUString& rServiceName );
  72
  73     /** Creates an instance from the passed service name, using the service factory of the passed object. */
  74     static css::uno::Reference< css::uno::XInterface > CreateInstance(
  75                             SfxObjectShell* pShell,
  76                             const OUString& rServiceName );
  77
  78     /** Creates an instance from the passed service name, using the process service factory. */
  79     static css::uno::Reference< css::uno::XInterface > CreateInstance( const OUString& rServiceName );
  80
  81     /** Opens a password dialog and returns the encryption data.
  82         @return  The encryption data or an empty sequence on 'Cancel' or any error. */
  83     static ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue > QueryEncryptionDataForMedium( SfxMedium& rMedium,
  84                             ::comphelper::IDocPasswordVerifier& rVerifier,
  85                             const ::std::vector< OUString >* pDefaultPasswords = 0 );
  86 };
  87
  88 template< typename Type >
  89 ::com::sun::star::uno::Sequence< Type > ScfApiHelper::VectorToSequence( const ::std::vector< Type >& rVector )
  90 {
  91     OSL_ENSURE( !rVector.empty(), "ScfApiHelper::VectorToSequence - vector is empty" );
  92     return ::com::sun::star::uno::Sequence< Type >( &rVector.front(), static_cast< sal_Int32 >( rVector.size() ) );
  93 }
  94
  95 // Property sets ==============================================================
  96
  97 /** A wrapper for a UNO property set.
  98
  99     This class provides functions to silently get and set properties (without
 100     exceptions, without the need to check validity of the UNO property set).
 101
 102     An instance is constructed with the reference to a UNO property set or any
 103     other interface (the constructor will query for the XPropertySet interface
 104     then). The reference to the property set will be kept as long as the
 105     instance of this class is alive.
 106
 107     The functions GetProperties() and SetProperties() try to handle all passed
 108     values at once, using the XMultiPropertySet interface. If the
 109     implementation does not support the XMultiPropertySet interface, all
 110     properties are handled separately in a loop.
 111  */
 112 class ScfPropertySet
 113 {
 114 public:
 115     inline explicit     ScfPropertySet() {}
 116     /** Constructs a property set wrapper with the passed UNO property set. */
 117     inline explicit     ScfPropertySet( const css::uno::Reference< css::beans::XPropertySet > & xPropSet ) { Set( xPropSet ); }
 118     /** Constructs a property set wrapper after querying the XPropertySet interface. */
 119     template< typename InterfaceType >
 120     inline explicit     ScfPropertySet( const css::uno::Reference< InterfaceType >& xInterface ) { Set( xInterface ); }
 121
 122                         ~ScfPropertySet();
 123
 124     /** Sets the passed UNO property set and releases the old UNO property set. */
 125     void                Set( css::uno::Reference< css::beans::XPropertySet > xPropSet );
 126     /** Queries the passed interface for an XPropertySet and releases the old UNO property set. */
 127     template< typename InterfaceType >
 128     inline void         Set( ::com::sun::star::uno::Reference< InterfaceType > xInterface )
 129                             { Set( css::uno::Reference< css::beans::XPropertySet >( xInterface, ::com::sun::star::uno::UNO_QUERY ) ); }
 130
 131     /** Returns true, if the contained XPropertySet interface is valid. */
 132     inline bool         Is() const { return mxPropSet.is(); }
 133
 134     /** Returns the contained XPropertySet interface. */
 135     inline css::uno::Reference< css::beans::XPropertySet > GetApiPropertySet() const { return mxPropSet; }
 136
 137     /** Returns the service name provided via the XServiceName interface, or an empty string on error. */
 138     OUString     GetServiceName() const;
 139
 140     // Get properties ---------------------------------------------------------
 141
 142     /** Returns true, if the property set contains the specified property. */
 143     bool                HasProperty( const OUString& rPropName ) const;
 144
 145     /** Gets the specified property from the property set.
 146         @return  true, if the Any could be filled with the property value. */
 147     bool                GetAnyProperty( css::uno::Any& rValue, const OUString& rPropName ) const;
 148
 149     /** Gets the specified property from the property set.
 150         @return  true, if the passed variable could be filled with the property value. */
 151     template< typename Type >
 152     inline bool         GetProperty( Type& rValue, const OUString& rPropName ) const
 153                             { css::uno::Any aAny; return GetAnyProperty( aAny, rPropName ) && (aAny >>= rValue); }
 154
 155     /** Gets the specified Boolean property from the property set.
 156         @return  true = property contains true; false = property contains false or error occurred. */
 157     bool                GetBoolProperty( const OUString& rPropName ) const;
 158
 159     /** Gets the specified Boolean property from the property set. */
 160     OUString       GetStringProperty( const OUString& rPropName ) const;
 161
 162     /** Gets the specified color property from the property set.
 163         @return  true, if the passed color variable could be filled with the property value. */
 164     bool                GetColorProperty( Color& rColor, const OUString& rPropName ) const;
 165
 166     /** Gets the specified properties from the property set. Tries to use the XMultiPropertySet interface.
 167         @param rPropNames  The property names. MUST be ordered alphabetically.
 168         @param rValues  The related property values. */
 169     void                GetProperties( css::uno::Sequence< css::uno::Any >& rValues, const css::uno::Sequence< OUString >& rPropNames ) const;
 170
 171     // Set properties ---------------------------------------------------------
 172
 173     /** Puts the passed Any into the property set. */
 174     void                SetAnyProperty( const OUString& rPropName, const css::uno::Any& rValue );
 175
 176     /** Puts the passed value into the property set. */
 177     template< typename Type >
 178     inline void         SetProperty( const OUString& rPropName, const Type& rValue )
 179                             { SetAnyProperty( rPropName, ::com::sun::star::uno::makeAny( rValue ) ); }
 180
 181     /** Puts the passed Boolean value into the property set. */
 182     inline void         SetBoolProperty( const OUString& rPropName, bool bValue )
 183                             { SetAnyProperty( rPropName, ::comphelper::makeBoolAny( bValue ) ); }
 184
 185     /** Puts the passed string into the property set. */
 186     inline void         SetStringProperty( const OUString& rPropName, const OUString& rValue )
 187                             { SetProperty( rPropName, rValue ); }
 188
 189     /** Puts the passed color into the property set. */
 190     inline void         SetColorProperty( const OUString& rPropName, const Color& rColor )
 191                             { SetProperty( rPropName, ScfApiHelper::ConvertToApiColor( rColor ) ); }
 192
 193     /** Puts the passed properties into the property set. Tries to use the XMultiPropertySet interface.
 194         @param rPropNames  The property names. MUST be ordered alphabetically.
 195         @param rValues  The related property values. */
 196     void                SetProperties( const css::uno::Sequence< OUString > & rPropNames, const css::uno::Sequence< css::uno::Any >& rValues );
 197
 198 private:
 199     css::uno::Reference< css::beans::XPropertySet >       mxPropSet;          /// The mandatory property set interface.
 200     css::uno::Reference< css::beans::XMultiPropertySet >  mxMultiPropSet;     /// The optional multi property set interface.
 201 };
 202
 203 /** Generic helper class for reading from and writing to property sets.
 204
 205     Usage:
 206     1)  Call the constructor with a null-terminated array of ASCII strings.
 207     2a) Read properties from a property set: Call the ReadFromPropertySet()
 208         function, then get the properties with the ReadValue() functions or the
 209         operator>> stream operator. The properties are returned in order of the
 210         array of property names passed in the constructor.
 211     2b) Write properties to a property set: Call InitializeWrite() to start a
 212         new cycle. Set the values with the WriteValue() functions or the
 213         operator<< stream operator. The order of the properties is equal to the
 214         array of property names passed in the constructor. Finally, call the
 215         WriteToPropertySet() function.
 216  */
 217 class ScfPropSetHelper
 218 {
 219 public:
 220     /** @param ppPropNames  A null-terminated array of ASCII property names. */
 221     explicit            ScfPropSetHelper( const sal_Char* const* ppcPropNames );
 222
 223     // read properties --------------------------------------------------------
 224
 225     /** Reads all values from the passed property set. */
 226     void                ReadFromPropertySet( const ScfPropertySet& rPropSet );
 227
 228     /** Reads the next value from the value sequence. */
 229     template< typename Type >
 230     bool                ReadValue( Type& rValue );
 231     /** Reads an Any from the value sequence. */
 232     bool                ReadValue( css::uno::Any& rAny );
 233     /** Reads a color value from the value sequence. */
 234     bool                ReadValue( Color& rColor );
 235     /** Reads a C++ boolean value from the value sequence. */
 236     bool                ReadValue( bool& rbValue );
 237
 238     // write properties -------------------------------------------------------
 239
 240     /** Must be called before reading or storing property values in the helper. */
 241     void                InitializeWrite( bool bClearAllAnys = false );
 242
 243     /** Writes the next value to the value sequence. */
 244     template< typename Type >
 245     void                WriteValue( const Type& rValue );
 246     /** Writes an Any to the value sequence. */
 247     void                WriteValue( const css::uno::Any& rAny );
 248     /** Writes a color value to the value sequence. */
 249     inline void         WriteValue( const Color& rColor )
 250                             { WriteValue( ScfApiHelper::ConvertToApiColor( rColor ) ); }
 251     /** Writes a C++ boolean value to the value sequence. */
 252     void                WriteValue( const bool& rbValue );
 253
 254     /** Writes all values to the passed property set. */
 255     void                WriteToPropertySet( ScfPropertySet& rPropSet ) const;
 256
 257 private:
 258     /** Returns a pointer to the next Any to be written to. */
 259     css::uno::Any*             GetNextAny();
 260
 261 private:
 262     css::uno::Sequence< OUString >       maNameSeq;          /// Sequence of property names.
 263     css::uno::Sequence< css::uno::Any >  maValueSeq;         /// Sequence of property values.
 264     ScfInt32Vec         maNameOrder;        /// Maps initial order to alphabetical order.
 265     size_t              mnNextIdx;          /// Counter for next Any to be processed.
 266 };
 267
 268 template< typename Type >
 269 bool ScfPropSetHelper::ReadValue( Type& rValue )
 270 {
 271     css::uno::Any* pAny = GetNextAny();
 272     return pAny && (*pAny >>= rValue);
 273 }
 274
 275 template< typename Type >
 276 void ScfPropSetHelper::WriteValue( const Type& rValue )
 277 {
 278     css::uno::Any* pAny = GetNextAny();
 279     if( pAny )
 280         *pAny <<= rValue;
 281 }
 282
 283 template< typename Type >
 284 ScfPropSetHelper& operator>>( ScfPropSetHelper& rPropSetHelper, Type& rValue )
 285 {
 286     rPropSetHelper.ReadValue( rValue );
 287     return rPropSetHelper;
 288 }
 289
 290 template< typename Type >
 291 ScfPropSetHelper& operator<<( ScfPropSetHelper& rPropSetHelper, const Type& rValue )
 292 {
 293     rPropSetHelper.WriteValue( rValue );
 294     return rPropSetHelper;
 295 }
 296
 297 #endif
 298
 299 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */