Public Member Functions | Public Attributes

nsIFocusManager Interface Reference

The focus manager deals with all focus related behaviour. More...

import "nsIFocusManager.idl";

Inheritance diagram for nsIFocusManager:
Collaboration diagram for nsIFocusManager:

List of all members.

Public Member Functions

PRUint32 getLastFocusMethod (in nsIDOMWindow window)
 Returns the method that was used to focus the element in window.
void setFocus (in nsIDOMElement aElement, in unsigned long aFlags)
 Changes the focused element reference within the window containing aElement to aElement.
nsIDOMElement moveFocus (in nsIDOMWindow aWindow, in nsIDOMElement aStartElement, in unsigned long aType, in unsigned long aFlags)
 Move the focus to another element.
void clearFocus (in nsIDOMWindow aWindow)
 Clears the focused element within aWindow.
nsIDOMElement getFocusedElementForWindow (in nsIDOMWindow aWindow, in PRBool aDeep, out nsIDOMWindow aFocusedWindow)
 Returns the currently focused element within aWindow.
void moveCaretToFocus (in nsIDOMWindow aWindow)
 Moves the selection caret within aWindow to the current focus.
void windowRaised (in nsIDOMWindow aWindow)
 Called when a window has been raised.
void windowLowered (in nsIDOMWindow aWindow)
 Called when a window has been lowered.
void contentRemoved (in nsIDocument aDocument, in nsIContent aElement)
 Called when content has been removed.
void windowShown (in nsIDOMWindow aWindow, in PRBool aNeedsFocus)
 Called when a new document in a window is shown.
void windowHidden (in nsIDOMWindow aWindow)
 Called when a document in a window has been hidden or otherwise can no longer accept focus.
void fireDelayedEvents (in nsIDocument aDocument)
 Fire any events that have been delayed due to synchronized actions.

Public Attributes

attribute nsIDOMWindow activeWindow
 The most active (frontmost) window, or null if no window that is part of the application is active.
attribute nsIDOMWindow focusedWindow
 The child window within the activeWindow that is focused.
readonly attribute nsIDOMElement focusedElement
 The element that is currently focused.
const unsigned long FLAG_RAISE = 1
const unsigned long FLAG_NOSCROLL = 2
 Do not scroll the element to focus into view.
const unsigned long FLAG_NOSWITCHFRAME = 4
 If attempting to change focus in a window that is not focused, do not switch focus to that window.
const unsigned long FLAG_BYMOUSE = 0x1000
 Focus is changing due to a mouse operation, for instance the mouse was clicked on an element.
const unsigned long FLAG_BYKEY = 0x2000
 Focus is changing due to a key operation, for instance pressing the tab key.
const unsigned long FLAG_BYMOVEFOCUS = 0x4000
 Focus is changing due to a call to MoveFocus.
const unsigned long MOVEFOCUS_FORWARD = 1
 move focus forward one element, used when pressing TAB
const unsigned long MOVEFOCUS_BACKWARD = 2
 move focus backward one element, used when pressing Shift+TAB
const unsigned long MOVEFOCUS_FORWARDDOC = 3
 move focus forward to the next frame document, used when pressing F6
const unsigned long MOVEFOCUS_BACKWARDDOC = 4
 move focus forward to the previous frame document, used when pressing Shift+F6
const unsigned long MOVEFOCUS_FIRST = 5
 move focus to the first focusable element
const unsigned long MOVEFOCUS_LAST = 6
 move focus to the last focusable element
const unsigned long MOVEFOCUS_ROOT = 7
 move focus to the root element in the document
const unsigned long MOVEFOCUS_CARET = 8
 move focus to a link at the position of the caret.

Detailed Description

The focus manager deals with all focus related behaviour.

Only one element in the entire application may have the focus at a time; this element receives any keyboard events. While there is only one application-wide focused element, each nsIDOMWindow maintains a reference to the element that would be focused if the window was active.

If the window's reference is to a frame element (iframe, browser, editor), then the child window contains the element that is currently focused. If the window's reference is to a root element, then the root is focused. If a window's reference is null, then no element is focused, yet the window is still focused.

The blur event is fired on an element when it loses the application focus. After this blur event, if the focus is moving away from a document, two additional blur events are fired on the old document and window containing the focus respectively.

When a new document is focused, two focus events are fired on the new document and window respectively. Then the focus event is fired on an element when it gains the application focus.

A special case is that the root element may be focused, yet does not receive the element focus and blur events. Instead a focus outline may be drawn around the document.

Blur and focus events do not bubble as per the W3C DOM Events spec.


Member Function Documentation

void nsIFocusManager::clearFocus ( in nsIDOMWindow  aWindow  ) 

Clears the focused element within aWindow.

If the current focusedWindow is a descendant of aWindow, sets the current focusedWindow to aWindow.

Exceptions:
NS_ERROR_INVALID_ARG if aWindow is null
void nsIFocusManager::contentRemoved ( in nsIDocument  aDocument,
in nsIContent  aElement 
)

Called when content has been removed.

void nsIFocusManager::fireDelayedEvents ( in nsIDocument  aDocument  ) 

Fire any events that have been delayed due to synchronized actions.

nsIDOMElement nsIFocusManager::getFocusedElementForWindow ( in nsIDOMWindow  aWindow,
in PRBool  aDeep,
out nsIDOMWindow  aFocusedWindow 
)

Returns the currently focused element within aWindow.

If aWindow is equal to the current value of focusedWindow, then the returned element will be the application-wide focused element (the value of focusedElement). The return value will be null if no element is focused.

If aDeep is true, then child frames are traversed and the return value may be the element within a child descendant window that is focused. If aDeep if false, then the return value will be the frame element if the focus is in a child frame.

aFocusedWindow will be set to the currently focused descendant window of aWindow, or to aWindow if aDeep is false. This will be set even if no element is focused.

Exceptions:
NS_ERROR_INVALID_ARG if aWindow is null
PRUint32 nsIFocusManager::getLastFocusMethod ( in nsIDOMWindow  window  ) 

Returns the method that was used to focus the element in window.

This will either be 0, FLAG_BYMOUSE or FLAG_BYKEY. If window is null, then the current focusedWindow will be used by default. This has the result of retrieving the method that was used to focus the currently focused element.

void nsIFocusManager::moveCaretToFocus ( in nsIDOMWindow  aWindow  ) 

Moves the selection caret within aWindow to the current focus.

nsIDOMElement nsIFocusManager::moveFocus ( in nsIDOMWindow  aWindow,
in nsIDOMElement  aStartElement,
in unsigned long  aType,
in unsigned long  aFlags 
)

Move the focus to another element.

If aStartElement is specified, then movement is done relative to aStartElement. If aStartElement is null, then movement is done relative to the currently focused element. If no element is focused, focus the first focusable element within the document (or the last focusable element if aType is MOVEFOCUS_END). This method is equivalent to setting the focusedElement to the new element.

Specifying aStartElement and using MOVEFOCUS_LAST is not currently implemented.

If no element is found, and aType is either MOVEFOCUS_ROOT or MOVEFOCUS_CARET, then the focus is cleared. If aType is any other value, the focus is not changed.

Returns the element that was focused.

void nsIFocusManager::setFocus ( in nsIDOMElement  aElement,
in unsigned long  aFlags 
)

Changes the focused element reference within the window containing aElement to aElement.

void nsIFocusManager::windowHidden ( in nsIDOMWindow  aWindow  ) 

Called when a document in a window has been hidden or otherwise can no longer accept focus.

void nsIFocusManager::windowLowered ( in nsIDOMWindow  aWindow  ) 

Called when a window has been lowered.

void nsIFocusManager::windowRaised ( in nsIDOMWindow  aWindow  ) 

Called when a window has been raised.

void nsIFocusManager::windowShown ( in nsIDOMWindow  aWindow,
in PRBool  aNeedsFocus 
)

Called when a new document in a window is shown.

If aNeedsFocus is true, then focus events are expected to be fired on the window if this window is in the focused window chain.


Member Data Documentation

The most active (frontmost) window, or null if no window that is part of the application is active.

Setting the activeWindow raises it, and focuses the current child window's current element, if any. Setting this to null or to a non-top-level window throws an NS_ERROR_INVALID_ARG exception.

const unsigned long nsIFocusManager::FLAG_BYKEY = 0x2000

Focus is changing due to a key operation, for instance pressing the tab key.

This flag would normally be passed when MOVEFOCUS_FORWARD or MOVEFOCUS_BACKWARD is used.

const unsigned long nsIFocusManager::FLAG_BYMOUSE = 0x1000

Focus is changing due to a mouse operation, for instance the mouse was clicked on an element.

const unsigned long nsIFocusManager::FLAG_BYMOVEFOCUS = 0x4000

Focus is changing due to a call to MoveFocus.

This flag will be implied when MoveFocus is called except when one of the other mechanisms (mouse or key) is specified, or when the type is MOVEFOCUS_ROOT or MOVEFOCUS_CARET.

const unsigned long nsIFocusManager::FLAG_NOSCROLL = 2

Do not scroll the element to focus into view.

const unsigned long nsIFocusManager::FLAG_NOSWITCHFRAME = 4

If attempting to change focus in a window that is not focused, do not switch focus to that window.

Instead, just update the focus within that window and leave the application focus as is. This flag will have no effect if a child window is focused and an attempt is made to adjust the focus in an ancestor, as the frame must be switched in this case.

const unsigned long nsIFocusManager::FLAG_RAISE = 1

The element that is currently focused.

This will always be an element within the document loaded in focusedWindow or null if no element in that document is focused.

The child window within the activeWindow that is focused.

This will always be activeWindow, a child window of activeWindow or null if no child window is focused. Setting the focusedWindow changes the focused window and raises the toplevel window it is in. If the current focus within the new focusedWindow is a frame element, then the focusedWindow will actually be set to the child window and the current element within that set as the focused element. This process repeats downwards until a non-frame element is found.

const unsigned long nsIFocusManager::MOVEFOCUS_BACKWARD = 2

move focus backward one element, used when pressing Shift+TAB

const unsigned long nsIFocusManager::MOVEFOCUS_BACKWARDDOC = 4

move focus forward to the previous frame document, used when pressing Shift+F6

const unsigned long nsIFocusManager::MOVEFOCUS_CARET = 8

move focus to a link at the position of the caret.

This is a special value used to focus links as the caret moves over them in caret browsing mode.

const unsigned long nsIFocusManager::MOVEFOCUS_FIRST = 5

move focus to the first focusable element

const unsigned long nsIFocusManager::MOVEFOCUS_FORWARD = 1

move focus forward one element, used when pressing TAB

const unsigned long nsIFocusManager::MOVEFOCUS_FORWARDDOC = 3

move focus forward to the next frame document, used when pressing F6

const unsigned long nsIFocusManager::MOVEFOCUS_LAST = 6

move focus to the last focusable element

const unsigned long nsIFocusManager::MOVEFOCUS_ROOT = 7

move focus to the root element in the document


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