xref: /trunk/main/framework/inc/helper/oframes.hxx (revision b12a77c9)
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 __FRAMEWORK_HELPER_OFRAMES_HXX_
25 #define __FRAMEWORK_HELPER_OFRAMES_HXX_
26 
27 //_________________________________________________________________________________________________________________
28 //	my own includes
29 //_________________________________________________________________________________________________________________
30 
31 #include <classes/framecontainer.hxx>
32 #include <threadhelp/threadhelpbase.hxx>
33 #include <macros/generic.hxx>
34 #include <macros/xinterface.hxx>
35 #include <macros/xtypeprovider.hxx>
36 #include <macros/debug.hxx>
37 #include <general.h>
38 
39 //_________________________________________________________________________________________________________________
40 //	interface includes
41 //_________________________________________________________________________________________________________________
42 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
43 #include <com/sun/star/frame/XFrames.hpp>
44 #include <com/sun/star/frame/XFrame.hpp>
45 
46 //_________________________________________________________________________________________________________________
47 //	other includes
48 //_________________________________________________________________________________________________________________
49 #include <cppuhelper/implbase1.hxx>
50 #include <cppuhelper/weakref.hxx>
51 
52 //_________________________________________________________________________________________________________________
53 //	namespace
54 //_________________________________________________________________________________________________________________
55 
56 namespace framework{
57 
58 //_________________________________________________________________________________________________________________
59 //	exported const
60 //_________________________________________________________________________________________________________________
61 
62 //_________________________________________________________________________________________________________________
63 //	exported definitions
64 //_________________________________________________________________________________________________________________
65 
66 /*-************************************************************************************************************//**
67 	@short          implement XFrames, XIndexAccess and XElementAccess interfaces as helper for services
68 	@descr			Use this class as helper for these interfaces. We share mutex and framecontainer with our owner.
69 					The framecontainer is a member of it from type "FrameContainer". That means;
70 					we have the same information as our owner. In current implementation we use mutex and lock-mechanism
71 					to prevent against compete access. In future we plan support of semaphore!
72 
73 	@devstatus		deprecated
74 	@implements		XInterface
75 					XFrames
76 					XIndexAccess
77 					XElementAccess
78 	@base			OWeakObject
79 
80 	@ATTENTION		Don't use this class as direct member - use it dynamicly. Do not derive from this class.
81 					We hold a weakreference to our owner not to our superclass.
82 
83 	@devstatus		deprecated
84 *//*-*************************************************************************************************************/
85 
86 class OFrames   :   private ThreadHelpBase      ,   // Must be the first of baseclasses - Is necessary for right initialization of objects!
87 					public ::cppu::WeakImplHelper1< ::com::sun::star::frame::XFrames >
88 {
89 	//-------------------------------------------------------------------------------------------------------------
90 	//	public methods
91 	//-------------------------------------------------------------------------------------------------------------
92 
93 	public:
94 
95 		//---------------------------------------------------------------------------------------------------------
96 		//	constructor / destructor
97 		//---------------------------------------------------------------------------------------------------------
98 
99 		/*-****************************************************************************************************//**
100 			@short		standard ctor
101 			@descr		These initialize a new instance of this class with all needed informations for work.
102                         We share framecontainer with owner implementation! It's a threadsafe container.
103 
104 			@seealso	-
105 
106 			@param		"xFactory"			, reference to factory which has created our owner(!). We can use these to create new uno-services.
107 			@param		"xOwner"			, reference to our owner. We hold a wekreference to prevent us against cross-references!
108 			@param		"pFrameContainer"	, pointer to shared framecontainer of owner. It's valid only, if weakreference is valid!
109 			@return		-
110 
111 			@onerror	-
112 		*//*-*****************************************************************************************************/
113 
114 	 	OFrames(	const	css::uno::Reference< css::lang::XMultiServiceFactory >&	xFactory		,
115 					const	css::uno::Reference< css::frame::XFrame >&				xOwner			,
116 							FrameContainer*											pFrameContainer	);
117 
118 		//---------------------------------------------------------------------------------------------------------
119 		//	XFrames
120 		//---------------------------------------------------------------------------------------------------------
121 
122 		/*-****************************************************************************************************//**
123 			@short      append frame to container
124 			@descr		We share the container with our owner. We can do this only, if no lock is set on container.
125 						Valid references are accepted only!
126 
127 			@seealso	class FrameContainer
128 
129 			@param		"xFrame", reference to an existing frame to append.
130 			@return		-
131 
132 			@onerror	We do nothing in release or throw an assert in debug version.
133 		*//*-*****************************************************************************************************/
134 
135     	virtual void SAL_CALL append( const css::uno::Reference< css::frame::XFrame >& xFrame ) throw( css::uno::RuntimeException );
136 
137 		/*-****************************************************************************************************//**
138 			@short      remove frame from container
139 			@descr		This is the companion to append(). We only accept valid references and don't work, if
140 						a lock is set.
141 
142 			@seealso	class FrameContainer
143 
144 			@param		"xFrame", reference to an existing frame to remove.
145 			@return		-
146 
147 			@onerror	We do nothing in release or throw an assert in debug version.
148 		*//*-*****************************************************************************************************/
149 
150     	virtual void SAL_CALL remove( const css::uno::Reference< css::frame::XFrame >& xFrame ) throw( css::uno::RuntimeException );
151 
152 		/*-****************************************************************************************************//**
153 			@short      return list of all applicable frames for given flags
154 			@descr		Call these to get a list of all frames, which are match with given search flags.
155 
156 			@seealso	-
157 
158 			@param		"nSearchFlag", flags to search right frames.
159 			@return		A list of founded frames.
160 
161 			@onerror	An empty list is returned.
162 		*//*-*****************************************************************************************************/
163 
164     	virtual css::uno::Sequence< css::uno::Reference< css::frame::XFrame > > SAL_CALL queryFrames( sal_Int32 nSearchFlags ) throw( css::uno::RuntimeException );
165 
166 		//---------------------------------------------------------------------------------------------------------
167 		//	XIndexAccess
168 		//---------------------------------------------------------------------------------------------------------
169 
170 		/*-****************************************************************************************************//**
171 			@short      get count of all current frames in container
172 			@descr		This is the beginning of full index-access. With a count you can step over all items in container.
173 						Next call shuo�d be getByIndex(). But these mechanism works only, if no lock in container is set!
174 
175 			@seealso	class FrameContainer
176 			@seealso	method getByIndex()
177 
178 			@param		-
179 			@return		Count of current items in container.
180 
181 			@onerror	If a lock is set, we return 0 for prevent further access!
182 		*//*-*****************************************************************************************************/
183 
184     	virtual sal_Int32 SAL_CALL getCount() throw( css::uno::RuntimeException );
185 
186 		/*-****************************************************************************************************//**
187 			@short		get specified container item by index
188 			@descr		If you called getCount() successful - this method return the specified element as an Any.
189 						You must observe the range from 0 to count-1! Otherwise an IndexOutOfBoundsException is thrown.
190 
191 			@seealso	class FrameContainer
192 			@seealso	method getCount()
193 
194 			@param		"nIndex", valid index to get container item.
195 			@return		A container item (specified by index) wrapped in an Any.
196 
197 			@onerror	If a lock is set, we return an empty Any!
198 			@onerror	If index out of range, an IndexOutOfBoundsException is thrown.
199 		*//*-*****************************************************************************************************/
200 
201     	virtual css::uno::Any SAL_CALL getByIndex( sal_Int32 nIndex ) throw(	css::lang::IndexOutOfBoundsException	,
202 																				css::lang::WrappedTargetException		,
203 																				css::uno::RuntimeException				);
204 
205 		//---------------------------------------------------------------------------------------------------------
206 		//	XElementAccess
207 		//---------------------------------------------------------------------------------------------------------
208 
209 		/*-****************************************************************************************************//**
210 			@short      get uno-type of all container items
211 			@descr		In current implementation type is fixed to XFrame!
212 						(container-lock is ignored)
213 
214 			@seealso	-
215 
216 			@param		-
217 			@return		A uno-type descriptor.
218 
219 			@onerror	-
220 		*//*-*****************************************************************************************************/
221 
222 		virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException );
223 
224 		/*-****************************************************************************************************//**
225 			@short      get fill state of current container
226 			@descr		Call these to get information about, if items exist in container or not.
227 						(container-lock is ignored)
228 
229 			@seealso	-
230 
231 			@param		-
232 			@return		sal_True, if container contains some items.
233 			@return		sal_False, otherwise.
234 
235 			@onerror	We return sal_False.
236 		*//*-*****************************************************************************************************/
237 
238     	virtual sal_Bool SAL_CALL hasElements() throw( css::uno::RuntimeException );
239 
240 	//-------------------------------------------------------------------------------------------------------------
241 	//	protected methods
242 	//-------------------------------------------------------------------------------------------------------------
243 
244 	protected:
245 
246 		/*-****************************************************************************************************//**
247 			@short		standard destructor
248 			@descr		This method destruct an instance of this class and clear some member.
249 						This method is protected, because its not allowed to use this class as a member!
250 						You MUST use a dynamical instance (pointer). That's the reason for a protected dtor.
251 
252 			@seealso	-
253 
254 			@param		-
255 			@return		-
256 
257 			@onerror	-
258 		*//*-*****************************************************************************************************/
259 
260 		virtual	~OFrames();
261 
262 		/*-****************************************************************************************************//**
263 			@short		reset instance to default values
264 			@descr		There are two ways to delete an instance of this class.<BR>
265 						1) delete with destructor<BR>
266 						2) dispose from parent or factory ore ...<BR>
267 						This method do the same for both ways! It free used memory and release references ...
268 
269 			@seealso	method dispose() (if it exist!)
270 			@seealso	destructor ~TaskEnumeration()
271 
272 			@param		-
273 
274 			@return		-
275 
276 			@onerror	-
277 		*//*-*****************************************************************************************************/
278 
279 		virtual void impl_resetObject();
280 
281 	//-------------------------------------------------------------------------------------------------------------
282 	//	private methods
283 	//-------------------------------------------------------------------------------------------------------------
284 
285 	private:
286 
287 		/*-****************************************************************************************************//**
288 			@short		append one sequence to another
289 			@descr		There is no operation to add to sequences! Use this helper-method to do this.
290 
291 			@seealso	class Sequence
292 
293 			@param		"seqDestination", reference to sequence on which operation will append the other sequence.
294 			@param		"seqSource"		, reference to sequence for append.
295 			@return		"seqDestination" is parameter AND return value at the same time.
296 
297 			@onerror	-
298 		*//*-*****************************************************************************************************/
299 
300 		void impl_appendSequence(			css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >&	seqDestination	,
301 			 						const	css::uno::Sequence< css::uno::Reference< css::frame::XFrame > >&	seqSource		);
302 
303 	//-------------------------------------------------------------------------------------------------------------
304 	//	debug methods
305 	//	(should be private everyway!)
306 	//-------------------------------------------------------------------------------------------------------------
307 
308 		/*-****************************************************************************************************//**
309 			@short		debug-method to check incoming parameter of some other mehods of this class
310 			@descr		The following methods are used to check parameters for other methods
311 						of this class. The return value is used directly for an ASSERT(...).
312 
313 			@seealso	ASSERTs in implementation!
314 
315 			@param		references to checking variables
316 			@return		sal_False ,on invalid parameter
317 			@return		sal_True  ,otherwise
318 
319 			@onerror	-
320 		*//*-*****************************************************************************************************/
321 
322 	#ifdef ENABLE_ASSERTIONS
323 
324 	private:
325 
326 		static sal_Bool impldbg_checkParameter_OFramesCtor	(	const	css::uno::Reference< css::lang::XMultiServiceFactory >&	xFactory		,
327 																const	css::uno::Reference< css::frame::XFrame >&				xOwner			,
328 																		FrameContainer*											pFrameContainer	);
329 		static sal_Bool impldbg_checkParameter_append		(	const	css::uno::Reference< css::frame::XFrame >&				xFrame			);
330 		static sal_Bool impldbg_checkParameter_remove		(	const	css::uno::Reference< css::frame::XFrame >&				xFrame			);
331 		static sal_Bool impldbg_checkParameter_queryFrames	(			sal_Int32												nSearchFlags	);
332 
333 	#endif	// #ifdef ENABLE_ASSERTIONS
334 
335 	//-------------------------------------------------------------------------------------------------------------
336 	//	variables
337 	//	(should be private everyway!)
338 	//-------------------------------------------------------------------------------------------------------------
339 
340 	private:
341 
342 		css::uno::Reference< css::lang::XMultiServiceFactory >		m_xFactory						;	/// reference to global servicemanager
343 		css::uno::WeakReference< css::frame::XFrame >				m_xOwner						;	/// reference to owner of this instance (Hold no hard reference!)
344 		FrameContainer*												m_pFrameContainer				;	/// with owner shared list to hold all direct childs of an XFramesSupplier
345 		sal_Bool													m_bRecursiveSearchProtection	;	/// flag to protect against recursive searches of frames at parents
346 
347 };		//	class OFrames
348 
349 }		//	namespace framework
350 
351 #endif	//	#ifndef __FRAMEWORK_HELPER_OFRAMES_HXX_
352