@sheetxl/models
Version:
Models - A Headless javascript spreadsheet library.
329 lines • 12.2 kB
TypeScript
import { RemoveListener, CellCoords, CellRangeCoords } from "@sheetxl/common";
import { AdjustedColor, SchemeColorLookup, IndexedColorLookup } from "../color";
import { IDocTheme } from "../theme";
import { SerializableProperties } from "../primitives";
import { ICellStyle, SerializableCellStyleValues, SerializableNamedCellStyleValues, CellStyleValues, CellStyleUpdate, ICellStyleUpdater, INamedCellStyle, NamedCellStyleUpdate, INamedCellStyleUpdater } from "./ICellStyle";
import { CellBorderValues } from "./ICellBorder";
import { ITableStyle, SerializableTableStyleValues, TableStylesJSON } from "./ITableStyle";
export interface SheetStyleJSON {
cells?: SerializableCellStyleValues[];
named?: Record<string, SerializableNamedCellStyleValues>;
tables?: TableStylesJSON;
mruColors?: string[];
indexedColors?: string[];
}
export interface IStyleContext {
schemeLookup: SchemeColorLookup;
indexedColorLookup: IndexedColorLookup;
normalizeFontSize: number;
}
/**
* A transient scope for persisting styles with a given
* set of StyleIDs.
* This is required because many styles may be inactive
* (for example the undo stack or a collaboration session)
*/
export interface IStylesPersistScope {
/**
* End the persist scope. This will clear the stack and stop tracking access to this.
*/
endPersist(): void;
/**
* A 0-based style id for the given style. If this is a named style
* or a style that is not available with the styles then this will return null.
*
* @remarks
* This is a side effect operation. Calling this will cause the style to be persisted as part of the toJSON
*
* @param style
*/
toResourceId(style: ICellStyle): number | null;
/**
* This can be called multiple times.
*
* @remarks
* Only shared styles that have had the toResourceId called will
* be shown in the persisted json.
*/
toJSON(): SheetStyleJSON;
/**
* Load a JSON for a SheetStyle object.
*
* @remarks
* Once this is called the getSharedStyle is available for all
* the ids defined in the JSON for the current scope.
* @param json
*/
fromJSON(json: SheetStyleJSON): void;
/**
* Given the id return the style.
* This assumes that the fromJSON has been called previously.
*
* @param id
* @param ref
*/
getSharedStyle(id: number, ref: any): ICellStyle;
}
export interface ISheetStyleListener {
/**
* Notify that the named styled has changed
*/
onNamedStylesChange?(): void;
onTableStylesChange?(): void;
onThemeChange?(): void;
onDefaultFontChange?(): void;
onAllChange?(): void;
}
/**
* For managing styles in a sheet.
*
* There are two types of cell styles; SharedStyles and Named Styles.
*
* Cells can only used SharedStyles directly.
*
* Named styles are a 'style template' and can be used by SharedStyles.
*
* When a shared style is create or retrieved using getSharedStyle
* releaseSharedStyled should be called when it is no longer required.
*/
export interface ISheetStyle {
/**
* Convenience mechanism (and slightly faster) way to call getNamedCellStyle('Normal');
*/
getNormalStyle(): INamedCellStyle;
/**
* Returns a style that is an adjustment of the original.
* This method also tracks usages of the styles.
*
* If an adjustment of null or has no values then the 'named' style will be returned.
*
* Note - If a style that is being updated is using the same original cell and the same ref. The original style is released.
*
* @adjustment either a new partial style or a ICellStyleUpdater that
* @original the original style. This is either another SharedStyle which will be used as a template or a NamedStyle. If this is not specified then the normal style will be used.
* @ref This is any object that is used for tracking.
*/
getSharedStyle(adjustment: CellStyleUpdate | ICellStyleUpdater | null, original: ICellStyle, ref: any): ICellStyle;
/**
* Add a reference for a shared style. This is done to allow styles to be shared.
* The reference passed is used to track the current style usage. Once it's released or GC'ed the
* style will be release from the shared pool.
*
* @remarks
* Returns a reference to a new style. If will generally be the same cell style
* but if the cells style was created from a different styles then a new one will be returned.
*
* @style The previously created style
* @param ref
*/
addSharedStyleRef(style: ICellStyle, ref: any): ICellStyle;
/**
* Returns The named style from either a custom style or a builtin.
* @remarks
*
* Will try to return:
* 1. The custom style for the name
* 2. The builtin style for the name.
* 3. nul if it doesn't exist.
*/
getNamedCellStyle(name: string): INamedCellStyle | null;
/**
* Returns the built in cell style for the given key.
* @param key
*
* @remarks
*
* Case insensitive; to find the actual name casing use @see {@link INamedCellStyle.name}
*/
getBuiltInCellStyle(key: string | number): INamedCellStyle;
/**
* Returns all customized named cell styles.
* @remarks
*
* This includes new style names and builtin overrides.
*/
getCustomCellStyles(): INamedCellStyle[];
/**
* This will add or update a cell style.
* @remarks
*
* Case insensitive; for duplicate detection purposes.
*
* @param name
* @param style
* @param mergeIfExists If true then the style will be merged with the existing style otherwise is a replace. @defaultValue false
* @return the new style after any merges.
*/
setCustomCellStyle(name: string, style: NamedCellStyleUpdate | INamedCellStyleUpdater, mergeIfExists?: boolean): INamedCellStyle;
/**
* This will remove a custom cell style.
*
* @param style The named style or the string name of a named style.
* @returns true if the style was removed.
*/
removeCustomCellStyle(style: INamedCellStyle | string): boolean;
/**
* This will remove a custom styles or hide built-in cell style.
*
* @param style The named style or the string name of a named style.
* @returns Returns a flag indicating if the style was removed or hidden.
*/
hideOrRemoveNamedCellStyle(style: INamedCellStyle | string): boolean;
/**
* Returns The table style. This can be either a custom or a built in table style.
* @remarks
*
* Will try to return:
* 1. The custom style for the name
* 2. The builtin style for the name.
* 3. null if it doesn't exist.
*/
getTableStyle(name?: string): ITableStyle | null;
/**
* Returns the built in style for the given key.
*
* @param name A string of the name of the table.
*
* @remarks
* Case insensitive; to find the actual name casing use @see {@link INamedCellStyle.name}
*/
getBuiltInTableStyle(name: string): ITableStyle;
/**
* Returns all customized table styles.
* @remarks
*
* This includes new table styles and builtin overrides.
*/
getCustomTableStyles(): ITableStyle[];
/**
* This will remove a custom table style.
*
* @remarks
* If the style is a built-in style or doesn't exist then this will do nothing and remove false.
*
* @param name A string of the name of the table.
* @returns true if the style was removed.
*/
removeCustomTableStyle(name: string): boolean;
/**
* This will add or update a table style.
* @remarks
*
* Case insensitive; for duplicate detection purposes.
*
* @param name A string of the name of the table.
* @param tableStyleValues the values to set for the table style.
*/
setCustomTableStyle(name: string, tableStyleValues: SerializableTableStyleValues): ITableStyle;
/**
* Set the default table style to use if a table is created without specifying a style.
* @remarks
* The style must exist or the defaultStyle will be set to 'TableStyleMedium2'.
*
* @param name A string of the name of the table
*/
setDefaultTableStyle(name: string): void;
/**
* Returns the default TableStyle. @see {@link setDefaultTableStyle}
*/
getDefaultTableStyle(): ITableStyle;
/**
* Returns the current theme
*/
getTheme(): IDocTheme;
/**
* Set the theme used to calculate styles.
*
* @param theme The IDocTheme to use.
*/
setTheme(theme: IDocTheme): void;
/**
* Themes do not contain font sizes but it is possible to set a default font size at the document or application level.
*/
getDefaultFontSize(): number;
/**
* Set the default fontSize. Note - A theme does NOT contain this.
* @param fontSize The new default font size.
*/
setDefaultFontSize(fontSize: number): void;
/**
* This is available for functions that want to resolve colors for the theme used specifically for this style.
*/
schemeLookup(): SchemeColorLookup;
/**
* This is available for functions that want to resolve colors using the index color palette.
*/
indexedColorLookup(): IndexedColorLookup;
/**
* Parses the color using the Theme being used by this style
* @param str Any string that represents a color @see {AdjustedColor}.
*/
resolveColor(str: any): AdjustedColor;
/**
* Returns a list of colors that were added via @see {@link addRecentColor}
*/
recentColors(): readonly AdjustedColor[];
/**
* Add a color to the mru list. This is used to populate color pickers.
*
* Note - Any color can be added but generally this should be limited to custom/non-themed color
* @param color
*/
addRecentColor(color: AdjustedColor): readonly AdjustedColor[];
/**
* Clears the mru color list
*/
clearRecentColors(): void;
/**
* Return an array of colors that will be used to resolve any colors that use IndexXX or ColorXX as a key.
* @remarks
* This will also return a list of colors.
*/
getIndexedColors(): readonly AdjustedColor[];
/**
* Override the default indexed colors.
* @param colors
*/
setCustomIndexedColors(colors: readonly AdjustedColor[]): void;
/**
* Return the customized Indexed colors.
*/
getCustomIndexedColors(): readonly AdjustedColor[];
/**
* Add a listener for style changes.
* @param listener
*/
addListener(listener: ISheetStyleListener): RemoveListener;
/**
* Converts a list of SerializableCellStyleValues that contain
* shorthand values into native values. It will also remove
* any value that resolve to the same values as the
* referenced named style (or Normal if this is not specified)
*
* @param values
*/
normalize(values: SerializableCellStyleValues): Partial<CellStyleValues>;
/**
* Checks the current name to see if this is a valid sheetName.
*/
validateStyleName(name: string, checkDuplicates?: boolean): void;
/**
* Allows for a non managed style. Useful for tooltips or other transient styles.
*
* @param overrides
* @param inherit (And original values to inherit from)
*/
createTemporaryStyle(overrides: SerializableCellStyleValues, inherit?: ICellStyle): ICellStyle;
/**
* Given a border rationalize the border edges for a coord with a range.
*/
normalizeBorder(original: SerializableProperties<CellBorderValues>, coords: CellCoords, range: CellRangeCoords): SerializableProperties<CellBorderValues>;
/**
* Start persisting styles.
* This is used during save/load to allow for styles to be references by an id count.
* This is a stack so multiple begins will need to be matched with an end.
* @see {@link IStylesPersistScope}
*/
beginPersist(): IStylesPersistScope;
}
//# sourceMappingURL=ISheetStyle.d.ts.map