include/unotools/configitem.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 _UTL_CONFIGITEM_HXX_
  21 #define _UTL_CONFIGITEM_HXX_
  22
  23 #include <sal/types.h>
  24 #include <rtl/ustring.hxx>
  25 #include <com/sun/star/uno/Sequence.h>
  26 #include <com/sun/star/uno/Reference.h>
  27 #include "unotools/unotoolsdllapi.h"
  28 #include "unotools/options.hxx"
  29
  30 //-----------------------------------------------------------------------------
  31 namespace com{ namespace sun{ namespace star{
  32     namespace uno{
  33         class Any;
  34     }
  35     namespace beans{
  36         struct PropertyValue;
  37     }
  38     namespace container{
  39         class XHierarchicalNameAccess;
  40     }
  41     namespace util{
  42         class XChangesListener;
  43     }
  44 }}}
  45 //-----------------------------------------------------------------------------
  46 namespace utl
  47 {
  48 #define CONFIG_MODE_IMMEDIATE_UPDATE    0x00
  49 #define CONFIG_MODE_DELAYED_UPDATE      0x01
  50 #define CONFIG_MODE_ALL_LOCALES         0x02
  51 #define CONFIG_MODE_RELEASE_TREE        0x04
  52
  53     enum  ConfigNameFormat
  54     {
  55         CONFIG_NAME_PLAINTEXT_NAME, // unescaped local node name, for user display etc.
  56         CONFIG_NAME_LOCAL_NAME,     // local node name, for use in XNameAccess etc. ("Item", "Q & A")
  57         CONFIG_NAME_LOCAL_PATH,     // one-level relative path, for use when building paths etc.  ("Item", "Typ['Q &amp; A']")
  58         CONFIG_NAME_FULL_PATH,       // full absolute path. ("/org.openoffice.Sample/Group/Item", "/org.openoffice.Sample/Set/Typ['Q &amp; A']")
  59
  60         CONFIG_NAME_DEFAULT = CONFIG_NAME_LOCAL_PATH // default format
  61     };
  62
  63     class ConfigChangeListener_Impl;
  64     class ConfigManager;
  65     struct ConfigItem_Impl;
  66
  67     class UNOTOOLS_DLLPUBLIC ConfigItem : public ConfigurationBroadcaster
  68     {
  69             friend class ConfigChangeListener_Impl;
  70             friend class ConfigManager;
  71
  72             const OUString              sSubTree;
  73             com::sun::star::uno::Reference< com::sun::star::container::XHierarchicalNameAccess>
  74                                         m_xHierarchyAccess;
  75             com::sun::star::uno::Reference< com::sun::star::util::XChangesListener >
  76                                         xChangeLstnr;
  77             ConfigItem_Impl*            pImpl;
  78
  79             ConfigItem();//
  80             void                    RemoveChangesListener();
  81             void                    CallNotify(
  82                                 const com::sun::star::uno::Sequence<OUString>& aPropertyNames);
  83
  84             //***********************************************************************************************************************
  85             // In special mode ALL_LOCALES we must support reading/writing of localized cfg entries as Sequence< PropertyValue >.
  86             // These methods are helper to convert given lists of names and Any-values.
  87             // format:  PropertyValue.Name  = <locale as ISO string>
  88             //          PropertyValue.Value = <value; type depends from cfg entry!>
  89             // e.g.
  90             //          LOCALIZED NODE
  91             //          "UIName"
  92             //                      LOCALE      VALUE
  93             //                      "de"        "Mein Name"
  94             //                      "en-US"     "my name"
  95             void impl_packLocalizedProperties   (   const   com::sun::star::uno::Sequence< OUString >&                  lInNames    ,
  96                                                     const   com::sun::star::uno::Sequence< com::sun::star::uno::Any >&  lInValues   ,
  97                                                             com::sun::star::uno::Sequence< com::sun::star::uno::Any >&  lOutValues  );
  98             void impl_unpackLocalizedProperties (   const   com::sun::star::uno::Sequence< OUString >&                  lInNames    ,
  99                                                     const   com::sun::star::uno::Sequence< com::sun::star::uno::Any >&  lInValues   ,
 100                                                             com::sun::star::uno::Sequence< OUString >&                  lOutNames   ,
 101                                                             com::sun::star::uno::Sequence< com::sun::star::uno::Any >&  lOutValues  );
 102
 103             com::sun::star::uno::Reference< com::sun::star::container::XHierarchicalNameAccess>
 104                                         GetTree();
 105
 106         protected:
 107             explicit ConfigItem(const OUString &rSubTree,
 108                         sal_Int16 nMode = CONFIG_MODE_DELAYED_UPDATE);
 109
 110             void                    SetModified  (); // mark item as modified
 111             void                    ClearModified(); // reset state after commit!
 112
 113             com::sun::star::uno::Sequence< com::sun::star::uno::Any>
 114                                     GetProperties(const com::sun::star::uno::Sequence< OUString >& rNames);
 115
 116             com::sun::star::uno::Sequence< sal_Bool >
 117                                     GetReadOnlyStates(const com::sun::star::uno::Sequence< OUString >& rNames);
 118
 119             sal_Bool                PutProperties(
 120                                         const com::sun::star::uno::Sequence< OUString >& rNames,
 121                                         const com::sun::star::uno::Sequence< com::sun::star::uno::Any>& rValues);
 122
 123             /** enables notifications about changes on selected sub nodes/values
 124
 125                 Before calling this method a second time for a possibly changed node/value set,
 126                 you must disable the current notifications by calling DisableNotification.
 127
 128                 @see Notify
 129                 @see DisableNotification
 130             */
 131             sal_Bool                EnableNotification(const com::sun::star::uno::Sequence< OUString >& rNames,
 132                                         sal_Bool bEnableInternalNotification = sal_False);
 133             /** disables notifications about changes on sub nodes/values, which previosly had
 134                 been enabled with EnableNotification
 135                 @see Notify
 136                 @see EnableNotification
 137             */
 138             void                    DisableNotification();
 139             sal_Bool                IsInternalNotification()const {return IsInValueChange();}
 140
 141             //returns all members of a node in a specific format
 142             com::sun::star::uno::Sequence< OUString >
 143                                     GetNodeNames(const OUString& rNode);
 144             //returns all members of a node in a specific format
 145             com::sun::star::uno::Sequence< OUString >
 146                                     GetNodeNames(const OUString& rNode, ConfigNameFormat eFormat);
 147             // remove all members of a set
 148             sal_Bool                ClearNodeSet(const OUString& rNode);
 149             // remove selected members of a set
 150             sal_Bool                ClearNodeElements(const OUString& rNode,
 151                                         com::sun::star::uno::Sequence< OUString >& rElements);
 152             // change or add members to a set
 153             sal_Bool                SetSetProperties(const OUString& rNode, com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > rValues);
 154             // remove, change or add members of a set
 155             sal_Bool                ReplaceSetProperties(const OUString& rNode, com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > rValues);
 156             // add a new node without setting any properties
 157             sal_Bool                AddNode(const OUString& rNode, const OUString& rNewNode);
 158
 159             /** get a name for a new element of a set node
 160                 @param _rSetNode
 161                     relative path to the set node
 162                 @param _rBaseName
 163                     <ul><li><b>in</b>: the base to use when calculating a new name</li>
 164                         <li><b>out</b>: an unused element name</li>
 165                     </ul>
 166                 @return <TRUE/> if a free name could be generated
 167             */
 168             sal_Bool                getUniqueSetElementName( const OUString& _rSetNode, OUString& _rBaseName);
 169
 170         public:
 171             virtual ~ConfigItem();
 172
 173             /** is called from the ConfigManager before application ends of from the
 174                 PropertyChangeListener if the sub tree broadcasts changes. */
 175             virtual void            Notify( const com::sun::star::uno::Sequence<OUString>& aPropertyNames)=0;
 176
 177             const OUString&         GetSubTreeName() const {return sSubTree;}
 178
 179             sal_Bool                IsModified() const;
 180
 181             /** writes the changed values into the sub tree. Always called in the Dtor of the derived class.  */
 182             virtual void            Commit()=0;
 183
 184             sal_Bool                IsInValueChange() const;
 185
 186             sal_Int16               GetMode() const;
 187
 188             /** checks if the configuration manager used by this item is valid.
 189             */
 190             sal_Bool                IsValidConfigMgr() const;
 191     };
 192 }//namespace utl
 193 #endif //_UTL_CONFIGITEM_HXX_
 194
 195 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */