1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: fapihelper.hxx,v $
10 * $Revision: 1.11.32.2 $
12 * This file is part of OpenOffice.org.
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.
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).
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.
29 ************************************************************************/
31 #ifndef SC_FAPIHELPER_HXX
32 #define SC_FAPIHELPER_HXX
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>
44 namespace com
{ namespace sun
{ namespace star
{
45 namespace lang
{ class XMultiServiceFactory
; }
48 namespace comphelper
{ class IDocPasswordVerifier
; }
50 // Static helper functions ====================================================
55 /** Static API helper functions. */
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
;
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
) ); }
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
);
76 /** Returns the service name provided via the XServiceName interface, or an empty string on error. */
77 static ::rtl::OUString
GetServiceName( XInterfaceRef xInt
);
79 /** Returns the multi service factory from a document shell. */
80 static XServiceFactoryRef
GetServiceFactory( SfxObjectShell
* pShell
);
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
);
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
);
92 /** Creates an instance from the passed service name, using the process service factory. */
93 static XInterfaceRef
CreateInstance( const ::rtl::OUString
& rServiceName
);
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
);
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 );
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
);
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 );
119 template< typename Type
>
120 ::com::sun::star::uno::Sequence
< Type
> ScfApiHelper::VectorToSequence( const ::std::vector
< Type
>& rVector
)
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() ) );
126 // Property sets ==============================================================
128 /** A wrapper for a UNO property set.
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).
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.
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.
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
;
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
); }
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
) ); }
169 /** Returns true, if the contained XPropertySet interface is valid. */
170 inline bool Is() const { return mxPropSet
.is(); }
172 /** Returns the contained XPropertySet interface. */
173 inline XPropertySetRef
GetApiPropertySet() const { return mxPropSet
; }
175 /** Returns the service name provided via the XServiceName interface, or an empty string on error. */
176 ::rtl::OUString
GetServiceName() const;
178 // Get properties ---------------------------------------------------------
180 /** Returns true, if the property set contains the specified property. */
181 bool HasProperty( const ::rtl::OUString
& rPropName
) const;
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;
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
); }
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;
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;
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;
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;
210 // Set properties ---------------------------------------------------------
212 /** Puts the passed Any into the property set. */
213 void SetAnyProperty( const ::rtl::OUString
& rPropName
, const UnoAny
& rValue
);
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
) ); }
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
) ); }
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
) ); }
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
) ); }
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
);
237 // ------------------------------------------------------------------------
239 XPropertySetRef mxPropSet
; /// The mandatory property set interface.
240 XMultiPropSetRef mxMultiPropSet
; /// The optional multi property set interface.
243 // ----------------------------------------------------------------------------
245 /** Generic helper class for reading from and writing to property sets.
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.
259 class ScfPropSetHelper
262 typedef ::com::sun::star::uno::Any UnoAny
;
265 /** @param ppPropNames A null-terminated array of ASCII property names. */
266 explicit ScfPropSetHelper( const sal_Char
* const* ppcPropNames
);
268 // read properties --------------------------------------------------------
270 /** Reads all values from the passed property set. */
271 void ReadFromPropertySet( const ScfPropertySet
& rPropSet
);
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
);
285 // write properties -------------------------------------------------------
287 /** Must be called before reading or storing property values in the helper. */
288 void InitializeWrite( bool bClearAllAnys
= false );
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
);
304 /** Writes all values to the passed property set. */
305 void WriteToPropertySet( ScfPropertySet
& rPropSet
) const;
307 // ------------------------------------------------------------------------
309 /** Returns a pointer to the next Any to be written to. */
310 UnoAny
* GetNextAny();
313 typedef ::com::sun::star::uno::Sequence
< ::rtl::OUString
> OUStringSequence
;
314 typedef ::com::sun::star::uno::Sequence
< UnoAny
> UnoAnySequence
;
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.
322 // ----------------------------------------------------------------------------
324 template< typename Type
>
325 bool ScfPropSetHelper::ReadValue( Type
& rValue
)
327 UnoAny
* pAny
= GetNextAny();
328 return pAny
&& (*pAny
>>= rValue
);
331 template< typename Type
>
332 void ScfPropSetHelper::WriteValue( const Type
& rValue
)
334 if( UnoAny
* pAny
= GetNextAny() )
338 template< typename Type
>
339 ScfPropSetHelper
& operator>>( ScfPropSetHelper
& rPropSetHelper
, Type
& rValue
)
341 rPropSetHelper
.ReadValue( rValue
);
342 return rPropSetHelper
;
345 template< typename Type
>
346 ScfPropSetHelper
& operator<<( ScfPropSetHelper
& rPropSetHelper
, const Type
& rValue
)
348 rPropSetHelper
.WriteValue( rValue
);
349 return rPropSetHelper
;
352 // ============================================================================