include/wx/containr.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/containr.h
   3 // Purpose:     wxControlContainer class declration: a "mix-in" class which
   4 //              implements the TAB navigation between the controls
   5 // Author:      Vadim Zeitlin
   6 // Modified by:
   7 // Created:     06.08.01
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2001 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
  10 // Licence:     wxWindows licence
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_CONTAINR_H_
  14 #define _WX_CONTAINR_H_
  15
  16 #include "wx/defs.h"
  17
  18 class WXDLLIMPEXP_FWD_CORE wxWindow;
  19 class WXDLLIMPEXP_FWD_CORE wxWindowBase;
  20
  21 /*
  22    Implementation note: wxControlContainer is not a real mix-in but rather
  23    a class meant to be aggregated with (and not inherited from). Although
  24    logically it should be a mix-in, doing it like this has no advantage from
  25    the point of view of the existing code but does have some problems (we'd
  26    need to play tricks with event handlers which may be difficult to do
  27    safely). The price we pay for this simplicity is the ugly macros below.
  28  */
  29
  30 // ----------------------------------------------------------------------------
  31 // wxControlContainerBase: common part used in both native and generic cases
  32 // ----------------------------------------------------------------------------
  33
  34 class WXDLLIMPEXP_CORE wxControlContainerBase
  35 {
  36 public:
  37     // default ctor, SetContainerWindow() must be called later
  38     wxControlContainerBase()
  39     {
  40         m_winParent = NULL;
  41
  42         // do accept focus initially, we'll stop doing it if/when any children
  43         // are added
  44         m_acceptsFocus = true;
  45         m_inSetFocus = false;
  46         m_winLastFocused = NULL;
  47     }
  48     virtual ~wxControlContainerBase() {}
  49
  50     void SetContainerWindow(wxWindow *winParent)
  51     {
  52         wxASSERT_MSG( !m_winParent, _T("shouldn't be called twice") );
  53
  54         m_winParent = winParent;
  55     }
  56
  57     // should be called from SetFocus(), returns false if we did nothing with
  58     // the focus and the default processing should take place
  59     bool DoSetFocus();
  60
  61     // should be called when we decide that we should [stop] accepting focus
  62     void SetCanFocus(bool acceptsFocus);
  63
  64     // returns whether we should accept focus ourselves or not
  65     bool AcceptsFocus() const { return m_acceptsFocus; }
  66
  67     // returns whether we or one of our children accepts focus: we always do
  68     // because if we don't have any focusable children it probably means that
  69     // we're not being used as a container at all (think of wxGrid or generic
  70     // wxListCtrl) and so should get focus for ourselves
  71     bool AcceptsFocusRecursively() const { return true; }
  72
  73     // this is used to determine whether we can accept focus when Tab or
  74     // another navigation key is pressed -- we alsways can, for the same reason
  75     // as mentioned above for AcceptsFocusRecursively()
  76     bool AcceptsFocusFromKeyboard() const { return true; }
  77
  78     // Call this when the number of children of the window changes.
  79     // If we have any children, this panel (used just as container for
  80     // them) shouldn't get focus for itself.
  81     void UpdateCanFocus() { SetCanFocus(!HasAnyFocusableChildren()); }
  82
  83 protected:
  84     // set the focus to the child which had it the last time
  85     virtual bool SetFocusToChild();
  86
  87     // return true if we have any children accepting focus
  88     bool HasAnyFocusableChildren() const;
  89
  90     // the parent window we manage the children for
  91     wxWindow *m_winParent;
  92
  93     // the child which had the focus last time this panel was activated
  94     wxWindow *m_winLastFocused;
  95
  96 private:
  97     // value returned by AcceptsFocus(), should be changed using SetCanFocus()
  98     // only
  99     bool m_acceptsFocus;
 100
 101     // a guard against infinite recursion
 102     bool m_inSetFocus;
 103 };
 104
 105 // common part of WX_DECLARE_CONTROL_CONTAINER in the native and generic cases,
 106 // it should be used in the wxWindow-derived class declaration
 107 #define WX_DECLARE_CONTROL_CONTAINER_BASE()                                   \
 108 public:                                                                       \
 109     virtual bool AcceptsFocus() const;                                        \
 110     virtual bool AcceptsFocusRecursively() const;                             \
 111     virtual bool AcceptsFocusFromKeyboard() const;                            \
 112     virtual void AddChild(wxWindowBase *child);                               \
 113     virtual void RemoveChild(wxWindowBase *child);                            \
 114     virtual void SetFocus();                                                  \
 115     void SetFocusIgnoringChildren();                                          \
 116     void AcceptFocus(bool acceptFocus)                                        \
 117     {                                                                         \
 118         m_container.SetCanFocus(acceptFocus);                                 \
 119     }                                                                         \
 120                                                                               \
 121 protected:                                                                    \
 122     wxControlContainer m_container
 123
 124 // this macro must be used in the derived class ctor
 125 #define WX_INIT_CONTROL_CONTAINER() \
 126     m_container.SetContainerWindow(this)
 127
 128 // common part of WX_DELEGATE_TO_CONTROL_CONTAINER in the native and generic
 129 // cases, must be used in the wxWindow-derived class implementation
 130 #define WX_DELEGATE_TO_CONTROL_CONTAINER_BASE(classname, basename)            \
 131     void classname::AddChild(wxWindowBase *child)                             \
 132     {                                                                         \
 133         basename::AddChild(child);                                            \
 134                                                                               \
 135         m_container.UpdateCanFocus();                                         \
 136     }                                                                         \
 137                                                                               \
 138     bool classname::AcceptsFocusRecursively() const                           \
 139     {                                                                         \
 140         return m_container.AcceptsFocusRecursively();                         \
 141     }                                                                         \
 142                                                                               \
 143     void classname::SetFocus()                                                \
 144     {                                                                         \
 145         if ( !m_container.DoSetFocus() )                                      \
 146             basename::SetFocus();                                             \
 147     }                                                                         \
 148                                                                               \
 149     bool classname::AcceptsFocus() const                                      \
 150     {                                                                         \
 151         return m_container.AcceptsFocus();                                    \
 152     }                                                                         \
 153                                                                               \
 154     bool classname::AcceptsFocusFromKeyboard() const                          \
 155     {                                                                         \
 156         return m_container.AcceptsFocusFromKeyboard();                        \
 157     }
 158
 159 #ifdef wxHAS_NATIVE_TAB_TRAVERSAL
 160
 161 // ----------------------------------------------------------------------------
 162 // wxControlContainer for native TAB navigation
 163 // ----------------------------------------------------------------------------
 164
 165 // this must be a real class as we forward-declare it elsewhere
 166 class WXDLLIMPEXP_CORE wxControlContainer : public wxControlContainerBase
 167 {
 168 protected:
 169     // set the focus to the child which had it the last time
 170     virtual bool SetFocusToChild();
 171 };
 172
 173 #define WX_EVENT_TABLE_CONTROL_CONTAINER(classname)
 174
 175 #define WX_DECLARE_CONTROL_CONTAINER WX_DECLARE_CONTROL_CONTAINER_BASE
 176
 177 #define WX_DELEGATE_TO_CONTROL_CONTAINER(classname, basename)                 \
 178     WX_DELEGATE_TO_CONTROL_CONTAINER_BASE(classname, basename)                \
 179                                                                               \
 180     void classname::RemoveChild(wxWindowBase *child)                          \
 181     {                                                                         \
 182         basename::RemoveChild(child);                                         \
 183                                                                               \
 184         m_container.UpdateCanFocus();                                         \
 185     }                                                                         \
 186                                                                               \
 187     void classname::SetFocusIgnoringChildren()                                \
 188     {                                                                         \
 189         basename::SetFocus();                                                 \
 190     }
 191
 192 #else // !wxHAS_NATIVE_TAB_TRAVERSAL
 193
 194 class WXDLLIMPEXP_FWD_CORE wxFocusEvent;
 195 class WXDLLIMPEXP_FWD_CORE wxNavigationKeyEvent;
 196
 197 // ----------------------------------------------------------------------------
 198 // wxControlContainer for TAB navigation implemented in wx itself
 199 // ----------------------------------------------------------------------------
 200
 201 class WXDLLIMPEXP_CORE wxControlContainer : public wxControlContainerBase
 202 {
 203 public:
 204     // default ctor, SetContainerWindow() must be called later
 205     wxControlContainer();
 206
 207     // the methods to be called from the window event handlers
 208     void HandleOnNavigationKey(wxNavigationKeyEvent& event);
 209     void HandleOnFocus(wxFocusEvent& event);
 210     void HandleOnWindowDestroy(wxWindowBase *child);
 211
 212     // called from OnChildFocus() handler, i.e. when one of our (grand)
 213     // children gets the focus
 214     void SetLastFocus(wxWindow *win);
 215
 216 protected:
 217
 218     wxDECLARE_NO_COPY_CLASS(wxControlContainer);
 219 };
 220
 221 // ----------------------------------------------------------------------------
 222 // macros which may be used by the classes wishing to implement TAB navigation
 223 // among their children
 224 // ----------------------------------------------------------------------------
 225
 226 // declare the methods to be forwarded
 227 #define WX_DECLARE_CONTROL_CONTAINER()                                        \
 228     WX_DECLARE_CONTROL_CONTAINER_BASE();                                      \
 229                                                                               \
 230 public:                                                                       \
 231     void OnNavigationKey(wxNavigationKeyEvent& event);                        \
 232     void OnFocus(wxFocusEvent& event);                                        \
 233     virtual void OnChildFocus(wxChildFocusEvent& event)
 234
 235 // implement the event table entries for wxControlContainer
 236 #define WX_EVENT_TABLE_CONTROL_CONTAINER(classname) \
 237     EVT_SET_FOCUS(classname::OnFocus) \
 238     EVT_CHILD_FOCUS(classname::OnChildFocus) \
 239     EVT_NAVIGATION_KEY(classname::OnNavigationKey)
 240
 241 // implement the methods forwarding to the wxControlContainer
 242 #define WX_DELEGATE_TO_CONTROL_CONTAINER(classname, basename)                 \
 243     WX_DELEGATE_TO_CONTROL_CONTAINER_BASE(classname, basename)                \
 244                                                                               \
 245     void classname::RemoveChild(wxWindowBase *child)                          \
 246     {                                                                         \
 247         m_container.HandleOnWindowDestroy(child);                             \
 248                                                                               \
 249         basename::RemoveChild(child);                                         \
 250                                                                               \
 251         m_container.UpdateCanFocus();                                         \
 252     }                                                                         \
 253                                                                               \
 254     void classname::OnNavigationKey( wxNavigationKeyEvent& event )            \
 255     {                                                                         \
 256         m_container.HandleOnNavigationKey(event);                             \
 257     }                                                                         \
 258                                                                               \
 259     void classname::SetFocusIgnoringChildren()                                \
 260     {                                                                         \
 261         basename::SetFocus();                                                 \
 262     }                                                                         \
 263                                                                               \
 264     void classname::OnChildFocus(wxChildFocusEvent& event)                    \
 265     {                                                                         \
 266         m_container.SetLastFocus(event.GetWindow());                          \
 267         event.Skip();                                                         \
 268     }                                                                         \
 269                                                                               \
 270     void classname::OnFocus(wxFocusEvent& event)                              \
 271     {                                                                         \
 272         m_container.HandleOnFocus(event);                                     \
 273     }
 274
 275 #endif // wxHAS_NATIVE_TAB_TRAVERSAL/!wxHAS_NATIVE_TAB_TRAVERSAL
 276
 277 // this function is for wxWidgets internal use only
 278 extern bool wxSetFocusToChild(wxWindow *win, wxWindow **child);
 279
 280 #endif // _WX_CONTAINR_H_