LCOV - code coverage report
Current view: top level - framework/source/inc/accelerators - presethandler.hxx (source / functions) Hit Total Coverage
Test: commit 10e77ab3ff6f4314137acd6e2702a6e5c1ce1fae Lines: 4 4 100.0 %
Date: 2014-11-03 Functions: 3 3 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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 INCLUDED_FRAMEWORK_SOURCE_INC_ACCELERATORS_PRESETHANDLER_HXX
      21             : #define INCLUDED_FRAMEWORK_SOURCE_INC_ACCELERATORS_PRESETHANDLER_HXX
      22             : 
      23             : #include <accelerators/storageholder.hxx>
      24             : #include <general.h>
      25             : #include <stdtypes.h>
      26             : 
      27             : #include <com/sun/star/embed/XStorage.hpp>
      28             : 
      29             : #include <com/sun/star/lang/XMultiServiceFactory.hpp>
      30             : 
      31             : #include <comphelper/processfactory.hxx>
      32             : #include <salhelper/singletonref.hxx>
      33             : #include <i18nlangtag/languagetag.hxx>
      34             : 
      35             : namespace framework
      36             : {
      37             : /**
      38             :     TODO document me
      39             : 
      40             :         <layer>/global/<resourcetype>/<preset>.xml
      41             :         <layer>/modules/<moduleid>/<resourcetype>/<preset>.xml
      42             : 
      43             :         RESOURCETYPE        PRESET        TARGET
      44             :                             (share)       (user)
      45             :         "accelerator"       "default"     "current"
      46             :                             "word"
      47             :                             "excel"
      48             : 
      49             :         "menubar"           "default"     "menubar"
      50             : 
      51             :  */
      52             : class PresetHandler
      53             : {
      54             :     public:
      55             : 
      56             :         /** @short  this handler can provide different
      57             :                     types of configuration.
      58             : 
      59             :             @descr  Means: a global or a module dependent
      60             :                     or ... configuration.
      61             :          */
      62             :         enum EConfigType
      63             :         {
      64             :             E_GLOBAL,
      65             :             E_MODULES,
      66             :             E_DOCUMENT
      67             :         };
      68             : 
      69             :     private:
      70             : 
      71             :         /** @short  because a concurrent access to the same storage from different implementations
      72             :                     isn't supported, we have to share it with others.
      73             : 
      74             :             @descr  This struct makes it possible to use any shared storage
      75             :                     in combination with a SingletonRef<> template ...
      76             : 
      77             :                     This struct is allegedly shared and must be used within a
      78             :                     synchronized section. But it isn't.
      79             :          */
      80             :         struct TSharedStorages
      81             :         {
      82             :             public:
      83             : 
      84             :                 StorageHolder m_lStoragesShare;
      85             :                 StorageHolder m_lStoragesUser;
      86             : 
      87         162 :                 TSharedStorages()
      88             :                     : m_lStoragesShare()
      89         162 :                     , m_lStoragesUser ()
      90         162 :                 {};
      91             : 
      92         300 :                 virtual ~TSharedStorages() {};
      93             :         };
      94             : 
      95             :     // member
      96             : 
      97             :     private:
      98             : 
      99             :         /** @short  can be used to create on needed uno resources. */
     100             :         css::uno::Reference< css::uno::XComponentContext > m_xContext;
     101             : 
     102             :         /** @short  knows the type of provided configuration.
     103             : 
     104             :             @descr  e.g. global, modules, ...
     105             :          */
     106             :         EConfigType m_eConfigType;
     107             : 
     108             :         /** @short  specify the type of resource, which configuration sets
     109             :                     must be provided here.
     110             : 
     111             :             @descr  e.g. menubars, toolbars, accelerators
     112             :          */
     113             :         OUString m_sResourceType;
     114             : 
     115             :         /** @short  specify the application module for a module
     116             :                     dependent configuration.
     117             : 
     118             :             @descr  Will be used only, if m_sResourceType is set to
     119             :                     "module". Further it must be a valid module identifier
     120             :                     then ...
     121             :          */
     122             :         OUString m_sModule;
     123             : 
     124             :         /** @short  provides access to the:
     125             :                     a) shared root storages
     126             :                     b) shared "inbetween" storages
     127             :                     of the share and user layer. */
     128             :         ::salhelper::SingletonRef< TSharedStorages > m_aSharedStorages;
     129             : 
     130             :         /** @short  if we run in document mode, we can't use the global root storages!
     131             :                     We have to use a special document storage explicitly. */
     132             :         StorageHolder m_lDocumentStorages;
     133             : 
     134             :         /** @short  holds the folder storage of the share layer alive,
     135             :                     where the current configuration set exists.
     136             : 
     137             :             @descr  Note: If this preset handler works in document mode
     138             :                     this member is meaned relative to the document root ...
     139             :                     not to the share layer root!
     140             : 
     141             :                     Further is defined, that m_xWorkingStorageUser
     142             :                     is equals to m_xWorkingStorageShare then!
     143             :          */
     144             :         css::uno::Reference< css::embed::XStorage > m_xWorkingStorageShare;
     145             : 
     146             :         /** @short  global language-independent storage
     147             :          */
     148             :         css::uno::Reference< css::embed::XStorage > m_xWorkingStorageNoLang;
     149             : 
     150             :         /** @short  holds the folder storage of the user layer alive,
     151             :                     where the current configuration set exists.
     152             : 
     153             :             @descr  Note: If this preset handler works in document mode
     154             :                     this member is meaned relative to the document root ...
     155             :                     not to the user layer root!
     156             : 
     157             :                     Further is defined, that m_xWorkingStorageUser
     158             :                     is equals to m_xWorkingStorageShare then!
     159             :          */
     160             :         css::uno::Reference< css::embed::XStorage > m_xWorkingStorageUser;
     161             : 
     162             :         /** @short  knows the names of all presets inside the current
     163             :                     working storage of the share layer. */
     164             :         OUStringList m_lPresets;
     165             : 
     166             :         /** @short  knows the names of all targets inside the current
     167             :                     working storage of the user layer. */
     168             :         OUStringList m_lTargets;
     169             : 
     170             :         /** @short  its the current office locale and will be used
     171             :                     to handle localized presets.
     172             : 
     173             :             @descr  Default is "x-no-translate" which disable any
     174             :                     localized handling inside this class! */
     175             :         LanguageTag m_aLanguageTag;
     176             : 
     177             :         /** @short  knows the relative path from the root. */
     178             :         OUString m_sRelPathShare;
     179             :         OUString m_sRelPathNoLang;
     180             :         OUString m_sRelPathUser;
     181             : 
     182             :     // native interface
     183             : 
     184             :     public:
     185             : 
     186             :         /** @short  does nothing real.
     187             : 
     188             :             @descr  Because this class should be useable in combination
     189             :                     with ::salhelper::SingletonRef template this ctor
     190             :                     can't have any special parameters!
     191             : 
     192             :             @param  xContext
     193             :                     points to an uno service manager, which is used internally
     194             :                     to create own needed uno resources.
     195             :          */
     196             :         PresetHandler(const css::uno::Reference< css::uno::XComponentContext >& xContext);
     197             : 
     198             :         /** @short  copy ctor */
     199             :         PresetHandler(const PresetHandler& rCopy);
     200             : 
     201             :         /** @short  closes all open storages ... if user forgot that .-) */
     202             :         virtual ~PresetHandler();
     203             : 
     204             :         /** @short  free all currently cache(!) storages. */
     205             :         void forgetCachedStorages();
     206             : 
     207             :         /** @short  return access to the internally used and cached root storage.
     208             : 
     209             :             @descr  These root storages are the base of all further opened
     210             :                     presets and targets. They are provided here only, to support
     211             :                     older implementations, which base on them ...
     212             : 
     213             :                     getOrCreate...() - What does it mean?
     214             :                     Such root storage will be created one times only and
     215             :                     cached then internally till the last instance of such PresetHandler
     216             :                     dies.
     217             : 
     218             :             @return com::sun::star::embed::XStorage
     219             :                     which represent a root storage.
     220             :          */
     221             :         css::uno::Reference< css::embed::XStorage > getOrCreateRootStorageShare();
     222             :         css::uno::Reference< css::embed::XStorage > getOrCreateRootStorageUser();
     223             : 
     224             :         /** @short  provides access to the current working storages.
     225             : 
     226             :             @descr  Working storages are the "lowest" storages, where the
     227             :                     preset and target files exists.
     228             : 
     229             :             @return com::sun::star::embed::XStorage
     230             :                     which the current working storage.
     231             :          */
     232             :         css::uno::Reference< css::embed::XStorage > getWorkingStorageShare();
     233             :         css::uno::Reference< css::embed::XStorage > getWorkingStorageUser();
     234             : 
     235             :         /** @short  check if there is a parent storage well known for
     236             :                     the specified child storage and return it.
     237             : 
     238             :             @param  xChild
     239             :                     the child storage where a paranet storage should be searched for.
     240             : 
     241             :             @return com::sun::star::embed::XStorage
     242             :                     A valid storage if a paranet exists. NULL otherwise.
     243             :          */
     244             :         css::uno::Reference< css::embed::XStorage > getParentStorageShare(const css::uno::Reference< css::embed::XStorage >& xChild);
     245             :         css::uno::Reference< css::embed::XStorage > getParentStorageUser (const css::uno::Reference< css::embed::XStorage >& xChild);
     246             : 
     247             :         /** @short  free all internal structures and let this handler
     248             :                     work on a new type of configuration sets.
     249             : 
     250             :             @param  eConfigType
     251             :                     differ between global or module dependent configuration.
     252             : 
     253             :             @param  sResourceType
     254             :                     differ between menubar/toolbar/accelerator/... configuration.
     255             : 
     256             :             @param  sModule
     257             :                     if sResourceType is set to a module dependent configuration,
     258             :                     it address the current application module.
     259             : 
     260             :             @param  xDocumentRoot
     261             :                     if sResourceType is set to E_DOCUMENT, this value points to the
     262             :                     root storage inside the document, where we can save our
     263             :                     configuration files. Note: Thats not the real root of the document ...
     264             :                     its only a sub storage. But we interpret it as our root storage.
     265             : 
     266             :             @param  rLanguageTag
     267             :                     in case this configuration supports localized entries,
     268             :                     the current locale must be set.
     269             : 
     270             :                     Localzation will be represented as directory structure
     271             :                     of provided presets. Means: you call us with a preset name "default";
     272             :                     and we use e.g. "/en-US/default.xml" internally.
     273             : 
     274             :                     If no localization exists for this preset set, this class
     275             :                     will work in default mode - means "no locale" - automatically.
     276             :                     e.g. "/default.xml"
     277             : 
     278             :             @throw  com::sun::star::uno::RuntimeException(!)
     279             :                     if the specified resource couldn't be located.
     280             :          */
     281             :         void connectToResource(      EConfigType                                  eConfigType   ,
     282             :                                const OUString&                             sResourceType ,
     283             :                                const OUString&                             sModule       ,
     284             :                                const css::uno::Reference< css::embed::XStorage >& xDocumentRoot ,
     285             :                                const LanguageTag&                                 rLanguageTag  = LanguageTag(LANGUAGE_USER_PRIV_NOTRANSLATE));
     286             : 
     287             :         /** @short  try to copy the specified preset from the share
     288             :                     layer to the user layer and establish it as the
     289             :                     specified target.
     290             : 
     291             :             @descr  Means: copy share/.../<preset>.xml user/.../<target>.xml
     292             :                     Note: The target will be overwritten completely or
     293             :                     created as new by this operation!
     294             : 
     295             :             @param  sPreset
     296             :                     the ALIAS name of an existing preset.
     297             : 
     298             :             @param  sTarget
     299             :                     the ALIAS name of the target.
     300             : 
     301             :             @throw  com::sun::star::container::NoSuchElementException
     302             :                     if the specified preset does not exists.
     303             : 
     304             :             @throw  com::sun::star::io::IOException
     305             :                     if copying failed.
     306             :          */
     307             :         void copyPresetToTarget(const OUString& sPreset,
     308             :                                 const OUString& sTarget);
     309             : 
     310             :         /** @short  open the specified preset as stream object
     311             :                     and return it.
     312             : 
     313             :             @descr  Note: Because presets resist inside the share
     314             :                     layer, they will be opened readonly every time.
     315             : 
     316             :             @param  sPreset
     317             :                     the ALIAS name of an existing preset.
     318             : 
     319             :             @param  bNoLangGlobal
     320             :                     access the global language-independent storage instead of the preset storage
     321             : 
     322             :             @return The opened preset stream ... or NULL if the preset does not exists.
     323             :          */
     324             :         css::uno::Reference< css::io::XStream > openPreset(const OUString& sPreset,
     325             :                                                            bool bUseNoLangGlobal = false);
     326             : 
     327             :         /** @short  open the specified target as stream object
     328             :                     and return it.
     329             : 
     330             :             @descr  Note: Targets resist inside the user
     331             :                     layer. Normally they are opened in read/write mode.
     332             :                    But it will be opened readonly automatically if that isn't possible
     333             :                     (may be the file is write protected on the system ...).
     334             : 
     335             :             @param  sTarget
     336             :                     the ALIAS name of the target.
     337             : 
     338             :             @param  bCreateIfMissing
     339             :                     create target file, if it does not still exists.
     340             :                     Note: That does not means reseting of an existing file!
     341             : 
     342             :             @return The opened target stream ... or NULL if the target does not exists
     343             :                     or couldnt be created as new one.
     344             :          */
     345             :         css::uno::Reference< css::io::XStream > openTarget(const OUString& sTarget         ,
     346             :                                                                  bool         bCreateIfMissing);
     347             : 
     348             :         /** @short  do anything which is necessary to flush all changes
     349             :                     back to disk.
     350             : 
     351             :             @descr  We have to call commit on all cached sub storages on the
     352             :                     path from the root storage upside down to the working storage
     353             :                     (which are not really used, but required to be holded alive!).
     354             :          */
     355             :         void commitUserChanges();
     356             : 
     357             :         /** TODO */
     358             :         void addStorageListener(IStorageListener* pListener);
     359             :         void removeStorageListener(IStorageListener* pListener);
     360             : 
     361             :     // helper
     362             : 
     363             :     private:
     364             : 
     365             :         /** @short  open a config path ignoring errors (catching exceptions).
     366             : 
     367             :             @descr  We catch only normal exceptions here - no runtime exceptions.
     368             : 
     369             :             @param  sPath
     370             :                     the configuration path, which should be opened.
     371             : 
     372             :             @param  eMode
     373             :                     the open mode (READ/READWRITE)
     374             : 
     375             :             @param  bShare
     376             :                     force using of the share layer instead of the user layer.
     377             : 
     378             :             @return An opened storage in case method was successfully - null otherwise.
     379             :          */
     380             :         css::uno::Reference< css::embed::XStorage > impl_openPathIgnoringErrors(const OUString& sPath ,
     381             :                                                                                       sal_Int32        eMode ,
     382             :                                                                                       bool         bShare);
     383             : 
     384             :         /** @short  try to find the specified locale inside list of possible ones.
     385             : 
     386             :             @descr  The lits of possible locale values was e.g. retrieved from the system
     387             :                     (configuration, directory listing etcpp). The locale normally represent
     388             :                     the current office locale. This method search for a suitable item by using
     389             :                     different algorithm.
     390             :                     a) exact search
     391             :                     b) search with using fallbacks
     392             : 
     393             :             @param  lLocalizedValues
     394             :                     list of BCP47 language tags / locale codes
     395             : 
     396             :             @param  rLanguageTag
     397             :                     [IN ] the current office locale, which should be searched inside lLocalizedValues.
     398             :                     [OUT] in case fallbacks was allowed, it contains afterwards the fallback locale.
     399             : 
     400             :             @param  bAllowFallbacks
     401             :                     enable/disable using of fallbacks
     402             : 
     403             :             @return An iterator, which points directly into lLocalizedValue list.
     404             :                     As a negative result the special iterator lLocalizedValues.end() will be returned.
     405             :          */
     406             :         ::std::vector< OUString >::const_iterator impl_findMatchingLocalizedValue(const ::std::vector< OUString >& lLocalizedValues,
     407             :                                                                                                OUString&             rLanguageTag         ,
     408             :                                                                                                bool                          bAllowFallbacks );
     409             : 
     410             :         /** @short  open a config path ignoring errors (catching exceptions).
     411             : 
     412             :             @descr  We catch only normal exceptions here - no runtime exceptions.
     413             :                     Further the path itself is tries in different versions (using locale
     414             :                     specific attributes).
     415             :                     e.g. "path/e-US" => "path/en" => "path/de"
     416             : 
     417             :             @param  sPath
     418             :                     the configuration path, which should be opened.
     419             :                     Its further used as out parameter too, so we can return the localized
     420             :                     path to the calli!
     421             : 
     422             :             @param  eMode
     423             :                     the open mode (READ/READWRITE)
     424             : 
     425             :             @param  bShare
     426             :                     force using of the share layer instead of the user layer.
     427             : 
     428             :             @param  rLanguageTag
     429             :                     [IN ] contains the start locale for searching localized sub dirs.
     430             :                     [OUT] contains the locale of a found localized sub dir
     431             : 
     432             :             @param  bAllowFallback
     433             :                     enable/disable fallback handling for locales
     434             : 
     435             :             @return An opened storage in case method was successfully - null otherwise.
     436             :          */
     437             :         css::uno::Reference< css::embed::XStorage > impl_openLocalizedPathIgnoringErrors(OUString&      sPath         ,
     438             :                                                                                          sal_Int32             eMode         ,
     439             :                                                                                          bool              bShare        ,
     440             :                                                                                          OUString&             rLanguageTag  ,
     441             :                                                                                          bool              bAllowFallback);
     442             : 
     443             :         /** @short  returns the names of all sub storages of specified storage.
     444             : 
     445             :             @param  xFolder
     446             :                     the base storage for this operation.
     447             : 
     448             :             @return [vector< string >]
     449             :                     a list of folder names.
     450             :          */
     451             :         ::std::vector< OUString > impl_getSubFolderNames(const css::uno::Reference< css::embed::XStorage >& xFolder);
     452             : };
     453             : 
     454             : } // namespace framework
     455             : 
     456             : #endif // INCLUDED_FRAMEWORK_SOURCE_INC_ACCELERATORS_PRESETHANDLER_HXX
     457             : 
     458             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10