contrib/include/wx/foldbar/foldpanelbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wxFoldPanelBar.h
   3 // Author:      XX
   4 // Created:     Tuesday, June 22, 2004 20:40:00
   5 // Copyright:   XX
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 #ifndef __WXFOLDPANELBAR_H__
   9 #define __WXFOLDPANELBAR_H__
  10
  11 #ifndef WX_PRECOMP
  12     #include "wx/wx.h"
  13 #endif
  14
  15 #include "foldpanelitem.h"
  16
  17 /** Not yet supported but added for future reference. Single fold forces other panels to close when
  18     they are open, and only opens the current panel. This will allow the open panel to gain the full
  19         size left in the client area */
  20 #define wxFPB_SINGLE_FOLD                       0x0001
  21
  22 /** All panels are stacked to the bottom. When they are expanded again they show up at the top */
  23 #define wxFPB_COLLAPSE_TO_BOTTOM        0x0002
  24
  25 /** Not yet supported, but added for future reference. Single fold plus panels will be stacked at the bottom */
  26 #define wxFPB_EXCLUSIVE_FOLD            wxFPB_SINGLE_FOLD | wxFPB_COLLAPSE_TO_BOTTOM
  27
  28 /** Default style of the wxFoldPanelBar */
  29 #define wxFPB_DEFAULT_EXTRASTYLE        0
  30
  31 #define wxFPB_DEFAULT_STYLE                     wxTAB_TRAVERSAL | wxNO_BORDER
  32
  33 /** \class wxFoldPanel
  34         This class is used to return a reference to the fold panel that is added by wxFoldPanelBar::AddFoldPanel(). Use
  35         wxFoldPanel::IsOk() to check wether the result is ok to be used in further operations. Use wxFoldPanel::GetItem()
  36         to obtain a parent window reference to create the controls on you want to add with wxFoldPanelBar::AddFoldPanelWindow().<br><br>
  37 */
  38
  39 class wxFoldPanel
  40 {
  41 private:
  42         wxFoldPanelItem *_item;
  43
  44 public:
  45         /** Constructor, usually not directly used by the developer. */
  46         wxFoldPanel(wxFoldPanelItem *item)
  47                 : _item(item)
  48         {
  49         }
  50
  51         /** Returns true if this is a valid wxFoldPanelItem reference. */
  52         bool IsOk() const {
  53                 return (_item != 0);
  54         };
  55
  56         /** Copy operator to assign one instance to the other, this is needed because these classes are passed
  57             as instance not by reference. */
  58         virtual void operator=(const wxFoldPanel &item) {
  59                 _item = item._item;
  60         };
  61
  62 #ifndef _NO_DOXYGEN_
  63         // not allowed to be seen by doxygen
  64         wxFoldPanelItem *GetItem() const {
  65                 return _item;
  66         };
  67 #endif
  68
  69         /** Use this method to obtain the wxPanel derived class to which you need to add your components. For example;<br>
  70
  71         \code
  72                 wxFoldPanel item = _pnl->AddFoldPanel("Test me", false);
  73                 _pnl->AddFoldPanelWindow(item, new wxButton(item.GetParent(), -1, "Press Me"));
  74         \endcode
  75         */
  76         wxFoldPanelItem *GetParent() const {
  77                 wxASSERT(_item);
  78                 return _item;
  79         };
  80
  81
  82 };
  83
  84 #include <wx/dynarray.h>
  85 WX_DEFINE_ARRAY(wxFoldPanelItem *, wxFoldPanelItemArray);
  86
  87 /** \class wxFoldPanelBar
  88         The wxFoldPanelBar is a class which can maintain a list of collapsable panels. Once a panel is collapsed, only
  89         it's panel bar is visible to the user. This will provide more space for the other panels, or allow the user to
  90         close panels which are not used often to get the most out of the work area.
  91
  92         This control is easy to use. Simply create it as a child for a panel or sash window, and populate panels with
  93         wxFoldPanelBar::AddFoldPanel(). Then use the wxFoldPanelBar::AddFoldPanelWindow() to add wxWindow derived controls
  94         to the current fold panel. Use wxFoldPanelBar::AddFoldPanelSeperator() to put separators between the groups of
  95         controls that need a visual separator to group them together. After all is constructed, the user can fold
  96         the panels by doubleclicking on the bar or single click on the arrow, which will indicate the collapsed or
  97         expanded state.
  98 */
  99
 100 class wxFoldPanelBar: public wxPanel
 101 {
 102 private:
 103     DECLARE_CLASS( wxFoldPanelBar )
 104     DECLARE_EVENT_TABLE()
 105
 106         wxImageList *_images;
 107         wxFoldPanelItemArray _panels;
 108         wxBoxSizer* _panelSizer;
 109         wxPanel *_foldPanel, *_bottomPanel;
 110         wxFlexGridSizer* _mainSizer;
 111         bool _controlCreated;
 112         wxBitmap *_moreBmp;
 113         int _extraStyle;
 114
 115 private:
 116         /** Refreshes all the panels from given index down to last one */
 117         void RefreshPanelsFrom(size_t i);
 118
 119         /** Refreshes all the panels from given pointer down to last one in the list */
 120         void RefreshPanelsFrom(wxFoldPanelItem *item);
 121
 122         /** Returns the height of the panels that are expanded and collapsed. This is useful to determine
 123             quickly what size is used to display, and what is left at the bottom to allign
 124                 the collapsed panels. */
 125         int GetPanelsHeight(int &collapsed, int &expanded);
 126
 127         /** Reposition all the collapsed panels to the bottom. When it is not possible to
 128                 allign them to the bottom, stick them behind the visible panels. The Rect holds the
 129                 slack area left between last repositioned panel and the bottom panels. This needs to
 130                 get a refresh */
 131         wxRect RepositionCollapsedToBottom();
 132
 133 public:
 134     /** Two step constructor used for XRC. Use wxFoldPanelBar::Create() to create the panel. Do not call
 135             any other methods before the control is fully created! */
 136     wxFoldPanelBar();
 137     /** One step creation. Look at wxPanel for the argument and style flags. The extraStyle flags are
 138         - wxFPB_DEFAULT_EXTRASTYLE : Takes default styles.
 139         - wxFPB_COLLAPSE_TO_BOTTOM : When panels are collapsed, they are put at the bottom of the area. */
 140         wxFoldPanelBar( wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition,
 141                     const wxSize& size = wxDefaultSize, long style = wxFPB_DEFAULT_STYLE,
 142                                         long extraStyle = wxFPB_DEFAULT_EXTRASTYLE);
 143
 144         /** wxFoldPanelBar destructor */
 145         virtual ~wxFoldPanelBar();
 146
 147         /** Two step create call. Use this when the control is not created using the wxPanel derived constructor.
 148             WARNING: Do not create this component more then once! */
 149         virtual void Create( wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition,
 150                                  const wxSize& size = wxDefaultSize, long style = wxFPB_DEFAULT_STYLE,
 151                                                  long extraStyle = wxFPB_DEFAULT_EXTRASTYLE);
 152
 153         /** Adds a fold panel to the list of panels. If the flag collapsedInitially is set to true, the panel
 154             is collapsed initially. The wxFoldPanel item which is returned, can be used as a reference to
 155                 perform actions upon the fold panel like collapsing it, expanding it, or deleting it from the list.
 156
 157                 Use this foldpanel to add windows to it. Please consult wxFoldPanelBar::AddFoldPanelWindow() and
 158                 wxFoldPanelBar::AddFoldPanelSeparator() how to add wxWindow items to the panels. */
 159         wxFoldPanel AddFoldPanel(const wxString &caption, bool collapsedInitially = false,
 160                                      const wxCaptionBarStyle &style = wxEmptyCaptionBarStyle);
 161
 162
 163         /** Adds a wxWindow derived class to the referenced wxFoldPanel. IMPORTANT: Make the to be created window,
 164             child of the wxFoldPanel. See example that follows. The flags to be used are:
 165         - wxFPB_ALIGN_WIDTH: Which means the wxWindow to be added will be alligned to fit the width of the
 166           wxFoldPanel when it is resized. Very handy for sizer items, buttons and text boxes.
 167         - wxFPB_ALIGN_LEFT: Alligns left instead of fitting the width of the child window to be added. Use either
 168           this one or wxFPB_ALIGN_WIDTH.
 169
 170             The wxWindow to be added can be slightly indented from left and right so it is more visibly placed
 171                 in the wxFoldPanel. Use ySpacing > 0 to give the control an y offset from the previous wxWindow added,
 172                 use leftSpacing to give it a slight indent from the left, and rightSpacing also reserves a little space
 173                 on the right so the wxWindow can be properly placed in the wxFoldPanel.
 174
 175                 The following example adds a wxFoldPanel to the wxFoldPanelBar and adds two wxWindow derived controls
 176                 to the wxFoldPanel:
 177
 178                 \code
 179
 180                         // create the wxFoldPanelBar
 181                         _pnl = new wxFoldPanelBar(this, -1, wxDefaultPosition, wxDefaultSize, wxFPB_DEFAULT_STYLE, wxFPB_COLLAPSE_TO_BOTTOM);
 182
 183                         // add a foldpanel to the control. "Test me" is the caption and it is initially not collapsed.
 184                         wxFoldPanel item = _pnl->AddFoldPanel("Test me", false);
 185
 186                         // now add a button to the fold panel. Mind that the button should be made child of the
 187                         // wxFoldPanel and not of the main form.
 188                         _pnl->AddFoldPanelWindow(item, new wxButton(item.GetParent(), ID_COLLAPSEME, "Collapse Me"));
 189
 190                         // add a separator between the two controls. This is purely a visual line that can have a certain
 191                         // color and also the indents and width alligning like a control.
 192                         _pnl->AddFoldPanelSeperator(item);
 193
 194                         // now add a text ctrl. Also very easy. Allign this on width so that when the control gets wider
 195                         // the text control also sizes along.
 196                         _pnl->AddFoldPanelWindow(item, new wxTextCtrl(item.GetParent(), -1, "Comment"), wxFPB_ALIGN_WIDTH, wxFPB_DEFAULT_YSPACING, 20);
 197
 198                 \endcode
 199         */
 200         int AddFoldPanelWindow(const wxFoldPanel &panel, wxWindow *window, int flags = wxFPB_ALIGN_WIDTH,
 201                                                    int ySpacing = wxFPB_DEFAULT_YSPACING, int leftSpacing = wxFPB_DEFAULT_LEFTSPACING,
 202                                                    int rightSpacing = wxFPB_DEFAULT_RIGHTSPACING);
 203
 204         /** Adds a seperator line to the current wxFoldPanel. The seperator is a simple line which is drawn and is no
 205             real component. It can be used to seperate groups of controls which belong to eachother. The colour is
 206                 adjustable, and it takes the same ySpacing, leftSpacing and rightSpacing as AddFoldPanelWindow(). */
 207         int AddFoldPanelSeperator(const wxFoldPanel &panel, const wxColour &color = wxColour(167,167,167),
 208                                                    int ySpacing = wxFPB_DEFAULT_YSPACING, int leftSpacing = wxFPB_DEFAULT_LEFTLINESPACING,
 209                                                    int rightSpacing = wxFPB_DEFAULT_RIGHTLINESPACING);
 210
 211         /** Returns the number of panels currently present in the wxFoldPanelBar. This is independent if they are
 212             visible or hidden. */
 213         size_t GetCount() const {
 214                 return _panels.GetCount();
 215         };
 216
 217         /** Returns the wxFoldPanel reference belonging to the current index. An empty panel is returned when the
 218             index is out of bounds. Use GetCount() to get the amount of panels present. Collapsing and folding the
 219                 panel does not change the order in which they are indexed. So it is safe enough to keep a reference
 220                 to the panel by number. */
 221         wxFoldPanel Item(size_t i) {
 222                 wxCHECK(i >= 0 && i < GetCount(), wxFoldPanel(0));
 223                 return wxFoldPanel(_panels.Item(i));
 224         };
 225
 226         /** Collapses the given wxFoldPanel reference, and updates the foldpanel bar. In the wxFPB_COLLAPSE_TO_BOTTOM
 227             style, all collapsed captions are put at the bottom of the control. In the normal mode, they stay where
 228                 they are */
 229         void Collapse(const wxFoldPanel &item) {
 230                 wxCHECK2(item.IsOk(), return);
 231                 item.GetItem()->Collapse();
 232
 233                 RefreshPanelsFrom(item.GetItem());
 234         };
 235
 236         /** Expands the given wxFoldPanel reference, and updates the foldpanel bar. In the wxFPB_COLLAPSE_TO_BOTTOM
 237            they will be removed from the bottom and the order where the panel originally was placed is restored.  */
 238         void Expand(const wxFoldPanel &item) {
 239                 wxCHECK2(item.IsOk(), return);
 240                 item.GetItem()->Expand();
 241
 242                 RefreshPanelsFrom(item.GetItem());
 243         };
 244
 245  /** Sets the style of the caption bar (called wxCaptionBar) of the wxFoldPanel. The changes are applied immediately.
 246             All styles not set in the wxCaptionBarStyle class are not applied. Use the wxCaptionBar reference to indicate
 247                 what captionbar you want to apply the style to. To apply one style to all wxCaptionBar items, use
 248                 ApplyCaptionStyleAll() */
 249         void ApplyCaptionStyle(wxFoldPanel &fp, const wxCaptionBarStyle &style) {
 250                 wxCHECK2(fp.IsOk(), return);
 251                 fp.GetItem()->ApplyCaptionStyle(style);
 252         };
 253
 254         /** Sets the style of all the caption bars of the wxFoldPanel. The changes are applied immediately */
 255         void ApplyCaptionStyleAll(const wxCaptionBarStyle &style) {
 256                 for(size_t i = 0; i < GetCount(); i++)
 257                 {
 258                         wxFoldPanel item = Item(i);
 259                         ApplyCaptionStyle(item, style);
 260                 }
 261         };
 262
 263         /** Returns the currently used caption style for the wxFoldPanel. It is returned as a wxCaptionBarStyle class.
 264             after modifying it, it can be set again */
 265         wxCaptionBarStyle GetCaptionStyle(wxFoldPanel &fp) const {
 266                 wxCHECK2(fp.IsOk(), wxEmptyCaptionBarStyle);
 267                 return fp.GetItem()->GetCaptionStyle();
 268         };
 269
 270
 271 private:
 272         void OnPressCaption(wxCaptionBarEvent &event);
 273         void OnSizePanel(wxSizeEvent &event);
 274
 275         /** Resize the fold panels so they match the width */
 276         void RedisplayFoldPanelItems();
 277
 278         void OnPaint(wxPaintEvent &event);
 279 };
 280
 281 #endif // __WXFOLDPANELBAR_H__