Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes

nsFocusManager Class Reference

The focus manager keeps track of where the focus is, that is, the node which receives key events. More...

#include <nsFocusManager.h>

Inheritance diagram for nsFocusManager:
Collaboration diagram for nsFocusManager:

List of all members.

Public Member Functions

nsIContent * GetFocusedContent ()
 A faster version of nsIFocusManager::GetFocusedElement, returning a raw nsIContent pointer (instead of having AddRef-ed nsIDOMElement pointer filled in to an out-parameter).

Static Public Member Functions

NS_DECL_CYCLE_COLLECTING_ISUPPORTS
NS_DECL_NSIOBSERVER static
NS_DECL_NSIFOCUSMANAGER
nsresult 
Init ()
static void Shutdown ()
static nsFocusManagerGetFocusManager ()
 Retrieve the single focus manager.
static nsIContent * GetFocusedDescendant (nsPIDOMWindow *aWindow, PRBool aDeep, nsPIDOMWindow **aFocusedWindow)
 Returns the content node that would be focused if aWindow was in an active window.
static nsIContent * GetRedirectedFocus (nsIContent *aContent)
 Returns the content node that focus will be redirected to if aContent was focused.

Protected Member Functions

 nsFocusManager ()
 ~nsFocusManager ()
void EnsureCurrentWidgetFocused ()
 Ensure that the widget associated with the currently focused window is focused at the widget level.
void SetFocusInner (nsIContent *aNewContent, PRInt32 aFlags, PRBool aFocusChanged)
 Blur whatever is currently focused and focus aNewContent.
PRBool IsSameOrAncestor (nsPIDOMWindow *aPossibleAncestor, nsPIDOMWindow *aWindow)
 Returns true if aPossibleAncestor is the same as aWindow or an ancestor of aWindow.
already_AddRefed< nsPIDOMWindowGetCommonAncestor (nsPIDOMWindow *aWindow1, nsPIDOMWindow *aWindow2)
 Returns the window that is the lowest common ancestor of both aWindow1 and aWindow2, or null if they share no common ancestor.
void AdjustWindowFocus (nsPIDOMWindow *aNewWindow, PRBool aCheckPermission)
 When aNewWindow is focused, adjust the ancestors of aNewWindow so that they also have their corresponding frames focused.
PRBool IsWindowVisible (nsPIDOMWindow *aWindow)
 Returns true if aWindow is visible.
nsIContent * CheckIfFocusable (nsIContent *aContent, PRUint32 aFlags)
 Checks and returns aContent if it may be focused, another content node if the focus should be retargeted at another node, or null if the node cannot be focused.
PRBool Blur (nsPIDOMWindow *aWindowToClear, nsPIDOMWindow *aAncestorWindowToFocus, PRBool aIsLeavingDocument)
 Blurs the currently focused element.
void Focus (nsPIDOMWindow *aWindow, nsIContent *aContent, PRUint32 aFlags, PRBool aIsNewDocument, PRBool aFocusChanged, PRBool aWindowRaised)
 Focus an element in the active window and child frame.
void SendFocusOrBlurEvent (PRUint32 aType, nsIPresShell *aPresShell, nsIDocument *aDocument, nsISupports *aTarget, PRUint32 aFocusMethod, PRBool aWindowRaised)
 Fires a focus or blur event at aTarget.
void ScrollIntoView (nsIPresShell *aPresShell, nsIContent *aContent, PRUint32 aFlags)
 Scrolls aContent into view unless the FLAG_NOSCROLL flag is set.
void RaiseWindow (nsPIDOMWindow *aWindow)
 Raises the top-level window aWindow at the widget level.
void UpdateCaret (PRBool aMoveCaretToFocus, PRBool aUpdateVisibility, nsIContent *aContent)
 Updates the caret positon and visibility to match the focus.
void MoveCaretToFocus (nsIPresShell *aPresShell, nsIContent *aContent)
 Helper method to move the caret to the focused element aContent.
nsresult SetCaretVisible (nsIPresShell *aPresShell, PRBool aVisible, nsIContent *aContent)
 Makes the caret visible or not, depending on aVisible.
nsresult GetSelectionLocation (nsIDocument *aDocument, nsIPresShell *aPresShell, nsIContent **aStartContent, nsIContent **aEndContent)
 Retrieves the start and end points of the current selection for aDocument and stores them in aStartContent and aEndContent.
nsresult DetermineElementToMoveFocus (nsPIDOMWindow *aWindow, nsIContent *aStart, PRInt32 aType, nsIContent **aNextContent)
 Helper function for MoveFocus which determines the next element to move the focus to and returns it in aNextContent.
nsresult GetNextTabbableContent (nsIPresShell *aPresShell, nsIContent *aRootContent, nsIContent *aOriginalStartContent, nsIContent *aStartContent, PRBool aForward, PRInt32 aCurrentTabIndex, PRBool aIgnoreTabIndex, nsIContent **aResultContent)
 Retrieve the next tabbable element within a document, using focusability and tabindex to determine the tab order.
nsIContent * GetNextTabbableMapArea (PRBool aForward, PRInt32 aCurrentTabIndex, nsIContent *aImageContent, nsIContent *aStartContent)
 Get the next tabbable image map area and returns it.
PRInt32 GetNextTabIndex (nsIContent *aParent, PRInt32 aCurrentTabIndex, PRBool aForward)
 Return the next valid tabindex value after aCurrentTabIndex, if aForward is true, or the previous tabindex value if aForward is false.
nsIContent * GetRootForFocus (nsPIDOMWindow *aWindow, nsIDocument *aDocument, PRBool aIsForDocNavigation, PRBool aCheckVisibility)
 Retrieves and returns the root node from aDocument to be focused.
void GetLastDocShell (nsIDocShellTreeItem *aItem, nsIDocShellTreeItem **aResult)
 Get the last docshell child of aItem and return it in aResult.
void GetNextDocShell (nsIDocShellTreeItem *aItem, nsIDocShellTreeItem **aResult)
 Get the next docshell child of aItem and return it in aResult.
void GetPreviousDocShell (nsIDocShellTreeItem *aItem, nsIDocShellTreeItem **aResult)
 Get the previous docshell child of aItem and return it in aResult.
nsIContent * GetNextTabbableDocument (PRBool aForward)
 Get the tabbable next document from the currently focused frame if aForward is true, or the previously tabbable document if aForward is false.
void GetFocusInSelection (nsPIDOMWindow *aWindow, nsIContent *aStartSelection, nsIContent *aEndSelection, nsIContent **aFocusedContent)
 Retreives a focusable element within the current selection of aWindow.

Protected Attributes

nsCOMPtr< nsPIDOMWindowmActiveWindow
nsCOMPtr< nsPIDOMWindowmFocusedWindow
nsCOMPtr< nsIContent > mFocusedContent
nsCOMPtr< nsIContent > mFirstBlurEvent
nsCOMPtr< nsIContent > mFirstFocusEvent
nsCOMPtr< nsPIDOMWindowmWindowBeingLowered
nsTArray
< nsDelayedBlurOrFocusEvent > 
mDelayedBlurFocusEvents

Static Protected Attributes

static nsFocusManagersInstance

Detailed Description

The focus manager keeps track of where the focus is, that is, the node which receives key events.


Constructor & Destructor Documentation

nsFocusManager::nsFocusManager (  )  [protected]
nsFocusManager::~nsFocusManager (  )  [protected]

Member Function Documentation

void nsFocusManager::AdjustWindowFocus ( nsPIDOMWindow aNewWindow,
PRBool  aCheckPermission 
) [protected]

When aNewWindow is focused, adjust the ancestors of aNewWindow so that they also have their corresponding frames focused.

Thus, one can start at the active top-level window and navigate down the currently focused elements for each frame in the tree to get to aNewWindow.

PRBool nsFocusManager::Blur ( nsPIDOMWindow aWindowToClear,
nsPIDOMWindow aAncestorWindowToFocus,
PRBool  aIsLeavingDocument 
) [protected]

Blurs the currently focused element.

Returns false if another element was focused as a result. This would mean that the caller should not proceed with a pending call to Focus. Normally, true would be returned.

The currently focused element within aWindowToClear will be cleared. aWindowToClear may be null, which means that no window is cleared. This will be the case, for example, when lowering a window, as we want to fire a blur, but not actually change what element would be focused, so that the same element will be focused again when the window is raised.

aAncestorWindowToFocus should be set to the common ancestor of the window that is being blurred and the window that is going to focused, when switching focus to a sibling window.

aIsLeavingDocument should be set to true if the document/window is being blurred as well. Document/window blur events will be fired. It should be false if an element is the same document is about to be focused.

nsIContent* nsFocusManager::CheckIfFocusable ( nsIContent *  aContent,
PRUint32  aFlags 
) [protected]

Checks and returns aContent if it may be focused, another content node if the focus should be retargeted at another node, or null if the node cannot be focused.

aFlags are the flags passed to SetFocus and similar methods.

An element is focusable if it is in a document, the document isn't in print preview mode and the element has an nsIFrame where the CheckIfFocusable method returns true. For <area> elements, there is no frame, so only the IsFocusable method on the content node must be true.

nsresult nsFocusManager::DetermineElementToMoveFocus ( nsPIDOMWindow aWindow,
nsIContent *  aStart,
PRInt32  aType,
nsIContent **  aNextContent 
) [protected]

Helper function for MoveFocus which determines the next element to move the focus to and returns it in aNextContent.

aWindow is the window to adjust the focus within, and aStart is the element to start navigation from. For tab key navigation, this should be the currently focused element.

aType is the type passed to MoveFocus.

void nsFocusManager::EnsureCurrentWidgetFocused (  )  [protected]

Ensure that the widget associated with the currently focused window is focused at the widget level.

void nsFocusManager::Focus ( nsPIDOMWindow aWindow,
nsIContent *  aContent,
PRUint32  aFlags,
PRBool  aIsNewDocument,
PRBool  aFocusChanged,
PRBool  aWindowRaised 
) [protected]

Focus an element in the active window and child frame.

aWindow is the window containing the element aContent to focus.

aFlags is the flags passed to the various focus methods in nsIFocusManager.

aIsNewDocument should be true if a new document is being focused. Document/window focus events will be fired.

aFocusChanged should be true if a new content node is being focused, so the focused content will be scrolled into view and the caret position will be updated. If false is passed, then a window is simply being refocused, for instance, due to a window being raised, or a tab is being switched to.

If aFocusChanged is true, then the focus has moved to a new location. Otherwise, the focus is just being updated because the window was raised.

aWindowRaised should be true if the window is being raised. In this case, command updaters will not be called.

already_AddRefed<nsPIDOMWindow> nsFocusManager::GetCommonAncestor ( nsPIDOMWindow aWindow1,
nsPIDOMWindow aWindow2 
) [protected]

Returns the window that is the lowest common ancestor of both aWindow1 and aWindow2, or null if they share no common ancestor.

nsIContent* nsFocusManager::GetFocusedContent (  )  [inline]

A faster version of nsIFocusManager::GetFocusedElement, returning a raw nsIContent pointer (instead of having AddRef-ed nsIDOMElement pointer filled in to an out-parameter).

static nsIContent* nsFocusManager::GetFocusedDescendant ( nsPIDOMWindow aWindow,
PRBool  aDeep,
nsPIDOMWindow **  aFocusedWindow 
) [static]

Returns the content node that would be focused if aWindow was in an active window.

This will traverse down the frame hierarchy, starting at the given window aWindow. Sets aFocusedWindow to the window with the document containing aFocusedContent. If no element is focused, aFocusedWindow may be still be set -- this means that the document is focused but no element within it is focused.

aWindow and aFocusedWindow must both be non-null.

void nsFocusManager::GetFocusInSelection ( nsPIDOMWindow aWindow,
nsIContent *  aStartSelection,
nsIContent *  aEndSelection,
nsIContent **  aFocusedContent 
) [protected]

Retreives a focusable element within the current selection of aWindow.

Currently, this only detects links.

This is used when MoveFocus is called with a type of MOVEFOCUS_CARET, which is used, for example, to focus links as the caret is moved over them.

static nsFocusManager* nsFocusManager::GetFocusManager (  )  [inline, static]

Retrieve the single focus manager.

void nsFocusManager::GetLastDocShell ( nsIDocShellTreeItem aItem,
nsIDocShellTreeItem **  aResult 
) [protected]

Get the last docshell child of aItem and return it in aResult.

void nsFocusManager::GetNextDocShell ( nsIDocShellTreeItem aItem,
nsIDocShellTreeItem **  aResult 
) [protected]

Get the next docshell child of aItem and return it in aResult.

nsresult nsFocusManager::GetNextTabbableContent ( nsIPresShell *  aPresShell,
nsIContent *  aRootContent,
nsIContent *  aOriginalStartContent,
nsIContent *  aStartContent,
PRBool  aForward,
PRInt32  aCurrentTabIndex,
PRBool  aIgnoreTabIndex,
nsIContent **  aResultContent 
) [protected]

Retrieve the next tabbable element within a document, using focusability and tabindex to determine the tab order.

The element is returned in aResultContent.

aRootContent is the root node -- nodes above this will not be examined. Typically this will be the root node of a document, but could also be a popup node.

aOriginalStartContent is the content which was originally the starting node, in the case of recursive or looping calls.

aStartContent is the starting point for this call of this method. If aStartContent doesn't have visual representation, the next content object, which does have a primary frame, will be used as a start. If that content object is focusable, the method may return it.

aForward should be true for forward navigation or false for backward navigation.

aCurrentTabIndex is the current tabindex.

aIgnoreTabIndex to ignore the current tabindex and find the element irrespective or the tab index. This will be true when a selection is active, since we just want to focus the next element in tree order from where the selection is. Similarly, if the starting element isn't focusable, since it doesn't really have a defined tab index.

nsIContent* nsFocusManager::GetNextTabbableDocument ( PRBool  aForward  )  [protected]

Get the tabbable next document from the currently focused frame if aForward is true, or the previously tabbable document if aForward is false.

If this document is a chrome or frameset document, returns the first focusable element within this document, otherwise, returns the root node of the document.

This method would be used for document navigation, which is typically invoked by pressing F6.

nsIContent* nsFocusManager::GetNextTabbableMapArea ( PRBool  aForward,
PRInt32  aCurrentTabIndex,
nsIContent *  aImageContent,
nsIContent *  aStartContent 
) [protected]

Get the next tabbable image map area and returns it.

aForward should be true for forward navigation or false for backward navigation.

aCurrentTabIndex is the current tabindex.

aImageContent is the image.

aStartContent is the current image map area.

PRInt32 nsFocusManager::GetNextTabIndex ( nsIContent *  aParent,
PRInt32  aCurrentTabIndex,
PRBool  aForward 
) [protected]

Return the next valid tabindex value after aCurrentTabIndex, if aForward is true, or the previous tabindex value if aForward is false.

aParent is the node from which to start looking for tab indicies.

void nsFocusManager::GetPreviousDocShell ( nsIDocShellTreeItem aItem,
nsIDocShellTreeItem **  aResult 
) [protected]

Get the previous docshell child of aItem and return it in aResult.

static nsIContent* nsFocusManager::GetRedirectedFocus ( nsIContent *  aContent  )  [static]

Returns the content node that focus will be redirected to if aContent was focused.

This is used for the special case of certain XUL elements such as textboxes which redirect focus to an anonymous child.

aContent must be non-null.

XXXndeakin this should be removed eventually but I want to do that as followup work.

nsIContent* nsFocusManager::GetRootForFocus ( nsPIDOMWindow aWindow,
nsIDocument *  aDocument,
PRBool  aIsForDocNavigation,
PRBool  aCheckVisibility 
) [protected]

Retrieves and returns the root node from aDocument to be focused.

Will return null if the root node cannot be focused. There are several reasons for this:

  • if aIsForDocNavigation is true, and aWindow is in an <iframe>.
  • if aIsForDocNavigation is false, and aWindow is a chrome shell.
  • if aCheckVisibility is true and the aWindow is not visible.
  • if aDocument is a frameset document.
nsresult nsFocusManager::GetSelectionLocation ( nsIDocument *  aDocument,
nsIPresShell *  aPresShell,
nsIContent **  aStartContent,
nsIContent **  aEndContent 
) [protected]

Retrieves the start and end points of the current selection for aDocument and stores them in aStartContent and aEndContent.

NS_DECL_CYCLE_COLLECTING_ISUPPORTS NS_DECL_NSIOBSERVER static NS_DECL_NSIFOCUSMANAGER nsresult nsFocusManager::Init (  )  [static]
PRBool nsFocusManager::IsSameOrAncestor ( nsPIDOMWindow aPossibleAncestor,
nsPIDOMWindow aWindow 
) [protected]

Returns true if aPossibleAncestor is the same as aWindow or an ancestor of aWindow.

PRBool nsFocusManager::IsWindowVisible ( nsPIDOMWindow aWindow  )  [protected]

Returns true if aWindow is visible.

void nsFocusManager::MoveCaretToFocus ( nsIPresShell *  aPresShell,
nsIContent *  aContent 
) [protected]

Helper method to move the caret to the focused element aContent.

void nsFocusManager::RaiseWindow ( nsPIDOMWindow aWindow  )  [protected]

Raises the top-level window aWindow at the widget level.

void nsFocusManager::ScrollIntoView ( nsIPresShell *  aPresShell,
nsIContent *  aContent,
PRUint32  aFlags 
) [protected]

Scrolls aContent into view unless the FLAG_NOSCROLL flag is set.

void nsFocusManager::SendFocusOrBlurEvent ( PRUint32  aType,
nsIPresShell *  aPresShell,
nsIDocument *  aDocument,
nsISupports aTarget,
PRUint32  aFocusMethod,
PRBool  aWindowRaised 
) [protected]

Fires a focus or blur event at aTarget.

aType should be either NS_FOCUS_CONTENT or NS_BLUR_CONTENT. For blur events, aFocusMethod should normally be non-zero.

aWindowRaised should only be true if called from WindowRaised.

nsresult nsFocusManager::SetCaretVisible ( nsIPresShell *  aPresShell,
PRBool  aVisible,
nsIContent *  aContent 
) [protected]

Makes the caret visible or not, depending on aVisible.

void nsFocusManager::SetFocusInner ( nsIContent *  aNewContent,
PRInt32  aFlags,
PRBool  aFocusChanged 
) [protected]

Blur whatever is currently focused and focus aNewContent.

aFlags is a bitmask of the flags defined in nsIFocusManager. If aFocusChanged is true, then the focus has actually shifted and the caret position will be updated to the new focus, aNewContent will be scrolled into view (unless a flag disables this) and the focus method for the window will be updated.

All actual focus changes must use this method to do so. (as opposed to those that update the focus in an inactive window for instance).

static void nsFocusManager::Shutdown (  )  [static]
void nsFocusManager::UpdateCaret ( PRBool  aMoveCaretToFocus,
PRBool  aUpdateVisibility,
nsIContent *  aContent 
) [protected]

Updates the caret positon and visibility to match the focus.

aMoveCaretToFocus should be true to move the caret to aContent.

aUpdateVisibility should be true to update whether the caret is visible or not.


Member Data Documentation

nsTArray<nsDelayedBlurOrFocusEvent> nsFocusManager::mDelayedBlurFocusEvents [protected]
nsCOMPtr<nsIContent> nsFocusManager::mFirstBlurEvent [protected]
nsCOMPtr<nsIContent> nsFocusManager::mFirstFocusEvent [protected]
nsCOMPtr<nsIContent> nsFocusManager::mFocusedContent [protected]

The documentation for this class was generated from the following file: