sdext/source/presenter/PresenterConfigurationAccess.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: PresenterConfigurationAccess.hxx,v $
  10  *
  11  * $Revision: 1.4 $
  12  *
  13  * This file is part of OpenOffice.org.
  14  *
  15  * OpenOffice.org is free software: you can redistribute it and/or modify
  16  * it under the terms of the GNU Lesser General Public License version 3
  17  * only, as published by the Free Software Foundation.
  18  *
  19  * OpenOffice.org is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Lesser General Public License version 3 for more details
  23  * (a copy is included in the LICENSE file that accompanied this code).
  24  *
  25  * You should have received a copy of the GNU Lesser General Public License
  26  * version 3 along with OpenOffice.org.  If not, see
  27  * <http://www.openoffice.org/license.html>
  28  * for a copy of the LGPLv3 License.
  29  *
  30  ************************************************************************/
  31
  32 #ifndef SDEXT_PRESENTER_CONFIGURATION_ACCESS_HXX
  33 #define SDEXT_PRESENTER_CONFIGURATION_ACCESS_HXX
  34
  35 #include <rtl/ustring.hxx>
  36 #include <com/sun/star/beans/XPropertySet.hpp>
  37 #include <com/sun/star/container/XNameAccess.hpp>
  38 #include <com/sun/star/container/XHierarchicalNameAccess.hpp>
  39 #include <com/sun/star/uno/XComponentContext.hpp>
  40 #include <vector>
  41 #include <boost/function.hpp>
  42
  43 namespace css = ::com::sun::star;
  44
  45 namespace sdext { namespace presenter {
  46
  47 /** This class gives access to the configuration.  Create an object of this
  48     class for one node of the configuration.  This will be the root node.
  49     From this one you can use this class in two ways.
  50
  51     <p>In a stateless mode (with exception of the root node) you can use static
  52     methods for obtaining child nodes, get values from properties at leaf
  53     nodes and iterate over children of inner nodes.</p>
  54
  55     <p>In a stateful mode use non-static methods like GoToChild() to
  56     navigate to children.</p>
  57
  58     <p>Note to call CommitChanges() after making changes to
  59     PresenterConfigurationAccess object that was opened in READ_WRITE mode.</p>
  60 */
  61 class PresenterConfigurationAccess
  62 {
  63 public:
  64     enum WriteMode { READ_WRITE, READ_ONLY };
  65     typedef ::boost::function<bool(
  66         const ::rtl::OUString&,
  67         const css::uno::Reference<css::beans::XPropertySet>&)> Predicate;
  68     static const ::rtl::OUString msPresenterScreenRootName;
  69
  70     /** Create a new object to access the configuration entries below the
  71         given root.
  72         @param rsRootName
  73             Name of the root.  You can use msPresenterScreenRootName to
  74             access the configuration of the presenter screen.
  75         @param eMode
  76             This flag specifies whether to give read-write or read-only
  77             access.
  78     */
  79     PresenterConfigurationAccess(
  80         const css::uno::Reference<css::uno::XComponentContext>& rxContext,
  81         const ::rtl::OUString& rsRootName,
  82         WriteMode eMode);
  83
  84     ~PresenterConfigurationAccess (void);
  85
  86     /** Return a configuration node below the root of the called object.
  87         @param rsPathToNode
  88             The relative path from the root (as given the constructor) to the node.
  89     */
  90     css::uno::Any GetConfigurationNode (
  91         const ::rtl::OUString& rsPathToNode);
  92     css::uno::Reference<css::beans::XPropertySet> GetNodeProperties (
  93         const ::rtl::OUString& rsPathToNode);
  94
  95     /** Return <TRUE/> when opening the configuration (via creating a new
  96         PresenterConfigurationAccess object) or previous calls to
  97         GoToChild() left the called PresenterConfigurationAccess object in a
  98         valid state.
  99     */
 100     bool IsValid (void) const;
 101
 102     /** Move the focused node to the (possibly indirect) child specified by the given path.
 103     */
 104     bool GoToChild (const ::rtl::OUString& rsPathToNode);
 105
 106     /** Move the focused node to the first direct child that fulfills the the given predicate.
 107     */
 108     bool GoToChild (const Predicate& rPredicate);
 109
 110     /** Modify the property child of the currently focused node.  Keep in
 111         mind to call CommitChanges() to write the change back to the
 112         configuration.
 113     */
 114     bool SetProperty (const ::rtl::OUString& rsPropertyName, const css::uno::Any& rValue);
 115
 116     /** Return a configuration node below the given node.
 117         @param rxNode
 118             The node that acts as root to the given relative path.
 119         @param rsPathToNode
 120             The relative path from the given node to the requested node.
 121             When this string is empty then rxNode is returned.
 122         @return
 123             The type of the returned node varies with the requested node.
 124             It is empty when the node was not found.
 125     */
 126     static css::uno::Any GetConfigurationNode (
 127         const css::uno::Reference<css::container::XHierarchicalNameAccess>& rxNode,
 128         const ::rtl::OUString& rsPathToNode);
 129
 130     static css::uno::Reference<css::beans::XPropertySet> GetNodeProperties (
 131         const css::uno::Reference<css::container::XHierarchicalNameAccess>& rxNode,
 132         const ::rtl::OUString& rsPathToNode);
 133
 134     /** Write any changes that have been made back to the configuration.
 135         This call is ignored when the called ConfigurationAccess object was
 136         not create with read-write mode.
 137     */
 138     void CommitChanges (void);
 139
 140     css::uno::Any GetValue (const rtl::OUString& sKey);
 141
 142     typedef ::boost::function<void(
 143         const ::rtl::OUString&,
 144         const ::std::vector<css::uno::Any>&) > ItemProcessor;
 145     typedef ::boost::function<void(
 146         const ::rtl::OUString&,
 147         const ::css::uno::Reference<css::beans::XPropertySet>&) > PropertySetProcessor;
 148
 149     /** Execute a functor for all elements of the given container.
 150         @param rxContainer
 151             The container is a XNameAccess to a list of the configuration.
 152             This can be a node returned by GetConfigurationNode().
 153         @param rArguments
 154             The functor is called with arguments that are children of each
 155             element of the container.  The set of children is specified  this
 156             list.
 157         @param rFunctor
 158             The functor to be executed for some or all of the elements in
 159             the given container.
 160     */
 161     static void ForAll (
 162         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 163         const ::std::vector<rtl::OUString>& rArguments,
 164         const ItemProcessor& rProcessor);
 165     static void ForAll (
 166         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 167         const PropertySetProcessor& rProcessor);
 168
 169     /** Fill a list with the string contents of all sub-elements in the given container.
 170         @param rxContainer
 171             The container is a XNameAccess to a list of the configuration.
 172             This can be a node returned by GetConfigurationNode().
 173         @param rsArgument
 174             This specifies which string children of the elements in the
 175             container are to be inserted into the list.  The specified child
 176             has to be of type string.
 177         @param rList
 178             The list to be filled.
 179     */
 180     static void FillList(
 181         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 182         const ::rtl::OUString& rsArgument,
 183         ::std::vector<rtl::OUString>& rList);
 184
 185     static css::uno::Any Find (
 186         const css::uno::Reference<css::container::XNameAccess>& rxContainer,
 187         const Predicate& rPredicate);
 188
 189     static bool IsStringPropertyEqual (
 190         const ::rtl::OUString& rsValue,
 191         const ::rtl::OUString& rsPropertyName,
 192         const css::uno::Reference<css::beans::XPropertySet>& rxNode);
 193
 194     /** This method wraps a call to getPropertyValue() and returns an empty
 195         Any instead of throwing an exception when the property does not
 196         exist.
 197     */
 198     static css::uno::Any GetProperty (
 199         const css::uno::Reference<css::beans::XPropertySet>& rxProperties,
 200         const ::rtl::OUString& rsKey);
 201
 202 private:
 203     css::uno::Reference<css::uno::XInterface> mxRoot;
 204     css::uno::Any maNode;
 205 };
 206
 207 } } // end of namespace sdext::tools
 208
 209 #endif