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 licence
   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     @beginEventEmissionTable{wxCollapsiblePaneEvent,wxNavigationKeyEvent}
  95     @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
  96         The user expanded or collapsed the collapsible pane.
  97     @event{EVT_NAVIGATION_KEY(func)}
  98         Process a navigation key event.
  99     @endEventTable
 100
 101     @library{wxcore}
 102     @category{ctrl}
 103     @appearance{collapsiblepane.png}
 104
 105     @see wxPanel, wxCollapsiblePaneEvent
 106 */
 107 class wxCollapsiblePane : public wxControl
 108 {
 109 public:
 110     /**
 111         Default constructor.
 112     */
 113     wxCollapsiblePane();
 114
 115     /**
 116         Initializes the object and calls Create() with all the parameters.
 117     */
 118     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
 119                       const wxString& label,
 120                       const wxPoint& pos = wxDefaultPosition,
 121                       const wxSize& size = wxDefaultSize,
 122                       long style = wxCP_DEFAULT_STYLE,
 123                       const wxValidator& validator = wxDefaultValidator,
 124                       const wxString& name = wxCollapsiblePaneNameStr);
 125
 126     /**
 127         @param parent
 128             Parent window, must not be non-@NULL.
 129         @param id
 130             The identifier for the control.
 131         @param label
 132             The initial label shown in the button which allows the user to
 133             expand or collapse the pane window.
 134         @param pos
 135             Initial position.
 136         @param size
 137             Initial size.
 138         @param style
 139             The window style, see wxCP_* flags.
 140         @param validator
 141             Validator which can be used for additional date checks.
 142         @param name
 143             Control name.
 144
 145         @return @true if the control was successfully created or @false if
 146                 creation failed.
 147     */
 148     bool Create(wxWindow* parent, wxWindowID id,
 149                 const wxString& label,
 150                 const wxPoint& pos = wxDefaultPosition,
 151                 const wxSize& size = wxDefaultSize,
 152                 long style = wxCP_DEFAULT_STYLE,
 153                 const wxValidator& validator = wxDefaultValidator,
 154                 const wxString& name = wxCollapsiblePaneNameStr);
 155
 156     /**
 157         Collapses or expands the pane window.
 158     */
 159     virtual void Collapse(bool collapse = true);
 160
 161     /**
 162         Same as calling Collapse(@false).
 163     */
 164     void Expand();
 165
 166     /**
 167         Returns a pointer to the pane window. Add controls to the returned
 168         wxWindow to make them collapsible.
 169     */
 170     virtual wxWindow* GetPane() const;
 171
 172     /**
 173         Returns @true if the pane window is currently hidden.
 174     */
 175     virtual bool IsCollapsed() const;
 176
 177     /**
 178         Returns @true if the pane window is currently shown.
 179     */
 180     bool IsExpanded() const;
 181 };
 182