1 /*************************************************************************
2  *
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * Copyright 2000, 2010 Oracle and/or its affiliates.
6  *
7  * OpenOffice.org - a multi-platform office productivity suite
8  *
9  * This file is part of OpenOffice.org.
10  *
11  * OpenOffice.org is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU Lesser General Public License version 3
13  * only, as published by the Free Software Foundation.
14  *
15  * OpenOffice.org is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU Lesser General Public License version 3 for more details
19  * (a copy is included in the LICENSE file that accompanied this code).
20  *
21  * You should have received a copy of the GNU Lesser General Public License
22  * version 3 along with OpenOffice.org.  If not, see
23  * <http://www.openoffice.org/license.html>
24  * for a copy of the LGPLv3 License.
25  *
26  ************************************************************************/
27 
28 #ifndef SD_TOOLPANEL_CONTROL_CONTAINER_HXX
29 #define SD_TOOLPANEL_CONTROL_CONTAINER_HXX
30 
31 #include <osl/mutex.hxx>
32 
33 #include <vector>
34 #include <memory>
35 
36 class Window;
37 
38 namespace sd { namespace toolpanel {
39 
40 class TreeNode;
41 
42 /** This container manages the children of a TreeNode.  It handles the
43     expansion and visibility state of its child controls.  The container
44     does not do the layouting or painting of the controls.  Instead it asks
45     its owner to do that.
46 
47     The difference between expansion state and visibility is that when a
48     control is collapsed at least a title bar is shown for it.  When it is
49     not visible then even this title bar is not shown.  In that case the
50     user can not expand the control.  A control has to be visible in order
51     to be expanded or collapsed.
52 
53     Whenever you expand or collapse, show or hide a child control then use
54     this container class.  Do not call the respective methods of the child
55     directly.
56 */
57 class ControlContainer
58 {
59 public:
60     enum VisibilityState { VS_SHOW, VS_HIDE, VS_TOGGLE };
61     enum ExpansionState { ES_EXPAND, ES_COLLAPSE, ES_TOGGLE };
62 
63     /** Create a new control container.
64         @param pParent
65             This node is asked to re-calculate the size of its children when
66             a child of this container is expanded or collapsed.
67     */
68     ControlContainer (TreeNode* pNode);
69 
70     virtual ~ControlContainer (void);
71 
72     /** This is function makes sure that all children are deleted.  Call
73         this function from the destructor of a sub class to have all child
74         windows deleted before the destructor of another base class of that
75         sub class is called.  When that other base class is some kind of a
76         window it would otherwise complain that there are living children.
77     */
78     void DeleteChildren (void);
79 
80     /** Add the given control to the set of controls managed by the
81         container.  This control is then expanded.
82         @return
83             Return the index under which the control has been inserted in
84             the container.  It is the same index that is returned by
85             GetControlIndex().
86     */
87     sal_uInt32 AddControl (::std::auto_ptr<TreeNode> pControl);
88 
89     /** Expand (default) or collapse the specified control.  When
90         expanding a control in a single expansion environment then all
91         other controls are collapsed.  The specified control is being
92         made the active control as returned by GetActiveControl().
93     */
94     virtual void SetExpansionState (
95         sal_uInt32 nIndex,
96         ExpansionState aState);
97     virtual void SetExpansionState (
98         TreeNode* pControl,
99         ExpansionState aState);
100     virtual void SetVisibilityState (
101         sal_uInt32 nIndex,
102         VisibilityState aState);
103 
104     /** Return the index of the given control.
105     */
106     sal_uInt32 GetControlIndex (TreeNode* pControl) const;
107 
108     /** Return the number of controls in the container.
109     */
110     sal_uInt32 GetControlCount (void) const;
111 
112     /** Return the number of visible controls in the container.
113     */
114     sal_uInt32 GetVisibleControlCount (void) const;
115 
116     /** Return the control with the specified index regardless of whether
117         that control is hidden or visible.
118     */
119     TreeNode* GetControl (sal_uInt32 nIndex) const;
120 
121     /** Return the index of the control previous to that that is specified
122         by the given index.
123         @param nIndex
124             Index of the control for which to return the index of the
125             previous control.  This index is guaranteed not to be returned.
126         @param bIncludeHidden
127             This flag tells the method whether to include the controls that
128             are not visible in the search for the previous control.  When it
129             is <FALSE/> the hidden controls are skipped.
130         @param bCycle
131             When this flag is <TRUE/> then the search for the previous
132             control wraps arround when reaching the first control.
133         @return
134             Returns the index to the previous control or (sal_uInt32)-1 when
135             there is no previous control.  This would be the case when there
136             is only one (visible) child.
137     */
138     sal_uInt32 GetPreviousIndex (
139         sal_uInt32 nIndex,
140         bool bIncludeHidden=false,
141         bool bCycle=false) const;
142 
143     /** Return the index of the control next to that that is specified by
144         the given index.
145         @param nIndex
146             Index of the control for which to return the index of the next
147             control.  This index is guaranteed not to be returned.
148         @param bIncludeHidden
149             This flag tells the method whether to include the controls that
150             are not visible in the search for the next control.  When it is
151             <FALSE/> the hidden controls are skipped.
152         @param bCycle
153             When this flag is <TRUE/> then the search for the next control
154             wraps arround when reaching the last control.
155         @return
156             Returns the index to the next control or (sal_uInt32)-1 when
157             there is no next control.  This would be the case when there is
158             only one (visible) child.
159     */
160     sal_uInt32 GetNextIndex (
161         sal_uInt32 nIndex,
162         bool bIncludeHidden=false,
163         bool bCycle=false) const;
164 
165     void SetMultiSelection (bool bFlag);
166 
167     /** This is method is called when the list of controls has changed,
168         i.e. a new control has been added.  The default implementation is
169         empty.  Overwrite this method in derived classes in order to react to
170         such changes.
171     */
172     virtual void ListHasChanged (void);
173 
174 private:
175 	osl::Mutex maMutex;
176 
177     /// List of controls managed by a container.
178     typedef ::std::vector<TreeNode*> ControlList;
179     ControlList maControlList;
180 
181     /** This parent is used for resize requests when children are expanded
182         or collapsed.
183     */
184     TreeNode* mpNode;
185 
186     /** The index of the currently expanded control.  A value of
187         (sal_uInt32)-1 indicates that no control is active.  This may be the
188         case after adding controls to the container.
189     */
190     sal_uInt32 mnActiveControlIndex;
191 
192     bool mbMultiSelection;
193 };
194 
195 } } // end of namespace ::sd::toolpanel
196 
197 #endif
198