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