Interface ILightDismissable

src/js/WinJS/_LightDismissService.ts:212–258

// Keep in sync with ILightDismissableElementArgs.
export interface ILightDismissable {
    // This dismissable should be rendered at a z-index of *zIndex*.
    setZIndex(zIndex: string): void;
    // How many z-indices are required by this dismissable?
    getZIndexCount(): number;
    // Does the dismissable contain *element*?
    containsElement(element: HTMLElement): boolean;

    // Hooks

    // The dismissable should take focus if focus isn't already inside of it.
    // This fires when:
    //   - the dismissable becomes the active/topmost dismissable
    //   - the topmost dismissable loses focus but doesn't dismiss
    // *useSetActive* is a hint to onTakeFocus as to whether or not it should draw a
    // keyboard focus visual when taking focus. If the last input type was keyboard,
    // use focus() so a keyboard focus visual is drawn. Otherwise, use setActive() so
    // no focus visual is drawn.
    onTakeFocus(useSetActive: boolean): void;
    // Focus has moved into or within this dismissable (similar to a focusin handler except
    // you don't have to explicitly register for it).
    onFocus(element: HTMLElement): void;
    // This dismissable is now shown (i.e. has been added to the light dismiss service).
    onShow(service: ILightDismissService): void;
    // This dismissable is now hidden (i.e. has been removed from the light dismiss service).
    onHide(): void;

    // Called when a keyDown, keyUp, or keyPress event happens on this dismissable or on a
    // dismissable that is higher in the light dismiss stack. Gives light dismissables the
    // opportunity to intercept keyboard events that occur on light dismissables that are
    // higher in the stack. This is used by modals to ensure that, when a modal is somewhere
    // in the light dismiss stack, keyboard events don't escape the light dismiss stack
    // and fire on the body element.
    onKeyInStack(info: IKeyboardInfo): void;

    // Dismissal

    // A light dismiss was triggered. Return whether or not this dismissable should be dismissed. Built-in
    // implementations of this method are specified in LightDismissalPolicies.
    onShouldLightDismiss(info: ILightDismissInfo): boolean;
    // Should implement what it means for this dismissable to be dismissed (e.g. call control.hide()). Just because
    // this method is called doesn't mean that the service thinks this dismissable has been dismissed. Consequently,
    // you can decide to do nothing in this method if you want the dismissable to remain shown. However, this decision
    // should generally be made in onShouldLightDismiss if possible. The dismissable is responsible for calling
    // _LightDismissService.hidden at some point.
    onLightDismiss(info: ILightDismissInfo): void;
}

//
// ILightDismissable implementations