DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (0b1de782bd32)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
/* -*- 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 mozIDOMWindowProxy;

webidl Document;
webidl Element;

[scriptable, uuid(86e1f1e1-365d-493b-b52a-a649f3f311dc)]
/**
 * 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 mozIDOMWindowProxy 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 mozIDOMWindowProxy 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 Element 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 mozIDOMWindowProxy window);

  /**
   * Changes the focused element reference within the window containing
   * aElement to aElement.
   */
  void setFocus(in Element 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. The return value may be null if focus
   * was moved into a child process.
   */
  Element moveFocus(in mozIDOMWindowProxy aWindow,
                    in Element 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 mozIDOMWindowProxy 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
   */
  Element getFocusedElementForWindow(in mozIDOMWindowProxy aWindow,
                                     in boolean aDeep,
                                     out mozIDOMWindowProxy aFocusedWindow);

  /**
   * Moves the selection caret within aWindow to the current focus.
   */
  void moveCaretToFocus(in mozIDOMWindowProxy aWindow);

  /***
   * Check if given element is focusable.
   */
  boolean elementIsFocusable(in Element 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. If FLAG_BYELEMENTFOCUS is
   * set too, the latter is ignored.
   */
  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;

  /**
   * Focus is changing due to a touch operation that generated a mouse event.
   * Normally used in conjunction with FLAG_BYMOUSE.
   */
  const unsigned long FLAG_BYTOUCH = 0x200000;

  /**
   * Focus is changing due to a Element.focus() call.
   * This is used to distinguish the Element.focus() call from other focus
   * functionalities since we need to factor scroll-margin and scroll-padding
   * values into the position where we scroll to the element by the
   * Element.focus() call.
   * NOTE: This flag is ignored if FLAG_NOSCROLL is set too.
   */
  const unsigned long FLAG_BYELEMENTFOCUS = 0x400000;

  // 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;

  /** move focus to the first focusable document */
  const unsigned long MOVEFOCUS_FIRSTDOC = 9;
  /** move focus to the last focusable document */
  const unsigned long MOVEFOCUS_LASTDOC = 10;

  /**
   * Called when a window has been raised.
   */
  [noscript] void windowRaised(in mozIDOMWindowProxy aWindow);

  /**
   * Called when a window has been lowered.
   */
  [noscript] void windowLowered(in mozIDOMWindowProxy 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 mozIDOMWindowProxy 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 mozIDOMWindowProxy aWindow);

  /**
   * Fire any events that have been delayed due to synchronized actions.
   */
  [noscript] void fireDelayedEvents(in Document 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 Element aPlugin);

  /**
   * Used in a child process to indicate that the parent window is now
   * active or deactive.
   */
  [noscript] void parentActivated(in mozIDOMWindowProxy aWindow,
                                  in bool active);
};