framework/source/inc/accelerators/presethandler.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 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                 TSharedStorages()
  88                     : m_lStoragesShare()
  89                     , m_lStoragesUser ()
  90                 {};
  91
  92                 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: */