1 /*************************************************************************
2  *
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * Copyright 2000, 2010 Oracle and/or its affiliates.
6  *
7  * OpenOffice.org - a multi-platform office productivity suite
8  *
9  * This file is part of OpenOffice.org.
10  *
11  * OpenOffice.org is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU Lesser General Public License version 3
13  * only, as published by the Free Software Foundation.
14  *
15  * OpenOffice.org is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU Lesser General Public License version 3 for more details
19  * (a copy is included in the LICENSE file that accompanied this code).
20  *
21  * You should have received a copy of the GNU Lesser General Public License
22  * version 3 along with OpenOffice.org.  If not, see
23  * <http://www.openoffice.org/license.html>
24  * for a copy of the LGPLv3 License.
25  *
26  ************************************************************************/
27 
28 #ifndef _XMLOFF_FORMS_PROPERTYEXPORT_HXX_
29 #define _XMLOFF_FORMS_PROPERTYEXPORT_HXX_
30 
31 #include "formattributes.hxx"
32 #include <comphelper/stl_types.hxx>
33 #include <com/sun/star/beans/XPropertySet.hpp>
34 #include <com/sun/star/beans/XPropertyState.hpp>
35 #include <callbacks.hxx>
36 #include <xmloff/xmlexp.hxx>
37 #include "callbacks.hxx"
38 #include "strings.hxx"
39 
40 //.........................................................................
41 namespace xmloff
42 {
43 //.........................................................................
44 
45 #define BOOLATTR_DEFAULT_FALSE			0x00
46 #define BOOLATTR_DEFAULT_TRUE			0x01
47 #define BOOLATTR_DEFAULT_VOID			0x02
48 #define BOOLATTR_DEFAULT_MASK			0x03
49 
50 #define BOOLATTR_INVERSE_SEMANTICS		0x04
51 	// if sal_True, indicates that the semantic of the property refered by <arg>_pPropertyName</arg>
52 	// is inverse to the semantic of the XML attribute.<br/>
53 	// I.e. if the property value is <TRUE/>, <FALSE/> has to be written and vice versa.
54 	// <p>Be careful with <arg>_bDefault</arg> and <arg>_bInverseSemantics</arg>: if <arg>_bInverseSemantics</arg>
55 	// is <TRUE/>, the current property value is inverted <em>before</em> comparing it to the default.</p>
56 
57 	class IFormsExportContext;
58 	//=====================================================================
59 	//= OPropertyExport
60 	//=====================================================================
61 	/** provides export related tools for attribute handling
62 
63 		<p>(The name is somewhat misleading. It's not only a PropertyExport, but in real a ElementExport.
64 		Anyway.)</p>
65 	*/
66 	class OPropertyExport
67 	{
68 	private:
69 		DECLARE_STL_STDKEY_SET(::rtl::OUString, StringSet);
70 		StringSet		m_aRemainingProps;
71 			// see examinePersistence
72 
73 		void exportRelativeTargetLocation(const ConstAsciiString& _sPropertyName,sal_Int32 _nProperty,bool _bAddType);
74 
75 	protected:
76 		IFormsExportContext&	m_rContext;
77 
78 		const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
79 						        m_xProps;
80 		const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySetInfo >
81 						        m_xPropertyInfo;
82 		const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyState >
83 						        m_xPropertyState;
84 
85 		// caching
86 		::rtl::OUString		m_sValueTrue;
87 		::rtl::OUString		m_sValueFalse;
88 
89 	public:
90 		/** constructs an object capable of handling attributes for export
91 			@param	_rContext
92 				the export context to which's attribute list the property translation should be added
93 			@param	m_xControl
94 				the property set to be exported
95 		*/
96 		OPropertyExport(IFormsExportContext& _rContext,
97 			const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxProps);
98 
99 	protected:
100 		/** examines a property set given for all properties which's value are to made persistent
101 
102 			<p>upon return the <method>m_aRemainingProps</method> will be filled with the names of all properties
103 			which need to be stored</p>
104 		*/
105 		void examinePersistence();
106 
107 		/**
108 		*/
109 		void exportRemainingProperties();
110 
111 		/** indicates that a property has been handled by a derived class, without using the helper methods of this
112 			class.
113 
114 			<p>Calling this method is necessary in case you use the suggested mechanism for the generic export of
115 			properties. This means that you want to use <method>exportRemainingProperties</method>, which exports
116 			all properties which need to ('cause they haven't been exported with one of the other type-specific
117 			methods).</p>
118 
119 			<p>In this case you should call exportedProperty for every property you export yourself, so the property
120 			will be flagged as <em>already handled</em></p>
121 		*/
122 		void exportedProperty(const ::rtl::OUString& _rPropertyName)
123 			{ m_aRemainingProps.erase(_rPropertyName); }
124 
125 		/** add an attribute which is represented by a string property to the export context
126 
127 			@param _nNamespaceKey
128 				the key of the namespace to use for the attribute name. Is used with the namespace map
129 				provided by the export context.
130 			@param _pAttributeName
131 				the name of the attribute to add. Must not contain any namespace
132 			@param _pPropertyName
133 				the name of the property to ask the control for
134 		*/
135 		void exportStringPropertyAttribute(
136 			const sal_uInt16 _nNamespaceKey,
137 			const sal_Char* _pAttributeName,
138 			const ::rtl::OUString& _rPropertyName
139 		);
140 
141 		/** add an attribute which is represented by a boolean property to the export context
142 
143 			@param _nNamespaceKey
144 				the key of the namespace to use for the attribute name. Is used with the namespace map
145 				provided by the export context.
146 			@param _pAttributeName
147 				the name of the attribute to add. Must not contain any namespace (it's added automatically)
148 			@param _pPropertyName
149 				the name of the property to ask the control for
150 			@param _nBooleanAttributeFlags
151 				specifies the default and the "alignment" (inverse semantics) of the boolean property
152 		*/
153 		void exportBooleanPropertyAttribute(
154 			const sal_uInt16 _nNamespaceKey,
155 			const sal_Char* _pAttributeName,
156 			const ::rtl::OUString& _rPropertyName,
157 			const sal_Int8 _nBooleanAttributeFlags);
158 
159 		/** add an attribute which is represented by a sal_Int16 property to the export context
160 
161 			@param _nNamespaceKey
162 				the key of the namespace to use for the attribute name. Is used with the namespace map
163 				provided by the export context.
164 			@param _pAttributeName
165 				the name of the attribute to add. Must not contain any namespace (it's added automatically)
166 			@param _pPropertyName
167 				the name of the property to ask the control for
168 			@param _nDefault
169 				the default of the attribute. If the current property value equals this default, no
170 				attribute is added.
171 		*/
172 		void exportInt16PropertyAttribute(
173 			const sal_uInt16 _nNamespaceKey,
174 			const sal_Char* _pAttributeName,
175 			const ::rtl::OUString& _rPropertyName,
176 			const sal_Int16 _nDefault);
177 
178 		/** add an attribute which is represented by a sal_Int32 property to the export context
179 
180 			@param _nNamespaceKey
181 				the key of the namespace to use for the attribute name. Is used with the namespace map
182 				provided by the export context.
183 			@param _pAttributeName
184 				the name of the attribute to add. Must not contain any namespace (it's added automatically)
185 			@param _pPropertyName
186 				the name of the property to ask the control for
187 			@param _nDefault
188 				the default of the attribute. If the current property value equals this default, no
189 				attribute is added.
190 		*/
191 		void exportInt32PropertyAttribute(
192 			const sal_uInt16 _nNamespaceKey,
193 			const sal_Char* _pAttributeName,
194 			const ::rtl::OUString& _rPropertyName,
195 			const sal_Int32 _nDefault);
196 
197 		/** add an attribute which is represented by a enum property to the export context
198 
199 			@param _nNamespaceKey
200 				the key of the namespace to use for the attribute name. Is used with the namespace map
201 				provided by the export context.
202 			@param _pAttributeName
203 				the name of the attribute to add. Must not contain any namespace (it's added automatically)
204 			@param _pPropertyName
205 				the name of the property to ask the control for
206 			@param _pValueMap
207 				the map to use when converting the property value to an attribute value
208 			@param _nDefault
209 				the default of the attribute. If the current property value equals this default, no
210 				attribute is added.
211 		*/
212 		void exportEnumPropertyAttribute(
213 			const sal_uInt16 _nNamespaceKey,
214 			const sal_Char* _pAttributeName,
215 			const sal_Char* _pPropertyName,
216 			const SvXMLEnumMapEntry* _pValueMap,
217 			const sal_Int32 _nDefault,
218 			const sal_Bool _bVoidDefault = sal_False);
219 
220 		// some very special methods for some very special attribute/property pairs
221 
222 		/** add the hlink:target-frame attribute to the export context.
223 
224 			<p>The value of this attribute is extracted from the TargetFrame property of the object given.</p>
225 
226 			<p>The property needs a special handling because conflicts between the default values for the attribute
227 			and the property.</p>
228 		*/
229 		void exportTargetFrameAttribute();
230 
231 		/** add the form:href attribute to the export context.
232 
233 			<p>The value of this attribute is extracted from the TargetURL property of the object given.</p>
234 
235 			<p>The property needs a special handling because the URL's need to be made relative</p>
236 
237 			<p>If _bAddType is set, an additional xlink:type="simple" attribute is also added.</p>
238 		*/
239 		inline void exportTargetLocationAttribute(bool _bAddType) { exportRelativeTargetLocation(PROPERTY_TARGETURL,CCA_TARGET_LOCATION,_bAddType); }
240 
241 		/** add the form:image attribute to the export context.
242 
243 			<p>The value of this attribute is extracted from the ImageURL property of the object given.</p>
244 
245 			<p>The property needs a special handling because the URL's need to be made relative</p>
246 		*/
247 		inline void exportImageDataAttribute() { exportRelativeTargetLocation(PROPERTY_IMAGEURL,CCA_IMAGE_DATA,false); }
248 
249 		/** flag the style properties as 'already exported'
250 
251 			<p>We don't have style support right now, so the only thing the method does is removing the style-relevant
252 			properties from the list of yet-to-be-exported properties (<member>m_aRemainingProps</member>)</p>
253 		*/
254 		void flagStyleProperties();
255 
256 		/** add an arbitrary attribute extracted from an arbitrary property to the export context
257 
258 			<p>The current value of the property specified wiht <arg>_pPropertyName</arg> is taken and converted
259 			into a string, no matter what type it has. (Okay, there are the usual limitations: We know Date, Datetime,
260 			double, integer ... to name just a few).</p>
261 
262 			<p>In case the property value is <NULL/> (void), no attribute is added</p>
263 
264 			<p>In case the property value is an empty string, and the property is a not allowed to be <NULL/> (void),
265 			no attribute is added</p>
266 
267 			<p>In case the property value is a sequence of any type, no attribute is added, 'cause sequences can't be
268 			transported as attribute. In the debug version, an additional assertion will occur if you nonetheless try
269 			to do this.</p>
270 
271 			@param _nNamespaceKey
272 				the key of the namespace to use for the attribute name. Is used with the namespace map
273 				provided by the export context.
274 			@param _pAttributeName
275 				the name of the attribute to add. Must not contain any namespace (it's added automatically)
276 			@param _pPropertyName
277 				the name of the property to ask the object for
278 		*/
279 		void exportGenericPropertyAttribute(
280 			const sal_uInt16 _nAttributeNamespaceKey,
281 			const sal_Char* _pAttributeName,
282 			const sal_Char* _pPropertyName);
283 
284 		/** exports a property value, which is a string sequence, as attribute
285 
286 			<p>The elements of the string sequence given are quoted and concatenated, with the characters used for
287 			this to be choosen by the caller</p>
288 
289 			<p>If you use the quote character, no check (except assertions) is made if one of the list items
290 			containes the quote character</p>
291 
292 			<p>If you don't use the quote character, no check (except assertions) is made if one of the list items
293 			containes the separator character (which would be deadly when reimporting the string)</p>
294 
295 			@param _nNamespaceKey
296 				the key of the namespace to use for the attribute name. Is used with the namespace map
297 				provided by the export context.
298 			@param _pAttributeName
299 				the name of the attribute to add. Must not contain any namespace (it's added automatically)
300 			@param _pPropertyName
301 				the name of the property to ask the object for
302 			@param _aQuoteCharacter
303 				the character to use to quote the sequence elements with. May be 0, in this case no quoting happens
304 			@param _aListSeparator
305 				the character to use to separate the list entries
306 		*/
307 		void exportStringSequenceAttribute(
308 			const sal_uInt16 _nAttributeNamespaceKey,
309 			const sal_Char* _pAttributeName,
310 			const ::rtl::OUString& _rPropertyName,
311 			const sal_Unicode _aQuoteCharacter = '"',
312 			const sal_Unicode _aListSeparator = ',');
313 
314         /** determines whether the given property is to be exported
315 
316             <p>Currently, the method simply checks whether the property's state is <em>not</em> PropertyState.DEFAULT,
317             or whether the property is a dynamic property (i.e. added via an <code>XPropertyContainer</code>).
318             So, take care when using the method - the heuristics is not applicable for all properties.</p>
319         */
320         bool shouldExportProperty( const ::rtl::OUString& i_propertyName ) const;
321 
322 		/** tries to convert an arbitrary <type scope="com.sun:star.uno">Any</type> into an string
323 
324 			<p>If the type contained in the Any is not supported, the returned string will be empty. In the
325 			debug version, an additional assertion occurs.</p>
326 
327 			@param	_rValue
328 				the value to convert
329 		*/
330 		::rtl::OUString implConvertAny(
331 			const ::com::sun::star::uno::Any& _rValue);
332 
333 		/**
334 			@return
335 				token which can be used in the <code>form:property</code> element's <code>type</code> attribute
336 				to describe the type of a value.<br/>
337 				Possible types returned are
338 				<ul>
339 					<li><b>boolean</b>: <arg>_rValue</arg> was interpreted as boolean value before converting
340 						it into a string</li>
341 					<li><b>float</b>: <arg>_rValue</arg> was interpreted as 64 bit floating point 16bit integer, 32bit integer or 64 bit integer value before
342 						converting it into a string</li>
343 					<li><b>string</b>: <arg>_rValue</arg> did not need any conversion as it already was a string</li>
344 				</ul>
345 				If the type is not convertable, float is returned
346 		*/
347 		::xmloff::token::XMLTokenEnum implGetPropertyXMLType(const ::com::sun::star::uno::Type& _rType);
348 
349 #ifdef DBG_UTIL
350 				void AddAttribute(sal_uInt16 _nPrefix, const sal_Char* _pName, const ::rtl::OUString& _rValue);
351                 void AddAttribute( sal_uInt16 _nPrefix, const ::rtl::OUString& _rName, const ::rtl::OUString& _rValue );
352 				void AddAttributeASCII( sal_uInt16 nPrefix, const sal_Char *pName, const sal_Char *pValue );
353 				void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, const ::rtl::OUString& _rValue);
354 				void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, ::xmloff::token::XMLTokenEnum _eValue );
355 #else
356 		//  in the product version, inline this, so it does not cost us extra time calling into our method
357 		inline	void AddAttribute(sal_uInt16 _nPrefix, const sal_Char* _pName, const ::rtl::OUString& _rValue)
358 			{ m_rContext.getGlobalContext().AddAttribute(_nPrefix, _pName, _rValue); }
359         inline void AddAttribute( sal_uInt16 _nPrefix, const ::rtl::OUString& _rName, const ::rtl::OUString& _rValue )
360             { m_rContext.getGlobalContext().AddAttribute( _nPrefix, _rName, _rValue ); }
361 		inline	void AddAttributeASCII( sal_uInt16 _nPrefix, const sal_Char* _pName, const sal_Char *pValue )
362 			{ m_rContext.getGlobalContext().AddAttributeASCII(_nPrefix, _pName, pValue); }
363 		inline void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, const ::rtl::OUString& _rValue)
364 			{ m_rContext.getGlobalContext().AddAttribute(_nPrefix, _eName, _rValue); }
365 		inline void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, ::xmloff::token::XMLTokenEnum _eValue )
366 			{ m_rContext.getGlobalContext().AddAttribute(_nPrefix, _eName, _eValue); }
367 #endif
368 
369 #ifdef DBG_UTIL
370 	protected:
371 		/** check a given property set for the existence and type correctness of a given property
372 
373 			<p>This method is available in the non-product version only.</p>
374 
375 			@param _rPropertyName
376 				the name of the property to ask the control model for
377 			@param _pType
378 				the expected type of the property. May be NULL, in this case no type check is made.
379 			@return sal_True, if the property exists and is of the correct type
380 		*/
381 		void dbg_implCheckProperty(
382 			const ::rtl::OUString& _rPropertyName,
383 			const ::com::sun::star::uno::Type* _pType);
384 
385 //		void dbg_implCheckProperty(
386 //			const sal_Char* _rPropertyName,
387 //			const ::com::sun::star::uno::Type* _pType)
388 //		{
389 //			dbg_implCheckProperty(::rtl::OUString::createFromAscii(_rPropertyName), _pType);
390 //		}
391 #endif
392 	};
393 
394 	//=====================================================================
395 	//= helper
396 	//=====================================================================
397 #ifdef DBG_UTIL
398 	#define DBG_CHECK_PROPERTY(name, type)	\
399 		dbg_implCheckProperty(name, &::getCppuType(static_cast< type* >(NULL)))
400 
401 	#define DBG_CHECK_PROPERTY_NO_TYPE(name)	\
402 		dbg_implCheckProperty(name, NULL)
403 
404 	#define DBG_CHECK_PROPERTY_ASCII( name, type ) \
405 		dbg_implCheckProperty( ::rtl::OUString::createFromAscii( name ), &::getCppuType(static_cast< type* >(NULL)))
406 
407 	#define DBG_CHECK_PROPERTY_ASCII_NO_TYPE( name ) \
408 		dbg_implCheckProperty( ::rtl::OUString::createFromAscii( name ), NULL )
409 #else
410 	#define DBG_CHECK_PROPERTY(name, type)
411 	#define DBG_CHECK_PROPERTY_NO_TYPE(name)
412 	#define DBG_CHECK_PROPERTY_ASCII_NO_TYPE( name )
413 #endif
414 
415 //.........................................................................
416 }	// namespace xmloff
417 //.........................................................................
418 
419 #endif // _XMLOFF_FORMS_PROPERTYEXPORT_HXX_
420 
421 
422