1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/base/nsIFocusManager.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,253 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "domstubs.idl"
1.10 +
1.11 +interface nsIDocument;
1.12 +interface nsIContent;
1.13 +
1.14 +[scriptable, uuid(51db277b-7ee7-4bce-9b84-fd2efcd2c8bd)]
1.15 +/**
1.16 + * The focus manager deals with all focus related behaviour. Only one element
1.17 + * in the entire application may have the focus at a time; this element
1.18 + * receives any keyboard events. While there is only one application-wide
1.19 + * focused element, each nsIDOMWindow maintains a reference to the element
1.20 + * that would be focused if the window was active.
1.21 + *
1.22 + * If the window's reference is to a frame element (iframe, browser,
1.23 + * editor), then the child window contains the element that is currently
1.24 + * focused. If the window's reference is to a root element, then the root is
1.25 + * focused. If a window's reference is null, then no element is focused, yet
1.26 + * the window is still focused.
1.27 + *
1.28 + * The blur event is fired on an element when it loses the application focus.
1.29 + * After this blur event, if the focus is moving away from a document, two
1.30 + * additional blur events are fired on the old document and window containing
1.31 + * the focus respectively.
1.32 + *
1.33 + * When a new document is focused, two focus events are fired on the new
1.34 + * document and window respectively. Then the focus event is fired on an
1.35 + * element when it gains the application focus.
1.36 + *
1.37 + * A special case is that the root element may be focused, yet does not
1.38 + * receive the element focus and blur events. Instead a focus outline may be
1.39 + * drawn around the document.
1.40 + *
1.41 + * Blur and focus events do not bubble as per the W3C DOM Events spec.
1.42 + */
1.43 +interface nsIFocusManager : nsISupports
1.44 +{
1.45 + /**
1.46 + * The most active (frontmost) window, or null if no window that is part of
1.47 + * the application is active. Setting the activeWindow raises it, and
1.48 + * focuses the current child window's current element, if any. Setting this
1.49 + * to null or to a non-top-level window throws an NS_ERROR_INVALID_ARG
1.50 + * exception.
1.51 + */
1.52 + attribute nsIDOMWindow activeWindow;
1.53 +
1.54 + /**
1.55 + * The child window within the activeWindow that is focused. This will
1.56 + * always be activeWindow, a child window of activeWindow or null if no
1.57 + * child window is focused. Setting the focusedWindow changes the focused
1.58 + * window and raises the toplevel window it is in. If the current focus
1.59 + * within the new focusedWindow is a frame element, then the focusedWindow
1.60 + * will actually be set to the child window and the current element within
1.61 + * that set as the focused element. This process repeats downwards until a
1.62 + * non-frame element is found.
1.63 + */
1.64 + attribute nsIDOMWindow focusedWindow;
1.65 +
1.66 + /**
1.67 + * The element that is currently focused. This will always be an element
1.68 + * within the document loaded in focusedWindow or null if no element in that
1.69 + * document is focused.
1.70 + */
1.71 + readonly attribute nsIDOMElement focusedElement;
1.72 +
1.73 + /**
1.74 + * Returns the method that was used to focus the element in window. This
1.75 + * will either be 0, FLAG_BYMOUSE or FLAG_BYKEY. If window is null, then
1.76 + * the current focusedWindow will be used by default. This has the result
1.77 + * of retrieving the method that was used to focus the currently focused
1.78 + * element.
1.79 + */
1.80 + uint32_t getLastFocusMethod(in nsIDOMWindow window);
1.81 +
1.82 + /**
1.83 + * Changes the focused element reference within the window containing
1.84 + * aElement to aElement.
1.85 + */
1.86 + void setFocus(in nsIDOMElement aElement, in unsigned long aFlags);
1.87 +
1.88 + /**
1.89 + * Move the focus to another element. If aStartElement is specified, then
1.90 + * movement is done relative to aStartElement. If aStartElement is null,
1.91 + * then movement is done relative to the currently focused element. If no
1.92 + * element is focused, focus the first focusable element within the
1.93 + * document (or the last focusable element if aType is MOVEFOCUS_END). This
1.94 + * method is equivalent to setting the focusedElement to the new element.
1.95 + *
1.96 + * Specifying aStartElement and using MOVEFOCUS_LAST is not currently
1.97 + * implemented.
1.98 + *
1.99 + * If no element is found, and aType is either MOVEFOCUS_ROOT or
1.100 + * MOVEFOCUS_CARET, then the focus is cleared. If aType is any other value,
1.101 + * the focus is not changed.
1.102 + *
1.103 + * Returns the element that was focused.
1.104 + */
1.105 + nsIDOMElement moveFocus(in nsIDOMWindow aWindow, in nsIDOMElement aStartElement,
1.106 + in unsigned long aType, in unsigned long aFlags);
1.107 +
1.108 + /**
1.109 + * Clears the focused element within aWindow. If the current focusedWindow
1.110 + * is a descendant of aWindow, sets the current focusedWindow to aWindow.
1.111 + *
1.112 + * @throws NS_ERROR_INVALID_ARG if aWindow is null
1.113 + */
1.114 + void clearFocus(in nsIDOMWindow aWindow);
1.115 +
1.116 + /**
1.117 + * Returns the currently focused element within aWindow. If aWindow is equal
1.118 + * to the current value of focusedWindow, then the returned element will be
1.119 + * the application-wide focused element (the value of focusedElement). The
1.120 + * return value will be null if no element is focused.
1.121 + *
1.122 + * If aDeep is true, then child frames are traversed and the return value
1.123 + * may be the element within a child descendant window that is focused. If
1.124 + * aDeep if false, then the return value will be the frame element if the
1.125 + * focus is in a child frame.
1.126 + *
1.127 + * aFocusedWindow will be set to the currently focused descendant window of
1.128 + * aWindow, or to aWindow if aDeep is false. This will be set even if no
1.129 + * element is focused.
1.130 + *
1.131 + * @throws NS_ERROR_INVALID_ARG if aWindow is null
1.132 + */
1.133 + nsIDOMElement getFocusedElementForWindow(in nsIDOMWindow aWindow, in boolean aDeep,
1.134 + out nsIDOMWindow aFocusedWindow);
1.135 +
1.136 + /**
1.137 + * Moves the selection caret within aWindow to the current focus.
1.138 + */
1.139 + void moveCaretToFocus(in nsIDOMWindow aWindow);
1.140 +
1.141 + /***
1.142 + * Check if given element is focusable.
1.143 + */
1.144 + boolean elementIsFocusable(in nsIDOMElement aElement, in unsigned long aFlags);
1.145 +
1.146 + /*
1.147 + * Raise the window when switching focus
1.148 + */
1.149 + const unsigned long FLAG_RAISE = 1;
1.150 +
1.151 + /**
1.152 + * Do not scroll the element to focus into view
1.153 + */
1.154 + const unsigned long FLAG_NOSCROLL = 2;
1.155 +
1.156 + /**
1.157 + * If attempting to change focus in a window that is not focused, do not
1.158 + * switch focus to that window. Instead, just update the focus within that
1.159 + * window and leave the application focus as is. This flag will have no
1.160 + * effect if a child window is focused and an attempt is made to adjust the
1.161 + * focus in an ancestor, as the frame must be switched in this case.
1.162 + */
1.163 + const unsigned long FLAG_NOSWITCHFRAME = 4;
1.164 +
1.165 + /**
1.166 + * This flag is only used when passed to moveFocus. If set, focus is never
1.167 + * moved to the parent frame of the starting element's document, instead
1.168 + * iterating around to the beginning of that document again. Child frames
1.169 + * are navigated as normal.
1.170 + */
1.171 + const unsigned long FLAG_NOPARENTFRAME = 8;
1.172 +
1.173 + /**
1.174 + * Focus is changing due to a mouse operation, for instance the mouse was
1.175 + * clicked on an element.
1.176 + */
1.177 + const unsigned long FLAG_BYMOUSE = 0x1000;
1.178 +
1.179 + /**
1.180 + * Focus is changing due to a key operation, for instance pressing the tab
1.181 + * key. This flag would normally be passed when MOVEFOCUS_FORWARD or
1.182 + * MOVEFOCUS_BACKWARD is used.
1.183 + */
1.184 + const unsigned long FLAG_BYKEY = 0x2000;
1.185 +
1.186 + /**
1.187 + * Focus is changing due to a call to MoveFocus. This flag will be implied
1.188 + * when MoveFocus is called except when one of the other mechanisms (mouse
1.189 + * or key) is specified, or when the type is MOVEFOCUS_ROOT or
1.190 + * MOVEFOCUS_CARET.
1.191 + */
1.192 + const unsigned long FLAG_BYMOVEFOCUS = 0x4000;
1.193 +
1.194 + /**
1.195 + * Always show the focus ring or other indicator of focus, regardless of
1.196 + * other state.
1.197 + */
1.198 + const unsigned long FLAG_SHOWRING = 0x100000;
1.199 +
1.200 + // these constants are used with the aType argument to MoveFocus
1.201 +
1.202 + /** move focus forward one element, used when pressing TAB */
1.203 + const unsigned long MOVEFOCUS_FORWARD = 1;
1.204 + /** move focus backward one element, used when pressing Shift+TAB */
1.205 + const unsigned long MOVEFOCUS_BACKWARD = 2;
1.206 + /** move focus forward to the next frame document, used when pressing F6 */
1.207 + const unsigned long MOVEFOCUS_FORWARDDOC = 3;
1.208 + /** move focus forward to the previous frame document, used when pressing Shift+F6 */
1.209 + const unsigned long MOVEFOCUS_BACKWARDDOC = 4;
1.210 + /** move focus to the first focusable element */
1.211 + const unsigned long MOVEFOCUS_FIRST = 5;
1.212 + /** move focus to the last focusable element */
1.213 + const unsigned long MOVEFOCUS_LAST = 6;
1.214 + /** move focus to the root element in the document */
1.215 + const unsigned long MOVEFOCUS_ROOT = 7;
1.216 + /** move focus to a link at the position of the caret. This is a special value used to
1.217 + * focus links as the caret moves over them in caret browsing mode.
1.218 + */
1.219 + const unsigned long MOVEFOCUS_CARET = 8;
1.220 +
1.221 + /**
1.222 + * Called when a window has been raised.
1.223 + */
1.224 + [noscript] void windowRaised(in nsIDOMWindow aWindow);
1.225 +
1.226 + /**
1.227 + * Called when a window has been lowered.
1.228 + */
1.229 + [noscript] void windowLowered(in nsIDOMWindow aWindow);
1.230 +
1.231 + /**
1.232 + * Called when a new document in a window is shown.
1.233 + *
1.234 + * If aNeedsFocus is true, then focus events are expected to be fired on the
1.235 + * window if this window is in the focused window chain.
1.236 + */
1.237 + [noscript] void windowShown(in nsIDOMWindow aWindow, in boolean aNeedsFocus);
1.238 +
1.239 + /**
1.240 + * Called when a document in a window has been hidden or otherwise can no
1.241 + * longer accept focus.
1.242 + */
1.243 + [noscript] void windowHidden(in nsIDOMWindow aWindow);
1.244 +
1.245 + /**
1.246 + * Fire any events that have been delayed due to synchronized actions.
1.247 + */
1.248 + [noscript] void fireDelayedEvents(in nsIDocument aDocument);
1.249 +
1.250 + /**
1.251 + * Indicate that a plugin wishes to take the focus. This is similar to a
1.252 + * normal focus except that the widget focus is not changed. Updating the
1.253 + * widget focus state is the responsibility of the caller.
1.254 + */
1.255 + [noscript] void focusPlugin(in nsIContent aPlugin);
1.256 +};
