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