summaryrefslogtreecommitdiffstats
path: root/framework/source/inc/loadenv/loadenv.hxx
blob: baad8fac9b7fe1aee1f285f974155a1b40ee6388 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */
#pragma once

#include <loadenv/actionlockguard.hxx>

#include <com/sun/star/frame/XComponentLoader.hpp>
#include <com/sun/star/frame/XFrame.hpp>
#include <com/sun/star/uno/XComponentContext.hpp>
#include <com/sun/star/util/URL.hpp>
#include <rtl/ref.hxx>
#include <unotools/mediadescriptor.hxx>
#include <o3tl/typed_flags_set.hxx>


/** @short  enable/disable special features
            of a load request.

    @desrc  Such features must outcome without
            any special parameters.
            To make enabling/disabling of
            features very easy (e.g. at the ctor of
             this class) these values must be combinable
            as flags. That means: its values must be in
            range of [2^n]!
 */
enum class LoadEnvFeatures
{
    /// we should be informed, if no feature is enabled :-)
    NONE = 0,
    /// enable using of UI elements during loading (means progress, interaction handler etcpp.)
    WorkWithUI = 1,
    /// enable loading of resources, which are not related to a target frame! (see concept of ContentHandler)
    AllowContentHandler = 2
};
namespace o3tl {
    template<> struct typed_flags<LoadEnvFeatures> : is_typed_flags<LoadEnvFeatures, 0x3> {};
}


namespace framework {

class QuietInteraction;

/** @short  implements general mechanism for loading documents.

    @descr  An instance of this class can be used inside the API calls
            XComponentLoader::loadComponentFromURL() and
            XDispatch::dispatch().
 */
class LoadEnv
{
public:
    /** @short  classify a content.

        @descr  The load environment must know, if a content
                is related to a target frame or not. Only "visible"
                components, which fulfill the requirements of the
                model-controller-view paradigm can be loaded into a frame.
                Such contents are classified as E_CAN_BE_LOADED.

                But e.g. for the dispatch framework exists special ContentHandler
                objects, which can load a content in "non visible" mode ...
                and do not need a target frame for its operation. Such
                ContentHandler e.g. plays sounds.
                Such contents are classified as E_CAN_BE_HANDLED.

                And last but not least a content can be "not valid" in general.
     */
    enum EContentType
    {
        /// identifies a content, which seems to be invalid in general
        E_UNSUPPORTED_CONTENT,
        /// identifies a content, which can be used with a ContentHandler and is not related to a target frame
        E_CAN_BE_HANDLED,
        /// identifies a content, which can be loaded into a target frame
        E_CAN_BE_LOADED,
        /// special mode for non real loading, In such case the model is given directly!
        E_CAN_BE_SET
    };

private:
    mutable osl::Mutex m_mutex;

    /** @short  reference to a uno service manager, which must be used
                to created on needed services on demand.
     */
    css::uno::Reference< css::uno::XComponentContext > m_xContext;

    /** @short  points to the frame, which uses this LoadEnv object
                and must be used to start target search there.
     */
    css::uno::Reference< css::frame::XFrame > m_xBaseFrame;

    /** @short  points to the frame, into which the new component was loaded.

        @descr  Note: This reference will be empty if loading failed
                or a non visible content was loaded!
                It can be the same frame as m_xBaseFrame it describe, in case
                the target "_self", "" or the search flag "SELF" was used.
                Otherwise it's the new created or recycled frame, which was
                used for loading and contains further the new component.

                Please use method getTarget() or getTargetComponent()
                to return the frame/controller or model to any interested
                user of the results of this load request.
     */
    css::uno::Reference< css::frame::XFrame > m_xTargetFrame;

    /** @short  contains the name of the target, in which the specified resource
                of this instance must be loaded.
     */
    OUString m_sTarget;

    /** @short  if m_sTarget is not a special one, this flags regulate searching
                of a suitable one.
     */
    sal_Int32 m_nSearchFlags;

    /** @short  contains all needed information about the resource,
                which should be loaded.

        @descr  Inside this struct e.g. the URL, its type and filter name,
                the stream or a model directly are saved.
     */
    utl::MediaDescriptor m_lMediaDescriptor;

    /** @short  because the mediadescriptor contains the complete URL ... but
                some functionality need the structured version, we hold it twice :-(.
     */
    css::util::URL m_aURL;

    /** @short  enable/disable special features of a load request. */
    LoadEnvFeatures m_eFeature;

    /** @short  classify the content, which should be loaded by this instance. */
    EContentType m_eContentType;

    /** @short  it indicates, that the member m_xTargetFrame was new created for this
                load request and must be closed in case loading (not handling!)
                operation failed. The default value is sal_False!
     */
    bool m_bCloseFrameOnError;

    /** @short  it indicates, that the old document (which was located inside m_xBaseFrame
                in combination with the m_sTarget value "_self") was suspended.
                Normally it will be replaced by the new loaded document. But in case
                loading (not handling!) failed, it must be reactivated.
                The default value is sal_False!
     */
    bool m_bReactivateControllerOnError;

    /** @short  it holds one (!) asynchronous used contenthandler or frameloader
                alive, till the asynchronous operation will be finished.
     */
    css::uno::Reference< css::uno::XInterface > m_xAsynchronousJob;

    /** @short  holds the information about the finished load process.

        @descr  The content of m_xTargetFrame can't be used as valid indicator,
                (in case the existing old document was reactivated)
                we must hold the result of the load process explicitly.
     */
    bool m_bLoaded;

    /** @short  If we already brought it to front; do not do that again
                (the user could switch elsewhere after the first activation,
                and we shouldn't nag them again).
     */
    bool m_bFocusedAndToFront = false;

    /** @short      holds an XActionLock on the internal used task member.

        @seealso    m_xTargetFrame
     */
    ActionLockGuard m_aTargetLock;

    rtl::Reference<QuietInteraction> m_pQuietInteraction;

public:

    /** @short  initialize a new instance of this load environment.

        @param  xContext
                reference to a uno service manager, which can be used internally
                to create on needed services on demand.

        @throw  Currently there is no reason to throw such exception!

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    LoadEnv(css::uno::Reference< css::uno::XComponentContext >  xContext);

    /** @short  deinitialize an instance of this class in the right way.
     */
    ~LoadEnv();

    /// @throws css::lang::IllegalArgumentException
    /// @throws css::io::IOException
    /// @throws css::uno::RuntimeException
    static css::uno::Reference< css::lang::XComponent > loadComponentFromURL(const css::uno::Reference< css::frame::XComponentLoader >&    xLoader,
                                                                             const css::uno::Reference< css::uno::XComponentContext >&     xContext,
                                                                             const OUString&                                        sURL   ,
                                                                             const OUString&                                        sTarget,
                                                                                   sal_Int32                                               nFlags ,
                                                                             const css::uno::Sequence< css::beans::PropertyValue >&        lArgs  );

    /** @short  start loading of a resource

        @descr  The parameter for targeting, the content description, and
                some environment specifier (UI, dispatch functionality)
                can be set here. Of course a still running load request
                will be detected here and a suitable exception will be thrown.
                Such constellation can be detected outside by using provided
                synchronisation methods or callbacks.

                There is no direct return value possible here. Because it depends
                from the usage of this instance! E.g. for loading a "visible component"
                a frame with a controller/model inside can be possible. For loading
                of a "non visible component" only an information about a successfully start
                can be provided.
                Further it can't be guaranteed, that the internal process runs synchronous.
                that's why we prefer using of specialized methods afterwards e.g. to:
                    - wait till the internal job will be finished
                      and get the results
                    - or to let it run without any further control from outside.

        @param  sURL
                points to the resource, which should be loaded.

        @param  lMediaDescriptor
                contains additional information for the following load request.

        @param  xBaseFrame
                points to the frame which must be used as start point for target search.

        @param  sTarget
                regulate searching/creating of frames, which should contain the
                new loaded component afterwards.

        @param  nSearchFlags
                regulate searching of targets, if sTarget is not a special one.

        @param  eFeature
                flag field, which enable/disable special features of this
                new instance for following load call.

        @throw  A LoadEnvException e.g. if another load operation is till in progress
                or initialization of a new one fail by other reasons.
                The real reason, a suitable message and ID will be given here immediately.

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    void startLoading(const OUString&                                           sURL            ,
                           const css::uno::Sequence< css::beans::PropertyValue >&    lMediaDescriptor,
                           const css::uno::Reference< css::frame::XFrame >&          xBaseFrame      ,
                           const OUString&                                           sTarget         ,
                                 sal_Int32                                           nSearchFlags    ,
                                 LoadEnvFeatures                                     eFeature        = LoadEnvFeatures::NONE);

    /** @short  wait for an already running load request (started by calling
                startLoading() before).

        @descr  The timeout parameter can be used to wait some times only
                or forever. The return value indicates if the load request
                was finished during the specified timeout period.
                But it indicates not, if the load request was successful or not!

        @param  nTimeout
                specify a timeout in [ms].
                A value 0 let it wait forever!

        @return sal_True if the started load process could be finished in time;
                sal_False if the specified time was over.

        @throw  ... currently not used :-)

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    bool waitWhileLoading(sal_uInt32 nTimeout = 0);

    /** TODO document me ... */
    css::uno::Reference< css::lang::XComponent > getTargetComponent() const;

public:

    /** @short      checks if the specified content can be handled by a
                    ContentHandler only and is not related to a target frame,
                    or if it can be loaded by a FrameLoader into a target frame
                    as "visible" component.

        @descr      using:
                        switch(classifyContent(...))
                        {
                            case E_CAN_BE_HANDLED :
                                handleIt(...);
                                break;

                            case E_CAN_BE_LOADED :
                                xFrame = locateTargetFrame();
                                loadIt(xFrame);
                                break;

                            case E_NOT_A_CONTENT :
                            default              : throw ...;
                        }

        @param      sURL
                    describe the content.

        @param      lMediaDescriptor
                    describe the content more detailed!

        @return     A suitable enum value, which classify the specified content.
     */
    static EContentType classifyContent(const OUString&                                 sURL            ,
                                        const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor);

    /** TODO document me ... */
    static  void initializeUIDefaults(
                const css::uno::Reference< css::uno::XComponentContext >& i_rxContext,
                utl::MediaDescriptor& io_lMediaDescriptor,
                const bool _bUIMode,
                rtl::Reference<QuietInteraction>* o_ppQuiteInteraction
            );

    /** TODO document me ... */
    void impl_setResult(bool bResult);

    /** TODO document me ... */
    css::uno::Reference< css::uno::XInterface > impl_searchLoader();

    /** @short  it means; show the frame, bring it to front,
                might set the right icon etcpp. in case loading was
                successfully or reactivate a might existing old document or
                close the frame if it was created before in case loading failed.

        @throw  A LoadEnvException only in cases, where an internal error indicates,
                that the complete load environment seems to be not usable in general.
                In such cases a RuntimeException would be to hard for the outside code :-)

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    void impl_reactForLoadingState();

private:
    void start();

    /** @short  tries to detect the type and the filter of the specified content.

        @descr  This method update the available media descriptor of this instance,
                so it contains the right type, a corresponding filter, may a
                valid frame loader etc. In case detection failed, this descriptor
                is corrected first, before a suitable exception will be thrown.
                (Excepting a RuntimeException occurrence!)

        @attention  Not all types we know, are supported by filters. So it does not
                    indicates an error, if no suitable filter(loader etcpp will be found
                    for a type. But a type must be detected for the specified content.
                    Otherwise it's an error and loading can't be finished successfully.

        @throw  A LoadEnvException if detection failed.

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    void impl_detectTypeAndFilter();

    /** @short  tries to use ContentHandler objects for loading.

        @descr  It searches for a suitable content handler object, registered
                for the detected content type (must be done before by calling
                impl_detectTypeAndFilter()). Because such handler does not depend
                from a real target frame, location of such frame will be
                suppressed here.
                In case handle failed all new created resources will be
                removed before a suitable exception is thrown.
                (Excepting a RuntimeException occurrence!)

        @return TODO

        @throw  A LoadEnvException if handling failed.

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    bool impl_handleContent();

    /** @short  tries to use FrameLoader objects for loading.

        @descr  First the target frame will be located. If it could be found
                or new created a filter/frame loader will be instantiated and
                used to load the content into this frame.
                In case loading failed all new created resources will be
                removed before a suitable exception is thrown.
                (Excepting a RuntimeException occurrence!)

        @return TODO

        @throw  A LoadEnvException if loading failed.

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    bool impl_loadContent();

    /** @short  checks if the specified content is already loaded.

        @descr  It depends from the set target information, if such
                search is allowed or not! So this method checks first,
                if the target is the special one "_default".
                If not it returns with an empty result immediately!
                In case search is allowed, an existing document with the
                same URL is searched. If it could be found, the corresponding
                view will get the focus and this method return the corresponding frame.
                Optional jumpmarks will be accepted here too. So the
                view of the document will be updated to show the position
                inside the document, which is related to the jumpmark.

        @return A valid reference to the target frame, which contains the already loaded content
                and could be activated successfully. An empty reference otherwise.

        @throw  A LoadEnvException only in cases, where an internal error indicates,
                that the complete load environment seems to be not usable in general.
                In such cases a RuntimeException would be to hard for the outside code :-)

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded();

    /** @short  search for any target frame, which seems to be usable
                for this load request.

        @descr  Because this special feature is bound to the target specifier "_default"
                its checked inside first. If it's not set => this method return an empty
                reference. Otherwise any currently existing frame will be analyzed, if
                it can be used here. The following rules exists:

                <ul>
                    <li>The frame must be empty ...</li>
                    <li>or contains an empty document of the same application module
                        which the new document will have (Note: the filter of the new content
                        must be well known here!)</li>
                    <li>and(!) this target must not be already used by any other load request.</li>
                </ul>

                If a suitable target is located it will be locked. That's why the last rule
                exists! If this method returns a valid frame reference, it was locked to be usable
                for this load request only. (Don't forget to reset this state later!)
                Concurrent LoadEnv instances can synchronize her work be using such locks :-) HOPEFULLY

        @throw  A LoadEnvException only in cases, where an internal error indicates,
                that the complete load environment seems to be not usable in general.
                In such cases a RuntimeException would be to hard for the outside code :-)

        @throw  A RuntimeException in case any internal process indicates, that
                the whole runtime can't be used any longer.
     */
    css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget();

    /** @short  because showing of a frame is needed more than once...
                it's implemented as a separate method .-)

        @descr  Note: Showing of a frame is bound to a special feature...
                a) If we recycle any existing frame, we must bring it to front.
                   Showing of such frame is not needed really... because we recycle
                   visible frames only!
                b) If the document was already shown (e.g. by our progress implementation)
                   we do nothing here. The reason behind: The document was already shown...
                   and it was already make a top window...
                   If the user activated another frame inbetween (because loading needed some time)
                   it's not allowed to disturb the user again. Then the frame must resists in the background.
                c) If the frame was not shown before... but loading of a visible document into this frame
                   was finished... we need both actions: setVisible() and toFront().

        @param  xWindow
                points to the container window of a frame.

        @param  bForceToFront
                if it's set to sal_False... showing of the window is done more intelligent.
                setVisible() is called only if the window was not shown before.
                This mode is needed by b) and c)
                If it's set to sal_True... both actions has to be done: setVisible(), toFront()!
                This mode is needed by a)
     */
    void impl_makeFrameWindowVisible(const css::uno::Reference< css::awt::XWindow >& xWindow      ,
                                           bool                                  bForceToFront);

    /** @short  checks whether a frame is already used for another load request or not.

        @descr  Such frames can't be used for our "recycle feature"!

        @param  xFrame
                the frame, which should be checked.

        @return [sal_Bool]
                sal_True if this frame is already used for loading,
                sal_False otherwise.
     */
    bool impl_isFrameAlreadyUsedForLoading(const css::uno::Reference< css::frame::XFrame >& xFrame) const;

    /** @short  try to determine the used application module
                of this load request and apply right position and size
                for this document window... hopefully before we show it .-)
     */
    void impl_applyPersistentWindowState(const css::uno::Reference< css::awt::XWindow >& xWindow);

    /** @short  determine if it's allowed to open new document frames.
     */
    bool impl_furtherDocsAllowed();

    /** @short  jumps to the requested bookmark inside a given document.
     */
    void impl_jumpToMark(const css::uno::Reference< css::frame::XFrame >& xFrame,
                         const css::util::URL&                            aURL  );

    /** @short  determine if this loader has an interactive dialog shown before
                loading the document.
     */
    bool impl_filterHasInteractiveDialog() const;

    /** @short  checks if this should bring to front and get focus on load,
                according to user settings and to the load flags.
     */
    bool shouldFocusAndToFront() const;
};

} // namespace framework

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */