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