framework/inc/jobs/helponstartup.hxx

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