interface/collpane.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        collpane.h
   3 // Purpose:     interface of wxCollapsiblePane
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCollapsiblePaneEvent
  11     @wxheader{collpane.h}
  12
  13     This event class is used for the events generated by wxCollapsiblePane.
  14
  15     @beginEventTable{wxCollapsiblePaneEvent}
  16     @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
  17            The user expanded or collapsed the collapsible pane.
  18     @endEventTable
  19
  20     @library{wxcore}
  21     @category{events}
  22
  23     @see wxCollapsiblePane
  24 */
  25 class wxCollapsiblePaneEvent : public wxCommandEvent
  26 {
  27 public:
  28     /**
  29         The constructor is not normally used by the user code.
  30     */
  31     wxCollapsiblePaneEvent(wxObject* generator, int id, bool collapsed);
  32
  33     /**
  34         Returns @true if the pane has been collapsed.
  35     */
  36     bool GetCollapsed() const;
  37
  38     /**
  39         Sets this as a collapsed pane event (if @a collapsed is @true) or as an
  40         expanded pane event (if @a collapsed is @false).
  41     */
  42     void SetCollapsed(bool collapsed);
  43 };
  44
  45
  46
  47 /**
  48     @class wxCollapsiblePane
  49     @wxheader{collpane.h}
  50
  51     A collapsible pane is a container with an embedded button-like control
  52     which can be used by the user to collapse or expand the pane's contents.
  53
  54     Once constructed you should use the GetPane() function to access the pane
  55     and add your controls inside it (i.e. use the returned pointer from
  56     GetPane() as parent for the controls which must go in the pane, @b not the
  57     wxCollapsiblePane itself!).
  58
  59     Note that because of its nature of control which can dynamically (and
  60     drastically) change its size at run-time under user-input, when putting
  61     wxCollapsiblePane inside a wxSizer you should be careful to add it with a
  62     proportion value of zero; this is because otherwise all other windows with
  63     non-null proportion values will automatically resize each time the user
  64     expands or collapse the pane window usually resulting in a weird,
  65     flickering effect.
  66
  67     Usage sample:
  68
  69     @code
  70     wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, wxT("Details:"));
  71
  72     // add the pane with a zero proportion value to the 'sz' sizer which contains it
  73     sz->Add(collpane, 0, wxGROW|wxALL, 5);
  74
  75     // now add a test label in the collapsible pane using a sizer to layout it:
  76     wxWindow *win = collpane->GetPane();
  77     wxSizer *paneSz = new wxBoxSizer(wxVERTICAL);
  78     paneSz->Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL, 2);
  79     win->SetSizer(paneSz);
  80     paneSz->SetSizeHints(win);
  81     @endcode
  82
  83     It is only available if @c wxUSE_COLLPANE is set to 1 (the default).
  84
  85     @beginStyleTable
  86     @style{wxCP_DEFAULT_STYLE}
  87            The default style: 0.
  88     @endStyleTable
  89
  90     @beginEventTable{wxCollapsiblePaneEvent}
  91     @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
  92            The user expanded or collapsed the collapsible pane.
  93     @endEventTable
  94
  95     @library{wxcore}
  96     @category{ctrl}
  97     <!-- @appearance{collapsiblepane.png} -->
  98
  99     @see wxPanel, wxCollapsiblePaneEvent
 100 */
 101 class wxCollapsiblePane : public wxControl
 102 {
 103 public:
 104     /**
 105         Default constructor.
 106     */
 107     wxCollapsiblePane();
 108
 109     /**
 110         Initializes the object and calls Create() with all the parameters.
 111     */
 112     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
 113                       const wxString& label,
 114                       const wxPoint& pos = wxDefaultPosition,
 115                       const wxSize& size = wxDefaultSize,
 116                       long style = wxCP_DEFAULT_STYLE,
 117                       const wxValidator& validator = wxDefaultValidator,
 118                       const wxString& name = "collapsiblePane");
 119
 120     /**
 121         @param parent
 122             Parent window, must not be non-@NULL.
 123         @param id
 124             The identifier for the control.
 125         @param label
 126             The initial label shown in the button which allows the user to
 127             expand or collapse the pane window.
 128         @param pos
 129             Initial position.
 130         @param size
 131             Initial size.
 132         @param style
 133             The window style, see wxCP_* flags.
 134         @param validator
 135             Validator which can be used for additional date checks.
 136         @param name
 137             Control name.
 138
 139         @returns @true if the control was successfully created or @false if
 140                  creation failed.
 141     */
 142     bool Create(wxWindow* parent, wxWindowID id,
 143                 const wxString& label,
 144                 const wxPoint& pos = wxDefaultPosition,
 145                 const wxSize& size = wxDefaultSize,
 146                 long style = wxCP_DEFAULT_STYLE,
 147                 const wxValidator& validator = wxDefaultValidator,
 148                 const wxString& name = "collapsiblePane");
 149
 150     /**
 151         Collapses or expands the pane window.
 152     */
 153     void Collapse(bool collapse = true);
 154
 155     /**
 156         Same as calling Collapse(@false).
 157     */
 158     void Expand();
 159
 160     /**
 161         Returns a pointer to the pane window. Add controls to the returned
 162         wxWindow to make them collapsible.
 163     */
 164     wxWindow* GetPane() const;
 165
 166     /**
 167         Returns @true if the pane window is currently hidden.
 168     */
 169     bool IsCollapsed() const;
 170
 171     /**
 172         Returns @true if the pane window is currently shown.
 173     */
 174     bool IsExpanded() const;
 175 };
 176