interface/collpane.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        collpane.h
   3 // Purpose:     documentation for wxCollapsiblePaneEvent class
   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     @seealso
  20     wxCollapsiblePane
  21 */
  22 class wxCollapsiblePaneEvent : public wxCommandEvent
  23 {
  24 public:
  25     /**
  26         The constructor is not normally used by the user code.
  27     */
  28     wxCollapsiblePaneEvent(wxObject * generator, int id,
  29                            bool collapsed);
  30
  31     /**
  32         Returns @true if the pane has been collapsed.
  33     */
  34     bool GetCollapsed();
  35
  36     /**
  37         Sets this as a collapsed pane event (if @e collapsed is @true) or as an
  38         expanded
  39         pane event (if @e collapsed is @false).
  40     */
  41     void SetCollapsed(bool collapsed);
  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     @seealso
 100     wxPanel, wxCollapsiblePaneEvent
 101 */
 102 class wxCollapsiblePane : public wxControl
 103 {
 104 public:
 105     /**
 106         Initializes the object and calls Create() with
 107         all the parameters.
 108     */
 109     wxCollapsiblePane(wxWindow * parent, wxWindowID id,
 110                       const wxString& label,
 111                       const wxPoint& pos = wxDefaultPosition,
 112                       const wxSize& size = wxDefaultSize,
 113                       long style = wxCP_DEFAULT_STYLE,
 114                       const wxValidator& validator = wxDefaultValidator,
 115                       const wxString& name = "collapsiblePane");
 116
 117     /**
 118         Collapses or expands the pane window.
 119     */
 120     void Collapse(bool collapse = @true);
 121
 122     /**
 123         @param parent
 124         Parent window, must not be non-@NULL.
 125
 126         @param id
 127         The identifier for the control.
 128
 129         @param label
 130         The initial label shown in the button which allows the user to expand or
 131         collapse the pane window.
 132
 133         @param pos
 134         Initial position.
 135
 136         @param size
 137         Initial size.
 138
 139         @param style
 140         The window style, see wxCP_* flags.
 141
 142         @param validator
 143         Validator which can be used for additional date checks.
 144
 145         @param name
 146         Control name.
 147
 148         @returns @true if the control was successfully created or @false if
 149                    creation failed.
 150     */
 151     bool Create(wxWindow * parent, wxWindowID id,
 152                 const wxString& label,
 153                 const wxPoint& pos = wxDefaultPosition,
 154                 const wxSize& size = wxDefaultSize,
 155                 long style = wxCP_DEFAULT_STYLE,
 156                 const wxValidator& validator = wxDefaultValidator,
 157                 const wxString& name = "collapsiblePane");
 158
 159     /**
 160         Same as @c wxCollapsiblePane::Collapse(@false).
 161     */
 162     void Expand();
 163
 164     /**
 165         Returns a pointer to the pane window. Add controls to the returned wxWindow
 166         to make them collapsible.
 167     */
 168     wxWindow * GetPane();
 169
 170     /**
 171         Returns @true if the pane window is currently hidden.
 172     */
 173     bool IsCollapsed();
 174
 175     /**
 176         Returns @true if the pane window is currently shown.
 177     */
 178     bool IsExpanded();
 179 };