interface/collpane.h

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