[Libreoffice-commits] .: 2 commits - framework/source
Kohei Yoshida
kohei at kemper.freedesktop.org
Fri Jul 27 16:19:40 PDT 2012
framework/source/inc/loadenv/loadenv.hxx | 1120 ++++++++++++++-----------------
1 file changed, 535 insertions(+), 585 deletions(-)
New commits:
commit a86bef45ec2c2ba16de5c552e206a07dc190f497
Author: Kohei Yoshida <kohei.yoshida at gmail.com>
Date: Thu Jul 26 10:02:33 2012 -0400
Fix excessive indentation.
Change-Id: Id96c7693a53981d69820aa45e97fb34c64cb787a
diff --git a/framework/source/inc/loadenv/loadenv.hxx b/framework/source/inc/loadenv/loadenv.hxx
index a389261..edd5e55 100644
--- a/framework/source/inc/loadenv/loadenv.hxx
+++ b/framework/source/inc/loadenv/loadenv.hxx
@@ -73,538 +73,538 @@ class QuietInteraction;
*/
class LoadEnv : private ThreadHelpBase
{
- public:
-
- /** @short enable/disable special features
- of a load request.
-
- @desrc Such features must outcome without
- any special parameters.
- To make enableing/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
- };
-
- 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.
- Otherwhise its 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.
- Normaly 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 cant be used as valid indicator,
- (in case the micht 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;
-
- QuietInteraction* m_pQuietInteraction;
-
- public:
-
- /** @short initialize a new instance of this load environment.
-
- @param xSMGR
- reference to an uno service manager, which can be used internaly
- 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 cant be used any longer.
- */
- LoadEnv(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR)
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @short deinitialize an instance of this class in the right way.
- */
- ~LoadEnv();
-
- 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 )
- throw(css::lang::IllegalArgumentException,
- css::io::IOException ,
- css::uno::RuntimeException );
-
- /** @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
- synchronisation 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 "UNKNWON_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 supress this
- might expensive check.
- That can be usefull in case this information is needed outside too,
- to decide if its neccessary to create some resources for this load
- request ... or to reject the request imidiatly 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 immidiatly.
-
- @throw A RuntimeException in case any internal process indicates, that
- the whole runtime cant be used any longer.
- */
- 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 cant be guranteed, that the internal process runs synchronous.
- Thats why we preferr 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 immidiatly.
-
- @throw A RuntimeException in case any internal process indicates, that
- the whole runtime cant be used any longer.
- */
- void startLoading();
-
- //_______________________________________
-
- /** @short wait for an alreay 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 cant be used any longer.
- */
- sal_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 ::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 useable 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 cant be used any longer.
- */
- void impl_reactForLoadingState()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- 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 occure!)
-
- @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.
- Otherwhise its an error and loading cant be finished successfully.
-
- @throw A LoadEnvException if detection failed.
-
- @throw A RuntimeException in case any internal process indicates, that
- the whole runtime cant be used any longer.
- */
- void impl_detectTypeAndFilter()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @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 Internaly we update the member m_lMediaDescriptor!
- */
- ::rtl::OUString impl_askUserForTypeAndFilterIfAllowed()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @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
- supressed here.
- In case handle failed all new created resources will be
- removed before a suitable exception is thrown.
- (Excepting a RuntimeException occure!)
-
- @return TODO
-
- @throw A LoadEnvException if handling failed.
-
- @throw A RuntimeException in case any internal process indicates, that
- the whole runtime cant be used any longer.
- */
- sal_Bool impl_handleContent()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @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 instanciated 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 occure!)
-
- @return TODO
-
- @throw A LoadEnvException if loading failed.
-
- @throw A RuntimeException in case any internal process indicates, that
- the whole runtime cant be used any longer.
- */
- sal_Bool impl_loadContent()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @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 immidatly!
- 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 oterwhise.
-
- @throw A LoadEnvException only in cases, where an internal error indicates,
- that the complete load environment seems to be not useable 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 cant be used any longer.
- */
- css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @short search for any target frame, which seems to be useable
- for this load request.
-
- @descr Because this special feature is bound to the target specifier "_default"
- its checked inside first. If its not set => this method return an empty
- reference. Otherwhise 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. Thats why the last rule
- exists! If this method returns a valid frame reference, it was locked to be useable
- for this load request only. (Dont 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 useable 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 cant be used any longer.
- */
- css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget()
- throw(LoadEnvException, css::uno::RuntimeException);
-
- /** @short because showing of a frame is needed more then once ...
- it's implemented as an seperate 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 isnt needed realy .. 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 ,
- sal_Bool bForceToFront);
-
- /** @short checks whether a frame is already used for another load request or not.
-
- @descr Such frames cant 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 applay 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 );
+public:
+
+ /** @short enable/disable special features
+ of a load request.
+
+ @desrc Such features must outcome without
+ any special parameters.
+ To make enableing/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
+ };
+
+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.
+ Otherwhise its 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.
+ Normaly 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 cant be used as valid indicator,
+ (in case the micht 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;
+
+ QuietInteraction* m_pQuietInteraction;
+
+public:
+
+ /** @short initialize a new instance of this load environment.
+
+ @param xSMGR
+ reference to an uno service manager, which can be used internaly
+ 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 cant be used any longer.
+ */
+ LoadEnv(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR)
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @short deinitialize an instance of this class in the right way.
+ */
+ ~LoadEnv();
+
+ 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 )
+ throw(css::lang::IllegalArgumentException,
+ css::io::IOException ,
+ css::uno::RuntimeException );
+
+ /** @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
+ synchronisation 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 "UNKNWON_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 supress this
+ might expensive check.
+ That can be usefull in case this information is needed outside too,
+ to decide if its neccessary to create some resources for this load
+ request ... or to reject the request imidiatly 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 immidiatly.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime cant be used any longer.
+ */
+ 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 cant be guranteed, that the internal process runs synchronous.
+ Thats why we preferr 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 immidiatly.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime cant be used any longer.
+ */
+ void startLoading();
+
+ //_______________________________________
+
+ /** @short wait for an alreay 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 cant be used any longer.
+ */
+ sal_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 ::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 useable 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 cant be used any longer.
+ */
+ void impl_reactForLoadingState()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+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 occure!)
+
+ @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.
+ Otherwhise its an error and loading cant be finished successfully.
+
+ @throw A LoadEnvException if detection failed.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime cant be used any longer.
+ */
+ void impl_detectTypeAndFilter()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @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 Internaly we update the member m_lMediaDescriptor!
+ */
+ ::rtl::OUString impl_askUserForTypeAndFilterIfAllowed()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @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
+ supressed here.
+ In case handle failed all new created resources will be
+ removed before a suitable exception is thrown.
+ (Excepting a RuntimeException occure!)
+
+ @return TODO
+
+ @throw A LoadEnvException if handling failed.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime cant be used any longer.
+ */
+ sal_Bool impl_handleContent()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @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 instanciated 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 occure!)
+
+ @return TODO
+
+ @throw A LoadEnvException if loading failed.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime cant be used any longer.
+ */
+ sal_Bool impl_loadContent()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @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 immidatly!
+ 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 oterwhise.
+
+ @throw A LoadEnvException only in cases, where an internal error indicates,
+ that the complete load environment seems to be not useable 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 cant be used any longer.
+ */
+ css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @short search for any target frame, which seems to be useable
+ for this load request.
+
+ @descr Because this special feature is bound to the target specifier "_default"
+ its checked inside first. If its not set => this method return an empty
+ reference. Otherwhise 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. Thats why the last rule
+ exists! If this method returns a valid frame reference, it was locked to be useable
+ for this load request only. (Dont 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 useable 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 cant be used any longer.
+ */
+ css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget()
+ throw(LoadEnvException, css::uno::RuntimeException);
+
+ /** @short because showing of a frame is needed more then once ...
+ it's implemented as an seperate 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 isnt needed realy .. 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 ,
+ sal_Bool bForceToFront);
+
+ /** @short checks whether a frame is already used for another load request or not.
+
+ @descr Such frames cant 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 applay 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
commit 6410afaa449659429decf369ba91fcb74a92562a
Author: Kohei Yoshida <kohei.yoshida at gmail.com>
Date: Thu Jul 26 10:01:26 2012 -0400
Remove unnecessary fluffy comment partitions.
Change-Id: I8fad1d7e4bb9827266b6b1f1d90fe1dd2b401b44
diff --git a/framework/source/inc/loadenv/loadenv.hxx b/framework/source/inc/loadenv/loadenv.hxx
index 4c72e6b..a389261 100644
--- a/framework/source/inc/loadenv/loadenv.hxx
+++ b/framework/source/inc/loadenv/loadenv.hxx
@@ -58,26 +58,21 @@
//_______________________________________________
// namespace
-namespace framework{
+namespace framework {
namespace css = ::com::sun::star;
class QuietInteraction;
-//_______________________________________________
-// definitions
/** @short implements general mechainsm 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 :-)).
+ XComponentLoader::loadComponentFromURL() and
+ XDispatch::dispatch().
@author as96863
*/
class LoadEnv : private ThreadHelpBase
{
- //___________________________________________
- // structs, types, etc.
-
public:
/** @short enable/disable special features
@@ -101,8 +96,6 @@ class LoadEnv : private ThreadHelpBase
E_ALLOW_CONTENTHANDLER = 2
};
- //_______________________________________
-
/** @short classify a content.
@descr The load environment must know, if a content
@@ -131,9 +124,6 @@ class LoadEnv : private ThreadHelpBase
E_CAN_BE_SET
};
- //___________________________________________
- // member
-
private:
/** @short reference to an uno service manager, which must be used
@@ -225,9 +215,6 @@ class LoadEnv : private ThreadHelpBase
QuietInteraction* m_pQuietInteraction;
- //___________________________________________
- // native interface
-
public:
/** @short initialize a new instance of this load environment.
@@ -244,16 +231,10 @@ class LoadEnv : private ThreadHelpBase
LoadEnv(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR)
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short deinitialize an instance of this class in the right way.
*/
~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 ,
@@ -264,8 +245,6 @@ class LoadEnv : private ThreadHelpBase
css::io::IOException ,
css::uno::RuntimeException );
- //_______________________________________
-
/** @short set some changeable parameters for a new load request.
@descr The parameter for targeting, the content description, and
@@ -323,8 +302,6 @@ class LoadEnv : private ThreadHelpBase
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
@@ -375,10 +352,6 @@ class LoadEnv : private ThreadHelpBase
/** TODO document me ... */
css::uno::Reference< css::lang::XComponent > getTargetComponent() const;
-
- //___________________________________________
- // static interface
-
public:
/** @short checks if the specified content can be handled by a
@@ -444,9 +417,6 @@ class LoadEnv : private ThreadHelpBase
void impl_reactForLoadingState()
throw(LoadEnvException, css::uno::RuntimeException);
- //___________________________________________
- // private helper
-
private:
/** @short tries to detect the type and the filter of the specified content.
@@ -470,8 +440,6 @@ class LoadEnv : private ThreadHelpBase
void impl_detectTypeAndFilter()
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short tries to ask user for it's filter decision in case
normal detection failed.
@@ -485,8 +453,6 @@ class LoadEnv : private ThreadHelpBase
::rtl::OUString impl_askUserForTypeAndFilterIfAllowed()
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short tries to use ContentHandler objects for loading.
@descr It searches for a suitable content handler object, registered
@@ -508,8 +474,6 @@ class LoadEnv : private ThreadHelpBase
sal_Bool impl_handleContent()
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short tries to use FrameLoader objects for loading.
@descr First the target frame will be located. If it could be found
@@ -529,8 +493,6 @@ class LoadEnv : private ThreadHelpBase
sal_Bool impl_loadContent()
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short checks if the specified content is already loaded.
@descr It depends from the set target information, if such
@@ -557,8 +519,6 @@ class LoadEnv : private ThreadHelpBase
css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded()
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short search for any target frame, which seems to be useable
for this load request.
@@ -590,8 +550,6 @@ class LoadEnv : private ThreadHelpBase
css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget()
throw(LoadEnvException, css::uno::RuntimeException);
- //_______________________________________
-
/** @short because showing of a frame is needed more then once ...
it's implemented as an seperate method .-)
@@ -620,8 +578,6 @@ class LoadEnv : private ThreadHelpBase
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 cant be used for our "recycle feature"!
@@ -635,22 +591,16 @@ class LoadEnv : private ThreadHelpBase
*/
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 applay 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,
More information about the Libreoffice-commits
mailing list