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