1f8e07b45SAndrew Rist /**************************************************************
2cdf0e10cSrcweir  *
3f8e07b45SAndrew Rist  * Licensed to the Apache Software Foundation (ASF) under one
4f8e07b45SAndrew Rist  * or more contributor license agreements.  See the NOTICE file
5f8e07b45SAndrew Rist  * distributed with this work for additional information
6f8e07b45SAndrew Rist  * regarding copyright ownership.  The ASF licenses this file
7f8e07b45SAndrew Rist  * to you under the Apache License, Version 2.0 (the
8f8e07b45SAndrew Rist  * "License"); you may not use this file except in compliance
9f8e07b45SAndrew Rist  * with the License.  You may obtain a copy of the License at
10f8e07b45SAndrew Rist  *
11f8e07b45SAndrew Rist  *   http://www.apache.org/licenses/LICENSE-2.0
12f8e07b45SAndrew Rist  *
13f8e07b45SAndrew Rist  * Unless required by applicable law or agreed to in writing,
14f8e07b45SAndrew Rist  * software distributed under the License is distributed on an
15f8e07b45SAndrew Rist  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16f8e07b45SAndrew Rist  * KIND, either express or implied.  See the License for the
17f8e07b45SAndrew Rist  * specific language governing permissions and limitations
18f8e07b45SAndrew Rist  * under the License.
19f8e07b45SAndrew Rist  *
20f8e07b45SAndrew Rist  *************************************************************/
21f8e07b45SAndrew Rist 
22f8e07b45SAndrew Rist 
23cdf0e10cSrcweir #ifndef __FRAMEWORK_LOADENV_LOADENV_HXX_
24cdf0e10cSrcweir #define __FRAMEWORK_LOADENV_LOADENV_HXX_
25cdf0e10cSrcweir 
26cdf0e10cSrcweir //_______________________________________________
27cdf0e10cSrcweir // includes of own project
28cdf0e10cSrcweir 
29cdf0e10cSrcweir #include <loadenv/loadenvexception.hxx>
30cdf0e10cSrcweir #include <loadenv/actionlockguard.hxx>
31cdf0e10cSrcweir #include <threadhelp/threadhelpbase.hxx>
32cdf0e10cSrcweir 
33cdf0e10cSrcweir //_______________________________________________
34cdf0e10cSrcweir // includes of uno interface
35cdf0e10cSrcweir #include <com/sun/star/lang/XMultiServiceFactory.hpp>
36cdf0e10cSrcweir #include <com/sun/star/frame/XComponentLoader.hpp>
37cdf0e10cSrcweir #include <com/sun/star/frame/XFrameLoader.hpp>
38cdf0e10cSrcweir #include <com/sun/star/frame/XLoadEventListener.hpp>
39cdf0e10cSrcweir #include <com/sun/star/frame/XDispatchResultListener.hpp>
40cdf0e10cSrcweir #include <com/sun/star/frame/XFrame.hpp>
41cdf0e10cSrcweir #include <com/sun/star/util/URL.hpp>
42cdf0e10cSrcweir 
43cdf0e10cSrcweir #ifndef _COM_SUN_STAR_LANG_IllegalArgumentException_HPP_
44cdf0e10cSrcweir #include <com/sun/star/lang/IllegalArgumentException.hpp>
45cdf0e10cSrcweir #endif
46cdf0e10cSrcweir 
47cdf0e10cSrcweir #ifndef _COM_SUN_STAR_IO_IOException_HPP_
48cdf0e10cSrcweir #include <com/sun/star/io/IOException.hpp>
49cdf0e10cSrcweir #endif
50cdf0e10cSrcweir 
51cdf0e10cSrcweir //_______________________________________________
52cdf0e10cSrcweir // includes of an other project
53cdf0e10cSrcweir #include <comphelper/mediadescriptor.hxx>
54cdf0e10cSrcweir #include <comphelper/sequenceashashmap.hxx>
55cdf0e10cSrcweir #include <cppuhelper/implbase2.hxx>
56cdf0e10cSrcweir 
57cdf0e10cSrcweir //_______________________________________________
58cdf0e10cSrcweir // namespace
59cdf0e10cSrcweir 
60cdf0e10cSrcweir namespace framework{
61cdf0e10cSrcweir 
62cdf0e10cSrcweir namespace css = ::com::sun::star;
63cdf0e10cSrcweir class QuietInteraction;
64cdf0e10cSrcweir //_______________________________________________
65cdf0e10cSrcweir // definitions
66cdf0e10cSrcweir 
67cdf0e10cSrcweir /** @short  implements general mechainsm for loading documents.
68cdf0e10cSrcweir 
69cdf0e10cSrcweir     @descr  An instance of this class can be used inside the API calls
70cdf0e10cSrcweir             XComponentLoader::loadComponentFromURL() and XDispatch::dispatch()
71cdf0e10cSrcweir             (of course in its derived interfaces too :-)).
72cdf0e10cSrcweir 
73cdf0e10cSrcweir     @author as96863
74cdf0e10cSrcweir  */
75cdf0e10cSrcweir class LoadEnv : private ThreadHelpBase
76cdf0e10cSrcweir {
77cdf0e10cSrcweir     //___________________________________________
78cdf0e10cSrcweir     // structs, types, etc.
79cdf0e10cSrcweir 
80cdf0e10cSrcweir     public:
81cdf0e10cSrcweir 
82cdf0e10cSrcweir         /** @short  enable/disable special features
83cdf0e10cSrcweir                     of a load request.
84cdf0e10cSrcweir 
85cdf0e10cSrcweir             @desrc  Such features must outcome without
86cdf0e10cSrcweir                     any special parameters.
87cdf0e10cSrcweir                     To make enableing/disabling of
88cdf0e10cSrcweir                     features very easy (e.g. at the ctor of
89cdf0e10cSrcweir                     this class) these values must be combinable
90cdf0e10cSrcweir                     as flags. That means: its values must be in
91cdf0e10cSrcweir                     range of [2^n]!
92cdf0e10cSrcweir          */
93cdf0e10cSrcweir         enum EFeature
94cdf0e10cSrcweir         {
95cdf0e10cSrcweir             /// we should be informed, if no feature is enabled :-)
96cdf0e10cSrcweir             E_NO_FEATURE = 0,
97cdf0e10cSrcweir             /// enable using of UI elements during loading (means progress, interaction handler etcpp.)
98cdf0e10cSrcweir             E_WORK_WITH_UI = 1,
99cdf0e10cSrcweir             /// enable loading of resources, which are not related to a target frame! (see concept of ContentHandler)
100cdf0e10cSrcweir             E_ALLOW_CONTENTHANDLER = 2
101cdf0e10cSrcweir         };
102cdf0e10cSrcweir 
103cdf0e10cSrcweir         //_______________________________________
104cdf0e10cSrcweir 
105cdf0e10cSrcweir         /** @short  classify a content.
106cdf0e10cSrcweir 
107cdf0e10cSrcweir             @descr  The load environment must know, if a content
108cdf0e10cSrcweir                     is related to a target frame or not. Only "visible"
109cdf0e10cSrcweir                     components, which full fill the requirements of the
110cdf0e10cSrcweir                     model-controller-view paradigm can be loaded into a frame.
111cdf0e10cSrcweir                     Such contents are classified as E_CAN_BE_LOADED.
112cdf0e10cSrcweir 
113cdf0e10cSrcweir                     But e.g. for the dispatch framework exists special ContentHandler
114cdf0e10cSrcweir                     objects, which can load a content in "non visible" mode ...
115cdf0e10cSrcweir                     and do not need a target frame for its operation. Such
116cdf0e10cSrcweir                     ContentHandler e.g. plays sounds.
117cdf0e10cSrcweir                     Such contents are classified as E_CAN_BE_HANDLED.
118cdf0e10cSrcweir 
119cdf0e10cSrcweir                     And last but not least a content can be "not valid" in general.
120cdf0e10cSrcweir          */
121cdf0e10cSrcweir         enum EContentType
122cdf0e10cSrcweir         {
123cdf0e10cSrcweir             /// identifies a content, which seems to be invalid in general
124cdf0e10cSrcweir             E_UNSUPPORTED_CONTENT,
125cdf0e10cSrcweir             /// identifies a content, which can be used with a ContentHandler and is not related to a target frame
126cdf0e10cSrcweir             E_CAN_BE_HANDLED,
127cdf0e10cSrcweir             /// identifies a content, which can be loaded into a target frame
128cdf0e10cSrcweir             E_CAN_BE_LOADED,
129cdf0e10cSrcweir             /// special mode for non real loading, In such case the model is given directly!
130cdf0e10cSrcweir             E_CAN_BE_SET
131cdf0e10cSrcweir         };
132cdf0e10cSrcweir 
133cdf0e10cSrcweir     //___________________________________________
134cdf0e10cSrcweir     // member
135cdf0e10cSrcweir 
136cdf0e10cSrcweir     private:
137cdf0e10cSrcweir 
138cdf0e10cSrcweir         /** @short  reference to an uno service manager, which must be used
139cdf0e10cSrcweir                     to created on needed services on demand.
140cdf0e10cSrcweir          */
141cdf0e10cSrcweir         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
142cdf0e10cSrcweir 
143cdf0e10cSrcweir         /** @short  points to the frame, which uses this LoadEnv object
144cdf0e10cSrcweir                     and must be used to start target search there.
145cdf0e10cSrcweir          */
146cdf0e10cSrcweir         css::uno::Reference< css::frame::XFrame > m_xBaseFrame;
147cdf0e10cSrcweir 
148cdf0e10cSrcweir         /** @short  points to the frame, into which the new component was loaded.
149cdf0e10cSrcweir 
150cdf0e10cSrcweir             @descr  Note: This reference will be empty if loading failed
151cdf0e10cSrcweir                     or a non visible content was loaded!
152cdf0e10cSrcweir                     It can be the same frame as m_xBaseFrame it describe, in case
153cdf0e10cSrcweir                     the target "_self", "" or the search flag "SELF" was used.
1544e7d57d8Smseidel                     Otherwise it's the new created or recycled frame, which was
155cdf0e10cSrcweir                     used for loading and contains further the new component.
156cdf0e10cSrcweir 
157cdf0e10cSrcweir                     Please use method getTarget() or getTargetComponent()
158cdf0e10cSrcweir                     to return the frame/controller or model to any interested
159cdf0e10cSrcweir                     user of the results of this load request.
160cdf0e10cSrcweir          */
161cdf0e10cSrcweir         css::uno::Reference< css::frame::XFrame > m_xTargetFrame;
162cdf0e10cSrcweir 
163cdf0e10cSrcweir         /** @short  contains the name of the target, in which the specified resource
164cdf0e10cSrcweir                     of this instance must be loaded.
165cdf0e10cSrcweir          */
166cdf0e10cSrcweir         ::rtl::OUString m_sTarget;
167cdf0e10cSrcweir 
168cdf0e10cSrcweir         /** @short  if m_sTarget is not a special one, this flags regulate searching
169cdf0e10cSrcweir                     of a suitable one.
170cdf0e10cSrcweir          */
171cdf0e10cSrcweir         sal_Int32 m_nSearchFlags;
172cdf0e10cSrcweir 
173cdf0e10cSrcweir         /** @short  contains all needed informations about the resource,
174cdf0e10cSrcweir                     which should be loaded.
175cdf0e10cSrcweir 
176cdf0e10cSrcweir             @descr  Inside this struct e.g. the URL, its type and filter name,
177cdf0e10cSrcweir                     the stream or a model directly are saved.
178cdf0e10cSrcweir          */
179cdf0e10cSrcweir         ::comphelper::MediaDescriptor m_lMediaDescriptor;
180cdf0e10cSrcweir 
181cdf0e10cSrcweir         /** @short  because the mediadescriptor contains the complete URL ... but
182cdf0e10cSrcweir                     some functionality need the structured version, we hold it twice :-(.
183cdf0e10cSrcweir          */
184cdf0e10cSrcweir         css::util::URL m_aURL;
185cdf0e10cSrcweir 
186cdf0e10cSrcweir         /** @short  enable/disable special features of a load request. */
187cdf0e10cSrcweir         EFeature m_eFeature;
188cdf0e10cSrcweir 
189cdf0e10cSrcweir         /** @short  classify the content, which should be loaded by this instance. */
190cdf0e10cSrcweir         EContentType m_eContentType;
191cdf0e10cSrcweir 
192cdf0e10cSrcweir         /** @short  it indicates, that the member m_xTargetFrame was new created for this
193cdf0e10cSrcweir                     load request and must be closed in case loading (not handling!)
194cdf0e10cSrcweir                     operation failed. The default value is sal_False!
195cdf0e10cSrcweir          */
196cdf0e10cSrcweir         sal_Bool m_bCloseFrameOnError;
197cdf0e10cSrcweir 
198cdf0e10cSrcweir         /** @short  it indicates, that the old document (which was located inside m_xBaseFrame
199cdf0e10cSrcweir                     in combination with the m_sTarget value "_self") was suspended.
200e9faf1d9Smseidel                     Normally it will be replaced by the new loaded document. But in case
201cdf0e10cSrcweir                     loading (not handling!) failed, it must be reactivated.
202cdf0e10cSrcweir                     The default value is sal_False!
203cdf0e10cSrcweir          */
204cdf0e10cSrcweir         sal_Bool m_bReactivateControllerOnError;
205cdf0e10cSrcweir 
206cdf0e10cSrcweir         /** @short  it holds one (!) asynchronous used contenthandler or frameloader
207cdf0e10cSrcweir                     alive, till the asynchronous operation will be finished.
208cdf0e10cSrcweir          */
209cdf0e10cSrcweir         css::uno::Reference< css::uno::XInterface > m_xAsynchronousJob;
210cdf0e10cSrcweir 
211cdf0e10cSrcweir         /** @short  holds the information about the finished load process.
212cdf0e10cSrcweir 
21307a3d7f1SPedro Giffuni             @descr  The content of m_xTargetFrame can't be used as valid indicator,
214cdf0e10cSrcweir                     (in case the micht existing old document was reactivated)
215cdf0e10cSrcweir                     we must hold the result of the load process explicitly.
216cdf0e10cSrcweir          */
217cdf0e10cSrcweir         sal_Bool m_bLoaded;
218cdf0e10cSrcweir 
219cdf0e10cSrcweir         /** @short      holds an XActionLock on the internal used task member.
220cdf0e10cSrcweir 
221cdf0e10cSrcweir             @seealso    m_xTargetFrame
222cdf0e10cSrcweir          */
223cdf0e10cSrcweir         ActionLockGuard m_aTargetLock;
224cdf0e10cSrcweir 
225cdf0e10cSrcweir         /** TODO document me ... */
226cdf0e10cSrcweir         void* m_pCheck;
227cdf0e10cSrcweir 
228cdf0e10cSrcweir 		QuietInteraction*	m_pQuietInteraction;
229cdf0e10cSrcweir 
230cdf0e10cSrcweir     //___________________________________________
231cdf0e10cSrcweir     // native interface
232cdf0e10cSrcweir 
233cdf0e10cSrcweir     public:
234cdf0e10cSrcweir 
235cdf0e10cSrcweir         /** @short  initialize a new instance of this load environment.
236cdf0e10cSrcweir 
237cdf0e10cSrcweir             @param  xSMGR
238a49f1911Smseidel                     reference to an uno service manager, which can be used internally
239a49f1911Smseidel                     to create own needed services on demand.
240cdf0e10cSrcweir 
241cdf0e10cSrcweir             @throw  Currently there is no reason to throw such exception!
242cdf0e10cSrcweir 
243cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
24407a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
245cdf0e10cSrcweir          */
246cdf0e10cSrcweir         LoadEnv(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR)
247cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
248cdf0e10cSrcweir 
249cdf0e10cSrcweir         //_______________________________________
250cdf0e10cSrcweir 
251cdf0e10cSrcweir         /** @short  deinitialize an instance of this class in the right way.
252cdf0e10cSrcweir          */
253cdf0e10cSrcweir         virtual ~LoadEnv();
254cdf0e10cSrcweir 
255cdf0e10cSrcweir         //_______________________________________
256cdf0e10cSrcweir 
257cdf0e10cSrcweir         /** @short  DRAFT TODO
258cdf0e10cSrcweir          */
259cdf0e10cSrcweir         static css::uno::Reference< css::lang::XComponent > loadComponentFromURL(const css::uno::Reference< css::frame::XComponentLoader >&    xLoader,
260cdf0e10cSrcweir                                                                                  const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
261cdf0e10cSrcweir                                                                                  const ::rtl::OUString&                                        sURL   ,
262cdf0e10cSrcweir                                                                                  const ::rtl::OUString&                                        sTarget,
263cdf0e10cSrcweir                                                                                        sal_Int32                                               nFlags ,
264cdf0e10cSrcweir                                                                                  const css::uno::Sequence< css::beans::PropertyValue >&        lArgs  )
265cdf0e10cSrcweir             throw(css::lang::IllegalArgumentException,
266cdf0e10cSrcweir                   css::io::IOException               ,
267cdf0e10cSrcweir                   css::uno::RuntimeException         );
268cdf0e10cSrcweir 
269cdf0e10cSrcweir         //_______________________________________
270cdf0e10cSrcweir 
271cdf0e10cSrcweir         /** @short  set some changeable parameters for a new load request.
272cdf0e10cSrcweir 
273cdf0e10cSrcweir             @descr  The parameter for targeting, the content description, and
274cdf0e10cSrcweir                     some environment specifier (UI, dispatch functionality)
275cdf0e10cSrcweir                     can be set here ... BEFORE the real load process is started
276cdf0e10cSrcweir                     by calling startLoading(). Of course a still running load request
277cdf0e10cSrcweir                     will be detected here and a suitable exception will be thrown.
278cdf0e10cSrcweir                     Such constellation can be detected outside by using provided
279cdf0e10cSrcweir                     synchronisation methods or callbacks.
280cdf0e10cSrcweir 
281cdf0e10cSrcweir             @param  sURL
282cdf0e10cSrcweir                     points to the resource, which should be loaded.
283cdf0e10cSrcweir 
284cdf0e10cSrcweir             @param  lMediaDescriptor
285cdf0e10cSrcweir                     contains additional informations for the following load request.
286cdf0e10cSrcweir 
287cdf0e10cSrcweir             @param  xBaseFrame
288cdf0e10cSrcweir                     points to the frame which must be used as start point for target search.
289cdf0e10cSrcweir 
290cdf0e10cSrcweir             @param  sTarget
291cdf0e10cSrcweir                     regulate searching/creating of frames, which should contain the
292cdf0e10cSrcweir                     new loaded component afterwards.
293cdf0e10cSrcweir 
294cdf0e10cSrcweir             @param  nSearchFlags
295cdf0e10cSrcweir                     regulate searching of targets, if sTarget is not a special one.
296cdf0e10cSrcweir 
297cdf0e10cSrcweir             @param  eFeature
298cdf0e10cSrcweir                     flag field, which enable/disable special features of this
299cdf0e10cSrcweir                     new instance for following load call.
300cdf0e10cSrcweir 
301cdf0e10cSrcweir             @param  eContentType
302cdf0e10cSrcweir                     classify the given content.
303cdf0e10cSrcweir                     This value is set to a default value "UNKNWON_CONTENT", which force
304cdf0e10cSrcweir                     an internal check, if this content is loadable or not.
305cdf0e10cSrcweir                     But may this check was already made by the caller of this method and
30607a3d7f1SPedro Giffuni                     passing this information to this LoadEnv instance can suppress this
307cdf0e10cSrcweir                     might expensive check.
30807a3d7f1SPedro Giffuni                     That can be useful in case this information is needed outside too,
30907a3d7f1SPedro Giffuni                     to decide if its necessary to create some resources for this load
310cdf0e10cSrcweir                     request ... or to reject the request imidiatly if it seems to be not
311cdf0e10cSrcweir                     loadable in general.
312cdf0e10cSrcweir 
313cdf0e10cSrcweir             @throw  A LoadEnvException e.g. if another load operation is till in progress
314cdf0e10cSrcweir                     or initialization of a new one fail by other reasons.
315cdf0e10cSrcweir                     The real reason, a suitable message and ID will be given here immidiatly.
316cdf0e10cSrcweir 
317cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
31807a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
319cdf0e10cSrcweir          */
320cdf0e10cSrcweir         virtual void initializeLoading(const ::rtl::OUString&                                           sURL            ,
321cdf0e10cSrcweir                                        const css::uno::Sequence< css::beans::PropertyValue >&           lMediaDescriptor,
322cdf0e10cSrcweir                                        const css::uno::Reference< css::frame::XFrame >&                 xBaseFrame      ,
323cdf0e10cSrcweir                                        const ::rtl::OUString&                                           sTarget         ,
324cdf0e10cSrcweir                                              sal_Int32                                                  nSearchFlags    ,
325cdf0e10cSrcweir                                              EFeature                                                   eFeature        = E_NO_FEATURE         ,
326cdf0e10cSrcweir                                              EContentType                                               eContentType    = E_UNSUPPORTED_CONTENT)
327cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
328cdf0e10cSrcweir 
329cdf0e10cSrcweir         //_______________________________________
330cdf0e10cSrcweir 
331cdf0e10cSrcweir         /** @short  start loading of the resource represented by this loadenv instance.
332cdf0e10cSrcweir 
333cdf0e10cSrcweir             @descr  There is no direct return value possible here. Because it depends
334cdf0e10cSrcweir                     from the usage of this instance! E.g. for loading a "visible component"
335cdf0e10cSrcweir                     a frame with a controller/model inside can be possible. For loading
336cdf0e10cSrcweir                     of a "non visible component" only an information about a successfully start
337cdf0e10cSrcweir                     can be provided.
33807a3d7f1SPedro Giffuni                     Further it can't be guaranteed, that the internal process runs synchronous.
339*796b7e2aSmseidel                     That's why we prefer using of specialized methods afterwards e.g. to:
340cdf0e10cSrcweir                         - wait till the internal job will be finished
341cdf0e10cSrcweir                           and get the results
342cdf0e10cSrcweir                         - or to let it run without any further control from outside.
343cdf0e10cSrcweir 
344cdf0e10cSrcweir             @throw  A LoadEnvException if start of the load process failed (because
345cdf0e10cSrcweir                     another is still in progress!).
346*796b7e2aSmseidel                     The reason, a suitable message and ID will be given here immediately.
347cdf0e10cSrcweir 
348cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
34907a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
350cdf0e10cSrcweir          */
351cdf0e10cSrcweir         virtual void startLoading()
352cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
353cdf0e10cSrcweir 
354cdf0e10cSrcweir         //_______________________________________
355cdf0e10cSrcweir 
356cdf0e10cSrcweir         /** @short  wait for an alreay running load request (started by calling
357cdf0e10cSrcweir                     startLoading() before).
358cdf0e10cSrcweir 
359cdf0e10cSrcweir             @descr  The timeout parameter can be used to wait some times only
360cdf0e10cSrcweir                     or forever. The return value indicates if the load request
361cdf0e10cSrcweir                     was finished during the specified timeout period.
362cdf0e10cSrcweir                     But it indicates not, if the load request was successfully or not!
363cdf0e10cSrcweir 
364cdf0e10cSrcweir             @param  nTimeout
365cdf0e10cSrcweir                     specify a timeout in [ms].
366cdf0e10cSrcweir                     A value 0 let it wait forever!
367cdf0e10cSrcweir 
368cdf0e10cSrcweir             @return sal_True if the started load process could be finished in time;
369cdf0e10cSrcweir                     sal_False if the specified time was over.
370cdf0e10cSrcweir 
371cdf0e10cSrcweir             @throw  ... currently not used :-)
372cdf0e10cSrcweir 
373cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
37407a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
375cdf0e10cSrcweir          */
376cdf0e10cSrcweir         virtual sal_Bool waitWhileLoading(sal_uInt32 nTimeout = 0)
377cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
378cdf0e10cSrcweir 
379cdf0e10cSrcweir         //_______________________________________
380cdf0e10cSrcweir         /** TODO document me ... */
381cdf0e10cSrcweir         virtual void cancelLoading()
382cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
383cdf0e10cSrcweir 
384cdf0e10cSrcweir         //_______________________________________
385cdf0e10cSrcweir         /** TODO document me ... */
386cdf0e10cSrcweir         virtual css::uno::Reference< css::frame::XFrame > getTarget() const;
387cdf0e10cSrcweir 
388cdf0e10cSrcweir         //_______________________________________
389cdf0e10cSrcweir         /** TODO document me ... */
390cdf0e10cSrcweir         virtual css::uno::Reference< css::lang::XComponent > getTargetComponent() const;
391cdf0e10cSrcweir /*
392cdf0e10cSrcweir     //___________________________________________
393cdf0e10cSrcweir     // helper uno interface!
394cdf0e10cSrcweir     // You have to use the native interface only!
395cdf0e10cSrcweir 
396cdf0e10cSrcweir     public:
397cdf0e10cSrcweir 
398cdf0e10cSrcweir         //_______________________________________
399cdf0e10cSrcweir         // frame.XLoadEventListener
400cdf0e10cSrcweir         virtual void SAL_CALL loadFinished(const css::uno::Reference< css::frame::XFrameLoader >& xLoader)
401cdf0e10cSrcweir             throw(css::uno::RuntimeException);
402cdf0e10cSrcweir 
403cdf0e10cSrcweir         virtual void SAL_CALL loadCancelled(const css::uno::Reference< css::frame::XFrameLoader >& xLoader)
404cdf0e10cSrcweir             throw(css::uno::RuntimeException);
405cdf0e10cSrcweir 
406cdf0e10cSrcweir         //_______________________________________
407cdf0e10cSrcweir         // frame.XDispatchResultListener
408cdf0e10cSrcweir         virtual void SAL_CALL dispatchFinished(const css::frame::DispatchResultEvent& aEvent)
409cdf0e10cSrcweir             throw(css::uno::RuntimeException);
410cdf0e10cSrcweir 
411cdf0e10cSrcweir         //_______________________________________
412cdf0e10cSrcweir         // lang.XEventListener
413cdf0e10cSrcweir         virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent)
414cdf0e10cSrcweir             throw(css::uno::RuntimeException);
415cdf0e10cSrcweir */
416cdf0e10cSrcweir 
417cdf0e10cSrcweir     //___________________________________________
418cdf0e10cSrcweir     // static interface
419cdf0e10cSrcweir 
420cdf0e10cSrcweir     public:
421cdf0e10cSrcweir 
422cdf0e10cSrcweir         /** @short      checks if the specified content can be handled by a
423cdf0e10cSrcweir                         ContentHandler only and is not related to a target frame,
424cdf0e10cSrcweir                         or if it can be loaded by a FrameLoader into a target frame
425cdf0e10cSrcweir                         as "visible" component.
426cdf0e10cSrcweir 
427cdf0e10cSrcweir             @descr      using:
428cdf0e10cSrcweir                             switch(classifyContent(...))
429cdf0e10cSrcweir                             {
430cdf0e10cSrcweir                                 case E_CAN_BE_HANDLED :
431cdf0e10cSrcweir                                     handleIt(...);
432cdf0e10cSrcweir                                     break;
433cdf0e10cSrcweir 
434cdf0e10cSrcweir                                 case E_CAN_BE_LOADED :
435cdf0e10cSrcweir                                     xFrame = locateTargetFrame();
436cdf0e10cSrcweir                                     loadIt(xFrame);
437cdf0e10cSrcweir                                     break;
438cdf0e10cSrcweir 
439cdf0e10cSrcweir                                 case E_NOT_A_CONTENT :
440cdf0e10cSrcweir                                 default              : throw ...;
441cdf0e10cSrcweir                             }
442cdf0e10cSrcweir 
443cdf0e10cSrcweir             @param      sURL
444cdf0e10cSrcweir                         describe the content.
445cdf0e10cSrcweir 
446cdf0e10cSrcweir             @param      lMediaDescriptor
447cdf0e10cSrcweir                         describe the content more detailed!
448cdf0e10cSrcweir 
449cdf0e10cSrcweir             @return     A suitable enum value, which classify the specified content.
450cdf0e10cSrcweir          */
451cdf0e10cSrcweir         static EContentType classifyContent(const ::rtl::OUString&                                 sURL            ,
452cdf0e10cSrcweir                                             const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor);
453cdf0e10cSrcweir 
454cdf0e10cSrcweir         /** TODO document me ... */
455cdf0e10cSrcweir         static  void initializeUIDefaults(
456cdf0e10cSrcweir                     const css::uno::Reference< css::lang::XMultiServiceFactory >& i_rSMGR,
457cdf0e10cSrcweir                     ::comphelper::MediaDescriptor& io_lMediaDescriptor,
458cdf0e10cSrcweir                     const bool _bUIMode,
459cdf0e10cSrcweir                     QuietInteraction** o_ppQuiteInteraction
460cdf0e10cSrcweir                 );
461cdf0e10cSrcweir 
462cdf0e10cSrcweir         /** TODO document me ... */
463cdf0e10cSrcweir         void impl_setResult(sal_Bool bResult);
464cdf0e10cSrcweir 
465cdf0e10cSrcweir         /** TODO document me ... */
466cdf0e10cSrcweir         css::uno::Reference< css::uno::XInterface > impl_searchLoader();
467cdf0e10cSrcweir 
468cdf0e10cSrcweir         //_______________________________________
469cdf0e10cSrcweir 
470cdf0e10cSrcweir         /** @short  it means; show the frame, bring it to front,
471cdf0e10cSrcweir                     might set the right icon etcpp. in case loading was
472cdf0e10cSrcweir                     successfully or reactivate a might existing old document or
473cdf0e10cSrcweir                     close the frame if it was created before in case loading failed.
474cdf0e10cSrcweir 
475cdf0e10cSrcweir             @throw  A LoadEnvException only in cases, where an internal error indicates,
476cdf0e10cSrcweir                     that the complete load environment seems to be not useable in general.
477cdf0e10cSrcweir                     In such cases a RuntimeException would be to hard for the outside code :-)
478cdf0e10cSrcweir 
479cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
48007a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
481cdf0e10cSrcweir          */
482cdf0e10cSrcweir         void impl_reactForLoadingState()
483cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
484cdf0e10cSrcweir 
485cdf0e10cSrcweir     //___________________________________________
486cdf0e10cSrcweir     // private helper
487cdf0e10cSrcweir 
488cdf0e10cSrcweir     private:
489cdf0e10cSrcweir 
490cdf0e10cSrcweir         /** @short  tries to detect the type and the filter of the specified content.
491cdf0e10cSrcweir 
492cdf0e10cSrcweir             @descr  This method update the available media descriptor of this instance,
493cdf0e10cSrcweir                     so it contains the right type, a corresponding filter, may a
494cdf0e10cSrcweir                     valid frame loader etc. In case detection failed, this descriptor
495cdf0e10cSrcweir                     is corrected first, before a suitable exception will be thrown.
49630acf5e8Spfg                     (Excepting a RuntimeException occurs!)
497cdf0e10cSrcweir 
498cdf0e10cSrcweir             @attention  Not all types we know, are supported by filters. So it does not
499cdf0e10cSrcweir                         indicates an error, if no suitable filter(loader etcpp will be found
500cdf0e10cSrcweir                         for a type. But a type must be detected for the specified content.
50107a3d7f1SPedro Giffuni                         Otherwise its an error and loading can't be finished successfully.
502cdf0e10cSrcweir 
503cdf0e10cSrcweir             @throw  A LoadEnvException if detection failed.
504cdf0e10cSrcweir 
505cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
50607a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
507cdf0e10cSrcweir          */
508cdf0e10cSrcweir         void impl_detectTypeAndFilter()
509cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
510cdf0e10cSrcweir 
511cdf0e10cSrcweir         //_______________________________________
512cdf0e10cSrcweir 
513cdf0e10cSrcweir         /** @short  tries to ask user for it's filter decision in case
514cdf0e10cSrcweir                     normal detection failed.
515cdf0e10cSrcweir 
516cdf0e10cSrcweir             @descr  We use a may existing interaction handler to do so.
517cdf0e10cSrcweir 
518cdf0e10cSrcweir             @return [string]
519cdf0e10cSrcweir                     the type selected by the user.
520cdf0e10cSrcweir 
521a49f1911Smseidel             @attention  Internally we update the member m_lMediaDescriptor!
522cdf0e10cSrcweir          */
523cdf0e10cSrcweir         ::rtl::OUString impl_askUserForTypeAndFilterIfAllowed()
524cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
525cdf0e10cSrcweir 
526cdf0e10cSrcweir         //_______________________________________
527cdf0e10cSrcweir 
528cdf0e10cSrcweir         /** @short  tries to use ContentHandler objects for loading.
529cdf0e10cSrcweir 
530cdf0e10cSrcweir             @descr  It searches for a suitable content handler object, registered
531cdf0e10cSrcweir                     for the detected content type (must be done before by calling
532cdf0e10cSrcweir                     impl_detectTypeAndFilter()). Because such handler does not depend
533cdf0e10cSrcweir                     from a real target frame, location of such frame will be
53407a3d7f1SPedro Giffuni                     suppressed here.
535cdf0e10cSrcweir                     In case handle failed all new created resources will be
536cdf0e10cSrcweir                     removed before a suitable exception is thrown.
53730acf5e8Spfg                     (Excepting a RuntimeException occurs!)
538cdf0e10cSrcweir 
539cdf0e10cSrcweir             @return TODO
540cdf0e10cSrcweir 
541cdf0e10cSrcweir             @throw  A LoadEnvException if handling failed.
542cdf0e10cSrcweir 
543cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
54407a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
545cdf0e10cSrcweir          */
546cdf0e10cSrcweir         sal_Bool impl_handleContent()
547cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
548cdf0e10cSrcweir 
549cdf0e10cSrcweir         //_______________________________________
550cdf0e10cSrcweir 
551cdf0e10cSrcweir         /** @short  tries to use FrameLoader objects for loading.
552cdf0e10cSrcweir 
553cdf0e10cSrcweir             @descr  First the target frame will be located. If it could be found
554cdf0e10cSrcweir                     or new created a filter/frame loader will be instanciated and
555cdf0e10cSrcweir                     used to load the content into this frame.
556cdf0e10cSrcweir                     In case loading failed all new created resources will be
557cdf0e10cSrcweir                     removed before a suitable exception is thrown.
55830acf5e8Spfg                     (Excepting a RuntimeException occurs!)
559cdf0e10cSrcweir 
560cdf0e10cSrcweir             @return TODO
561cdf0e10cSrcweir 
562cdf0e10cSrcweir             @throw  A LoadEnvException if loading failed.
563cdf0e10cSrcweir 
564cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
56507a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
566cdf0e10cSrcweir          */
567cdf0e10cSrcweir         sal_Bool impl_loadContent()
568cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
569cdf0e10cSrcweir 
570cdf0e10cSrcweir         //_______________________________________
571cdf0e10cSrcweir 
572cdf0e10cSrcweir         /** @short  checks if the specified content is already loaded.
573cdf0e10cSrcweir 
574cdf0e10cSrcweir             @descr  It depends from the set target information, if such
575cdf0e10cSrcweir                     search is allowed or not! So this method checks first,
576cdf0e10cSrcweir                     if the target is the special one "_default".
577cdf0e10cSrcweir                     If not it returns with an empty result immidatly!
578cdf0e10cSrcweir                     In case search is allowed, an existing document with the
579cdf0e10cSrcweir                     same URL is searched. If it could be found, the corresponding
580cdf0e10cSrcweir                     view will get the focus and this method return the corresponding frame.
581cdf0e10cSrcweir                     Optional jumpmarks will be accepted here too. So the
582cdf0e10cSrcweir                     view of the document will be updated to show the position
583cdf0e10cSrcweir                     inside the document, which is related to the jumpmark.
584cdf0e10cSrcweir 
585cdf0e10cSrcweir             @return A valid reference to the target frame, which contains the already loaded content
586cdf0e10cSrcweir                     and could be activated successfully. An empty reference oterwhise.
587cdf0e10cSrcweir 
588cdf0e10cSrcweir             @throw  A LoadEnvException only in cases, where an internal error indicates,
589cdf0e10cSrcweir                     that the complete load environment seems to be not useable in general.
590cdf0e10cSrcweir                     In such cases a RuntimeException would be to hard for the outside code :-)
591cdf0e10cSrcweir 
592cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
59307a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
594cdf0e10cSrcweir          */
595cdf0e10cSrcweir         css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded()
596cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
597cdf0e10cSrcweir 
598cdf0e10cSrcweir         //_______________________________________
599cdf0e10cSrcweir 
600cdf0e10cSrcweir         /** @short  search for any target frame, which seems to be useable
601cdf0e10cSrcweir                     for this load request.
602cdf0e10cSrcweir 
603cdf0e10cSrcweir             @descr  Because this special feature is bound to the target specifier "_default"
6044e7d57d8Smseidel                     it's checked inside first. If it's not set => this method return an empty
6054e7d57d8Smseidel                     reference. Otherwise any currently existing frame will be analyzed, if
606cdf0e10cSrcweir                     it can be used here. The following rules exists:
607cdf0e10cSrcweir 
608cdf0e10cSrcweir                     <ul>
609cdf0e10cSrcweir                         <li>The frame must be empty ...</li>
610cdf0e10cSrcweir                         <li>or contains an empty document of the same application module
611cdf0e10cSrcweir                             which the new document will have (Note: the filter of the new content
612cdf0e10cSrcweir                             must be well known here!)</li>
613cdf0e10cSrcweir                         <li>and(!) this target must not be already used by any other load request.</li>
614cdf0e10cSrcweir                     </ul>
615cdf0e10cSrcweir 
616*796b7e2aSmseidel                     If a suitable target is located it will be locked. That's why the last rule
617cdf0e10cSrcweir                     exists! If this method returns a valid frame reference, it was locked to be useable
618cdf0e10cSrcweir                     for this load request only. (Dont forget to reset this state later!)
619cdf0e10cSrcweir                     Concurrent LoadEnv instances can synchronize her work be using such locks :-) HOPEFULLY
620cdf0e10cSrcweir 
621cdf0e10cSrcweir             @throw  A LoadEnvException only in cases, where an internal error indicates,
622cdf0e10cSrcweir                     that the complete load environment seems to be not useable in general.
623cdf0e10cSrcweir                     In such cases a RuntimeException would be to hard for the outside code :-)
624cdf0e10cSrcweir 
625cdf0e10cSrcweir             @throw  A RuntimeException in case any internal process indicates, that
62607a3d7f1SPedro Giffuni                     the whole runtime can't be used any longer.
627cdf0e10cSrcweir          */
628cdf0e10cSrcweir         css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget()
629cdf0e10cSrcweir             throw(LoadEnvException, css::uno::RuntimeException);
630cdf0e10cSrcweir 
631cdf0e10cSrcweir         //_______________________________________
632cdf0e10cSrcweir 
633cdf0e10cSrcweir         /** @short  because showing of a frame is needed more then once ...
63407a3d7f1SPedro Giffuni                     it's implemented as an separate method .-)
635cdf0e10cSrcweir 
636cdf0e10cSrcweir             @descr  Note: Showing of a frame is bound to a special feature ...
637cdf0e10cSrcweir                     a) If we recycle any existing frame, we must bring it to front.
63807a3d7f1SPedro Giffuni                        Showing of such frame isn't needed really .. because we recycle
639cdf0e10cSrcweir                        visible frames only!
640cdf0e10cSrcweir                     b) If the document was already shown (e.g. by our progress implementation)
641cdf0e10cSrcweir                        we do nothing here. The reason  behind: The document was already shown ..
642cdf0e10cSrcweir                        and it was already make a top window ...
643cdf0e10cSrcweir                        If the user activated another frame inbetween (because loading needed some time)
644cdf0e10cSrcweir                        it's not allowed to disturb the user again. Then the frame must resists in the background.
645cdf0e10cSrcweir                     c) If the frame was not shown before ... but loading of a visible document into this frame
646cdf0e10cSrcweir                        was finished ... we need both actions: setVisible() and toFront().
647cdf0e10cSrcweir 
648cdf0e10cSrcweir             @param  xWindow
649cdf0e10cSrcweir                     points to the container window of a frame.
650cdf0e10cSrcweir 
651cdf0e10cSrcweir             @param  bForceToFront
652cdf0e10cSrcweir                     if it's set to sal_False ... showing of the window is done more intelligent.
653cdf0e10cSrcweir                     setVisible() is called only if the window was not shown before.
654cdf0e10cSrcweir                     This mode is needed by b) and c)
655cdf0e10cSrcweir                     If it's set to sal_True ... both actions has to be done: setVisible(), toFront()!
656cdf0e10cSrcweir                     This mode is needed by a)
657cdf0e10cSrcweir          */
658cdf0e10cSrcweir         void impl_makeFrameWindowVisible(const css::uno::Reference< css::awt::XWindow >& xWindow      ,
659cdf0e10cSrcweir                                                sal_Bool                                  bForceToFront);
660cdf0e10cSrcweir 
661cdf0e10cSrcweir         //_______________________________________
662cdf0e10cSrcweir 
663cdf0e10cSrcweir         /** @short  checks weather a frame is already used for another load request or not.
664cdf0e10cSrcweir 
66507a3d7f1SPedro Giffuni             @descr  Such frames can't be used for our "recycle feature"!
666cdf0e10cSrcweir 
667cdf0e10cSrcweir             @param  xFrame
668cdf0e10cSrcweir                     the frame, which should be checked.
669cdf0e10cSrcweir 
670cdf0e10cSrcweir             @return [sal_Bool]
671cdf0e10cSrcweir                     sal_True if this frame is already used for loading,
672cdf0e10cSrcweir                     sal_False otherwise.
673cdf0e10cSrcweir          */
674cdf0e10cSrcweir         sal_Bool impl_isFrameAlreadyUsedForLoading(const css::uno::Reference< css::frame::XFrame >& xFrame) const;
675cdf0e10cSrcweir 
676cdf0e10cSrcweir         //_______________________________________
677cdf0e10cSrcweir 
678cdf0e10cSrcweir         /** @short  try to determine the used application module
679cdf0e10cSrcweir                     of this load request and applay right position and size
680cdf0e10cSrcweir                     for this document window ... hopefully before we show it .-)
681cdf0e10cSrcweir          */
682cdf0e10cSrcweir         void impl_applyPersistentWindowState(const css::uno::Reference< css::awt::XWindow >& xWindow);
683cdf0e10cSrcweir 
684cdf0e10cSrcweir         //_______________________________________
685cdf0e10cSrcweir 
686cdf0e10cSrcweir         /** @short  determine if it's allowed to open new document frames.
687cdf0e10cSrcweir          */
688cdf0e10cSrcweir         sal_Bool impl_furtherDocsAllowed();
689cdf0e10cSrcweir 
690cdf0e10cSrcweir         //_______________________________________
691cdf0e10cSrcweir 
692cdf0e10cSrcweir         /** @short  jumps to the requested bookmark inside a given document.
693cdf0e10cSrcweir          */
694cdf0e10cSrcweir         void impl_jumpToMark(const css::uno::Reference< css::frame::XFrame >& xFrame,
695cdf0e10cSrcweir                              const css::util::URL&                            aURL  );
696cdf0e10cSrcweir };
697cdf0e10cSrcweir 
698cdf0e10cSrcweir } // namespace framework
699cdf0e10cSrcweir 
700cdf0e10cSrcweir #endif // __FRAMEWORK_LOADENV_LOADENV_HXX_
701