chromium/ui/views/focus/focus_manager.h

// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef UI_VIEWS_FOCUS_FOCUS_MANAGER_H_
#define UI_VIEWS_FOCUS_FOCUS_MANAGER_H_

#include <memory>

#include "base/memory/raw_ptr.h"
#include "base/observer_list.h"
#include "ui/base/accelerators/accelerator_manager.h"
#include "ui/views/view_observer.h"
#include "ui/views/views_export.h"

// FocusManager handles focus traversal, stores and restores focused views, and
// handles keyboard accelerators. This class is an implementation detail of
// views::. Most callers should use methods of views:: classes rather than using
// FocusManager directly.
//
// There are 2 types of focus:
//
// - The native focus, which is the focus that a gfx::NativeView has.
// - The view focus, which is the focus that a views::View has.
//
// When a top window (derived from views::Widget) that is not a child window is
// created, it creates and owns a FocusManager to manage the focus for itself
// and all its child windows.
//
// To be able to be focus-traversed when the Tab key is pressed, a class should
// implement the FocusTraversable interface. RootViews implement
// FocusTraversable. The FocusManager contains a top FocusTraversable instance,
// which is the top RootView.
//
// If you just use Views, then the RootView handles focus traversal for you. The
// default traversal order is the order in which the views have been added to
// their container. You can call View::Insert{Before,After}InFocusList() to
// explicitly control the focus order.
//
// If you are embedding a native view containing a nested RootView (for example
// by adding a view that contains a native widget as its native component),
// then you need to:
//
// - Override the View::GetFocusTraversable method in your outer component.
//   It should return the RootView of the inner component. This is used when
//   the focus traversal traverse down the focus hierarchy to enter the nested
//   RootView. In the example mentioned above, the NativeControl overrides
//   GetFocusTraversable and returns hwnd_view_container_->GetRootView().
//
// - Call Widget::SetFocusTraversableParent on the nested RootView and point
//   it to the outer RootView. This is used when the focus goes out of the
//   nested RootView. In the example:
//
//     hwnd_view_container_->GetWidget()->SetFocusTraversableParent(
//         native_control->GetRootView());
//
// - Call RootView::SetFocusTraversableParentView on the nested RootView with
//   the parent view that directly contains the native window. This is needed
//   when traversing up from the nested RootView to know which view to start
//   with when going to the next/previous view. In the example:
//
//     hwnd_view_container_->GetWidget()->SetFocusTraversableParent(
//         native_control);
//
// Note that FocusTraversable views do not have to be RootViews:
// AccessibleToolbarView is FocusTraversable.

namespace ui {
class Accelerator;
class AcceleratorTarget;
class KeyEvent;
}  // namespace ui

namespace views {

class FocusManagerDelegate;
class FocusSearch;
class View;
class ViewTracker;
class Widget;

// The FocusTraversable interface is used by components that want to process
// focus traversal events (due to Tab/Shift-Tab key events).
class VIEWS_EXPORT FocusTraversable { … };

// This interface should be implemented by classes that want to be notified when
// the focus is about to change.  See the Add/RemoveFocusChangeListener methods.
class VIEWS_EXPORT FocusChangeListener { … };

// FocusManager adds itself as a ViewObserver to the currently focused view.
class VIEWS_EXPORT FocusManager : public ViewObserver { … };

}  // namespace views

#endif  // UI_VIEWS_FOCUS_FOCUS_MANAGER_H_