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