framework/inc/jobs/helponstartup.hxx

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