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