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_OCOMPONENTACCESS_HXX_
25 #define __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_
26 
27 //_________________________________________________________________________________________________________________
28 //	my own includes
29 //_________________________________________________________________________________________________________________
30 
31 #include <threadhelp/threadhelpbase.hxx>
32 #include <macros/generic.hxx>
33 #include <macros/xinterface.hxx>
34 #include <macros/xtypeprovider.hxx>
35 #include <macros/debug.hxx>
36 #include <general.h>
37 
38 //_________________________________________________________________________________________________________________
39 //	interface includes
40 //_________________________________________________________________________________________________________________
41 #include <com/sun/star/frame/XFramesSupplier.hpp>
42 #include <com/sun/star/container/XEnumerationAccess.hpp>
43 #include <com/sun/star/container/XElementAccess.hpp>
44 #include <com/sun/star/container/XEnumeration.hpp>
45 #include <com/sun/star/frame/XDesktop.hpp>
46 #include <com/sun/star/lang/XComponent.hpp>
47 
48 //_________________________________________________________________________________________________________________
49 //	other includes
50 //_________________________________________________________________________________________________________________
51 #include <cppuhelper/implbase1.hxx>
52 #include <cppuhelper/weakref.hxx>
53 
54 //_________________________________________________________________________________________________________________
55 //	namespace
56 //_________________________________________________________________________________________________________________
57 
58 namespace framework{
59 
60 //_________________________________________________________________________________________________________________
61 //	exported const
62 //_________________________________________________________________________________________________________________
63 
64 //_________________________________________________________________________________________________________________
65 //	exported definitions
66 //_________________________________________________________________________________________________________________
67 
68 /*-************************************************************************************************************//**
69 	@short			implement XEnumerationAccess interface as helper to create many oneway enumeration of components
70 	@descr			We share mutex and framecontainer with our owner and have full access to his child tasks.
71 					(Our owner can be the Desktop only!) We create oneway enumerations on demand. These "lists"
72 					can be used for one time only. Step during the list from first to last element.
73 					(The type of created enumerations is OComponentEnumeration.)
74 
75 	@implements		XInterface
76 					XTypeProvider
77 					XEnumerationAccess
78 					XElementAccess
79 
80     @base           ThreadHelpBase
81                     OWeakObject
82 
83 	@devstatus		ready to use
84 *//*-*************************************************************************************************************/
85 
86 class OComponentAccess	:	private ThreadHelpBase                      ,   // Must be the first of baseclasses - Is necessary for right initialization of objects!
87 							public ::cppu::WeakImplHelper1< ::com::sun::star::container::XEnumerationAccess >
88 {
89 	//-------------------------------------------------------------------------------------------------------------
90 	//	public methods
91 	//-------------------------------------------------------------------------------------------------------------
92 
93 	public:
94 
95 		//---------------------------------------------------------------------------------------------------------
96 		//	constructor / destructor
97 		//---------------------------------------------------------------------------------------------------------
98 
99 		/*-****************************************************************************************************//**
100 			@short		constructor to initialize this instance
101 			@descr		A desktop will create an enumeration-access-object. An enumeration is a oneway-list and a
102 						snapshot of the components of current tasks under the desktop.
103 						But we need a instance to create more then one enumerations at different times!
104 
105 			@seealso	class Desktop
106 			@seealso	class OComponentEnumeration
107 
108 			@param		"xOwner" is a reference to our owner and must be the desktop!
109 			@return		-
110 
111 			@onerror	Do nothing and reset this object to default with an empty list.
112 		*//*-*****************************************************************************************************/
113 
114         OComponentAccess( const css::uno::Reference< css::frame::XDesktop >& xOwner );
115 
116 		//---------------------------------------------------------------------------------------------------------
117 		//	XEnumerationAccess
118 		//---------------------------------------------------------------------------------------------------------
119 
120 		/*-****************************************************************************************************//**
121 			@short		create a new enumeration of components
122 			@descr		You can call this method to get a new snapshot from all components of all tasks of the desktop as an enumeration.
123 
124 			@seealso	interface XEnumerationAccess
125 			@seealso	interface XEnumeration
126 			@seealso	class Desktop
127 
128 			@param		-
129 			@return		If the desktop and some components exist => a valid reference to an enumeration<BR>
130 						An NULL-reference, other way.
131 
132 			@onerror	-
133 		*//*-*****************************************************************************************************/
134 
135 	    virtual css::uno::Reference< css::container::XEnumeration > SAL_CALL createEnumeration() throw( css::uno::RuntimeException );
136 
137 		//---------------------------------------------------------------------------------------------------------
138 		//	XElementAccess
139 		//---------------------------------------------------------------------------------------------------------
140 
141 		/*-****************************************************************************************************//**
142 			@short		get the type of elements in enumeration
143 			@descr		-
144 
145 			@seealso	interface XElementAccess
146 			@seealso	class OComponentEnumeration
147 
148 			@param		-
149 			@return		The uno-type XComponent.
150 
151 			@onerror	-
152 		*//*-*****************************************************************************************************/
153 
154 		virtual css::uno::Type SAL_CALL getElementType() throw( css::uno::RuntimeException );
155 
156 		/*-****************************************************************************************************//**
157 			@short		get state of componentlist of enumeration.
158 			@descr		-
159 
160 			@seealso	interface XElementAccess
161 
162 			@param		-
163 			@return		sal_True  ,if more then 0 elements exist.
164 			@return		sal_False ,otherwise.
165 
166 			@onerror	-
167 		*//*-*****************************************************************************************************/
168 
169     	virtual sal_Bool SAL_CALL hasElements() throw( css::uno::RuntimeException );
170 
171 	//-------------------------------------------------------------------------------------------------------------
172 	//	protected methods
173 	//-------------------------------------------------------------------------------------------------------------
174 
175 	protected:
176 
177 		/*-****************************************************************************************************//**
178 			@short		standard destructor
179 			@descr		This method destruct an instance of this class and clear some member.
180 						Don't use an instance of this class as normal member. Use it dynamically with a pointer.
181 						We hold a weakreference to our owner and not to our superclass!
182 						That's the reason for a protected dtor.
183 
184 			@seealso	class Desktop
185 
186 			@param		-
187 			@return		-
188 
189 			@onerror	-
190 		*//*-*****************************************************************************************************/
191 
192 		virtual	~OComponentAccess();
193 
194 	//-------------------------------------------------------------------------------------------------------------
195 	//	private methods
196 	//-------------------------------------------------------------------------------------------------------------
197 
198 	private:
199 
200 		/*-****************************************************************************************************//**
201 			@short		recursive method (!) to collect all components of all frames from the subtree of given node
202 			@descr		This is necessary to create the enumeration.
203 
204 			@seealso	method createEnumeration
205 
206 			@param		"xNode"        , root of subtree and start point of search
207 			@param		"seqComponents", result list of search. We can't use a return value, we search recursive
208 										 and must collect all informations.
209 			@return		-
210 
211 			@onerror	-
212 		*//*-*****************************************************************************************************/
213 
214 		void impl_collectAllChildComponents(	const	css::uno::Reference< css::frame::XFramesSupplier >&					xNode			,
215 	 		 											css::uno::Sequence< css::uno::Reference< css::lang::XComponent > >&	seqComponents	);
216 
217 		/*-****************************************************************************************************//**
218 			@short		get the component of a frame
219 			@descr		The component of a frame can be the window, the controller or the model.
220 
221 			@seealso	method createEnumeration
222 
223 			@param		"xFrame", frame which contains the component
224 			@return		A reference to the component of given frame.
225 
226 			@onerror	A null reference is returned.
227 		*//*-*****************************************************************************************************/
228 
229 		css::uno::Reference< css::lang::XComponent > impl_getFrameComponent( const css::uno::Reference< css::frame::XFrame >& xFrame ) const;
230 
231 	//-------------------------------------------------------------------------------------------------------------
232 	//	debug methods
233 	//	(should be private everyway!)
234 	//-------------------------------------------------------------------------------------------------------------
235 
236 		/*-****************************************************************************************************//**
237 			@short		debug-method to check incoming parameter of some other mehods of this class
238 			@descr		The following methods are used to check parameters for other methods
239 						of this class. The return value is used directly for an ASSERT(...).
240 
241 			@seealso	ASSERTs in implementation!
242 
243 			@param		references to checking variables
244 			@return		sal_False ,on invalid parameter.
245 			@return		sal_True  ,otherwise
246 
247 			@onerror	-
248 		*//*-*****************************************************************************************************/
249 
250 	#ifdef ENABLE_ASSERTIONS
251 
252 	private:
253 
254         static sal_Bool impldbg_checkParameter_OComponentAccessCtor( const css::uno::Reference< css::frame::XDesktop >& xOwner );
255 
256 	#endif	// #ifdef ENABLE_ASSERTIONS
257 
258 	//-------------------------------------------------------------------------------------------------------------
259 	//	variables
260 	//	(should be private everyway!)
261 	//-------------------------------------------------------------------------------------------------------------
262 
263 	private:
264 
265         css::uno::WeakReference< css::frame::XDesktop >     m_xOwner    ;   /// weak reference to the desktop object!
266 
267 };		//	class OComponentAccess
268 
269 }		//	namespace framework
270 
271 #endif	//	#ifndef __FRAMEWORK_HELPER_OCOMPONENTACCESS_HXX_
272