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/implbase3.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 : private ThreadHelpBase
  70                       ,public ::cppu::WeakImplHelper3< ::com::sun::star::lang::XServiceInfo,::com::sun::star::lang::XEventListener,::com::sun::star::task::XJob >
  71 {
  72     //-------------------------------------------
  73     // member
  74     private:
  75
  76         //.......................................
  77         /** @short  reference to an uno service manager. */
  78         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
  79
  80         //.......................................
  81         /** @short  such module manager is used to classify new opened documents. */
  82         css::uno::Reference< css::frame::XModuleManager > m_xModuleManager;
  83
  84         //.......................................
  85         /** @short  is needed to locate a might open help frame. */
  86         css::uno::Reference< css::frame::XFrame > m_xDesktop;
  87
  88         //.......................................
  89         /** @short  provides read access to the underlying configuration. */
  90         css::uno::Reference< css::container::XNameAccess > m_xConfig;
  91
  92         //.......................................
  93         /** @short  knows the current locale of this office session,
  94                     which is needed to build complete help URLs.
  95          */
  96         ::rtl::OUString m_sLocale;
  97
  98         //.......................................
  99         /** @short  knows the current operating system of this office session,
 100                     which is needed to build complete help URLs.
 101          */
 102         ::rtl::OUString m_sSystem;
 103
 104     //-------------------------------------------
 105     // native interface
 106     public:
 107
 108         //---------------------------------------
 109         /** @short  create new instance of this class.
 110
 111             @param  xSMGR
 112                     reference to the uno service manager, which created this instance.
 113                     Can be used later to create own needed uno resources on demand.
 114          */
 115         HelpOnStartup(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR);
 116
 117         //---------------------------------------
 118         /** @short  does nothing real ...
 119
 120             @descr  But it should exists as virtual function,
 121                     so this class cant make trouble
 122                     related to inline/symbols etcpp.!
 123          */
 124         virtual ~HelpOnStartup();
 125
 126     //-------------------------------------------
 127     // uno interface
 128     public:
 129
 130         //---------------------------------------
 131         // css.lang.XServiceInfo
 132         DECLARE_XSERVICEINFO
 133
 134         // css.task.XJob
 135         virtual css::uno::Any SAL_CALL execute(const css::uno::Sequence< css::beans::NamedValue >& lArguments)
 136             throw(css::lang::IllegalArgumentException,
 137                   css::uno::Exception                ,
 138                   css::uno::RuntimeException         );
 139
 140         // css.lang.XEventListener
 141         virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent)
 142             throw(css::uno::RuntimeException);
 143
 144     //-------------------------------------------
 145     // helper
 146     private:
 147
 148         //---------------------------------------
 149         /** @short  analyze the given job arguments, try to locate a model reference
 150                     and try to classify this model.
 151
 152             @descr  As a result of this operation a module identifier will be returned.
 153                     It can be used against the module configuration then to retrieve further informations.
 154
 155             @param  lArguments
 156                     the list of job arguments which is given on our interface method execute().
 157
 158             @return [string]
 159                     a module identifier ... or an empty value if no model could be located ...
 160                     or if it could not be classified successfully.
 161          */
 162         ::rtl::OUString its_getModuleIdFromEnv(const css::uno::Sequence< css::beans::NamedValue >& lArguments);
 163
 164         //---------------------------------------
 165         /** @short  tries to locate the open help module and return
 166                     the url of the currently shown help content.
 167
 168             @descr  It returns an empty string, if the help isnt still
 169                     open at calling time.
 170
 171             @return The URL of the current shown help content;
 172                     or an empty value if the help isnt still open.
 173          */
 174         ::rtl::OUString its_getCurrentHelpURL();
 175
 176         //---------------------------------------
 177         /** @short  checks if the given help url match to a default help url
 178                     of any office module.
 179
 180             @param  sHelpURL
 181                     the help url for checking.
 182
 183             @return [bool]
 184                     TRUE if the given URL is any default one ...
 185                     FALSE otherwise.
 186          */
 187         ::sal_Bool its_isHelpUrlADefaultOne(const ::rtl::OUString& sHelpURL);
 188
 189         //---------------------------------------
 190         /** @short  checks, if the help module should be shown automaticly for the
 191                     currently opened office module.
 192
 193             @descr  This value is readed from the module configuration.
 194                     In case the help should be shown, this method returns
 195                     a help URL, which can be used to show the right help content.
 196
 197             @param  sModule
 198                     identifies the used office module.
 199
 200             @return [string]
 201                     A valid help URL in case the help content should be shown;
 202                     an empty value if such automatism was disabled for the specified office module.
 203          */
 204         ::rtl::OUString its_checkIfHelpEnabledAndGetURL(const ::rtl::OUString& sModule);
 205
 206         //---------------------------------------
 207         /** @short  create a help URL for the given parameters.
 208
 209             @param  sBaseURL
 210                     must be the base URL for a requested help content
 211                     e.g. "vnd.sun.star.help://swriter/"
 212                     or   "vnd.sun.star.help://swriter/67351"
 213
 214             @param  sLocale
 215                     the current office locale
 216                     e.g. "en-US"
 217
 218             @param  sSystem
 219                     the current operating system
 220                     e.g. "WIN"
 221
 222             @return The URL which was generated.
 223                     e.g.
 224                     e.g. "vnd.sun.star.help://swriter/?Language=en-US&System=WIN"
 225                     or   "vnd.sun.star.help://swriter/67351?Language=en-US&System=WIN"
 226          */
 227         static ::rtl::OUString ist_createHelpURL(const ::rtl::OUString& sBaseURL,
 228                                                  const ::rtl::OUString& sLocale ,
 229                                                  const ::rtl::OUString& sSystem );
 230 };
 231
 232 } // namespace framework
 233
 234 #endif // __FRAMEWORK_JOBS_HELPONSTARTUP_HXX_