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 SD_TASKPANE_TREE_NODE_HXX
25 #define SD_TASKPANE_TREE_NODE_HXX
26 
27 #include "ILayoutableWindow.hxx"
28 #include <memory>
29 #include <vector>
30 #include <com/sun/star/accessibility/XAccessible.hpp>
31 #include <tools/link.hxx>
32 
33 namespace sd {
34 class ObjectBarManager;
35 }
36 
37 namespace sd { namespace toolpanel {
38 
39 class ControlContainer;
40 class TaskPaneShellManager;
41 
42 enum TreeNodeStateChangeEventId {
43     EID_CHILD_ADDED,
44     EID_ALL_CHILDREN_REMOVED,
45     EID_EXPANSION_STATE_CHANGED,
46     EID_FOCUSED_STATE_CHANGED,
47     EID_SHOWING_STATE_CHANGED
48 };
49 
50 
51 /** Base class for all members of the object hierarchy that makes up the
52     tool panel. In the task pane, there are multiple hierarchies of such nodes,
53     with every panel having an own tree. The pane node is the root of the tree, below
54     that there are SubToolPanels and Window/Control objects. At the
55     lowest level there are only Window or Control objects.
56 
57     This class provides the means of communication between objects on
58     different levels.
59 */
60 class TreeNode
61     : public ILayoutableWindow,
62       public ILayouter
63 {
64 public:
65     TreeNode (TreeNode* pParent);
66     virtual ~TreeNode (void);
67 
68     void SetParentNode (TreeNode* pNewParent);
69     TreeNode* GetParentNode (void);
70 
71     /** Return the Window pointer of a tree node.
72     */
73     virtual ::Window* GetWindow (void);
74 
75     /** Return a const pointer to the window of a tree node.
76     */
77     virtual const ::Window* GetConstWindow (void) const;
78 
79     /** Return the joined minimum width of all children, i.e. the largest of
80         the minimum widths.
81     */
82     virtual sal_Int32 GetMinimumWidth (void);
83 
84     /** The default implementaion always returns <FALSE/>
85     */
86     virtual bool IsResizable (void);
87 
88     /** Call this method whenever the size of one of the children of the
89         called node has to be changed, e.g. when the layout menu shows more
90         or less items than before.  As a typical result the node will layout
91         and resize its children according to their size requirements.
92 
93         Please remember that the size of the children can be changed in the
94         first place because scroll bars can give a node the space it needs.
95 
96         The default implementation passes this call to its parent.
97     */
98     virtual void RequestResize (void);
99 
100     /** The default implementation shows the window (when it exists) when
101         bExpansionState is <TRUE/>.  It hides the window otherwise.
102         @return
103             Returns <TRUE/> when the expansion state changes.  When an
104             expansion state is requested that is already in place then
105             <FALSE/> is returned.
106     */
107     virtual bool Expand (bool bExpansionState);
108 
109     /** The default implementation returns whether the window is showing.
110         When there is no window then it returns <FALSE/>.
111     */
112     virtual bool IsExpanded (void) const;
113 
114     /** Return whether the node can be expanded or collapsed.  The default
115         implementation always returns <TRUE/> when there is window and
116         <FALSE/> otherwise.  If <FALSE/> is returned
117         then Expand() may be called but it will not change the expansion
118         state.
119     */
120     virtual bool IsExpandable (void) const;
121 
122     /** The default implementation calls GetWindow()->Show().
123     */
124     virtual void Show (bool bVisibilityState);
125 
126     /** The default implementation returns GetWindow()->IsVisible().
127     */
128     virtual bool IsShowing (void) const;
129 
130     ControlContainer& GetControlContainer (void);
131 
132     /** Give each node access to a shell manage.  This usually is the shell
133         manager of the ToolPanelViewShell.
134 
135         At least the root node has to overwrite this method since the
136         default implementation simply returns the shell manager of its
137         parent.
138     */
139     virtual TaskPaneShellManager* GetShellManager (void);
140 
141     /** You will rarely need to overload this method.  To supply your own
142         accessible object you should overload CreateAccessible() instead.
143     */
144     virtual ::com::sun::star::uno::Reference<
145         ::com::sun::star::accessibility::XAccessible> GetAccessibleObject (void);
146 
147     /** Overload this method in order to supply a class specific accessible
148         object.
149         The default implementation will return a new instance of
150         AccessibleTreeNode.
151         @param rxParent
152             The accessible parent of the accessible object to create.  It is
153             not necessaryly the accessible object of the parent window of
154             GetWindow().
155 
156     */
157     virtual ::com::sun::star::uno::Reference<
158         ::com::sun::star::accessibility::XAccessible> CreateAccessibleObject (
159             const ::com::sun::star::uno::Reference<
160             ::com::sun::star::accessibility::XAccessible>&rxParent);
161 
162     /** Add a listener that will be informated in the future about state
163         changes of the tree node.  This includes adding and removing
164         children as well as focus, visibility, and expansion state.
165         Multiple calls are ignored.  Each listener is added only once.
166     */
167     void AddStateChangeListener (const Link& rListener);
168 
169     /** Call the state change listeners and pass a state change event with
170         the specified event id.  The source field is set to this.
171         @param pChild
172             This optional parameter makes sense only with the
173             EID_CHILD_ADDED event.
174     */
175     void FireStateChangeEvent (
176         TreeNodeStateChangeEventId eEventId,
177         TreeNode* pChild = NULL) const;
178 
179 protected:
180     ::std::auto_ptr<ControlContainer> mpControlContainer;
181 
182 private:
183     TreeNode* mpParent;
184     typedef ::std::vector<Link> StateChangeListenerContainer;
185     StateChangeListenerContainer maStateChangeListeners;
186 };
187 
188 
189 
190 
191 /** Objects of this class are sent to listeners to notify them about state
192     changes of a tree node.
193 */
194 class TreeNodeStateChangeEvent
195 {
196 public:
197 
198     TreeNodeStateChangeEvent (
199         const TreeNode& rNode,
200         TreeNodeStateChangeEventId eEventId,
201         TreeNode* pChild = NULL);
202 
203     const TreeNode& mrSource;
204     TreeNodeStateChangeEventId meEventId;
205     TreeNode* mpChild;
206 };
207 
208 } } // end of namespace ::sd::toolpanel
209 
210 #endif
211