import _FocusMixin = require("./_FocusMixin");
import _WidgetBase = require("./_WidgetBase");
import { DeclareConstructor } from "dojo/_base/declare";

/**
 * A mixin to allow arrow key and letter key navigation of child or descendant widgets.
 * It can be used by dijit/_Container based widgets with a flat list of children, or more complex widgets like dijit/Tree.
 *
 * To use this mixin, the subclass must:
 *
 * 	- Implement  _getNext(), _getFirst(), _getLast(), _onLeftArrow(), _onRightArrow() _onDownArrow(), _onUpArrow() methods to handle home/end/left/right/up/down keystrokes. Next and previous in this context refer to a linear ordering of the descendants used by letter key search.
 * 	- Set all descendants' initial tabIndex to "-1"; both initial descendants and any descendants added later, by for example addChild()
 * 	- Define childSelector to a function or string that identifies focusable descendant widgets
 *
 * Also, child widgets must implement a focus() method.
 */
interface _KeyNavMixin extends _FocusMixin {
    /**
     * Tab index of the container; same as HTML tabIndex attribute.
     * Note then when user tabs into the container, focus is immediately moved to the first item in the container.
     */
    tabIndex: string;

    /**
     * Selector (passed to on.selector()) used to identify what to treat as a child widget.   Used to monitor focus events and set this.focusedChild.   Must be set by implementing class.   If this is a string (ex: "> *") then the implementing class must require dojo/query.
     */
    childSelector: string | Function | null;

    /**
     * Called on left arrow key, or right arrow key if widget is in RTL mode.
     * Should go back to the previous child in horizontal container widgets like Toolbar.
     */
    _onLeftArrow(evt?: KeyboardEvent): void;

    /**
     * Called on right arrow key, or left arrow key if widget is in RTL mode.
     * Should go to the next child in horizontal container widgets like Toolbar.
     */
    _onRightArrow(evt?: KeyboardEvent): void;

    /**
     * Called on up arrow key. Should go to the previous child in vertical container widgets like Menu.
     */
    _onUpArrow(evt?: KeyboardEvent): void;

    /**
     * Called on down arrow key. Should go to the next child in vertical container widgets like Menu.
     */
    _onDownArrow(evt?: KeyboardEvent): void;

    /**
     * Default focus() implementation: focus the first child.
     */
    focus(): void;

    /**
     * Returns first child that can be focused.
     */
    _getFirstFocusableChild(): _WidgetBase;

    /**
     * Returns last child that can be focused.
     */
    _getLastFocusableChild(): _WidgetBase;

    /**
     * Focus the first focusable child in the container.
     */
    focusFirstChild(): void;

    /**
     * Focus the last focusable child in the container.
     */
    focusLastChild(): void;

    /**
     * Focus specified child widget.
     *
     * @param widget Reference to container's child widget
     * @param last If true and if widget has multiple focusable nodes, focus the last one instead of the first one
     */
    focusChild(widget: _WidgetBase, last?: boolean): void;

    /**
     * Handler for when the container itself gets focus.
     *
     * Initially the container itself has a tabIndex, but when it gets focus, switch focus to first child.
     */
    _onContainerFocus(evt: Event): void;

    /**
     * Called when a child widget gets focus, either by user clicking it, or programatically by arrow key handling code.
     *
     * It marks that the current node is the selected one, and the previously selected node no longer is.
     */
    _onChildFocus(child?: _WidgetBase): void;

    _searchString: string;

    multiCharSearchDuration: number;

    /**
     * When a key is pressed that matches a child item, this method is called so that a widget can take appropriate action is necessary.
     */
    onKeyboardSearch(tem: _WidgetBase, evt: Event, searchString: string, numMatches: number): void;

    /**
     * Compares the searchString to the widget's text label, returning:
     *
     * 	* -1: a high priority match  and stop searching
     * 	* 0: not a match
     * 	* 1: a match but keep looking for a higher priority match
     */
    _keyboardSearchCompare(item: _WidgetBase, searchString: string): -1 | 0 | 1;

    /**
     * When a key is pressed, if it's an arrow key etc. then it's handled here.
     */
    _onContainerKeydown(evt: Event): void;

    /**
     * When a printable key is pressed, it's handled here, searching by letter.
     */
    _onContainerKeypress(evt: Event): void;

    /**
     * Perform a search of the widget's options based on the user's keyboard activity
     *
     * Called on keypress (and sometimes keydown), searches through this widget's children looking for items that match the user's typed search string.  Multiple characters typed within 1 sec of each other are combined for multicharacter searching.
     */
    _keyboardSearch(evt: Event, keyChar: string): void;

    /**
     * Called when focus leaves a child widget to go to a sibling widget.
     */
    _onChildBlur(widget: _WidgetBase): void;

    /**
     * Returns the next or previous focusable descendant, compared to "child".
     * Implements and extends _KeyNavMixin._getNextFocusableChild() for a _Container.
     */
    _getNextFocusableChild(child: _WidgetBase, dir: 1 | -1): _WidgetBase | null;

    /**
     * Returns the first child.
     */
    _getFirst(): _WidgetBase | null;

    /**
     * Returns the last descendant.
     */
    _getLast(): _WidgetBase | null;

    /**
     * Returns the next descendant, compared to "child".
     */
    _getNext(child: _WidgetBase, dir: 1 | -1): _WidgetBase | null;
}

declare module "dojo/_base/kernel" {
    interface Dijit {
        _KeyNavMixin: _KeyNavMixinConstructor;
    }
}

type _KeyNavMixinConstructor = DeclareConstructor<_KeyNavMixin>;
declare const _KeyNavMixin: _KeyNavMixinConstructor;
export = _KeyNavMixin;