interface/wx/collpane.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        collpane.h
   3 // Purpose:     interface of wxCollapsiblePane
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 #define wxCP_DEFAULT_STYLE          (wxTAB_TRAVERSAL | wxNO_BORDER)
   9 #define wxCP_NO_TLW_RESIZE          (0x0002)
  10
  11 /**
  12     @class wxCollapsiblePaneEvent
  13
  14     This event class is used for the events generated by wxCollapsiblePane.
  15
  16     @beginEventTable{wxCollapsiblePaneEvent}
  17     @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
  18            The user expanded or collapsed the collapsible pane.
  19     @endEventTable
  20
  21     @library{wxcore}
  22     @category{events}
  23
  24     @see wxCollapsiblePane
  25 */
  26 class wxCollapsiblePaneEvent : public wxCommandEvent
  27 {
  28 public:
  29     /**
  30         The constructor is not normally used by the user code.
  31     */
  32     wxCollapsiblePaneEvent(wxObject* generator, int id, bool collapsed);
  33
  34     /**
  35         Returns @true if the pane has been collapsed.
  36     */
  37     bool GetCollapsed() const;
  38
  39     /**
  40         Sets this as a collapsed pane event (if @a collapsed is @true) or as an
  41         expanded pane event (if @a collapsed is @false).
  42     */
  43     void SetCollapsed(bool collapsed);
  44 };
  45
  46 wxEventType wxEVT_COLLAPSIBLEPANE_CHANGED;
  47
  48 /**
  49     @class wxCollapsiblePane
  50
  51     A collapsible pane is a container with an embedded button-like control
  52     which can be used by the user to collapse or expand the pane's contents.
  53
  54     Once constructed you should use the GetPane() function to access the pane
  55     and add your controls inside it (i.e. use the returned pointer from
  56     GetPane() as parent for the controls which must go in the pane, @b not the
  57     wxCollapsiblePane itself!).
  58
  59     Note that because of its nature of control which can dynamically (and
  60     drastically) change its size at run-time under user-input, when putting
  61     wxCollapsiblePane inside a wxSizer you should be careful to add it with a
  62     proportion value of zero; this is because otherwise all other windows with
  63     non-null proportion values will automatically resize each time the user
  64     expands or collapse the pane window usually resulting in a weird,
  65     flickering effect.
  66
  67     Usage sample:
  68
  69     @code
  70     wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, "Details:");
  71
  72     // add the pane with a zero proportion value to the 'sz' sizer which contains it
  73     sz->Add(collpane, 0, wxGROW|wxALL, 5);
  74
  75     // now add a test label in the collapsible pane using a sizer to layout it:
  76     wxWindow *win = collpane->GetPane();
  77     wxSizer *paneSz = new wxBoxSizer(wxVERTICAL);
  78     paneSz->Add(new wxStaticText(win, wxID_ANY, "test!"), 1, wxGROW|wxALL, 2);
  79     win->SetSizer(paneSz);
  80     paneSz->SetSizeHints(win);
  81     @endcode
  82
  83     It is only available if @c wxUSE_COLLPANE is set to 1 (the default).
  84
  85     @beginStyleTable
  86     @style{wxCP_DEFAULT_STYLE}
  87         The default style. It includes wxTAB_TRAVERSAL and wxBORDER_NONE.
  88     @style{wxCP_NO_TLW_RESIZE}
  89         By default wxCollapsiblePane resizes the top level window containing it
  90         when its own size changes. This allows to easily implement dialogs
  91         containing an optionally shown part, for example, and so is the default
  92         behaviour but can be inconvenient in some specific cases -- use this
  93         flag to disable this automatic parent resizing then.
  94     @endStyleTable
  95
  96     @beginEventEmissionTable{wxCollapsiblePaneEvent,wxNavigationKeyEvent}
  97     @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
  98         The user expanded or collapsed the collapsible pane.
  99     @event{EVT_NAVIGATION_KEY(func)}
 100         Process a navigation key event.
 101     @endEventTable
 102
 103     @library{wxcore}
 104     @category{ctrl}
 105     @appearance{collapsiblepane}
 106
 107     @see wxPanel, wxCollapsiblePaneEvent
 108 */
 109 class wxCollapsiblePane : public wxControl
 110 {
 111 public:
 112     /**
 113         Default constructor.
 114     */
 115     wxCollapsiblePane();
 116
 117     /**
 118         Initializes the object and calls Create() with all the parameters.
 119     */
 120     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
 121                       const wxString& label,
 122                       const wxPoint& pos = wxDefaultPosition,
 123                       const wxSize& size = wxDefaultSize,
 124                       long style = wxCP_DEFAULT_STYLE,
 125                       const wxValidator& validator = wxDefaultValidator,
 126                       const wxString& name = wxCollapsiblePaneNameStr);
 127
 128     /**
 129         @param parent
 130             Parent window, must not be non-@NULL.
 131         @param id
 132             The identifier for the control.
 133         @param label
 134             The initial label shown in the button which allows the user to
 135             expand or collapse the pane window.
 136         @param pos
 137             Initial position.
 138         @param size
 139             Initial size.
 140         @param style
 141             The window style, see wxCP_* flags.
 142         @param validator
 143             Validator which can be used for additional date checks.
 144         @param name
 145             Control name.
 146
 147         @return @true if the control was successfully created or @false if
 148                 creation failed.
 149     */
 150     bool Create(wxWindow* parent, wxWindowID id,
 151                 const wxString& label,
 152                 const wxPoint& pos = wxDefaultPosition,
 153                 const wxSize& size = wxDefaultSize,
 154                 long style = wxCP_DEFAULT_STYLE,
 155                 const wxValidator& validator = wxDefaultValidator,
 156                 const wxString& name = wxCollapsiblePaneNameStr);
 157
 158     /**
 159         Collapses or expands the pane window.
 160     */
 161     virtual void Collapse(bool collapse = true);
 162
 163     /**
 164         Same as calling Collapse(@false).
 165     */
 166     void Expand();
 167
 168     /**
 169         Returns a pointer to the pane window. Add controls to the returned
 170         wxWindow to make them collapsible.
 171     */
 172     virtual wxWindow* GetPane() const;
 173
 174     /**
 175         Returns @true if the pane window is currently hidden.
 176     */
 177     virtual bool IsCollapsed() const;
 178
 179     /**
 180         Returns @true if the pane window is currently shown.
 181     */
 182     bool IsExpanded() const;
 183 };