1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef __FRAMEWORK_JOBS_HELPONSTARTUP_HXX_
25 #define __FRAMEWORK_JOBS_HELPONSTARTUP_HXX_
26 
27 //_______________________________________________
28 // my own includes
29 
30 #include <threadhelp/threadhelpbase.hxx>
31 #include <macros/xinterface.hxx>
32 #include <macros/xtypeprovider.hxx>
33 #include <macros/xserviceinfo.hxx>
34 
35 //_______________________________________________
36 // other includes
37 #include <cppuhelper/implbase3.hxx>
38 
39 //_______________________________________________
40 // uno includes
41 #include <com/sun/star/frame/XFrame.hpp>
42 #include <com/sun/star/task/XJob.hpp>
43 #include <com/sun/star/lang/XEventListener.hpp>
44 #include <com/sun/star/container/XNameAccess.hpp>
45 #include <com/sun/star/frame/XModuleManager.hpp>
46 
47 //_______________________________________________
48 // namespace
49 
50 namespace framework{
51 
52 //_______________________________________________
53 // declarations
54 
55 //_______________________________________________
56 /** @short  implements a job component, which handle the special
57             feature to show a suitable help page for every (visible!)
58             loaded document.
59 
60     @author as96863
61  */
62 class HelpOnStartup : private ThreadHelpBase
63                       ,public ::cppu::WeakImplHelper3< ::com::sun::star::lang::XServiceInfo,::com::sun::star::lang::XEventListener,::com::sun::star::task::XJob >
64 {
65     //-------------------------------------------
66     // member
67     private:
68 
69         //.......................................
70         /** @short  reference to an uno service manager. */
71         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
72 
73         //.......................................
74         /** @short  such module manager is used to classify new opened documents. */
75         css::uno::Reference< css::frame::XModuleManager > m_xModuleManager;
76 
77         //.......................................
78         /** @short  is needed to locate a might open help frame. */
79         css::uno::Reference< css::frame::XFrame > m_xDesktop;
80 
81         //.......................................
82         /** @short  provides read access to the underlying configuration. */
83         css::uno::Reference< css::container::XNameAccess > m_xConfig;
84 
85         //.......................................
86         /** @short  knows the current locale of this office session,
87                     which is needed to build complete help URLs.
88          */
89         ::rtl::OUString m_sLocale;
90 
91         //.......................................
92         /** @short  knows the current operating system of this office session,
93                     which is needed to build complete help URLs.
94          */
95         ::rtl::OUString m_sSystem;
96 
97     //-------------------------------------------
98     // native interface
99     public:
100 
101         //---------------------------------------
102         /** @short  create new instance of this class.
103 
104             @param  xSMGR
105                     reference to the uno service manager, which created this instance.
106                     Can be used later to create own needed uno resources on demand.
107          */
108         HelpOnStartup(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR);
109 
110         //---------------------------------------
111         /** @short  does nothing real ...
112 
113             @descr  But it should exists as virtual function,
114                     so this class cant make trouble
115                     related to inline/symbols etcpp.!
116          */
117         virtual ~HelpOnStartup();
118 
119     //-------------------------------------------
120     // uno interface
121     public:
122 
123         //---------------------------------------
124         // css.lang.XServiceInfo
125         DECLARE_XSERVICEINFO
126 
127         // css.task.XJob
128         virtual css::uno::Any SAL_CALL execute(const css::uno::Sequence< css::beans::NamedValue >& lArguments)
129             throw(css::lang::IllegalArgumentException,
130                   css::uno::Exception                ,
131                   css::uno::RuntimeException         );
132 
133         // css.lang.XEventListener
134         virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent)
135             throw(css::uno::RuntimeException);
136 
137     //-------------------------------------------
138     // helper
139     private:
140 
141         //---------------------------------------
142         /** @short  analyze the given job arguments, try to locate a model reference
143                     and try to classify this model.
144 
145             @descr  As a result of this operation a module identifier will be returned.
146                     It can be used against the module configuration then to retrieve further informations.
147 
148             @param  lArguments
149                     the list of job arguments which is given on our interface method execute().
150 
151             @return [string]
152                     a module identifier ... or an empty value if no model could be located ...
153                     or if it could not be classified successfully.
154          */
155         ::rtl::OUString its_getModuleIdFromEnv(const css::uno::Sequence< css::beans::NamedValue >& lArguments);
156 
157         //---------------------------------------
158         /** @short  tries to locate the open help module and return
159                     the url of the currently shown help content.
160 
161             @descr  It returns an empty string, if the help isnt still
162                     open at calling time.
163 
164             @return The URL of the current shown help content;
165                     or an empty value if the help isnt still open.
166          */
167         ::rtl::OUString its_getCurrentHelpURL();
168 
169         //---------------------------------------
170         /** @short  checks if the given help url match to a default help url
171                     of any office module.
172 
173             @param  sHelpURL
174                     the help url for checking.
175 
176             @return [bool]
177                     sal_True if the given URL is any default one ...
178                     sal_False otherwise.
179          */
180         ::sal_Bool its_isHelpUrlADefaultOne(const ::rtl::OUString& sHelpURL);
181 
182         //---------------------------------------
183         /** @short  checks, if the help module should be shown automaticly for the
184                     currently opened office module.
185 
186             @descr  This value is readed from the module configuration.
187                     In case the help should be shown, this method returns
188                     a help URL, which can be used to show the right help content.
189 
190             @param  sModule
191                     identifies the used office module.
192 
193             @return [string]
194                     A valid help URL in case the help content should be shown;
195                     an empty value if such automatism was disabled for the specified office module.
196          */
197         ::rtl::OUString its_checkIfHelpEnabledAndGetURL(const ::rtl::OUString& sModule);
198 
199         //---------------------------------------
200         /** @short  create a help URL for the given parameters.
201 
202             @param  sBaseURL
203                     must be the base URL for a requested help content
204                     e.g. "vnd.sun.star.help://swriter/"
205                     or   "vnd.sun.star.help://swriter/67351"
206 
207             @param  sLocale
208                     the current office locale
209                     e.g. "en-US"
210 
211             @param  sSystem
212                     the current operating system
213                     e.g. "WIN"
214 
215             @return The URL which was generated.
216                     e.g.
217                     e.g. "vnd.sun.star.help://swriter/?Language=en-US&System=WIN"
218                     or   "vnd.sun.star.help://swriter/67351?Language=en-US&System=WIN"
219          */
220         static ::rtl::OUString ist_createHelpURL(const ::rtl::OUString& sBaseURL,
221                                                  const ::rtl::OUString& sLocale ,
222                                                  const ::rtl::OUString& sSystem );
223 };
224 
225 } // namespace framework
226 
227 #endif // __FRAMEWORK_JOBS_HELPONSTARTUP_HXX_
228