sc/source/filter/inc/fapihelper.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: fapihelper.hxx,v $
  10  * $Revision: 1.11.32.2 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef SC_FAPIHELPER_HXX
  32 #define SC_FAPIHELPER_HXX
  33
  34 #include <com/sun/star/uno/Any.hxx>
  35 #include <com/sun/star/uno/Reference.hxx>
  36 #include <com/sun/star/uno/Sequence.hxx>
  37 #include <com/sun/star/beans/XPropertySet.hpp>
  38 #include <com/sun/star/beans/XMultiPropertySet.hpp>
  39 #include <tools/color.hxx>
  40 #include <comphelper/types.hxx>
  41 #include "ftools.hxx"
  42 #include "scdllapi.h"
  43
  44 namespace com { namespace sun { namespace star {
  45     namespace lang { class XMultiServiceFactory; }
  46 } } }
  47
  48 namespace comphelper { class IDocPasswordVerifier; }
  49
  50 // Static helper functions ====================================================
  51
  52 class SfxMedium;
  53 class SfxObjectShell;
  54
  55 /** Static API helper functions. */
  56 class ScfApiHelper
  57 {
  58 public:
  59     typedef ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >               XInterfaceRef;
  60     typedef ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >    XServiceFactoryRef;
  61     typedef ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >                       UnoAnySequence;
  62
  63 public:
  64     /** Converts a tools color to a UNO color value. */
  65     inline static sal_Int32 ConvertToApiColor( const Color& rColor )
  66                             { return static_cast< sal_Int32 >( rColor.GetColor() ); }
  67     /** Converts a UNO color value to a tools color. */
  68     inline static Color ConvertFromApiColor( sal_Int32 nApiColor )
  69                             { return Color( static_cast< ColorData >( nApiColor ) ); }
  70
  71     /** Converts a non-empty vector into a UNO sequence containing elements of the same type. */
  72     template< typename Type >
  73     static ::com::sun::star::uno::Sequence< Type >
  74                             VectorToSequence( const ::std::vector< Type >& rVector );
  75
  76     /** Returns the service name provided via the XServiceName interface, or an empty string on error. */
  77     static ::rtl::OUString GetServiceName( XInterfaceRef xInt );
  78
  79     /** Returns the multi service factory from a document shell. */
  80     static XServiceFactoryRef GetServiceFactory( SfxObjectShell* pShell );
  81
  82     /** Creates an instance from the passed service name, using the passed service factory. */
  83     static XInterfaceRef CreateInstance(
  84                             XServiceFactoryRef xFactory,
  85                             const ::rtl::OUString& rServiceName );
  86
  87     /** Creates an instance from the passed service name, using the service factory of the passed object. */
  88     static XInterfaceRef CreateInstance(
  89                             SfxObjectShell* pShell,
  90                             const ::rtl::OUString& rServiceName );
  91
  92     /** Creates an instance from the passed service name, using the process service factory. */
  93     static XInterfaceRef CreateInstance( const ::rtl::OUString& rServiceName );
  94
  95     /** Creates an instance from the passed service name, using the passed service factory. */
  96     static XInterfaceRef CreateInstanceWithArgs(
  97                             XServiceFactoryRef xFactory,
  98                             const ::rtl::OUString& rServiceName,
  99                             const UnoAnySequence& rArgs );
 100
 101 //UNUSED2008-05  /** Creates an instance from the passed service name, using the service factory of the passed object. */
 102 //UNUSED2008-05  static XInterfaceRef CreateInstanceWithArgs(
 103 //UNUSED2008-05                          SfxObjectShell* pShell,
 104 //UNUSED2008-05                          const ::rtl::OUString& rServiceName,
 105 //UNUSED2008-05                          const UnoAnySequence& rArgs );
 106
 107     /** Creates an instance from the passed service name, using the process service factory. */
 108     static XInterfaceRef CreateInstanceWithArgs(
 109                             const ::rtl::OUString& rServiceName,
 110                             const UnoAnySequence& rArgs );
 111
 112     /** Opens a password dialog and returns the entered password.
 113         @return  The entered password or an empty string on 'Cancel' or any error. */
 114     static String       QueryPasswordForMedium( SfxMedium& rMedium,
 115                             ::comphelper::IDocPasswordVerifier& rVerifier,
 116                             const ::std::vector< ::rtl::OUString >* pDefaultPasswords = 0 );
 117 };
 118
 119 template< typename Type >
 120 ::com::sun::star::uno::Sequence< Type > ScfApiHelper::VectorToSequence( const ::std::vector< Type >& rVector )
 121 {
 122     DBG_ASSERT( !rVector.empty(), "ScfApiHelper::VectorToSequence - vector is empty" );
 123     return ::com::sun::star::uno::Sequence< Type >( &rVector.front(), static_cast< sal_Int32 >( rVector.size() ) );
 124 }
 125
 126 // Property sets ==============================================================
 127
 128 /** A wrapper for a UNO property set.
 129
 130     This class provides functions to silently get and set properties (without
 131     exceptions, without the need to check validity of the UNO property set).
 132
 133     An instance is constructed with the reference to a UNO property set or any
 134     other interface (the constructor will query for the XPropertySet interface
 135     then). The reference to the property set will be kept as long as the
 136     instance of this class is alive.
 137
 138     The functions GetProperties() and SetProperties() try to handle all passed
 139     values at once, using the XMultiPropertySet interface. If the
 140     implementation does not support the XMultiPropertySet interface, all
 141     properties are handled separately in a loop.
 142  */
 143 class ScfPropertySet
 144 {
 145 public:
 146     typedef ::com::sun::star::uno::Reference<
 147                 ::com::sun::star::beans::XPropertySet >         XPropertySetRef;
 148     typedef ::com::sun::star::uno::Reference<
 149                 ::com::sun::star::beans::XMultiPropertySet >    XMultiPropSetRef;
 150     typedef ::com::sun::star::uno::Any                          UnoAny;
 151     typedef ::com::sun::star::uno::Sequence< UnoAny >           UnoAnySequence;
 152     typedef ::com::sun::star::uno::Sequence< ::rtl::OUString >  OUStringSequence;
 153
 154 public:
 155     inline explicit     ScfPropertySet() {}
 156     /** Constructs a property set wrapper with the passed UNO property set. */
 157     inline explicit     ScfPropertySet( XPropertySetRef xPropSet ) { Set( xPropSet ); }
 158     /** Constructs a property set wrapper after querying the XPropertySet interface. */
 159     template< typename InterfaceType >
 160     inline explicit     ScfPropertySet( ::com::sun::star::uno::Reference< InterfaceType > xInterface ) { Set( xInterface ); }
 161
 162     /** Sets the passed UNO property set and releases the old UNO property set. */
 163     void                Set( XPropertySetRef xPropSet );
 164     /** Queries the passed interface for an XPropertySet and releases the old UNO property set. */
 165     template< typename InterfaceType >
 166     inline void         Set( ::com::sun::star::uno::Reference< InterfaceType > xInterface )
 167                             { Set( XPropertySetRef( xInterface, ::com::sun::star::uno::UNO_QUERY ) ); }
 168
 169     /** Returns true, if the contained XPropertySet interface is valid. */
 170     inline bool         Is() const { return mxPropSet.is(); }
 171
 172     /** Returns the contained XPropertySet interface. */
 173     inline XPropertySetRef GetApiPropertySet() const { return mxPropSet; }
 174
 175     /** Returns the service name provided via the XServiceName interface, or an empty string on error. */
 176     ::rtl::OUString     GetServiceName() const;
 177
 178     // Get properties ---------------------------------------------------------
 179
 180     /** Returns true, if the property set contains the specified property. */
 181     bool                HasProperty( const ::rtl::OUString& rPropName ) const;
 182
 183     /** Gets the specified property from the property set.
 184         @return  true, if the Any could be filled with the property value. */
 185     bool                GetAnyProperty( UnoAny& rValue, const ::rtl::OUString& rPropName ) const;
 186
 187     /** Gets the specified property from the property set.
 188         @return  true, if the passed variable could be filled with the property value. */
 189     template< typename Type >
 190     inline bool         GetProperty( Type& rValue, const ::rtl::OUString& rPropName ) const
 191                             { UnoAny aAny; return GetAnyProperty( aAny, rPropName ) && (aAny >>= rValue); }
 192
 193     /** Gets the specified Boolean property from the property set.
 194         @return  true = property contains true; false = property contains false or error occured. */
 195     bool                GetBoolProperty( const ::rtl::OUString& rPropName ) const;
 196
 197     /** Gets the specified Boolean property from the property set.
 198         @return  true, if the passed Boolean variable could be filled with the property value. */
 199     bool                GetStringProperty( String& rValue, const ::rtl::OUString& rPropName ) const;
 200
 201     /** Gets the specified color property from the property set.
 202         @return  true, if the passed color variable could be filled with the property value. */
 203     bool                GetColorProperty( Color& rColor, const ::rtl::OUString& rPropName ) const;
 204
 205     /** Gets the specified properties from the property set. Tries to use the XMultiPropertySet interface.
 206         @param rPropNames  The property names. MUST be ordered alphabetically.
 207         @param rValues  The related property values. */
 208     void                GetProperties( UnoAnySequence& rValues, const OUStringSequence& rPropNames ) const;
 209
 210     // Set properties ---------------------------------------------------------
 211
 212     /** Puts the passed Any into the property set. */
 213     void                SetAnyProperty( const ::rtl::OUString& rPropName, const UnoAny& rValue );
 214
 215     /** Puts the passed value into the property set. */
 216     template< typename Type >
 217     inline void         SetProperty( const ::rtl::OUString& rPropName, const Type& rValue )
 218                             { SetAnyProperty( rPropName, ::com::sun::star::uno::makeAny( rValue ) ); }
 219
 220     /** Puts the passed Boolean value into the property set. */
 221     inline void         SetBoolProperty( const ::rtl::OUString& rPropName, bool bValue )
 222                             { SetAnyProperty( rPropName, ::comphelper::makeBoolAny( bValue ) ); }
 223
 224     /** Puts the passed string into the property set. */
 225     inline void         SetStringProperty( const ::rtl::OUString& rPropName, const String& rValue )
 226                             { SetProperty( rPropName, ::rtl::OUString( rValue ) ); }
 227
 228     /** Puts the passed color into the property set. */
 229     inline void         SetColorProperty( const ::rtl::OUString& rPropName, const Color& rColor )
 230                             { SetProperty( rPropName, ScfApiHelper::ConvertToApiColor( rColor ) ); }
 231
 232     /** Puts the passed properties into the property set. Tries to use the XMultiPropertySet interface.
 233         @param rPropNames  The property names. MUST be ordered alphabetically.
 234         @param rValues  The related property values. */
 235     void                SetProperties( const OUStringSequence& rPropNames, const UnoAnySequence& rValues );
 236
 237     // ------------------------------------------------------------------------
 238 private:
 239     XPropertySetRef     mxPropSet;          /// The mandatory property set interface.
 240     XMultiPropSetRef    mxMultiPropSet;     /// The optional multi property set interface.
 241 };
 242
 243 // ----------------------------------------------------------------------------
 244
 245 /** Generic helper class for reading from and writing to property sets.
 246
 247     Usage:
 248     1)  Call the constructor with a null-terminated array of ASCII strings.
 249     2a) Read properties from a property set: Call the ReadFromPropertySet()
 250         function, then get the properties with the ReadValue() functions or the
 251         operator>> stream operator. The properties are returned in order of the
 252         array of property names passed in the constructor.
 253     2b) Write properties to a property set: Call InitializeWrite() to start a
 254         new cycle. Set the values with the WriteValue() functions or the
 255         operator<< stream operator. The order of the properties is equal to the
 256         array of property names passed in the constructor. Finally, call the
 257         WriteToPropertySet() function.
 258  */
 259 class ScfPropSetHelper
 260 {
 261 public:
 262     typedef ::com::sun::star::uno::Any UnoAny;
 263
 264 public:
 265     /** @param ppPropNames  A null-terminated array of ASCII property names. */
 266     explicit            ScfPropSetHelper( const sal_Char* const* ppcPropNames );
 267
 268     // read properties --------------------------------------------------------
 269
 270     /** Reads all values from the passed property set. */
 271     void                ReadFromPropertySet( const ScfPropertySet& rPropSet );
 272
 273     /** Reads the next value from the value sequence. */
 274     template< typename Type >
 275     bool                ReadValue( Type& rValue );
 276     /** Reads an Any from the value sequence. */
 277     bool                ReadValue( UnoAny& rAny );
 278     /** Reads a tools string from the value sequence. */
 279     bool                ReadValue( String& rString );
 280     /** Reads a color value from the value sequence. */
 281     bool                ReadValue( Color& rColor );
 282     /** Reads a C++ boolean value from the value sequence. */
 283     bool                ReadValue( bool& rbValue );
 284
 285     // write properties -------------------------------------------------------
 286
 287     /** Must be called before reading or storing property values in the helper. */
 288     void                InitializeWrite( bool bClearAllAnys = false );
 289
 290     /** Writes the next value to the value sequence. */
 291     template< typename Type >
 292     void                WriteValue( const Type& rValue );
 293     /** Writes an Any to the value sequence. */
 294     void                WriteValue( const UnoAny& rAny );
 295     /** Writes a tools string to the value sequence. */
 296     inline void         WriteValue( const String& rString )
 297                             { WriteValue( ::rtl::OUString( rString ) ); }
 298     /** Writes a color value to the value sequence. */
 299     inline void         WriteValue( const Color& rColor )
 300                             { WriteValue( ScfApiHelper::ConvertToApiColor( rColor ) ); }
 301     /** Writes a C++ boolean value to the value sequence. */
 302     void                WriteValue( const bool& rbValue );
 303
 304     /** Writes all values to the passed property set. */
 305     void                WriteToPropertySet( ScfPropertySet& rPropSet ) const;
 306
 307     // ------------------------------------------------------------------------
 308 private:
 309     /** Returns a pointer to the next Any to be written to. */
 310     UnoAny*             GetNextAny();
 311
 312 private:
 313     typedef ::com::sun::star::uno::Sequence< ::rtl::OUString >  OUStringSequence;
 314     typedef ::com::sun::star::uno::Sequence< UnoAny >           UnoAnySequence;
 315
 316     OUStringSequence    maNameSeq;          /// Sequence of property names.
 317     UnoAnySequence      maValueSeq;         /// Sequence of property values.
 318     ScfInt32Vec         maNameOrder;        /// Maps initial order to alphabetical order.
 319     size_t              mnNextIdx;          /// Counter for next Any to be processed.
 320 };
 321
 322 // ----------------------------------------------------------------------------
 323
 324 template< typename Type >
 325 bool ScfPropSetHelper::ReadValue( Type& rValue )
 326 {
 327     UnoAny* pAny = GetNextAny();
 328     return pAny && (*pAny >>= rValue);
 329 }
 330
 331 template< typename Type >
 332 void ScfPropSetHelper::WriteValue( const Type& rValue )
 333 {
 334     if( UnoAny* pAny = GetNextAny() )
 335         *pAny <<= rValue;
 336 }
 337
 338 template< typename Type >
 339 ScfPropSetHelper& operator>>( ScfPropSetHelper& rPropSetHelper, Type& rValue )
 340 {
 341     rPropSetHelper.ReadValue( rValue );
 342     return rPropSetHelper;
 343 }
 344
 345 template< typename Type >
 346 ScfPropSetHelper& operator<<( ScfPropSetHelper& rPropSetHelper, const Type& rValue )
 347 {
 348     rPropSetHelper.WriteValue( rValue );
 349     return rPropSetHelper;
 350 }
 351
 352 // ============================================================================
 353
 354 #endif
 355