import _WidgetBase = require("./_WidgetBase");
import { Handle } from "dojo/interfaces";

declare namespace focus {

    /**
     * Tracks the currently focused node, and which widgets are currently "active".
     * Access via require(["dijit/focus"], function(focus){ ... }).
     * 
     * A widget is considered active if it or a descendant widget has focus,
     * or if a non-focusable node of this widget or a descendant was recently clicked.
     * 
     * Call focus.watch("curNode", callback) to track the current focused DOMNode,
     * or focus.watch("activeStack", callback) to track the currently focused stack of widgets.
     *
     * Call focus.on("widget-blur", func) or focus.on("widget-focus", ...) to monitor when
     * when widgets become active/inactive
     * 
     * Finally, focus(node) will focus a node, suppressing errors if the node doesn't exist.
     */
    interface FocusManager {
        /**
         * Currently focused item on screen
         */
        curNode: Element;

        /**
         * List of currently active widgets (focused widget and it's ancestors)
         */
        activeStack: _WidgetBase[];

        /**
         * Registers listeners on the specified iframe so that any click
         * or focus event on that iframe (or anything in it) is reported
         * as a focus/click event on the `<iframe>` itself.
         * 
         * @param iframe Currently only used by editor.
         * @returns Handle with remove() method to deregister.
         */
        registerIframe(iframe: Element): Handle;

        /**
         * Registers listeners on the specified window (either the main
         * window or an iframe's window) to detect when the user has clicked somewhere
         * or focused somewhere.
         * 
         * Users should call registerIframe() instead of this method.
         * 
         * @param targetWindow If specified this is the window associated with the iframe,
         *  i.e. iframe.contentWindow.
         * @param effectiveNode If specified, report any focus events inside targetWindow as
         *  an event on effectiveNode, rather than on evt.target.
         * 
         * @returns Handle with remove() method to deregister.
         */
        registerWin(targetWindow?: Window, effectiveNode?: Element): Handle;
    }

}

declare const focus: focus.FocusManager;
export = focus;