@amcharts/amcharts4

/** * This is the main class that encapsulates every object on the chart. * * If it's an element that is to be displayed on the screen at some point, its * class must extend [[Sprite]] class. */ /** * ============================================================================ * IMPORTS * ============================================================================ * @hidden */ import { SpriteState } from "./SpriteState"; import { ISpriteEvents, SpriteEventDispatcher, AMEvent } from "./SpriteEvents"; export { ISpriteEvents, SpriteEventDispatcher, AMEvent }; import { BaseObjectEvents } from "./Base"; import { Adapter } from "./utils/Adapter"; import { ITheme } from "../themes/ITheme"; import { Dictionary, IDictionaryEvents, DictionaryTemplate } from "./utils/Dictionary"; import { ListTemplate, List } from "./utils/List"; import { EventDispatcher } from "./utils/EventDispatcher"; import { MultiDisposer, IDisposer, MutableValueDisposer } from "./utils/Disposer"; import { Animation, IAnimatable } from "./utils/Animation"; import { Optional } from "./utils/Type"; import { Group } from "./rendering/Group"; import { Paper } from "./rendering/Paper"; import { DataItem } from "./DataItem"; import { Container } from "./Container"; import { Pattern } from "./rendering/fills/Pattern"; import { LinearGradient } from "./rendering/fills/LinearGradient"; import { RadialGradient } from "./rendering/fills/RadialGradient"; import { SVGContainer } from "./rendering/SVGContainer"; import { Align } from "./defs/Align"; import { Roles, AriaLive } from "./defs/Accessibility"; import { IPlugin } from "./utils/Plugin"; import { Popup } from "./elements/Popup"; import { Modal } from "./elements/Modal"; import { Color } from "./utils/Color"; import { Ordering } from "./utils/Order"; import { HorizontalCenter } from "./defs/HorizontalCenter"; import { VerticalCenter } from "./defs/VerticalCenter"; import { VerticalAlign } from "./defs/VerticalAlign"; import { ShapeRendering } from "./defs/ShapeRendering"; import { AMElement } from "./rendering/AMElement"; import { Filter } from "./rendering/filters/Filter"; import { ColorModifier } from "./rendering/fills/ColorModifier"; import { InteractionObject } from "./interaction/InteractionObject"; import { IInertiaOptions, ISwipeOptions, IHitOptions, IHoverOptions, ICursorOptions, IKeyboardOptions, IMouseOptions } from "./interaction/InteractionOptions"; import { IPointer } from "./interaction/Pointer"; import { InertiaTypes } from "./interaction/Inertia"; import { IStyleProperty } from "./defs/IStyleProperty"; import { IPoint } from "./defs/IPoint"; import { IRectangle } from "./defs/IRectangle"; import { Tooltip } from "./elements/Tooltip"; import { NumberFormatter } from "./formatters/NumberFormatter"; import { DateFormatter } from "./formatters/DateFormatter"; import { DurationFormatter } from "./formatters/DurationFormatter"; import { Language } from "./utils/Language"; import { Export } from "./export/Export"; import { AmChartsLogo } from "./elements/AmChartsLogo"; import { ISVGAttribute } from "./rendering/AMElement"; import * as $type from "./utils/Type"; import { Percent } from "./utils/Percent"; /** * ============================================================================ * REQUISITES * ============================================================================ * @hidden */ /** * Defines properties for [[Sprite]] */ export interface ISpriteProperties { disabled?: boolean; x?: number | Percent; y?: number | Percent; width?: number | Percent; height?: number | Percent; scale?: number; rotation?: number; pixelPerfect?: boolean; marginLeft?: number; marginRight?: number; marginTop?: number; marginBottom?: number; fillOpacity?: number; fill?: Color | LinearGradient | RadialGradient | Pattern; opacity?: number; stroke?: Color | LinearGradient | RadialGradient | Pattern; strokeOpacity?: number; strokeWidth?: number; strokeDasharray?: string; strokeDashoffset?: number; strokeLinecap?: "butt" | "square" | "round"; strokeLinejoin?: "miter" | "round" | "bevel"; shapeRendering?: ShapeRendering; draggable?: boolean; inert?: boolean; resizable?: boolean; swipeable?: boolean; trackable?: boolean; hoverable?: boolean; clickable?: boolean; togglable?: boolean; wheelable?: boolean; focusable?: boolean; tabindex?: number; contextMenuDisabled?: boolean; visible?: boolean; tooltipText?: string; tooltipHTML?: string; tooltipX?: number | Percent; tooltipY?: number | Percent; alwaysShowTooltip?: boolean; tooltipPosition?: "fixed" | "pointer"; showTooltipOn?: "hover" | "hit" | "always"; interactionsEnabled?: boolean; horizontalCenter?: HorizontalCenter; verticalCenter?: VerticalCenter; align?: Align; valign?: VerticalAlign; paddingLeft?: number; paddingRight?: number; paddingTop?: number; paddingBottom?: number; minX?: number; minY?: number; maxX?: number; maxY?: number; dx?: number; dy?: number; role?: Roles; readerDescribedBy?: string; readerLabelledBy?: string; readerLive?: AriaLive; readerControls?: string; readerChecked?: boolean; readerHidden?: boolean; readerDescription?: string; readerTitle?: string; readerOrientation?: string; readerValueNow?: string; readerValueText?: string; nonScaling?: boolean; nonScalingStroke?: boolean; zIndex?: number; minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number; fillModifier?: ColorModifier; strokeModifier?: ColorModifier; hoverOnFocus?: boolean; path?: string; urlTarget?: string; url?: string; hidden?: boolean; showOnInit?: boolean; id?: string; isActive?: boolean; isHover?: boolean; userClassName?: string; } /** * Defines animation options */ export interface ISpriteAnimationOptions { from?: Percent | Color | number | string; to: Percent | Color | number | string; property: any; } /** * Defines list ofvisual properties */ export declare const visualProperties: (keyof ISpriteProperties)[]; /** * Represents a list of available adapters for [[Sprite]] */ export interface ISpriteAdapters extends ISpriteProperties { pixelHeight: number; pixelWidth: number; relativeHeight: number; relativeWidth: number; measuredHeight: number; measuredWidth: number; outerHeight: number; outerWidth: number; innerHeight: number; innerWidth: number; globalScale: number; pixelMarginRight: number; relativeMarginRight: number; pixelMarginLeft: number; relativeMarginLeft: number; pixelMarginTop: number; relativeMarginTop: number; pixelMarginBottom: number; relativeMarginBottom: number; pixelX: number; relativeX: number; pixelY: number; relativeY: number; mask: Sprite; populateString: string; inertiaOptions: Dictionary<InertiaTypes, IInertiaOptions>; hitOptions: IHitOptions; hoverOptions: IHoverOptions; swipeOptions: ISwipeOptions; keyboardOptions: IKeyboardOptions; mouseOptions: IMouseOptions; cursorOptions: ICursorOptions; criticalError: Error; } /** * ============================================================================ * MAIN CLASS * ============================================================================ * @hidden */ /** * Sprite represents any displayable element. * * This is the main class that encapsulates every object on the chart. * * If it's an element that is to be displayed on the screen at some point, its * class must extend [[Sprite]] class. * * [[Sprite]] class represents the a hierarchical structure. Every object that * extends [[Sprite]] can have children, that would inherit their properties, * such as language, formatters, etc. * * @see {@link SpriteState} * @see {@link ISpriteEvents} for a list of available events * @see {@link ISpriteAdapters} for a list of available Adapters * * @todo Review child elements that need to go into `_disposers` * @important */ export declare class Sprite extends BaseObjectEvents implements IAnimatable { /** * Defines property types. */ _properties: ISpriteProperties; /** * Defines state type. * * @ignore Exclude from docs */ /** * Defines type used in the Sprite. */ _adapter: ISpriteAdapters; /** * Holds values for Sprite's properties. */ properties: this["_properties"]; /** * Defines available events. */ _events: ISpriteEvents; /** * @ignore */ _eventDispatcher: SpriteEventDispatcher<AMEvent<this, this["_events"]>>; /** * Event dispatcher. * * @see {@link https://www.amcharts.com/docs/v4/concepts/event-listeners/} for more info about Events */ readonly events: SpriteEventDispatcher<AMEvent<this, this["_events"]>>; /** * @ignore */ _adapterO: Adapter<this, this["_adapter"]>; /** * Holds Adapter. * * @see {@link https://www.amcharts.com/docs/v4/concepts/adapters/} for more info about Adapters */ readonly adapter: Adapter<this, this["_adapter"]>; /** * @ignore Exclude from docs * @todo Description */ private _bindings; /** * Holds indicator if this Sprite is a "template" to be used for creating * other Sprites from and should not be treated as full-fledged element. * * @ignore Exclude from docs */ protected _isTemplate: boolean; protected _isPath: boolean; /** * Holds collection of Sprite States. */ _states: $type.Optional<DictionaryTemplate<string, SpriteState<this["_properties"], this["_adapter"]>>>; /** * Holds indicator whether this sprite was already initialized. * * @ignore Exclude from docs */ protected _inited: boolean; /** * Holds indicator whether this sprite was already initialized and ready. * * @ignore Exclude from docs */ protected _ready: boolean; /** * A reference to a Tooltip for this Sprite. * * @ignore Exclude from docs */ protected _tooltip: $type.Optional<Tooltip>; /** * A special data item which tooltip will use when formatting data. In case * it is not set, dataItem will be used. * * @ignore Exclude from docs */ protected _tooltipDataItem: $type.Optional<DataItem>; /** * A reference to another sprite or sprite template from which tooltip should take colors if getFillFromObject or getStrokeFromObject are set to true. * Mostly used when we need to adjust tooltip color for a series, depending on column or bullet color. * * @ignore Exclude from docs */ protected _tooltipColorSource: $type.Optional<Sprite>; /** * If `sprite.hide()` is called and we have "hidden" state and * `transitionDuration > 0`, we set `isHiding` flag to `true` in order to * avoid restarting animations in case `hide()` method is called multiple * times. */ isHiding: boolean; /** * If `sprite.hide()` is called, we set isHidden to true when sprite is hidden. * This was added becaus hidden state might have visibility set to true and so * there would not be possible to find out if a sprite is technically hidden or not. */ protected _isHidden: boolean; /** * This property indicates if Sprite is currently being revealed from hidden * state. This is used to prevent multiple calls to `sprite.show()` to * restart reveal animation. (if enabled) */ isShowing: boolean; /** * Indicates if this element is a standalone instance. A "standalone * instance" means this is a autonomous object which maintains its own * set of controls like Preloader, Export, etc. * * @ignore Exclude from docs */ isStandaloneInstance: boolean; /** * Indicates if togglable Sprite is currently active (toggled on). * * @ignore Exclude from docs */ protected _isActive: boolean; /** * A Sprite element to use as a mask for this Sprite. * * @ignore Exclude from docs */ protected _mask: MutableValueDisposer<Sprite>; /** * @ignore Exclude from docs * @todo Description */ protected _clipPath: Optional<Group>; /** * @ignore Exclude from docs * @todo Description */ protected _clipElement: $type.Optional<AMElement>; /** * @ignore Exclude from docs * @todo Description */ protected _positionPrecision: number; /** * Holds reference to Sprite's [[InteractionObject]]. Sprite does not * perform any user interactions directly, it happens via [[InteractionObject]]. * * @ignore Exclude from docs */ protected _interaction: $type.Optional<InteractionObject>; /** * An instance of [[Language]]. * * @ignore Exclude from docs */ protected _language: MutableValueDisposer<Language>; /** * An instance of [[NumberFormatter]]. * * @ignore Exclude from docs */ protected _numberFormatter: $type.Optional<NumberFormatter>; /** * An instance of [[DateFormatter]]. * * @ignore Exclude from docs */ protected _dateFormatter: $type.Optional<DateFormatter>; /** * An instance of [[DurationFormatter]]. * * @ignore Exclude from docs */ protected _durationFormatter: $type.Optional<DurationFormatter>; /** * An HTML element to which [[svgContainer]] is added. * * @ignore Exclude from docs */ protected _htmlContainer: $type.Optional<HTMLElement>; /** * An HTML element to which all chart elements are added. * * @ignore Exclude from docs */ protected _svgContainer: $type.Optional<SVGContainer>; /** * A [[Container]] instance to place this element's [[Tooltip]] elements in * * @ignore Exclude from docs */ protected _tooltipContainer: $type.Optional<Container>; protected _urlDisposer: $type.Optional<IDisposer>; /** * Should this element be measured when measuring its parent container's * dimentions? * * @ignore Exclude from docs */ protected _isMeasured: $type.Optional<boolean>; /** * Indicates if the chart should follow right-to-left rules. * * @ignore Exclude from docs */ protected _rtl: boolean; /** * Holds [[Export]] object. * * @ignore Exclude from docs */ protected _exporting: MutableValueDisposer<Export>; /** * Should this Sprite be included when exporting? */ protected _exportable: boolean; /** * A reference to a top-level SVG node for this Sprite element. * * @ignore Exclude from docs */ protected _element: Optional<AMElement>; /** * Holds Sprite's main SVG group (`<g>`) element. Other Sprite's elements * are all placed in this group. */ group: Group; /** * A reference to [[Paper]] SVG renderer used to create SVG nodes. * * @ignore Exclude from docs */ protected _paper: $type.Optional<Paper>; /** * Elements's top-level [[Container]]. * * * @return Top-level ascendant */ protected _topParent: Optional<Container>; /** * Data item assigned to the sprite. It might contain information defining * some style properties. */ _dataItem: $type.Optional<DataItem>; /** * Parent container. * * @ignore Exclude from docs */ protected _parent: Container; /** * Sprite's "virtual" parent. * * @ignore Exclude from docs */ protected _virtualParent: Sprite; /** * Defines bounding box (square) for this element. * * @ignore Exclude from docs */ protected _bbox: IRectangle; /** * Base tab index for the Sprite. Used for TAB-key selection order. * * Use accessors `tabIndex` to set and retrieve. * * @ignore Exclude from docs */ protected _tabindex: $type.Optional<number>; /** * Should system tooltips be allowed to be displayed if the element has * `readerTitle` set? * * Use accessors `showSystemTooltip` to set and retrieve. * * This is an accessibility feature. * * @ignore Exclude from docs */ protected _showSystemTooltip: $type.Optional<boolean>; /** * List of animations currently playing for this Sprite. * * @ignore Exclude from docs */ protected _animations: $type.Optional<Array<Animation>>; /** * A link to [[Disposer]] for event handler which is attached to hide * animation. In some cases we need to cancel this event. This property is * used to hold the reference to disposer of this event so that we can * cancel it by calling its `dispose()` method. * * @ignore Exclude from docs */ protected _showHideDisposer: $type.Optional<IDisposer>; /** * If element is currently hiding, this property will hold a reference to * [[Animation]] instance, which is handling hiding animation. * * @ignore Exclude from docs */ protected _hideAnimation: $type.Optional<Animation>; /** * List of [[Filter]] items that are currently applied to the element. * * @ignore Exclude from docs */ protected _filters: $type.Optional<List<Filter>>; /** * A shortcut to the special "Focus" filter which is applied when the element * gains focus. * * This is an accessibility feature. * * @ignore Exclude from docs */ protected _focusFilter: $type.Optional<Filter>; /** * Indicates if this element is invalid and should be re-validated (redrawn). * * @ignore Exclude from docs */ invalid: boolean; /** * Indicates if this elements position is invalid and should be repositioned * * @ignore Exclude from docs */ positionInvalid: boolean; /** * A collection of key/value pairs that can be used to bind specific Sprite * properties to [[DataItem]]. * * For example: `fill` property can be bound to `myCustomColor` field in * DataItem. The Sprite will automatically get the value for `fill` from its * DataItem. * * Can be set for each [[SpriteState]] individually to override default * bindings. * * @see {@link SpriteState} */ propertyFields: { [index in keyof this["_properties"]]?: string; }; /** * Element's relative width. * * Do not set this property directly. Use `width` accessor with [[Percent]] * value instead. * * @ignore Exclude from docs */ percentWidth: $type.Optional<number>; /** * Element's relative height. * * Do not set this property directly. Use `height` accessor with [[Percent]] * value instead. * * @ignore Exclude from docs */ percentHeight: $type.Optional<number>; /** * An SVG group element that is used to put all SVG filters to. * * @ignore Exclude from docs */ filterElement: $type.Optional<Group>; /** * A field in data context of element's `dataItem` that holds config values * for this element. * * This is a very powerful feature, allowing changing virtually any setting, * including those for element's children, for the element via data. * * Example data: * * ```JSON * { * "value": 100, * "config": { * "fill": "#F00" * } * } * ``` * * If you set element's `configField = "config"`, the element for this * specific data point will have a red fill. */ configField: $type.Optional<string>; /** * Reference to element's `<title>` element. * * @ignore Exclude from docs */ protected _titleElement: Optional<AMElement>; /** * Reference to element's `<description>` element. * * @ignore Exclude from docs */ protected _descriptionElement: Optional<AMElement>; /** * Specifies if property changes on this object should be propagated to the * objects cloned from this object. * * This setting affects property changes *after* cloning, since at the moment * of cloning all of properties from source object are copied to the clone * anyway. * * @default false */ applyOnClones: boolean; /** * a reference to an object which should be used when populating string. used for tooltip label mostly. * @ignore */ populateStringFrom: any; /** * Internal storage properties. * * @ignore Exclude from docs */ protected _measuredWidth: number; protected _measuredHeight: number; protected _measuredWidthSelf: number; protected _measuredHeightSelf: number; protected _prevMeasuredWidth: number; protected _prevMeasuredHeight: number; protected _pixelWidth: $type.Optional<number>; protected _pixelHeight: $type.Optional<number>; protected _relativeWidth: $type.Optional<number>; protected _relativeHeight: $type.Optional<number>; /** * @ignore */ maxLeft: number; /** * @ignore */ maxRight: number; /** * @ignore */ maxTop: number; /** * @ignore */ maxBottom: number; /** * @ignore */ maxLeftSelf: number; /** * @ignore */ maxRightSelf: number; /** * @ignore */ maxTopSelf: number; /** * @ignore */ maxBottomSelf: number; protected _isDragged: boolean; protected _isResized: boolean; /** * @deprecated Moved to [[SpriteProperties]] */ protected _disabled: boolean; protected _internalDisabled: boolean; protected _updateDisabled: boolean; protected _maskRectangle: $type.Optional<IRectangle>; protected _internalDefaultsApplied: boolean; protected _interactionDisposer: $type.Optional<IDisposer>; /** * You can set bbox from outside if you know what size your element must be (used in radar chart for example) * @ignore */ definedBBox: IRectangle; /** * Time in milliseconds after which rollout event happens when user rolls-out of the sprite. This helps to avoid flickering in some cases. */ rollOutDelay: number; /** * @ignore */ protected _outTimeout: $type.Optional<IDisposer>; /** * This flag is set to `true` for the initial sprite you create and place * to the div so that we could clear all additional * sprites/containers when this sprite is disposed. * * @ignore */ isBaseSprite: boolean; /** * Indicates whether this sprite should be cloned when cloning its parent * container. We set this to `false` in those cases when a sprite is created * by the class, so that when cloning a duplicate sprite would not appear. */ shouldClone: boolean; /** * A property which you can use to store any data you want. */ dummyData: any; /** * A reference to a real fill object. Sometimes might be useful to modify * gradient (when fill is color but we have FillModifier). */ realFill: Color | Pattern | LinearGradient | RadialGradient; /** * A reference to a real stroke object. Sometimes might be useful to modify * gradient (when fill is color but we have a FillModifier). */ realStroke: Color | Pattern | LinearGradient | RadialGradient; /** * A reference to amCharts logo element. * * @ignore */ logo: AmChartsLogo; /** * [_baseId description] * * @todo Description */ protected _baseId: string; /** * A read-only flag which indicates if a sprite has completed its initial * animation (if `showOnInit = true`). * * In case `showOnInit = false`, `appeared` is set to `true` on init. * * @readonly */ appeared: boolean; /** * [ex description] * * @todo Description * @ignore */ ex: number; /** * [ey description] * * @todo Description * @ignore */ ey: number; /** * [_showOnInitDisposer description] * * @todo Description */ protected _showOnInitDisposer: MultiDisposer; /** * Holds the list of plugins attached to this Sprite. */ protected _plugins: $type.Optional<List<IPlugin>>; /** * Indicates if the sprite can be moved around when resizing it with two fingers (will only work if draggable = false) * @ignore */ dragWhileResize: boolean; /** * @ignore */ vpDisposer: MultiDisposer; protected _alwaysShowDisposers: IDisposer[]; /** * @ignore */ measureFailed: boolean; /** * If this flag is set to true, calling show() will not reveal the sprite. * * @ignore */ preventShow: boolean; /** * When cloning a sprite, if the template has it's own tooltip assigned, this tooltip is also cloned by default. * This is not good for cpu and sometimes you might only need one single tooltip for all clones. Set this to false in order not to clone tooltip. */ cloneTooltip: boolean; /** * Constructor: * * Creates initial node * * Sets default properties * * Creates required default states * * Inits accessibility */ constructor(); /** * ========================================================================== * ELEMENT VALIDATION, INIT, AND DRAWING STUFF * ========================================================================== * @hidden */ /** * Applies properties from all assigned themes. * * We do this here so that we can apply class names as well. * * @ignore Exclude from docs */ applyTheme(): void; /** * Returns theme(s) used by this object either set explicitly on this * element, inherited from parent, or inherited from [[System]]. * * @return An array of theme references */ getCurrentThemes(): ITheme[]; /** * Called just before element's validation, this function allows setting * defaults. * * @ignore Exclude from docs */ protected applyInternalDefaults(): void; /** * Invalidates element. * * Object will be redrawn during the next update cycle. * * Please note that in most cases elements will auto-invalidate when needed. If * everything works, DO NOT use this method. Use it only if some changes do * not take otherwise. */ invalidate(): void; /** * Validates element: * * Triggers events * * Redraws the element * * @ignore Exclude from docs */ validate(): void; /** * Invalidates element's position. * * @ignore Exclude from docs */ invalidatePosition(): void; /** * Transforms the element. * * @todo Description (review) * @ignore Exclude from docs */ validatePosition(): void; /** * A placeholder method that is called **before** element begins to be drawn. * * @ignore Exclude from docs */ protected beforeDraw(): void; /** * A placeholder method that draws the element. * * @ignore Exclude from docs */ protected draw(): void; /** * A placeholder method that is called **after** element finishes drawing * itself. * * @ignore Exclude from docs */ protected afterDraw(): void; /** * Dispatches `"ready"` event. Sprite dispatches it right after `"inited"` event. * * @ignore */ dispatchReady(): void; /** * Triggers a re-initialization of this element. * * Will result in complete redrawing of the element. * * @ignore Exclude from docs */ reinit(): void; /** * Handles the situation where parent element is resized. * * @ignore Exclude from docs */ handleGlobalScale(): void; /** * Updates filter properties which might depend on scale * * @ignore Exclude from docs */ protected updateFilterScale(): void; /** * Removes itself from system's invalid lists. * * @ignore Exclude from docs */ protected removeFromInvalids(): void; /** * Copies all parameters from another [[Sprite]]. * * @param source Source Sprite */ copyFrom(source: this): void; /** * Destroys this object and all related data. */ dispose(): void; /** * Indicates if this element is a "template". * * Template Sprites act only as a holders for config for other "real" * elements to be cloned from. * * Templates are treated differently, as they are not validated, redrawn, or * otherwise are processed. * * @ignore Exclude from docs * @param value Is template? */ /** * @ignore Exclude from docs * @return Is template? */ isTemplate: boolean; /** * Indicates whether the element should attempt to construct itself in a way * so that system tooltip is shown if its `readerTitle` is set. * * @param value Show system tooltip? */ /** * @return Show system tooltip? */ showSystemTooltip: boolean; /** * ========================================================================== * HIERARCHY AND STRUCTURE RELATED STUFF * ========================================================================== * @hidden */ /** * Sprites's top-level [[Container]]. * * Please note that in most cases it won't be the chart element. * * To access base chart element, use `baseSprite` instead. * * @return Top-level ascendant */ /** * @ignore * @param value {Container} top parent of a sprite */ topParent: Optional<Container>; /** * Elements' parent [[Container]]. * * @param parent Parent container */ /** * @return Parent container */ parent: Optional<Container>; /** * @ignore */ protected handleAlwaysShow(): void; /** * @ignore */ protected handleAlwaysShowTooltip(): void; /** * Element's "virtual" parent. * * This is required in ordere to maintain proper inheritance (like * formatters). * * Sometimes an element is a "logical" parent, even though it's not a direct * ascendant. * * Example: a bullet is not a child of the axis, but it would make sense * for it to inherit series' formatters. * * @ignore Exclude from docs * @param value Virtual parent */ /** * @return Virtual parent */ virtualParent: Sprite; /** * Moves `<defs>` to correct place in DOM. * * Some elements are initially created in "ghost" container. When moving * those into proper place in DOM, their respective `<defs>` need to be moved * as well. * * @ignore Exclude from docs */ appendDefs(): void; /** * Returns a [[Dictionary]] which maps object ids with their respective * objects. * * Can be used to retrieve any object by id, e.g.: * * ```TypeScript * console.log(mySprite.map.getKey("myid")); * ``` * ```JavaScript * console.log(mySprite.map.getKey("myid")); * ``` * * @return Map collection */ readonly map: Dictionary<string, any>; /** * @ignore * @return Map collection */ readonly delayedMap: Dictionary<string, any>; /** * Element's user-defined ID. * * Will throw an Error if there already is an object with the same ID. * * Please note that above check will be performed withing the scope of the * current chart instance. It will not do checks across other chart instances * or in globally in DOM. * * Make sure the IDs are unique. * * @param value ID */ /** * @return ID */ id: string; /** * ========================================================================== * ELEMENT AND DOM TREE MANIPULATION AND MEASURING * ========================================================================== * @hidden */ /** * Returns DOM element reference associated with this element. * * @readonly * @return DOM element */ readonly dom: SVGSVGElement; /** * A [[Paper]] instance to place elements on. * * If there's no Paper set for this element, it goes up the ascendant tree * until it finds one. * * This method is used by important `addChild()` method, so it's essential * to have a [[Paper]] instance. * * If this element has a separate `htmlContainer` set, it will have a * [[Paper]] instance itself. * * @ignore Exclude from docs * @param paper Paper */ /** * @ignore Exclude from docs * @return Paper */ paper: Paper; /** * Sets [[Paper]] instance to use to draw elements. * @ignore * @param paper Paper * @return true if paper was changed, false, if it's the same */ setPaper(paper: Paper): boolean; /** * An HTML element to be used when placing wrapper element (`<div>`) * for the whole chart. * * This is the same for **all** elements within the same chart. * * @param htmlContainer HTML element */ /** * @return HTML element */ htmlContainer: $type.Optional<HTMLElement>; /** * Creates (if not yet created) and returns element's `<title>` element. * * @ignore Exclude from docs * @return Title element */ readonly titleElement: AMElement; /** * Creates (if not yet created) and returns element's `<desc>` element. * * @ignore Exclude from docs * @return Desc element */ readonly descriptionElement: AMElement; /** * Returns list of SVG filters (effects) applied to element. If the filter * list is not yet initilized, creates and returns an empty one. * Note, not all filters combine well with one another. We recommend using one filter per sprite. * * @return List of filters */ readonly filters: List<Filter>; /** * Sets required SVG attributes. Must be called every time an element is * redrawn so that attributes are (re)applied. * * @ignore Exclude from docs */ protected setSVGAttributes(): void; /** * Sets an attribute directly on an SVG element. * * @ignore Exclude from docs * @param attribute Attribute object */ protected setSVGAttribute(attribute: ISVGAttribute): void; /** * Removes an attribute directly from SVG element. * * @param attribute Attribute key to remove */ protected removeSVGAttribute(attribute: string): void; /** * Sets `class` attribute of the elements SVG node. * * Uses `am4core.options.classNamePrefix`. * * @ignore Exclude from docs */ setClassName(): void; /** * Adds an `id` attribute the the element and returns the id. * * @ignore Exclude from docs * @return Element's ID */ uidAttr(): string; /** * [updateClipPath description] * * @todo Description */ protected updateClipPath(): void; /** * @ignore */ protected createClipPath(): void; /** * Applies the mask Sprite. * * @ignore Exclude from docs */ protected applyMask(): void; /** * Applies filters to the element. * * @ignore Exclude from docs */ protected applyFilters(): void; /** * [removeClipPath description] * * @ignore Exclude from docs * @todo Description */ protected removeClipPath(): void; /** * [setElement description] * * @ignore * @todo Description * @param element [description] */ setElement(element: AMElement): void; /** * The main element for this Sprite, usually an SVG `<g>`. * * All other sub-elements are created in it. * * @param element Element */ /** * @return Element */ element: Optional<AMElement>; /** * HTML container (`<div>`) which is used to place chart's `<svg>` element * in. * * @return Container for chart elements */ /** * Sets HTML container to add SVG and other chart elements to. * * @param svgContainer Container for chart elements */ svgContainer: $type.Optional<SVGContainer>; /** * Measures main element. * * Saves measurements into private `_bbox` property. * * @ignore Exclude from docs */ protected measureElement(): void; /** * Positions element according its center settings. * * @todo Description (review) * @ignore Exclude from docs */ updateCenter(): void; /** * Measures the whole element. * * Returns `true` if the size has changed from the last measurement. * * @ignore Exclude from docs * @return Did the size changed from the last measurement? */ measure(): boolean; /** * Insert this element before sibling element. * * @param sprite Target element * @return This element */ insertBefore(sprite: Sprite): Sprite; /** * Insert this element after sibling element. * * @param sprite Target element * @return This element */ insertAfter(sprite: Sprite): Sprite; /** * Removes the main SVG element. * * This does not destroy the whole Sprite element. To do that use * `dispose()` instead. * * @ignore Exclude from docs */ protected removeElement(): void; /** * Returns relative (percent) value of the X coordindate within this element. * * A relative value is a hundredth of a percent. So 100% would result in a 1 * as relative value. * * @param value Absolute or relative X coordinate * @return Relative value */ getRelativeX(value: number | Percent): number; /** * Returns relative (percent) value of the Y coordindate within this element. * * A relative value is a hundredth of a percent. So 100% would result in a 1 * as relative value. * * @param value Absolute or relative Y coordinate * @return Relative value */ getRelativeY(value: number | Percent): number; /** * Returns an X coordinate in pixel within the element. * * If number is passed in as parameter, the same number will be returned * back. * * If [[Percent]] is passed in, it will be recalculated to pixels. * * @param value Absolute or relative X coordinate * @return X coordinate in pixels */ getPixelX(value: number | Percent): number; /** * Returns an Y coordinate in pixel within the element. * * If number is passed in as parameter, the same number will be returned * back. * * If [[Percent]] is passed in, it will be recalculated to pixels. * * @param value Absolute or relative Y coordinate * @return Y coordinate in pixels */ getPixelY(value: number | Percent): number; /** * Moves the element to a specified coordinates. * * Using this method is preferred method of moving element, as it saves some * CPU processing power over setting `x` and `y` properties separately. * * The method respects element's center settings. The element will be * positioned so that `point` coordinates come in whatever "center" of the * element is, as set in `horizontalCenter` and `verticalCenter`. * * Besides moving the element, you can also at the same time scale and * rotate the element. * * @param point New coordinates * @param rotation New rotation * @param scale New Scale */ moveTo(point: IPoint, rotation?: number, scale?: number, isDragged?: boolean): void; /** * Sets another [[Sprite]] element as this elements mask. * * @ignore Exclude from docs * @param mask A [[Sprite]] to use as mask */ /** * Returns [[Sprite]] element currently used as mask for this element. * * @ignore Exclude from docs * @return A [[Sprite]] to use as mask */ mask: Optional<Sprite>; /** * Instead of creating a [[Sprite]] for mask, you can just use a * [[Rectangle]] by setting this accessor. * * Please note that the element will not monitor any changes to the mask * rectangle. * * @ignore Exclude from docs * @param rect Mask Rectangle */ /** * @ignore Exclude from docs * @return Mask Rectangle */ maskRectangle: IRectangle; /** * Indicates if this element was already measured. * * @ignore Exclude from docs * @param value Was element already measured? */ /** * @ignore Exclude from docs * @return Was element already measured? */ isMeasured: boolean; /** * Checks if the this element has any of its parts overlapping with another * element. * * @todo Description (review) * @param sprite Second element to test again * @return Overlapping? */ hitTest(sprite: Sprite): boolean; /** * ========================================================================== * STATE-RELATED * ========================================================================== * @hidden */ /** * Returns `true` if Sprite has already finished initializing. * * @return Initialized? */ readonly inited: boolean; /** * Returns `true` if Sprite has already finished initializing and is ready. * * If this object is a [[Container]] it will wait for all of its children * are ready before becoming ready itself and firing a `"ready"` event. * * @return is ready? */ isReady(): boolean; /** * Returns a collection of element's available [[SpriteState]] entries. * * @see {@link SpriteState} * @return States */ readonly states: DictionaryTemplate<string, SpriteState<this["_properties"], this["_adapter"]>>; /** * Returns a [[SpriteState]] object for "hidden" state. * * This is a shortcut to `this.states.getKey("hidden")`. * * @return Hidden state */ readonly hiddenState: SpriteState<this["_properties"], this["_adapter"]>; /** * Returns a [[SpriteState]] object for "default" state. * * This is a shortcut to `this.states.getKey("default")`. * * @return Hidden state */ readonly defaultState: SpriteState<this["_properties"], this["_adapter"]>; /** * Checks if some key states are defined and updates Sprite properties * accordingly. * * For example if there's a state "down" defined for Sprite, we automatically * make it "clickable". * * @ignore Exclude from docs * @param event An event which caused state list update */ protected processState(event: IDictionaryEvents<string, SpriteState<this["_properties"], this["_adapter"]>>["insertKey" | "setKey"]): void; /** * Returns a list elements's animations currently being played. * * If the list has not been initialized it is created. * * @return List of animations */ readonly animations: Array<Animation>; /** * Converts element's local coordinates to the coordinates within the main * chart container. * * @param point Local point * @return Global point */ getSvgPoint(point: IPoint): IPoint; /** * Creates and starts an [[Animation]] with given `animationOptions`. * * @see {@link Animation} for additional information about available options * @param animationOptions Animation options * @param duration Duration in milliseconds * @param easing Easing function * @return Animation instance */ animate(animationOptions: ISpriteAnimationOptions[] | ISpriteAnimationOptions, duration: number, easing?: (value: number) => number): Animation; /** * Applies a [[SpriteState]] on this element. * * The first parameter can either be a name state or a [[SpriteState]] * instance. * * When run, this method will apply SVG properties defined in a * [[SpriteState]], but only those that are relevant to this particular * element, i.e. are in the `properties` array. * * @see {@link SpriteState} * @param value A state - name key or instance * @param transitionDuration Duration of the transition between current and new state * @param easing An easing function */ setState(value: string | SpriteState<this["_properties"], this["_adapter"]>, transitionDuration?: number, easing?: (value: number) => number): $type.Optional<Animation>; /** * Applies proper state based on the condition of the element. A condition is * deducted in this order: * * "hover" if Sprite has currently any pointers over it * * "down" if Sprite has any pointers (touch or mouse) currently pressed over it * * "focus" if Sprite has currently got focus (accessibility) * * "hidden" if Sprite is currently hidden * * Returns an [[Animation]] object, which is handling gradual transition from * current values of properties, to the new target state(s). * * @param duration Duration for the animation (ms) * @return [[Animation]] object which is handling the transition */ applyCurrentState(duration?: number): $type.Optional<Animation>; /** * Starts an [[Animation]] of the properties to specific values as they are * set in `state`. * * @ignore Exclude from docs * @param state Target State * @param duration Duration in milliseconds * @param easing Easing function * @return Transition Animation */ protected transitTo(state: SpriteState<this["_properties"], this["_adapter"]>, duration: number, easing?: (value: number) => number): Optional<Animation>; /** * Returns `true` if Sprite is currently transiting from one state/value to * another. * * @return Is in transition? */ isInTransition(): boolean; /** * Indicates if this element has a mouse pointer currently hovering * over it, or if it has any touch pointers pressed on it. * * You can force element to be "hovered" manually, by setting this property * to `true`. * * @param value Is hovered? */ /** * @return Is hovered? */ isHover: boolean; /** * Returns indicator if this element is being dragged at the moment. * * @return Is dragged? */ readonly isDragged: boolean; /** * Returns indicator if this element is being resized at the moment. * * @return Is resized? */ readonly isResized: boolean; /** * Indicates if this element has any pointers (mouse or touch) pressing down * on it. * * @param value Is down? */ /** * @return Is down? */ isDown: boolean; /** * Indicates if this element is focused (possibly by tab navigation). * * @param value Is focused? */ /** * @return Is focused? */ isFocused: boolean; /** * Indicates if this element is currently active (toggled on) or not * (toggled off). * * @param value Is active? */ /** * @return Is active? */ isActive: boolean; protected setActive(value: boolean)