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