sd/source/ui/inc/taskpane/ControlContainer.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef SD_TOOLPANEL_CONTROL_CONTAINER_HXX
  21 #define SD_TOOLPANEL_CONTROL_CONTAINER_HXX
  22
  23 #include <osl/mutex.hxx>
  24
  25 #include <vector>
  26 #include <memory>
  27
  28 namespace sd { namespace toolpanel {
  29
  30 class TreeNode;
  31
  32 /** This container manages the children of a TreeNode.  It handles the
  33     expansion and visibility state of its child controls.  The container
  34     does not do the layouting or painting of the controls.  Instead it asks
  35     its owner to do that.
  36
  37     The difference between expansion state and visibility is that when a
  38     control is collapsed at least a title bar is shown for it.  When it is
  39     not visible then even this title bar is not shown.  In that case the
  40     user can not expand the control.  A control has to be visible in order
  41     to be expanded or collapsed.
  42
  43     Whenever you expand or collapse, show or hide a child control then use
  44     this container class.  Do not call the respective methods of the child
  45     directly.
  46 */
  47 class ControlContainer
  48 {
  49 public:
  50     enum VisibilityState { VS_SHOW, VS_HIDE, VS_TOGGLE };
  51     enum ExpansionState { ES_EXPAND, ES_COLLAPSE, ES_TOGGLE };
  52
  53     /** Create a new control container.
  54         @param pParent
  55             This node is asked to re-calculate the size of its children when
  56             a child of this container is expanded or collapsed.
  57     */
  58     ControlContainer (TreeNode* pNode);
  59
  60     virtual ~ControlContainer (void);
  61
  62     /** This is function makes sure that all children are deleted.  Call
  63         this function from the destructor of a sub class to have all child
  64         windows deleted before the destructor of another base class of that
  65         sub class is called.  When that other base class is some kind of a
  66         window it would otherwise complain that there are living children.
  67     */
  68     void DeleteChildren (void);
  69
  70     /** Add the given control to the set of controls managed by the
  71         container.  This control is then expanded.
  72         @return
  73             Return the index under which the control has been inserted in
  74             the container.  It is the same index that is returned by
  75             GetControlIndex().
  76     */
  77     sal_uInt32 AddControl (::std::auto_ptr<TreeNode> pControl);
  78
  79     /** Expand (default) or collapse the specified control.  When
  80         expanding a control in a single expansion environment then all
  81         other controls are collapsed.  The specified control is being
  82         made the active control as returned by GetActiveControl().
  83     */
  84     virtual void SetExpansionState (
  85         sal_uInt32 nIndex,
  86         ExpansionState aState);
  87     virtual void SetExpansionState (
  88         TreeNode* pControl,
  89         ExpansionState aState);
  90     virtual void SetVisibilityState (
  91         sal_uInt32 nIndex,
  92         VisibilityState aState);
  93
  94     /** Return the index of the given control.
  95     */
  96     sal_uInt32 GetControlIndex (TreeNode* pControl) const;
  97
  98     /** Return the number of controls in the container.
  99     */
 100     sal_uInt32 GetControlCount (void) const;
 101
 102     /** Return the number of visible controls in the container.
 103     */
 104     sal_uInt32 GetVisibleControlCount (void) const;
 105
 106     /** Return the control with the specified index regardless of whether
 107         that control is hidden or visible.
 108     */
 109     TreeNode* GetControl (sal_uInt32 nIndex) const;
 110
 111     /** Return the index of the control previous to that that is specified
 112         by the given index.
 113         @param nIndex
 114             Index of the control for which to return the index of the
 115             previous control.  This index is guaranteed not to be returned.
 116         @param bIncludeHidden
 117             This flag tells the method whether to include the controls that
 118             are not visible in the search for the previous control.  When it
 119             is <FALSE/> the hidden controls are skipped.
 120         @param bCycle
 121             When this flag is <TRUE/> then the search for the previous
 122             control wraps arround when reaching the first control.
 123         @return
 124             Returns the index to the previous control or (sal_uInt32)-1 when
 125             there is no previous control.  This would be the case when there
 126             is only one (visible) child.
 127     */
 128     sal_uInt32 GetPreviousIndex (
 129         sal_uInt32 nIndex,
 130         bool bIncludeHidden=false,
 131         bool bCycle=false) const;
 132
 133     /** Return the index of the control next to that that is specified by
 134         the given index.
 135         @param nIndex
 136             Index of the control for which to return the index of the next
 137             control.  This index is guaranteed not to be returned.
 138         @param bIncludeHidden
 139             This flag tells the method whether to include the controls that
 140             are not visible in the search for the next control.  When it is
 141             <FALSE/> the hidden controls are skipped.
 142         @param bCycle
 143             When this flag is <TRUE/> then the search for the next control
 144             wraps arround when reaching the last control.
 145         @return
 146             Returns the index to the next control or (sal_uInt32)-1 when
 147             there is no next control.  This would be the case when there is
 148             only one (visible) child.
 149     */
 150     sal_uInt32 GetNextIndex (
 151         sal_uInt32 nIndex,
 152         bool bIncludeHidden=false,
 153         bool bCycle=false) const;
 154
 155     void SetMultiSelection (bool bFlag);
 156
 157     /** This is method is called when the list of controls has changed,
 158         i.e. a new control has been added.  The default implementation is
 159         empty.  Overwrite this method in derived classes in order to react to
 160         such changes.
 161     */
 162     virtual void ListHasChanged (void);
 163
 164 private:
 165     osl::Mutex maMutex;
 166
 167     /// List of controls managed by a container.
 168     typedef ::std::vector<TreeNode*> ControlList;
 169     ControlList maControlList;
 170
 171     /** This parent is used for resize requests when children are expanded
 172         or collapsed.
 173     */
 174     TreeNode* mpNode;
 175
 176     /** The index of the currently expanded control.  A value of
 177         (sal_uInt32)-1 indicates that no control is active.  This may be the
 178         case after adding controls to the container.
 179     */
 180     sal_uInt32 mnActiveControlIndex;
 181
 182     bool mbMultiSelection;
 183 };
 184
 185 } } // end of namespace ::sd::toolpanel
 186
 187 #endif
 188
 189 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */