diff --git a/ui-grid/ui-grid.d.ts b/ui-grid/ui-grid.d.ts index 9dbb6dac9..a6460dbd4 100644 --- a/ui-grid/ui-grid.d.ts +++ b/ui-grid/ui-grid.d.ts @@ -6,13 +6,18 @@ // These are very definitely preliminary. Please feel free to improve. // Changelog: +// 8/11/2015 ui-grid v3.0.3 +// Extensive plugin support added (Plugin specific API, ColumnDef, GridOptions, GridRow, Constants). +// Added docs for all existing interfaces. +// Fixed a few incorrect interfaces, updated interfaces to reflect latest version. +// Did some cleanup... Moved all plugins into their own modules // 7/8/2015 ui-grid v3.0.0-rc.22-482dc67 // Added primary interfaces for row, column, api, grid, columnDef, and gridOptions. Needs more tests! - +/// /// declare module uiGrid { - export interface UIGridConstants { + export interface IUiGridConstants { LOG_DEBUG_MESSAGES: boolean; LOG_WARN_MESSAGES: boolean; LOG_ERROR_MESSAGES: boolean; @@ -116,67 +121,394 @@ declare module uiGrid { } } export interface IGridInstance { - appScope?: ng.IScope; - columnFooterHeight?: number; - footerHeight?: number; - isScrollingHorizontally?: boolean; - isScrollingVertically?: boolean; - scrollDirection?: number; - addRowHeaderColumn(column: IGridColumn): void; + /** + * adds a row header column to the grid + * @param {IColumnDef} colDef The column definition + */ + addRowHeaderColumn(colDef: IColumnDef): void; + /** + * uses the first row of data to assign colDef.type for any types not defined. + */ assignTypes(): void; + /** + * Populates columnDefs from the provided data + * @param {IRowBuilder} rowBuilder function to be called + */ buildColumnDefsFromData(rowBuilder: IRowBuilder): void; + /** + * creates GridColumn objects from the columnDefinition. + * Calls each registered columnBuilder to further process the column + * @param {IBuildColumnsOptions} options An object containing options to use when building columns + * * orderByColumnDefs: defaults to false. When true, buildColumns will order existing columns + * according to the order within the column definitions + * @returns {ng.IPromise} A promise to load any needed column resources + */ buildColumns(options: IBuildColumnsOptions): ng.IPromise; + /** + * calls each styleComputation function + */ buildStyles(): void; + /** + * Calls the callbacks based on the type of data change that has occurred. + * Always calls the ALL callbacks, calls the ROW, EDIT, COLUMN and OPTIONS callbacks + * if the event type is matching, or if the type is ALL. + * @param {number} type the type of event that occurred - one of the uiGridConstants.dataChange values + * (ALL, ROW, EDIT, COLUMN, OPTIONS + */ callDataChangeCallbacks(type: number): void; - clearAllFilters(refreshRows: boolean, clearConditions: boolean, clearFlags: boolean): void; + /** + * Clears all filters and optionally refreshes the visible rows. + * @param {boolean} [refreshRows=true] Refresh the rows? + * @param {boolean} [clearConditions=true] Clear conditions? + * @param {boolean} [clearFlags=true] Clear flags? + * @returns {ng.IPromise} If refreshRows is true, returns a promise of the rows refreshing + */ + clearAllFilters(refreshRows: boolean, clearConditions: boolean, + clearFlags: boolean): ng.IPromise; + /** + * refreshes the grid when a column refresh is notified, which triggers handling of the visible flag. + * This is called on uiGridConstants.dataChange.COLUMN, and is registered as a dataChangeCallback in grid.js + * @param {string} name column name + */ columnRefreshCallback(name: string): void; + /** + * creates the left render container if it doesn't already exist + */ createLeftContainer(): void; + /** + * creates the right render container if it doesn't already exist + */ createRightContainer(): void; + /** + * sets isScrollingHorizontally to true and sets it to false in a debounced function + */ flagScrollingHorizontally(): void; + /** + * sets isScrollingVertically to true and sets it to false in a debounced function + */ flagScrollingVertically(): void; + /** + * Gets the displayed value of a cell after applying any the cellFilter + * @param {IGridRow} row Row to access + * @param {IGridColumn} col Column to access + * @returns {string} Cell display value + */ getCellDisplayValue(row: IGridRow, col: IGridColumn): string; + /** + * Gets the displayed value of a cell + * @param {IGridRow} row Row to access + * @param {IGridColumn} col Column to access + * @returns {any} Cell value + */ getCellValue(row: IGridRow, col: IGridColumn): any; + /** + * returns a grid colDef for the column name + * @param {string} name Column name + * @returns {IColumnDef} The column definition + */ getColDef(name: string): IColumnDef; + /** + * returns a grid column by name + * @param {string} name Column name + * @returns {IGridColumn} The column + */ getColumn(name: string): IGridColumn; + /** + * Return the columns that the grid is currently being sorted by + * @returns {Array} the columns that the grid is currently being sorted by + */ getColumnSorting(): Array; - getGridQualifiedColField(col: IGridColumn): any; + /** + * Returns the $parse-able accessor for a column within its $scope + * @param {IGridColumn} col Column object + * @returns {string} $parse-able accessor for a column within its $scope + */ + getGridQualifiedColField(col: IGridColumn): string; + /** + * returns all columns except for rowHeader columns + * @returns {Array} All data columns + */ getOnlyDataColumns(): Array; + /** + * returns the GridRow that contains the rowEntity + * @param {any} rowEntity the gridOptionms.data array element instance + * @param {Array} rows The rows to look in. if not provided then it looks in grid.rows + */ getRow(rowEntity: any, rows?: Array): IGridRow; - handleWindowResize(): void; + /** + * Triggered when the browser window resizes; automatically resizes the grid + * @param {ng.IAngularEvent} $event Resize event + */ + handleWindowResize($event: ng.IAngularEvent): void; + /** + * returns true if leftContainer exists + * @returns {boolean} container exists? + */ hasLeftContainer(): boolean; + /** + * returns true if rightContainer exists + * @returns {boolean} container exists? + */ hasRightContainer(): boolean; + /** + * returns true if leftContainer has columns + * @returns {boolean} container has columns + */ hasLeftContainerColumns(): boolean; + /** + * returns true if rightContainer has columns + * @returns {boolean} container has columns + */ hasRightContainerColumns(): boolean; + /** + * Is grid right to left + * @returns {boolean} true if grid is RTL + */ isRTL(): boolean; - isRowHeaderColumn(col: IGridColumn): boolean; - modifyRows(): void; + /** + * Checks if column is a row header + * @param {IGridColumn} column The column + * @returns {boolean} true if the column is a row header + */ + isRowHeaderColumn(column: IGridColumn): boolean; + /** + * creates or removes GridRow objects from the newRawData array. Calls each registered + * rowBuilder to further process the row + * + * This method aims to achieve three things: + * 1. the resulting rows array is in the same order as the newRawData, we'll call + * rowsProcessors immediately after to sort the data anyway + * 2. if we have row hashing available, we try to use the rowHash to find the row + * 3. no memory leaks - rows that are no longer in newRawData need to be garbage collected + * + * The basic logic flow makes use of the newRawData, oldRows and oldHash, and creates + * the newRows and newHash + * + * Rows are identified using the hashKey if configured. If not configured, then rows + * are identified using the gridOptions.rowEquality function + * @param {Array} newRawData The new grid data + * @return {ng.IPromise} Promise which resolves when the rows have been created or removed + */ + modifyRows(newRawData: Array): ng.IPromise; + /** + * Notify the grid that a data or config change has occurred, + * where that change isn't something the grid was otherwise noticing. This + * might be particularly relevant where you've changed values within the data + * and you'd like cell classes to be re-evaluated, or changed config within + * the columnDef and you'd like headerCellClasses to be re-evaluated. + * @param {string} type one of the uiGridConstants.dataChange values [ALL, ROW, EDIT, COLUMN], which tells + * us which refreshes to fire + */ notifyDataChange(type: string): void; + /** + * precompiles all cell templates + */ precompileCellTemplates(): void; + /** + * processes all RowBuilders for the gridRow + * @param {IGridRow} gridRow reference to gridRow + * @returns {IGridRow} the gridRow with all additional behavior added + */ processRowBuilders(gridRow: IGridRow): IGridRow; + /** + * calls the row processors, specifically + * intended to reset the sorting when an edit is called, + * registered as a dataChangeCallback on uiGridConstants.dataChange.EDIT + * @param {string} name column name + */ processRowsCallback(name: string): void; + /** + * queues a grid refresh, a way of debouncing all the refreshes we might otherwise issue + */ queueGridRefresh(): void; + /** + * queues a grid refreshCanvas, a way of debouncing all the refreshes we might otherwise issue + */ queueRefresh(): void; + /** + * Redraw the rows and columns based on our current scroll position + * @param {boolean} [rowsAdded] Optional to indicate rows are added and the scroll percentage must be + * recalculated + */ redrawCanvas(rowsAdded?: boolean): void; + /** + * Refresh the rendered grid on screen. + * The refresh method re-runs both the columnProcessors and the + * rowProcessors, as well as calling refreshCanvas to update all + * the grid sizing. In general you should prefer to use queueGridRefresh + * instead, which is basically a debounced version of refresh. + * + * If you only want to resize the grid, not regenerate all the rows + * and columns, you should consider directly calling refreshCanvas instead. + * @param {boolean} rowsAltered Optional flag for refreshing when the number of rows has changed + */ refresh(rowsAltered?: boolean): void; + /** + * Builds all styles and recalculates much of the grid sizing + * @param {boolean} buildStyles optional parameter. Use TBD + * @returns {ng.IPromise} promise that is resolved when the canvas + * has been refreshed + */ refreshCanvas(buildStyles?: boolean): ng.IPromise; + /** + * Refresh the rendered rows on screen? Note: not functional at present + * @returns {ng.IPromise} promise that is resolved when render completes? + */ refreshRows(): ng.IPromise; + /** + * When the build creates columns from column definitions, the columnbuilders will be called to add + * additional properties to the column. + * @param {IColumnBuilder} columnBuilder function to be called + */ registerColumnBuilder(columnBuilder: IColumnBuilder): void; + /** + * Register a "columns processor" function. When the columns are updated, + * the grid calls each registered "columns processor", which has a chance + * to alter the set of columns, as long as the count is not modified. + * @param {IColumnProcessor} columnProcessor column processor function, which + * is run in the context of the grid (i.e. this for the function will be the grid), and + * which must return an updated renderedColumnsToProcess which can be passed to the next processor + * in the chain + * @param {number} priority the priority of this processor. In general we try to do them in 100s to leave room + * for other people to inject columns processors at intermediate priorities. + * Lower priority columnsProcessors run earlier.priority + */ registerColumnsProcessor(columnProcessor: IColumnProcessor, priority: number): void; + /** + * When a data change occurs, the data change callbacks of the specified type + * will be called. The rules are: + * + * - when the data watch fires, that is considered a ROW change (the data watch only notices + * added or removed rows) + * - when the api is called to inform us of a change, the declared type of that change is used + * - when a cell edit completes, the EDIT callbacks are triggered + * - when the columnDef watch fires, the COLUMN callbacks are triggered + * - when the options watch fires, the OPTIONS callbacks are triggered + * + * For a given event: + * - ALL calls ROW, EDIT, COLUMN, OPTIONS and ALL callbacks + * - ROW calls ROW and ALL callbacks + * - EDIT calls EDIT and ALL callbacks + * - COLUMN calls COLUMN and ALL callbacks + * - OPTIONS calls OPTIONS and ALL callbacks + * + * @param {(grid: IGridInstance) => void} callback function to be called + * @param {Array} types the types of data change you want to be informed of. Values from + * the uiGridConstants.dataChange values ( ALL, EDIT, ROW, COLUMN, OPTIONS ). Optional and defaults to + * ALL + * @returns {Function} deregister function - a function that can be called to deregister this callback + */ registerDataChangeCallback(callback: (grid: IGridInstance) => void, types: Array): Function; + /** + * When the build creates rows from gridOptions.data, the rowBuilders will be called to add + * additional properties to the row. + * @param {IRowBuilder} rowBuilder Function to be called + */ registerRowBuilder(rowBuilder: IRowBuilder): void; + /** + * Register a "rows processor" function. When the rows are updated, + * the grid calls each registered "rows processor", which has a chance + * to alter the set of rows (sorting, etc) as long as the count is not + * modified. + * + * @param {IRowProcessor} rowProcessor rows processor function, which + * is run in the context of the grid (i.e. this for the function will be the grid), and must + * return the updated rows list, which is passed to the next processor in the chain + * @param {number} priority the priority of this processor. + * In general we try to do them in 100s to leave room for other people to inject rows processors at + * intermediate priorities. Lower priority rowsProcessors run earlier. At present all rows visible + * is running at 50, filter is running at 100, sort is at 200, grouping at 400, selectable rows at + * 500, pagination at 900 (pagination will generally want to be last) + */ registerRowsProcessor(rowProcessor: IRowProcessor, priority: number): void; + /** + * registered a styleComputation function + * + * If the function returns a value it will be appended into the grid's `