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         Initializes the object and calls Create() with all the parameters.
 106     */
 107     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
 108                       const wxString& label,
 109                       const wxPoint& pos = wxDefaultPosition,
 110                       const wxSize& size = wxDefaultSize,
 111                       long style = wxCP_DEFAULT_STYLE,
 112                       const wxValidator& validator = wxDefaultValidator,
 113                       const wxString& name = "collapsiblePane");
 114
 115     /**
 116         @param parent
 117             Parent window, must not be non-@NULL.
 118         @param id
 119             The identifier for the control.
 120         @param label
 121             The initial label shown in the button which allows the user to
 122             expand or collapse the pane window.
 123         @param pos
 124             Initial position.
 125         @param size
 126             Initial size.
 127         @param style
 128             The window style, see wxCP_* flags.
 129         @param validator
 130             Validator which can be used for additional date checks.
 131         @param name
 132             Control name.
 133
 134         @returns @true if the control was successfully created or @false if
 135                  creation failed.
 136     */
 137     bool Create(wxWindow* parent, wxWindowID id,
 138                 const wxString& label,
 139                 const wxPoint& pos = wxDefaultPosition,
 140                 const wxSize& size = wxDefaultSize,
 141                 long style = wxCP_DEFAULT_STYLE,
 142                 const wxValidator& validator = wxDefaultValidator,
 143                 const wxString& name = "collapsiblePane");
 144
 145     /**
 146         Collapses or expands the pane window.
 147     */
 148     void Collapse(bool collapse = true);
 149
 150     /**
 151         Same as calling Collapse(@false).
 152     */
 153     void Expand();
 154
 155     /**
 156         Returns a pointer to the pane window. Add controls to the returned
 157         wxWindow to make them collapsible.
 158     */
 159     wxWindow* GetPane() const;
 160
 161     /**
 162         Returns @true if the pane window is currently hidden.
 163     */
 164     bool IsCollapsed() const;
 165
 166     /**
 167         Returns @true if the pane window is currently shown.
 168     */
 169     bool IsExpanded() const;
 170 };
 171