| /************************************************************** | |
| * | |
| * 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 | |
| * | |
| * Unless required by applicable law or agreed to in writing, | |
| * software distributed under the License is distributed on an | |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| * KIND, either express or implied. See the License for the | |
| * specific language governing permissions and limitations | |
| * under the License. | |
| * | |
| *************************************************************/ | |
| #ifndef __FRAMEWORK_LOADENV_LOADENV_HXX_ | |
| #define __FRAMEWORK_LOADENV_LOADENV_HXX_ | |
| //_______________________________________________ | |
| // includes of own project | |
| #include <loadenv/loadenvexception.hxx> | |
| #include <loadenv/actionlockguard.hxx> | |
| #include <threadhelp/threadhelpbase.hxx> | |
| //_______________________________________________ | |
| // includes of uno interface | |
| #include <com/sun/star/lang/XMultiServiceFactory.hpp> | |
| #include <com/sun/star/frame/XComponentLoader.hpp> | |
| #include <com/sun/star/frame/XFrameLoader.hpp> | |
| #include <com/sun/star/frame/XLoadEventListener.hpp> | |
| #include <com/sun/star/frame/XDispatchResultListener.hpp> | |
| #include <com/sun/star/frame/XFrame.hpp> | |
| #include <com/sun/star/util/URL.hpp> | |
| #ifndef _COM_SUN_STAR_LANG_IllegalArgumentException_HPP_ | |
| #include <com/sun/star/lang/IllegalArgumentException.hpp> | |
| #endif | |
| #ifndef _COM_SUN_STAR_IO_IOException_HPP_ | |
| #include <com/sun/star/io/IOException.hpp> | |
| #endif | |
| //_______________________________________________ | |
| // includes of an other project | |
| #include <comphelper/mediadescriptor.hxx> | |
| #include <comphelper/sequenceashashmap.hxx> | |
| #include <cppuhelper/implbase2.hxx> | |
| //_______________________________________________ | |
| // namespace | |
| namespace framework{ | |
| namespace css = ::com::sun::star; | |
| class QuietInteraction; | |
| //_______________________________________________ | |
| // definitions | |
| /** @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() | |
| (of course in its derived interfaces too :-)). | |
| @author as96863 | |
| */ | |
| class LoadEnv : private ThreadHelpBase | |
| { | |
| //___________________________________________ | |
| // structs, types, etc. | |
| public: | |
| /** @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 EFeature | |
| { | |
| /// we should be informed, if no feature is enabled :-) | |
| E_NO_FEATURE = 0, | |
| /// enable using of UI elements during loading (means progress, interaction handler etcpp.) | |
| E_WORK_WITH_UI = 1, | |
| /// enable loading of resources, which are not related to a target frame! (see concept of ContentHandler) | |
| E_ALLOW_CONTENTHANDLER = 2 | |
| }; | |
| //_______________________________________ | |
| /** @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 full fill 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 | |
| }; | |
| //___________________________________________ | |
| // member | |
| private: | |
| /** @short reference to an uno service manager, which must be used | |
| to created on needed services on demand. | |
| */ | |
| css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR; | |
| /** @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. | |
| */ | |
| ::rtl::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 informations 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. | |
| */ | |
| ::comphelper::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. */ | |
| EFeature 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! | |
| */ | |
| sal_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! | |
| */ | |
| sal_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 might existing old document was reactivated) | |
| we must hold the result of the load process explicitly. | |
| */ | |
| sal_Bool m_bLoaded; | |
| /** @short holds an XActionLock on the internal used task member. | |
| @seealso m_xTargetFrame | |
| */ | |
| ActionLockGuard m_aTargetLock; | |
| /** TODO document me ... */ | |
| void* m_pCheck; | |
| QuietInteraction* m_pQuietInteraction; | |
| //___________________________________________ | |
| // native interface | |
| public: | |
| /** @short initialize a new instance of this load environment. | |
| @param xSMGR | |
| reference to an uno service manager, which can be used internally | |
| to create own 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(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR); | |
| //_______________________________________ | |
| /** @short deinitialize an instance of this class in the right way. | |
| */ | |
| virtual ~LoadEnv(); | |
| //_______________________________________ | |
| /** @short DRAFT TODO | |
| */ | |
| static css::uno::Reference< css::lang::XComponent > loadComponentFromURL(const css::uno::Reference< css::frame::XComponentLoader >& xLoader, | |
| const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR , | |
| const ::rtl::OUString& sURL , | |
| const ::rtl::OUString& sTarget, | |
| sal_Int32 nFlags , | |
| const css::uno::Sequence< css::beans::PropertyValue >& lArgs ); | |
| //_______________________________________ | |
| /** @short set some changeable parameters for a new load request. | |
| @descr The parameter for targeting, the content description, and | |
| some environment specifier (UI, dispatch functionality) | |
| can be set here ... BEFORE the real load process is started | |
| by calling startLoading(). 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 | |
| synchronization methods or callbacks. | |
| @param sURL | |
| points to the resource, which should be loaded. | |
| @param lMediaDescriptor | |
| contains additional informations 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. | |
| @param eContentType | |
| classify the given content. | |
| This value is set to a default value "UNKNOWN_CONTENT", which force | |
| an internal check, if this content is loadable or not. | |
| But may this check was already made by the caller of this method and | |
| passing this information to this LoadEnv instance can suppress this | |
| might expensive check. | |
| That can be useful in case this information is needed outside too, | |
| to decide if its necessary to create some resources for this load | |
| request ... or to reject the request immediately if it seems to be not | |
| loadable in general. | |
| @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. | |
| */ | |
| virtual void initializeLoading(const ::rtl::OUString& sURL , | |
| const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor, | |
| const css::uno::Reference< css::frame::XFrame >& xBaseFrame , | |
| const ::rtl::OUString& sTarget , | |
| sal_Int32 nSearchFlags , | |
| EFeature eFeature = E_NO_FEATURE , | |
| EContentType eContentType = E_UNSUPPORTED_CONTENT); | |
| //_______________________________________ | |
| /** @short start loading of the resource represented by this loadenv instance. | |
| @descr 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. | |
| @throw A LoadEnvException if start of the load process failed (because | |
| another is still in progress!). | |
| The 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. | |
| */ | |
| virtual void startLoading(); | |
| //_______________________________________ | |
| /** @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 successfully 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. | |
| */ | |
| virtual sal_Bool waitWhileLoading(sal_uInt32 nTimeout = 0); | |
| //_______________________________________ | |
| /** TODO document me ... */ | |
| virtual void cancelLoading(); | |
| //_______________________________________ | |
| /** TODO document me ... */ | |
| virtual css::uno::Reference< css::frame::XFrame > getTarget() const; | |
| //_______________________________________ | |
| /** TODO document me ... */ | |
| virtual css::uno::Reference< css::lang::XComponent > getTargetComponent() const; | |
| /* | |
| //___________________________________________ | |
| // helper uno interface! | |
| // You have to use the native interface only! | |
| public: | |
| //_______________________________________ | |
| // frame.XLoadEventListener | |
| virtual void SAL_CALL loadFinished(const css::uno::Reference< css::frame::XFrameLoader >& xLoader) | |
| throw(css::uno::RuntimeException); | |
| virtual void SAL_CALL loadCancelled(const css::uno::Reference< css::frame::XFrameLoader >& xLoader) | |
| throw(css::uno::RuntimeException); | |
| //_______________________________________ | |
| // frame.XDispatchResultListener | |
| virtual void SAL_CALL dispatchFinished(const css::frame::DispatchResultEvent& aEvent) | |
| throw(css::uno::RuntimeException); | |
| //_______________________________________ | |
| // lang.XEventListener | |
| virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent) | |
| throw(css::uno::RuntimeException); | |
| */ | |
| //___________________________________________ | |
| // static interface | |
| 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 ::rtl::OUString& sURL , | |
| const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor); | |
| /** TODO document me ... */ | |
| static void initializeUIDefaults( | |
| const css::uno::Reference< css::lang::XMultiServiceFactory >& i_rSMGR, | |
| ::comphelper::MediaDescriptor& io_lMediaDescriptor, | |
| const bool _bUIMode, | |
| QuietInteraction** o_ppQuiteInteraction | |
| ); | |
| /** TODO document me ... */ | |
| void impl_setResult(sal_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 helper | |
| private: | |
| /** @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 occurs!) | |
| @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 ask user for it's filter decision in case | |
| normal detection failed. | |
| @descr We use a may existing interaction handler to do so. | |
| @return [string] | |
| the type selected by the user. | |
| @attention Internally we update the member m_lMediaDescriptor! | |
| */ | |
| ::rtl::OUString impl_askUserForTypeAndFilterIfAllowed(); | |
| //_______________________________________ | |
| /** @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 occurs!) | |
| @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. | |
| */ | |
| sal_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 occurs!) | |
| @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. | |
| */ | |
| sal_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" | |
| it's 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 then once ... | |
| it's implemented as an 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 isn't 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 in between (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 , | |
| sal_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. | |
| */ | |
| sal_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. | |
| */ | |
| sal_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 ); | |
| }; | |
| } // namespace framework | |
| #endif // __FRAMEWORK_LOADENV_LOADENV_HXX_ |