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() const;
  35
  36     /**
  37         Sets this as a collapsed pane event (if @a collapsed is @true) or as an
  38         expanded
  39         pane event (if @a 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         @param id
 126             The identifier for the control.
 127         @param label
 128             The initial label shown in the button which allows the user to expand or
 129         collapse the pane window.
 130         @param pos
 131             Initial position.
 132         @param size
 133             Initial size.
 134         @param style
 135             The window style, see wxCP_* flags.
 136         @param validator
 137             Validator which can be used for additional date checks.
 138         @param name
 139             Control name.
 140
 141         @returns @true if the control was successfully created or @false if
 142                  creation failed.
 143     */
 144     bool Create(wxWindow* parent, wxWindowID id,
 145                 const wxString& label,
 146                 const wxPoint& pos = wxDefaultPosition,
 147                 const wxSize& size = wxDefaultSize,
 148                 long style = wxCP_DEFAULT_STYLE,
 149                 const wxValidator& validator = wxDefaultValidator,
 150                 const wxString& name = "collapsiblePane");
 151
 152     /**
 153         Same as @c wxCollapsiblePane::Collapse(@false).
 154     */
 155     void Expand();
 156
 157     /**
 158         Returns a pointer to the pane window. Add controls to the returned wxWindow
 159         to make them collapsible.
 160     */
 161     wxWindow* GetPane() const;
 162
 163     /**
 164         Returns @true if the pane window is currently hidden.
 165     */
 166     bool IsCollapsed() const;
 167
 168     /**
 169         Returns @true if the pane window is currently shown.
 170     */
 171     bool IsExpanded() const;
 172 };