com.phloxui

import { INavigatee } from './INavigatee'; /** * * An interface for component class having navigation mechanism. For example, a menu bar having * menu items to navigate through each page should implement this interface. * * * @typeparam T A type of <code>navigatee</code> item can be navigated by this <code>navigator</code>. * * @author shiorin, tee4cute * @see [[INavigatee]] */ export interface INavigator<T extends INavigatee> { /** * * Get <code>navigatee</code> ([[INavigatee]]) items can be navigated by this <code>navigator</code>. * * * @returns An array of <code>navigatee</code> ([[INavigatee]]) items can be navigated by this <code>navigator</code>. */ getItems(): T[]; /** * * Get number of <code>navigatee</code> ([[INavigatee]]) items can be navigated by this <code>navigator</code>. * This must be the same value as [[getItems]]'s length. * * * @returns The <code>navigatee</code> ([[INavigatee]]) item count. */ getItemCount(): number; /** * * Get current active <code>navigatee</code> ([[INavigatee]]) item. In most scenarios, this method should return the item * representing the component (page) being displayed by this <code>navigator</code>. * * * @returns The current active <code>navigatee</code> ([[INavigatee]]) item being displayed by this <code>navigator</code>. * Returns <code>null</code> if there is no current active item. */ getActiveItem(): T; /** * * Get current active <code>navigatee</code> ([[INavigatee]]) item's index. The value returned from this method must be an * index of array returning from method [[getItems]]. * * * @returns The index of <code>navigatee</code> ([[INavigatee]]) item currently active. Returns <code>-1</code> if there is no * current active item. */ getActiveIndex(): number; /** * * Find the index of the given <code>navigatee</code> <code>item</code> in the items array returned from method [[getItems]]. * * * @param item The <code>navigatee</code> item to find the index. * @returns The index of the given <code>item</code>. Returns <code>-1</code> if not found. */ getItemIndex(item: T): number; /** * * Find the index of <code>navigatee</code> item having <code>item name</code> ([[INavigatee.getName]]) matches the <code>name</code> * passed as a parameter. * * * @param name The name of <code>navigatee</code> item to find the index. * @returns The index of the <code>navigatee</code> item having <code>item name</code> ([[INavigatee.getName]]) matches the <code>name</code> * passed as a parameter. Returns <code>-1</code> if not found. */ getItemIndexByName(name: string): number; /** * * Get the <code>navigatee</code> item ([[INavigatee]]) by the given <code>idx</code>. * * * @param idx The <code>navigatee</code> item array index (starting from <code>0</code>). * @returns The <code>navigatee</code> item ([[INavigatee]]) at the specified <code>idx</code>. If the specified <code>idx</code> is * out of bound, this method will returns <code>null</code> without throwing any exceptions. */ getItemByIndex(idx: number): T; /** * * Get the <code>navigatee</code> item ([[INavigatee]]) by the given item <code>name</code>. * * * @param name The name of <code>navigatee</code> item. * @returns The <code>navigatee</code> item having the name ([[INavigatee.getName]]) matches the <code>name</code> passed as a parameter. * Returns <code>null</code> if not found. */ getItemByName(name: string): T; /** * * Set <code>navigatee</code> items ([[INavigatee]]) into this <code>navigator</code>. * * * @param items The <code>navigatee</code> items ([[INavigatee]]) to be set into this <code>navigator</code>. */ setItems(items: T[]): void; /** * * Add a new <code>navigatee</code> <code>item</code> ([[INavigatee]]) into this <code>navigator</code>. This method will check that there already is the * given <code>item</code> in this <code>navigator</code> or not. If yes, the <code>item</code> will not be added and this method * will return <code>false</code>. * * * @param item A new <code>navigatee</code> item ([[INavigatee]]) to be added into this <code>navigator</code>. * @returns Returns <code>true</code> if the given <code>item</code> is newly added into this <code>navigator</code>. Otherwise, returns * <code>false</code>. */ addItem(item: T): boolean; /** * * Remove the given <code>navigatee</code> <code>item</code> ([[INavigatee]]) from this <code>navigator</code>. If the given <code>item</code> is * not currently in this <code>navigator</code>, this method will do nothing and return <code>false</code>. * * * @param item The <code>navigatee</code> item to be removed from this <code>navigator</code>. * @returns Returns <code>true</code> if the given <code>item</code> is in this <code>navigator</code> and successfully removed. Otherwise, returns * <code>false</code>. */ removeItem(item: T): boolean; /** * * To check that the given <code>navigatee</code> <code>item</code> ([[INavigatee]]) is currently in this <code>navigator</code> or not. * * * @param item The <code>navigatee</code> item to be checked. * @returns Returns <code>true</code> if the given <code>item</code> is currently in this <code>navigator</code>. Otherwise, returns <code>false</code>. */ containsItem(item: T): boolean; /** * * Navigate this <code>navigator</code> to the given <code>item</code> ([[INavigatee]]). This method returns <code>Promise</code> to allow the navigation to be * asynchronous. If the <code>item</code> is not in this <code>navigator</code>, this method will suddenly return resolved <code>Promise</code> having result value * <code>"false"</code>. Otherwise, it'll return a <code>Promise</code> which will be resolved when the navigation is done with result value <code>"true"</code>. The * navigated-to <code>item</code> will be set <code>active</code> flag to <code>true</code> and all other <code>navigatee</code> items in this <code>navigator</code> * will be set <code>active</code> flag to <code>false</code>. * * * @param item The <code>navigatee</code> item to be navigated to. * @param options The <code>options</code> object used for the navigation. This will depend on each navigator implementation. * @returns A <code>Promise</code> which will be resolved when the navigation is done with result value <code>"true"</code>. If the given <code>item</code> is not * in this <code>navigator</code>, this method will return a resolved <code>Promise</code> with result value <code>"false"</code>. */ navigateTo(item: T, options?: any): Promise<boolean>; /** * * Navigate this <code>navigator</code> to the given <code>navigatee</code> item <code>idx</code>. This method returns <code>Promise</code> to allow the navigation to be * asynchronous. If the given <code>idx</code> is out of bound, this method will suddenly return resolved <code>Promise</code> having result value <code>"false"</code>. * Otherwise, it'll return a <code>Promise</code> which will be resolved when the navigation is done with result value <code>"true"</code>. The navigated-to <code>item</code> * will be set <code>active</code> flag to <code>true</code> and all other <code>navigatee</code> items in this <code>navigator</code> will be set <code>active</code> flag to * <code>false</code>. * * * @param idx The <code>navigatee</code> item <code>idx</code> to be navigated to. * @param options The <code>options</code> object used for the navigation. This will depend on each navigator implementation. * @returns A <code>Promise</code> which will be resolved when the navigation is done with result value <code>"true"</code>. If the given <code>idx</code> is out of * bound, this method will return a resolved <code>Promise</code> with result value <code>"false"</code>. */ navigateToIndex(idx: number, options?: any): Promise<boolean>; /** * * Navigate this <code>navigator</code> to the given <code>navigatee</code> item <code>name</code>. This method returns <code>Promise</code> to allow the navigation to be * asynchronous. If the given item <code>name</code> does not exist, this method will suddenly return resolved <code>Promise</code> having result value <code>"false"</code>. * Otherwise, it'll return a <code>Promise</code> which will be resolved when the navigation is done with result value <code>"true"</code>. The navigated-to <code>item</code> * will be set <code>active</code> flag to <code>true</code> and all other <code>navigatee</code> items in this <code>navigator</code> will be set <code>active</code> flag to * <code>false</code>. * * * @param name The <code>navigatee</code> item <code>name</code> to be navigated to. * @param options The <code>options</code> object used for the navigation. This will depend on each navigator implementation. * @returns A <code>Promise</code> which will be resolved when the navigation is done with result value <code>"true"</code>. If the given item <code>name</code> does not * exist, this method will return a resolved <code>Promise</code> with result value <code>"false"</code>. */ navigateToName(name: string, options?: any): Promise<boolean>; /** * * Reset this <code>navigator</code> to the original state. * */ reset(): void; }