sdext/source/presenter/PresenterConfigurationAccess.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_SDEXT_SOURCE_PRESENTER_PRESENTERCONFIGURATIONACCESS_HXX
  21 #define INCLUDED_SDEXT_SOURCE_PRESENTER_PRESENTERCONFIGURATIONACCESS_HXX
  22
  23 #include <rtl/ustring.hxx>
  24 #include <com/sun/star/beans/XPropertySet.hpp>
  25 #include <com/sun/star/container/XNameAccess.hpp>
  26 #include <com/sun/star/container/XHierarchicalNameAccess.hpp>
  27 #include <com/sun/star/uno/XComponentContext.hpp>
  28 #include <vector>
  29 #include <boost/function.hpp>
  30
  31 namespace sdext { namespace presenter {
  32
  33 /** This class gives access to the configuration.  Create an object of this
  34     class for one node of the configuration.  This will be the root node.
  35     From this one you can use this class in two ways.
  36
  37     <p>In a stateless mode (with exception of the root node) you can use static
  38     methods for obtaining child nodes, get values from properties at leaf
  39     nodes and iterate over children of inner nodes.</p>
  40
  41     <p>In a stateful mode use non-static methods like GoToChild() to
  42     navigate to children.</p>
  43
  44     <p>Note to call CommitChanges() after making changes to
  45     PresenterConfigurationAccess object that was opened in READ_WRITE mode.</p>
  46 */
  47 class PresenterConfigurationAccess
  48 {
  49 public:
  50     enum WriteMode { READ_WRITE, READ_ONLY };
  51     typedef ::boost::function<bool(
  52         const OUString&,
  53         const css::uno::Reference<css::beans::XPropertySet>&)> Predicate;
  54     static const OUString msPresenterScreenRootName;
  55
  56     /** Create a new object to access the configuration entries below the
  57         given root.
  58         @param rsRootName
  59             Name of the root.  You can use msPresenterScreenRootName to
  60             access the configuration of the presenter screen.
  61         @param eMode
  62             This flag specifies whether to give read-write or read-only
  63             access.
  64     */
  65     PresenterConfigurationAccess(
  66         const css::uno::Reference<css::uno::XComponentContext>& rxContext,
  67         const OUString& rsRootName,
  68         WriteMode eMode);
  69
  70     ~PresenterConfigurationAccess();
  71
  72     /** Return a configuration node below the root of the called object.
  73         @param rsPathToNode
  74             The relative path from the root (as given the constructor) to the node.
  75     */
  76     css::uno::Any GetConfigurationNode (
  77         const OUString& rsPathToNode);
  78
  79     /** Return <TRUE/> when opening the configuration (via creating a new
  80         PresenterConfigurationAccess object) or previous calls to
  81         GoToChild() left the called PresenterConfigurationAccess object in a
  82         valid state.
  83     */
  84     bool IsValid() const;
  85
  86     /** Move the focused node to the (possibly indirect) child specified by the given path.
  87     */
  88     bool GoToChild (const OUString& rsPathToNode);
  89
  90     /** Move the focused node to the first direct child that fulfills the given predicate.
  91     */
  92     bool GoToChild (const Predicate& rPredicate);
  93
  94     /** Modify the property child of the currently focused node.  Keep in
  95         mind to call CommitChanges() to write the change back to the
  96         configuration.
  97     */
  98     bool SetProperty (const OUString& rsPropertyName, const css::uno::Any& rValue);
  99
 100     /** Return a configuration node below the given node.
 101         @param rxNode
 102             The node that acts as root to the given relative path.
 103         @param rsPathToNode
 104             The relative path from the given node to the requested node.
 105             When this string is empty then rxNode is returned.
 106         @return
 107             The type of the returned node varies with the requested node.
 108             It is empty when the node was not found.
 109     */
 110     static css::uno::Any GetConfigurationNode (
 111         const css::uno::Reference<css::container::XHierarchicalNameAccess>& rxNode,
 112         const OUString& rsPathToNode);
 113
 114     static css::uno::Reference<css::beans::XPropertySet> GetNodeProperties (
 115         const css::uno::Reference<css::container::XHierarchicalNameAccess>& rxNode,
 116         const OUString& rsPathToNode);
 117
 118     /** Write any changes that have been made back to the configuration.
 119         This call is ignored when the called ConfigurationAccess object was
 120         not create with read-write mode.
 121     */
 122     void CommitChanges();
 123
 124     typedef ::boost::function<void(
 125         const OUString&,
 126         const ::std::vector<css::uno::Any>&) > ItemProcessor;
 127     typedef ::boost::function<void(
 128         const OUString&,
 129         const css::uno::Reference<css::beans::XPropertySet>&) > PropertySetProcessor;
 130
 131     /** Execute a functor for all elements of the given container.
 132         @param rxContainer
 133             The container is a XNameAccess to a list of the configuration.
 134             This can be a node returned by GetConfigurationNode().
 135         @param rArguments
 136             The functor is called with arguments that are children of each
 137             element of the container.  The set of children is specified  this
 138             list.
 139         @param rFunctor
 140             The functor to be executed for some or all of the elements in
 141             the given container.
 142     */
 143     static void ForAll (
 144         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 145         const ::std::vector<OUString>& rArguments,
 146         const ItemProcessor& rProcessor);
 147     static void ForAll (
 148         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 149         const PropertySetProcessor& rProcessor);
 150
 151     static css::uno::Any Find (
 152         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 153         const Predicate& rPredicate);
 154
 155     static bool IsStringPropertyEqual (
 156         const OUString& rsValue,
 157         const OUString& rsPropertyName,
 158         const css::uno::Reference<css::beans::XPropertySet>& rxNode);
 159
 160     /** This method wraps a call to getPropertyValue() and returns an empty
 161         Any instead of throwing an exception when the property does not
 162         exist.
 163     */
 164     static css::uno::Any GetProperty (
 165         const css::uno::Reference<css::beans::XPropertySet>& rxProperties,
 166         const OUString& rsKey);
 167
 168 private:
 169     css::uno::Reference<css::uno::XInterface> mxRoot;
 170     css::uno::Any maNode;
 171 };
 172
 173 } } // end of namespace sdext::tools
 174
 175 #endif
 176
 177 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */