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, "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, "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. It includes wxTAB_TRAVERSAL and wxBORDER_NONE.
  86     @style{wxCP_NO_TLW_RESIZE}
  87         By default wxCollapsiblePane resizes the top level window containing it
  88         when its own size changes. This allows to easily implement dialogs
  89         containing an optionally shown part, for example, and so is the default
  90         behaviour but can be inconvenient in some specific cases -- use this
  91         flag to disable this automatic parent resizing then.
  92     @endStyleTable
  93
  94     @beginEventTable{wxCollapsiblePaneEvent}
  95     @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
  96            The user expanded or collapsed the collapsible pane.
  97     @endEventTable
  98
  99     @library{wxcore}
 100     @category{ctrl}
 101     @appearance{collapsiblepane.png}
 102
 103     @see wxPanel, wxCollapsiblePaneEvent
 104 */
 105 class wxCollapsiblePane : public wxControl
 106 {
 107 public:
 108     /**
 109         Default constructor.
 110     */
 111     wxCollapsiblePane();
 112
 113     /**
 114         Initializes the object and calls Create() with all the parameters.
 115     */
 116     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
 117                       const wxString& label,
 118                       const wxPoint& pos = wxDefaultPosition,
 119                       const wxSize& size = wxDefaultSize,
 120                       long style = wxCP_DEFAULT_STYLE,
 121                       const wxValidator& validator = wxDefaultValidator,
 122                       const wxString& name = wxCollapsiblePaneNameStr);
 123
 124     /**
 125         @param parent
 126             Parent window, must not be non-@NULL.
 127         @param id
 128             The identifier for the control.
 129         @param label
 130             The initial label shown in the button which allows the user to
 131             expand or collapse the pane window.
 132         @param pos
 133             Initial position.
 134         @param size
 135             Initial size.
 136         @param style
 137             The window style, see wxCP_* flags.
 138         @param validator
 139             Validator which can be used for additional date checks.
 140         @param name
 141             Control name.
 142
 143         @return @true if the control was successfully created or @false if
 144                 creation failed.
 145     */
 146     bool Create(wxWindow* parent, wxWindowID id,
 147                 const wxString& label,
 148                 const wxPoint& pos = wxDefaultPosition,
 149                 const wxSize& size = wxDefaultSize,
 150                 long style = wxCP_DEFAULT_STYLE,
 151                 const wxValidator& validator = wxDefaultValidator,
 152                 const wxString& name = wxCollapsiblePaneNameStr);
 153
 154     /**
 155         Collapses or expands the pane window.
 156     */
 157     virtual void Collapse(bool collapse = true);
 158
 159     /**
 160         Same as calling Collapse(@false).
 161     */
 162     void Expand();
 163
 164     /**
 165         Returns a pointer to the pane window. Add controls to the returned
 166         wxWindow to make them collapsible.
 167     */
 168     virtual wxWindow* GetPane() const;
 169
 170     /**
 171         Returns @true if the pane window is currently hidden.
 172     */
 173     virtual bool IsCollapsed() const;
 174
 175     /**
 176         Returns @true if the pane window is currently shown.
 177     */
 178     bool IsExpanded() const;
 179 };
 180