include/wx/containr.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/containr.h
   3 // Purpose:     wxControlContainer and wxNavigationEnabled declarations
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     06.08.01
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2001, 2011 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_CONTAINR_H_
  13 #define _WX_CONTAINR_H_
  14
  15 #include "wx/defs.h"
  16
  17 class WXDLLIMPEXP_FWD_CORE wxWindow;
  18 class WXDLLIMPEXP_FWD_CORE wxWindowBase;
  19
  20 /*
  21     This header declares wxControlContainer class however it's not a real
  22     container of controls but rather just a helper used to implement TAB
  23     navigation among the window children. You should rarely need to use it
  24     directly, derive from the documented public wxNavigationEnabled<> class to
  25     implement TAB navigation in a custom composite window.
  26  */
  27
  28 // ----------------------------------------------------------------------------
  29 // wxControlContainerBase: common part used in both native and generic cases
  30 // ----------------------------------------------------------------------------
  31
  32 class WXDLLIMPEXP_CORE wxControlContainerBase
  33 {
  34 public:
  35     // default ctor, SetContainerWindow() must be called later
  36     wxControlContainerBase()
  37     {
  38         m_winParent = NULL;
  39
  40         // do accept focus initially, we'll stop doing it if/when any children
  41         // are added
  42         m_acceptsFocus = true;
  43         m_inSetFocus = false;
  44         m_winLastFocused = NULL;
  45     }
  46     virtual ~wxControlContainerBase() {}
  47
  48     void SetContainerWindow(wxWindow *winParent)
  49     {
  50         wxASSERT_MSG( !m_winParent, wxT("shouldn't be called twice") );
  51
  52         m_winParent = winParent;
  53     }
  54
  55     // should be called from SetFocus(), returns false if we did nothing with
  56     // the focus and the default processing should take place
  57     bool DoSetFocus();
  58
  59     // should be called when we decide that we should [stop] accepting focus
  60     void SetCanFocus(bool acceptsFocus);
  61
  62     // returns whether we should accept focus ourselves or not
  63     bool AcceptsFocus() const { return m_acceptsFocus; }
  64
  65     // returns whether we or one of our children accepts focus: we always do
  66     // because if we don't have any focusable children it probably means that
  67     // we're not being used as a container at all (think of wxGrid or generic
  68     // wxListCtrl) and so should get focus for ourselves
  69     bool AcceptsFocusRecursively() const { return true; }
  70
  71     // this is used to determine whether we can accept focus when Tab or
  72     // another navigation key is pressed -- we alsways can, for the same reason
  73     // as mentioned above for AcceptsFocusRecursively()
  74     bool AcceptsFocusFromKeyboard() const { return true; }
  75
  76     // Call this when the number of children of the window changes.
  77     // If we have any children, this panel (used just as container for
  78     // them) shouldn't get focus for itself.
  79     void UpdateCanFocus() { SetCanFocus(!HasAnyFocusableChildren()); }
  80
  81 protected:
  82     // set the focus to the child which had it the last time
  83     virtual bool SetFocusToChild();
  84
  85     // return true if we have any children accepting focus
  86     bool HasAnyFocusableChildren() const;
  87
  88     // the parent window we manage the children for
  89     wxWindow *m_winParent;
  90
  91     // the child which had the focus last time this panel was activated
  92     wxWindow *m_winLastFocused;
  93
  94 private:
  95     // value returned by AcceptsFocus(), should be changed using SetCanFocus()
  96     // only
  97     bool m_acceptsFocus;
  98
  99     // a guard against infinite recursion
 100     bool m_inSetFocus;
 101 };
 102
 103 #ifdef wxHAS_NATIVE_TAB_TRAVERSAL
 104
 105 // ----------------------------------------------------------------------------
 106 // wxControlContainer for native TAB navigation
 107 // ----------------------------------------------------------------------------
 108
 109 // this must be a real class as we forward-declare it elsewhere
 110 class WXDLLIMPEXP_CORE wxControlContainer : public wxControlContainerBase
 111 {
 112 protected:
 113     // set the focus to the child which had it the last time
 114     virtual bool SetFocusToChild();
 115 };
 116
 117 #else // !wxHAS_NATIVE_TAB_TRAVERSAL
 118
 119 class WXDLLIMPEXP_FWD_CORE wxFocusEvent;
 120 class WXDLLIMPEXP_FWD_CORE wxNavigationKeyEvent;
 121
 122 // ----------------------------------------------------------------------------
 123 // wxControlContainer for TAB navigation implemented in wx itself
 124 // ----------------------------------------------------------------------------
 125
 126 class WXDLLIMPEXP_CORE wxControlContainer : public wxControlContainerBase
 127 {
 128 public:
 129     // default ctor, SetContainerWindow() must be called later
 130     wxControlContainer();
 131
 132     // the methods to be called from the window event handlers
 133     void HandleOnNavigationKey(wxNavigationKeyEvent& event);
 134     void HandleOnFocus(wxFocusEvent& event);
 135     void HandleOnWindowDestroy(wxWindowBase *child);
 136
 137     // called from OnChildFocus() handler, i.e. when one of our (grand)
 138     // children gets the focus
 139     void SetLastFocus(wxWindow *win);
 140
 141 protected:
 142
 143     wxDECLARE_NO_COPY_CLASS(wxControlContainer);
 144 };
 145
 146 #endif // wxHAS_NATIVE_TAB_TRAVERSAL/!wxHAS_NATIVE_TAB_TRAVERSAL
 147
 148 // this function is for wxWidgets internal use only
 149 extern bool wxSetFocusToChild(wxWindow *win, wxWindow **child);
 150
 151 // ----------------------------------------------------------------------------
 152 // wxNavigationEnabled: Derive from this class to support keyboard navigation
 153 // among window children in a wxWindow-derived class. The details of this class
 154 // don't matter, you just need to derive from it to make navigation work.
 155 // ----------------------------------------------------------------------------
 156
 157 // The template parameter W must be a wxWindow-derived class.
 158 template <class W>
 159 class wxNavigationEnabled : public W
 160 {
 161 public:
 162     typedef W BaseWindowClass;
 163
 164     wxNavigationEnabled()
 165     {
 166         m_container.SetContainerWindow(this);
 167
 168 #ifndef wxHAS_NATIVE_TAB_TRAVERSAL
 169         Connect(wxEVT_NAVIGATION_KEY,
 170                 wxNavigationKeyEventHandler(wxNavigationEnabled::OnNavigationKey));
 171
 172         Connect(wxEVT_SET_FOCUS,
 173                 wxFocusEventHandler(wxNavigationEnabled::OnFocus));
 174
 175         Connect(wxEVT_CHILD_FOCUS,
 176                 wxChildFocusEventHandler(wxNavigationEnabled::OnChildFocus));
 177 #endif // !wxHAS_NATIVE_TAB_TRAVERSAL
 178     }
 179
 180     virtual bool AcceptsFocus() const
 181     {
 182         return m_container.AcceptsFocus();
 183     }
 184
 185     virtual bool AcceptsFocusRecursively() const
 186     {
 187         return m_container.AcceptsFocusRecursively();
 188     }
 189
 190     virtual bool AcceptsFocusFromKeyboard() const
 191     {
 192         return m_container.AcceptsFocusFromKeyboard();
 193     }
 194
 195     virtual void AddChild(wxWindowBase *child)
 196     {
 197         BaseWindowClass::AddChild(child);
 198
 199         m_container.UpdateCanFocus();
 200     }
 201
 202     virtual void RemoveChild(wxWindowBase *child)
 203     {
 204 #ifndef wxHAS_NATIVE_TAB_TRAVERSAL
 205         m_container.HandleOnWindowDestroy(child);
 206 #endif // !wxHAS_NATIVE_TAB_TRAVERSAL
 207
 208         BaseWindowClass::RemoveChild(child);
 209
 210         m_container.UpdateCanFocus();
 211     }
 212
 213     virtual void SetFocus()
 214     {
 215         if ( !m_container.DoSetFocus() )
 216             BaseWindowClass::SetFocus();
 217     }
 218
 219     void SetFocusIgnoringChildren()
 220     {
 221         BaseWindowClass::SetFocus();
 222     }
 223
 224     void AcceptFocus(bool acceptFocus)
 225     {
 226         m_container.SetCanFocus(acceptFocus);
 227     }
 228
 229 protected:
 230 #ifndef wxHAS_NATIVE_TAB_TRAVERSAL
 231     void OnNavigationKey(wxNavigationKeyEvent& event)
 232     {
 233         m_container.HandleOnNavigationKey(event);
 234     }
 235
 236     void OnFocus(wxFocusEvent& event)
 237     {
 238         m_container.HandleOnFocus(event);
 239     }
 240
 241     void OnChildFocus(wxChildFocusEvent& event)
 242     {
 243         m_container.SetLastFocus(event.GetWindow());
 244         event.Skip();
 245     }
 246 #endif // !wxHAS_NATIVE_TAB_TRAVERSAL
 247
 248     wxControlContainer m_container;
 249
 250
 251     wxDECLARE_NO_COPY_TEMPLATE_CLASS(wxNavigationEnabled, W);
 252 };
 253
 254 // ----------------------------------------------------------------------------
 255 // Compatibility macros from now on, do NOT use them and preferably do not even
 256 // look at them.
 257 // ----------------------------------------------------------------------------
 258
 259 #ifdef WXWIN_COMPATIBILITY_2_8
 260
 261 // common part of WX_DECLARE_CONTROL_CONTAINER in the native and generic cases,
 262 // it should be used in the wxWindow-derived class declaration
 263 #define WX_DECLARE_CONTROL_CONTAINER_BASE()                                   \
 264 public:                                                                       \
 265     virtual bool AcceptsFocus() const;                                        \
 266     virtual bool AcceptsFocusRecursively() const;                             \
 267     virtual bool AcceptsFocusFromKeyboard() const;                            \
 268     virtual void AddChild(wxWindowBase *child);                               \
 269     virtual void RemoveChild(wxWindowBase *child);                            \
 270     virtual void SetFocus();                                                  \
 271     void SetFocusIgnoringChildren();                                          \
 272     void AcceptFocus(bool acceptFocus)                                        \
 273     {                                                                         \
 274         m_container.SetCanFocus(acceptFocus);                                 \
 275     }                                                                         \
 276                                                                               \
 277 protected:                                                                    \
 278     wxControlContainer m_container
 279
 280 // this macro must be used in the derived class ctor
 281 #define WX_INIT_CONTROL_CONTAINER() \
 282     m_container.SetContainerWindow(this)
 283
 284 // common part of WX_DELEGATE_TO_CONTROL_CONTAINER in the native and generic
 285 // cases, must be used in the wxWindow-derived class implementation
 286 #define WX_DELEGATE_TO_CONTROL_CONTAINER_BASE(classname, basename)            \
 287     void classname::AddChild(wxWindowBase *child)                             \
 288     {                                                                         \
 289         basename::AddChild(child);                                            \
 290                                                                               \
 291         m_container.UpdateCanFocus();                                         \
 292     }                                                                         \
 293                                                                               \
 294     bool classname::AcceptsFocusRecursively() const                           \
 295     {                                                                         \
 296         return m_container.AcceptsFocusRecursively();                         \
 297     }                                                                         \
 298                                                                               \
 299     void classname::SetFocus()                                                \
 300     {                                                                         \
 301         if ( !m_container.DoSetFocus() )                                      \
 302             basename::SetFocus();                                             \
 303     }                                                                         \
 304                                                                               \
 305     bool classname::AcceptsFocus() const                                      \
 306     {                                                                         \
 307         return m_container.AcceptsFocus();                                    \
 308     }                                                                         \
 309                                                                               \
 310     bool classname::AcceptsFocusFromKeyboard() const                          \
 311     {                                                                         \
 312         return m_container.AcceptsFocusFromKeyboard();                        \
 313     }
 314
 315
 316 #ifdef wxHAS_NATIVE_TAB_TRAVERSAL
 317
 318 #define WX_EVENT_TABLE_CONTROL_CONTAINER(classname)
 319
 320 #define WX_DECLARE_CONTROL_CONTAINER WX_DECLARE_CONTROL_CONTAINER_BASE
 321
 322 #define WX_DELEGATE_TO_CONTROL_CONTAINER(classname, basename)                 \
 323     WX_DELEGATE_TO_CONTROL_CONTAINER_BASE(classname, basename)                \
 324                                                                               \
 325     void classname::RemoveChild(wxWindowBase *child)                          \
 326     {                                                                         \
 327         basename::RemoveChild(child);                                         \
 328                                                                               \
 329         m_container.UpdateCanFocus();                                         \
 330     }                                                                         \
 331                                                                               \
 332     void classname::SetFocusIgnoringChildren()                                \
 333     {                                                                         \
 334         basename::SetFocus();                                                 \
 335     }
 336
 337 #else // !wxHAS_NATIVE_TAB_TRAVERSAL
 338
 339 // declare the methods to be forwarded
 340 #define WX_DECLARE_CONTROL_CONTAINER()                                        \
 341     WX_DECLARE_CONTROL_CONTAINER_BASE();                                      \
 342                                                                               \
 343 public:                                                                       \
 344     void OnNavigationKey(wxNavigationKeyEvent& event);                        \
 345     void OnFocus(wxFocusEvent& event);                                        \
 346     virtual void OnChildFocus(wxChildFocusEvent& event)
 347
 348 // implement the event table entries for wxControlContainer
 349 #define WX_EVENT_TABLE_CONTROL_CONTAINER(classname) \
 350     EVT_SET_FOCUS(classname::OnFocus) \
 351     EVT_CHILD_FOCUS(classname::OnChildFocus) \
 352     EVT_NAVIGATION_KEY(classname::OnNavigationKey)
 353
 354 // implement the methods forwarding to the wxControlContainer
 355 #define WX_DELEGATE_TO_CONTROL_CONTAINER(classname, basename)                 \
 356     WX_DELEGATE_TO_CONTROL_CONTAINER_BASE(classname, basename)                \
 357                                                                               \
 358     void classname::RemoveChild(wxWindowBase *child)                          \
 359     {                                                                         \
 360         m_container.HandleOnWindowDestroy(child);                             \
 361                                                                               \
 362         basename::RemoveChild(child);                                         \
 363                                                                               \
 364         m_container.UpdateCanFocus();                                         \
 365     }                                                                         \
 366                                                                               \
 367     void classname::OnNavigationKey( wxNavigationKeyEvent& event )            \
 368     {                                                                         \
 369         m_container.HandleOnNavigationKey(event);                             \
 370     }                                                                         \
 371                                                                               \
 372     void classname::SetFocusIgnoringChildren()                                \
 373     {                                                                         \
 374         basename::SetFocus();                                                 \
 375     }                                                                         \
 376                                                                               \
 377     void classname::OnChildFocus(wxChildFocusEvent& event)                    \
 378     {                                                                         \
 379         m_container.SetLastFocus(event.GetWindow());                          \
 380         event.Skip();                                                         \
 381     }                                                                         \
 382                                                                               \
 383     void classname::OnFocus(wxFocusEvent& event)                              \
 384     {                                                                         \
 385         m_container.HandleOnFocus(event);                                     \
 386     }
 387
 388 #endif // wxHAS_NATIVE_TAB_TRAVERSAL/!wxHAS_NATIVE_TAB_TRAVERSAL
 389
 390 #endif // WXWIN_COMPATIBILITY_2_8
 391
 392 #endif // _WX_CONTAINR_H_