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