The Tor Browser: comparison dom/interfaces/base/nsIFocusManager.idl

--1:000000000000
+:6dc63846061c
+/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+#include "domstubs.idl"
+interface nsIDocument;
+interface nsIContent;
+[scriptable, uuid(51db277b-7ee7-4bce-9b84-fd2efcd2c8bd)]
+/**
+* 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.
+*/
+interface nsIFocusManager : nsISupports
+{
+/**
+* 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.
+*/
+attribute nsIDOMWindow activeWindow;
+/**
+* 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.
+*/
+attribute nsIDOMWindow focusedWindow;
+/**
+* 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.
+*/
+readonly attribute nsIDOMElement focusedElement;
+/**
+* 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.
+*/
+uint32_t getLastFocusMethod(in nsIDOMWindow window);
+/**
+* Changes the focused element reference within the window containing
+* aElement to aElement.
+*/
+void setFocus(in nsIDOMElement aElement, 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.
+*/
+nsIDOMElement moveFocus(in nsIDOMWindow aWindow, in nsIDOMElement aStartElement,
+in unsigned long aType, in unsigned long aFlags);
+/**
+* Clears the focused element within aWindow. If the current focusedWindow
+* is a descendant of aWindow, sets the current focusedWindow to aWindow.
+*
+* @throws NS_ERROR_INVALID_ARG if aWindow is null
+*/
+void clearFocus(in nsIDOMWindow aWindow);
+/**
+* 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.
+*
+* @throws NS_ERROR_INVALID_ARG if aWindow is null
+*/
+nsIDOMElement getFocusedElementForWindow(in nsIDOMWindow aWindow, in boolean aDeep,
+out nsIDOMWindow aFocusedWindow);
+/**
+* Moves the selection caret within aWindow to the current focus.
+*/
+void moveCaretToFocus(in nsIDOMWindow aWindow);
+/***
+* Check if given element is focusable.
+*/
+boolean elementIsFocusable(in nsIDOMElement aElement, in unsigned long aFlags);
+/*
+* Raise the window when switching focus
+*/
+const unsigned long FLAG_RAISE = 1;
+/**
+* Do not scroll the element to focus into view
+*/
+const unsigned long FLAG_NOSCROLL = 2;
+/**
+* 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 FLAG_NOSWITCHFRAME = 4;
+/**
+* This flag is only used when passed to moveFocus. If set, focus is never
+* moved to the parent frame of the starting element's document, instead
+* iterating around to the beginning of that document again. Child frames
+* are navigated as normal.
+*/
+const unsigned long FLAG_NOPARENTFRAME = 8;
+/**
+* Focus is changing due to a mouse operation, for instance the mouse was
+* clicked on an element.
+*/
+const unsigned long FLAG_BYMOUSE = 0x1000;
+/**
+* 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 FLAG_BYKEY = 0x2000;
+/**
+* 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 FLAG_BYMOVEFOCUS = 0x4000;
+/**
+* Always show the focus ring or other indicator of focus, regardless of
+* other state.
+*/
+const unsigned long FLAG_SHOWRING = 0x100000;
+// these constants are used with the aType argument to MoveFocus
+/** move focus forward one element, used when pressing TAB */
+const unsigned long MOVEFOCUS_FORWARD = 1;
+/** move focus backward one element, used when pressing Shift+TAB */
+const unsigned long MOVEFOCUS_BACKWARD = 2;
+/** move focus forward to the next frame document, used when pressing F6 */
+const unsigned long MOVEFOCUS_FORWARDDOC = 3;
+/** move focus forward to the previous frame document, used when pressing Shift+F6 */
+const unsigned long MOVEFOCUS_BACKWARDDOC = 4;
+/** move focus to the first focusable element */
+const unsigned long MOVEFOCUS_FIRST = 5;
+/** move focus to the last focusable element */
+const unsigned long MOVEFOCUS_LAST = 6;
+/** move focus to the root element in the document */
+const unsigned long MOVEFOCUS_ROOT = 7;
+/** 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 MOVEFOCUS_CARET = 8;
+/**
+* Called when a window has been raised.
+*/
+[noscript] void windowRaised(in nsIDOMWindow aWindow);
+/**
+* Called when a window has been lowered.
+*/
+[noscript] void windowLowered(in nsIDOMWindow aWindow);
+/**
+* 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.
+*/
+[noscript] void windowShown(in nsIDOMWindow aWindow, in boolean aNeedsFocus);
+/**
+* Called when a document in a window has been hidden or otherwise can no
+* longer accept focus.
+*/
+[noscript] void windowHidden(in nsIDOMWindow aWindow);
+/**
+* Fire any events that have been delayed due to synchronized actions.
+*/
+[noscript] void fireDelayedEvents(in nsIDocument aDocument);
+/**
+* Indicate that a plugin wishes to take the focus. This is similar to a
+* normal focus except that the widget focus is not changed. Updating the
+* widget focus state is the responsibility of the caller.
+*/
+[noscript] void focusPlugin(in nsIContent aPlugin);
+};

The Tor Browser / file comparison

comparison: dom/interfaces/base/nsIFocusManager.idl

dom/interfaces/base/nsIFocusManager.idl