juce/source/src/gui/components/keyboard/juce_KeyboardFocusTraverser.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_KEYBOARDFOCUSTRAVERSER_JUCEHEADER__
  27 #define __JUCE_KEYBOARDFOCUSTRAVERSER_JUCEHEADER__
  28
  29 class Component;
  30
  31
  32 //==============================================================================
  33 /**
  34     Controls the order in which focus moves between components.
  35
  36     The default algorithm used by this class to work out the order of traversal
  37     is as follows:
  38     - if two components both have an explicit focus order specified, then the
  39       one with the lowest number comes first (see the Component::setExplicitFocusOrder()
  40       method).
  41     - any component with an explicit focus order greater than 0 comes before ones
  42       that don't have an order specified.
  43     - any unspecified components are traversed in a left-to-right, then top-to-bottom
  44       order.
  45
  46     If you need traversal in a more customised way, you can create a subclass
  47     of KeyboardFocusTraverser that uses your own algorithm, and use
  48     Component::createFocusTraverser() to create it.
  49
  50     @see Component::setExplicitFocusOrder, Component::createFocusTraverser
  51 */
  52 class JUCE_API  KeyboardFocusTraverser
  53 {
  54 public:
  55     KeyboardFocusTraverser();
  56
  57     /** Destructor. */
  58     virtual ~KeyboardFocusTraverser();
  59
  60     /** Returns the component that should be given focus after the specified one
  61         when moving "forwards".
  62
  63         The default implementation will return the next component which is to the
  64         right of or below this one.
  65
  66         This may return 0 if there's no suitable candidate.
  67     */
  68     virtual Component* getNextComponent (Component* current);
  69
  70     /** Returns the component that should be given focus after the specified one
  71         when moving "backwards".
  72
  73         The default implementation will return the next component which is to the
  74         left of or above this one.
  75
  76         This may return 0 if there's no suitable candidate.
  77     */
  78     virtual Component* getPreviousComponent (Component* current);
  79
  80     /** Returns the component that should receive focus be default within the given
  81         parent component.
  82
  83         The default implementation will just return the foremost child component that
  84         wants focus.
  85
  86         This may return 0 if there's no suitable candidate.
  87     */
  88     virtual Component* getDefaultComponent (Component* parentComponent);
  89 };
  90
  91
  92 #endif   // __JUCE_KEYBOARDFOCUSTRAVERSER_JUCEHEADER__