MAIDR JavaScript API
    Preparing search index...

    Interface Trace

    Interface representing a trace with navigation and observation capabilities

    interface Trace {
        getId: () => string;
        traceType: TraceType;
        layerLabel: string;
        placeAxisLabel: string;
        level: "trace";
        runSilently: (action: () => void) => void;
        getCurrentXValue: () => any;
        moveToXValue: (xValue: any) => boolean;
        getAlternateXValue?: () => XValue | null;
        hasXValue?: (xValue: XValue) => boolean;
        getCurrentYValue?: () => number | null;
        moveToXAndYValue?: (xValue: any, yValue: number) => boolean;
        getCurrentSection?: () => string | null;
        moveToXValueAndSection?: (xValue: any, section: string) => boolean;
        notifyOutOfBounds: () => void;
        resetToInitialEntry: () => void;
        cursorKey?: () => string | null;
        restoreCursor?: (key?: string | null) => void;
        getStateAt: (row: number, col: number) => TraceState;
        notifyObserversWithState: (state: TraceState) => void;
        getAllHighlightElements: () => SVGElement[];
        getAllOriginalElements: () => SVGElement[];
        getGeometryElements?: () => SVGElement[];
        moveToPointAndGetPointerGuidance: (
            x: number,
            y: number,
        ) => PointerGuidanceState | null;
        getExtremaTargets?: () => ExtremaTarget[];
        navigateToExtrema?: (target: ExtremaTarget) => void;
        extremeRefusal?: (direction: "FORWARD" | "BACKWARD") => string | null;
        getObjectList?: () => ChartObjectList | null;
        moveToObject?: (key: string) => boolean;
        dispose: () => void;
        moveOnce: (direction: MovableDirection) => boolean;
        moveToExtreme: (direction: MovableDirection) => boolean;
        moveToIndex: (row: number, col: number) => boolean;
        isMovable: (target: [number, number] | MovableDirection) => boolean;
        get isInitialEntry(): boolean;
        set isInitialEntry(value: boolean): void;
        get row(): number;
        set row(value: number): void;
        get col(): number;
        set col(value: number): void;
        addObserver: (observer: Observer<TraceState>) => void;
        removeObserver: (observer: Observer<TraceState>) => void;
        notifyStateUpdate: () => void;
        get state(): T;
    }

    Hierarchy (View Summary)

    Implemented by

    Index

    Properties

    getId traceType layerLabel placeAxisLabel level runSilently getCurrentXValue moveToXValue getAlternateXValue? hasXValue? getCurrentYValue? moveToXAndYValue? getCurrentSection? moveToXValueAndSection? notifyOutOfBounds resetToInitialEntry cursorKey? restoreCursor? getStateAt notifyObserversWithState getAllHighlightElements getAllOriginalElements getGeometryElements? moveToPointAndGetPointerGuidance getExtremaTargets? navigateToExtrema? extremeRefusal? getObjectList? moveToObject? dispose moveOnce moveToExtreme moveToIndex isMovable addObserver removeObserver notifyStateUpdate

    Accessors

    isInitialEntry row col state

    Properties

    getId: () => string

    Gets the unique identifier for the trace

    Type Declaration

      • (): string

      • Returns string

        The trace ID

    traceType: TraceType

    The trace's chart type, exposed without computing the full state.

    layerLabel: string

    How the layer names itself in the chart description's layer tabs — the producer's name when there is one, and the chart-type label otherwise. Exposed here for the same reason Trace.traceType is: the tab strip names every layer of a subplot, including the ones the reader has not visited, and building each one's full state to read a label would compute an audio, braille, text and highlight snapshot per layer per keypress.

    placeAxisLabel: string

    The label of the axis a layer switch reads this layer's place along -- the place Trace.getCurrentXValue gives -- trimmed: the x axis's, or the y axis's for a layer drawn on its side, whose categories run up the side (a horizontal box plot, error bar or dumbbell); '' when the layer authored none, or is found along both of its axes, as a horizontal bar is. Exposed for the same reason Trace.traceType is: a layer switch asks it of the layer it leaves and the one it enters, to tell whether a number read on one is a place on the other.

    level: "trace"

    Which level of the figure this element is, for the same reason Trace.traceType exists: state.type answers it too, but only after building the whole audio/braille/text/highlight snapshot.

    runSilently: (action: () => void) => void

    Runs the given moves with this trace's observers muted, so a relocation the reader did not ask for does not announce itself. See AbstractPlot.runSilently.

    getCurrentXValue: () => any

    Gets the current X value from the trace

    Type Declaration

      • (): any

      • Returns any

        The current X value or null if not available

    moveToXValue: (xValue: any) => boolean

    Moves the trace to the position that matches the given X value

    Type Declaration

      • (xValue: any): boolean

      • Parameters

        • xValue: any

          The X value to move to

        Returns boolean

        True if the position was found and set, false otherwise

    getAlternateXValue?: () => XValue | null

    A second X the reader's position reads as, which a layer switch may carry instead of Trace.getCurrentXValue; Subplot.carriedXValue says when. Optional; a horizontal bar offers its category here, its magnitude being its X.

    Type Declaration

      • (): XValue | null

      • Returns XValue | null

        The other X, or null when the position reads one way

    hasXValue?: (xValue: XValue) => boolean

    Whether a mark sits at exactly this X, as Trace.moveToXValue finds one before it falls back to the nearest. Optional; asked only to choose between the two X values of Trace.getAlternateXValue.

    Type Declaration

      • (xValue: XValue): boolean

      • Parameters

        • xValue: XValue

          The X a layer switch would carry

        Returns boolean

        True when the trace holds xValue exactly

    getCurrentYValue?: () => number | null

    Get the current Y value from the trace. Optional method implemented by traces that support Y value preservation during layer switching.

    Type Declaration

      • (): number | null

      • Returns number | null

        The current Y value or null if not available

    moveToXAndYValue?: (xValue: any, yValue: number) => boolean

    Move to a specific X value and find the closest position with the given Y value. Optional method implemented by traces that support preserving both X and Y values during layer switching.

    Type Declaration

      • (xValue: any, yValue: number): boolean

      • Parameters

        • xValue: any

          The X value to move to

        • yValue: number

          The Y value to find the closest matching position for

        Returns boolean

        true if the move was successful, false otherwise

    getCurrentSection?: () => string | null

    The section of a sectioned mark the cursor stands on -- a box plot's "25%" or "Maximum". Optional; implemented by traces whose position is a mark and a part of it, so a layer switch between two of them keeps both.

    Type Declaration

      • (): string | null

      • Returns string | null

        The section, or null when there is none

    moveToXValueAndSection?: (xValue: any, section: string) => boolean

    Moves to the mark a layer switch carried over, standing on the given section of it. Optional; see Trace.getCurrentSection.

    Type Declaration

      • (xValue: any, section: string): boolean

      • Parameters

        • xValue: any

          The X value to move to

        • section: string

          The section to stand on

        Returns boolean

        true if the move was successful, false otherwise

    notifyOutOfBounds: () => void

    Notify observers that the trace is out of bounds

    resetToInitialEntry: () => void

    Resets the trace to initial entry state

    cursorKey?: () => string | null

    The part of the cursor a trace keeps beside row/col that should survive a live data update -- a candlestick's segment. Context captures it before the update and hands it to restoreCursor. The key is opaque: it means something only to the same kind of trace that returned it. Optional; pairs with restoreCursor.

    Type Declaration

      • (): string | null

      • Returns string | null

        The key, or null when there is none

    restoreCursor?: (key?: string | null) => void

    Re-derives the navigation state a trace keeps beside row/col from them. Context calls it after restoring row/col onto a trace that a live data update rebuilt; a trace that navigates by row/col alone does not implement it.

    Type Declaration

      • (key?: string | null): void

      • Parameters

        • Optionalkey: string | null

          What cursorKey returned on the trace before the update

        Returns void

    getStateAt: (row: number, col: number) => TraceState

    Computes the trace state at an arbitrary position without moving the cursor or notifying observers (used by monitor mode).

    Type Declaration

      • (row: number, col: number): TraceState

      • Parameters

        • row: number

          The row of the position to compute state for

        • col: number

          The column of the position to compute state for

        Returns TraceState

        The trace state at the requested position

    notifyObserversWithState: (state: TraceState) => void

    Notifies all observers with a specific state

    Type Declaration

      • (state: TraceState): void

      • Parameters

        • state: TraceState

          The trace state to send to observers

        Returns void

    getAllHighlightElements: () => SVGElement[]

    Get all highlight SVG elements for this trace Used by HighlightService for high contrast mode

    Type Declaration

      • (): SVGElement[]

      • Returns SVGElement[]

        Array of all SVG elements, or empty array if none

    getAllOriginalElements: () => SVGElement[]
    getGeometryElements?: () => SVGElement[]

    The elements whose geometry is the trace as the chart drew it, when that differs from the highlight elements.

    Optional, and empty rather than absent when a trace has nothing extra to offer, so a caller can fall back to the highlight elements in one check. Implemented by traces whose highlight markers stand in for a shape rather than being it -- a line whose per-point circles maidr synthesised from the rendered <path>, where the path is the geometry and the circles are only the vertices on it.

    Type Declaration

      • (): SVGElement[]

      • Returns SVGElement[]

        The drawn elements, or an empty array when there are none

    moveToPointAndGetPointerGuidance: (
        x: number,
        y: number,
    ) => PointerGuidanceState | null

    Moves to the nearest point at (x, y) and returns directional guidance toward the nearest data geometry in a single call. Combining the two operations avoids running findNearestPoint twice per pointer event.

    For ViolinKdeTrace, coordinates map to (violin index, y-value within KDE curve); for ViolinBoxTrace, to (section index, violin index) for vertical orientation, or the inverse for horizontal.

    Type Declaration

      • (x: number, y: number): PointerGuidanceState | null

      • Parameters

        • x: number

          Screen-space x position in viewport pixels

        • y: number

          Screen-space y position in viewport pixels

        Returns PointerGuidanceState | null

        Guidance state, or null when unavailable for this plot level

    getExtremaTargets?: () => ExtremaTarget[]

    Gets extrema targets for navigation. Optional method implemented by traces that support extrema navigation.

    Type Declaration

    navigateToExtrema?: (target: ExtremaTarget) => void

    Navigate to a specific extrema target. Optional method implemented by traces that support extrema navigation.

    Type Declaration

    extremeRefusal?: (direction: "FORWARD" | "BACKWARD") => string | null

    What a jump to the left or right extreme is refused with, when the trace has a reason the edge signal would misstate: on a flow whose largest flows go round in a cycle, there is no end to jump to, and the next arrow still moves. Optional, and null where the jump is made as usual.

    Type Declaration

      • (direction: "FORWARD" | "BACKWARD"): string | null

      • Parameters

        • direction: "FORWARD" | "BACKWARD"

          Which way the jump goes

        Returns string | null

        What to tell the reader, or null

    getObjectList?: () => ChartObjectList | null

    Every object the o list offers, or null on a chart walked along axes.

    Type Declaration

    moveToObject?: (key: string) => boolean

    Moves to the object the list knows by this key.

    Type Declaration

      • (key: string): boolean

      • Parameters

        • key: string

          The object's key

        Returns boolean

        True when the cursor moved

    dispose: () => void
    moveOnce: (direction: MovableDirection) => boolean
    moveToExtreme: (direction: MovableDirection) => boolean
    moveToIndex: (row: number, col: number) => boolean
    isMovable: (target: [number, number] | MovableDirection) => boolean
    addObserver: (observer: Observer<TraceState>) => void
    removeObserver: (observer: Observer<TraceState>) => void
    notifyStateUpdate: () => void

    Accessors

    • get isInitialEntry(): boolean

      Returns boolean

    • set isInitialEntry(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get row(): number

      Returns number

    • set row(value: number): void

      Parameters

      • value: number

      Returns void

    • get col(): number

      Returns number

    • set col(value: number): void

      Parameters

      • value: number

      Returns void

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors