Annotations

The annotations are just a way for users to add notes/reminders/visual cues which supplement the chart reflecting the data fetched and/or computed. Unlike other aspects of the chart the annotations are quite interactive in their nature - they get added as well as modified, mostly by users interacting with them directly. In other words, the chart will automatically handle aspects like selection/deselection, annotation removal etc. In most if not all case, the host page will be notified about changes being done to the annotation (or the chart itself). For details, there’s a separate page on notifications.

The main API entry point for annotations is the following call

annotate(id, (traits = null), (data = null));

Ignoring the last parameter (data), this call will set the chart into drawing mode for the given annotation’s id (you may discover ids from the taxonomy under annotations). If you provide null or undefined as id you’ll reset the active tool (say user clicked on a tool by mistake and wants “out”).

You may optionally provide traits for the annotation (described in the Chart API); additionally, list of traits applicable to each annotation is provided in the taxonomy.

There’s one common element you may (optionally) put into traits for a given annotation: marker. This is an object representing adornment of the line ends. It consists of two parameters, one being kind which can currently only be arrow (though other kinds will likely be added in the future) and the other (vertex) describing the points this applies to: set start for first, end for last, both for both and none if you want to remove the marker.

Sometimes though, you may have everything ready and just want the chart to put the annotation at a given place. At the moment, there are two annotations of this kind, the first of which represents a family of similar annotations. For both you’ll need to provide data which should contain placement information (since users won’t be adding the annotation interactively, clicking on a chart).

Notes on slightly specific annotations

Computed Text

The ComputedText represents a text annotation which is not editable as text, whose text is provided by host and which can optionally include several additional prices (optionally shown as horizontal lines). Let’s see an example of this:

chart.annotate(
    "ComputedText",
    {
        line: { color: "#0b0", width: 2, dashStyle: "LongDashDot" },
    },
    {
        points: [
            { price: 125.25, time: 1487589126661.0598 },
            { price: 135.75, time: 1487589126661.0598 },
        ],
        prices: [125.25, 135.75],
        drawLines: true,
        textLines: [
            "Entry price: 125.25",
            "Exit price:135.75",
            "# Contracts: 12",
            "Long",
            "Profit: $17225.00",
        ],
        kind: "ProfitLoss",
        numContracts: 12,
        pos: "Long",
    },
);

We won’t go into details of the traits as that’s explained already.

The third parameter carries the data necessary for annotation creation; placement is handled automatically when user clicks on the chart.

The fields drawLines (draw lines representing these prices) and textLines (actual text to be shown) are mandatory, the rest is optional and isn’t interpreted by chart in any way. In the example above, we have added kind, numContrats, prices and pos because these will ultimately be necessary when the user tries to edit the annotation. Without this additional info it might be impossible to recompute the textLines.

The points are the anchors of the lines to be optionally shown with the computed text and typically (but chart does not check nor enforce this) have the same values as prices array (which is itself optional). While the points/anchors are shown like for other annotations, they are not movable because typically (but again, chart does not enforce this) the prices of these anchors are shown in the textLines yet it’s up to the UI to keep the two in sync; chart helps by preventing interactive change.

Please note that when editing already placed ComputedText you will get back almost exactly the same thing you’ve put in: traits are editable data, extras are non-editable (example above: prices, pos, kind, numContracts), points are all anchor points but please note that the first two points are reserved as top-left and bottom-right coordinates of the text - the remaining points are what you set initially. When you update ComputedText you may update the points other than the first two; if you try to update any points of any other annotation, this will simply be ignored (we don’t anticipate points of other annotations to be updated non-interactively).

Unlike FiftyPercentLine below which gets placed entirely non-interactively, for this annotation to be placed on the char (after calling chart.annotate) the user still needs to click once, to position the text part of the computed text. The click position will become the first point of the newly created annotation, the second will be auto-computed and further points will be what you provided in the annotate call (if any). Since the user clicks somewhere, chart can figure out what the axis and pane of the chart are so you don’t need to provide this info.

Fifty Percent Line

This is a relatively simple annotation: three horizontal lines are drawn, upper and lower are movable, the third is placed exactly at 50% (hence the name) between the two, on the price scale. By default, we show the price info next to each of the lines. Upper and lower line share a style, the middle (50%) one gets its own separate style.

The annotation can be used in a “classic” way, meaning you simply call chart.annotate("FiftyPercentLine") and then wait for user to click twice (for upper and lower line). In this case, all three lines are styled the same (inheriting the default line style).

Alternatively, the annotation can be immediately placed on the chart assuming you’ve prepared all the data, similar to ComputedText above. Example:

chart.annotate(
    "FiftyPercentLine",
    {
        line2: {
            color: "#7ec0ee",
            width: 1,
            dashStyle: "LongDashDotDot",
        },
    },
    {
        axis: axisOfTheChart, // optional
        points: [
            {
                price: 31.3621,
                time: 1487589126661.0598,
            },
            {
                price: 23.1847,
                time: 1487754369386.0386,
            },
        ],
    },
);

The following things are worth mentioning:

1. Note that the style of the 50% line is denoted by using line2; line style is reserved for the other two lines. As usual, you don’t have to provide traits (simply pass null); if you don’t you get default style
2. Unlike ComputedText where the user clicks on a given chart and axis, we’re immediately placing the annotation onto a given chart; however, charts have many panes and axes and therefore you should provide the concrete axis to put the annotation into. It’s trivial to obtain the axis by using synthetic annotation called PickPoint (described below). If you don’t have the axis (for example, user entered point prices manually) just omit the axis and the chart will default to main axis of the chart.
3. Just like ComputedText we’re providing both time and price for the two points defining upper/lower line; unlike ComputedText the engine will allow the two lines to be dragged by the anchors (these two points) because there’s no risk of incoherent data (all that we need to represent FiftyPercentLine is encapsulated in the anchor points and when user moves these interactively chart recomputes the annotation to keep it coherent).

How to “pick” a point on a chart

You will have several cases where the users won’t interactively place points on the chart, or will do so partially; often there’ll be a dialog open where users will be able to adjust prices of the points chosen (or fill them in manually). In order to help you for cases like this, there is an “annotation” (which doesn’t do anything) called PickPoint that you can use which will provide the following after the chart has been clicked: chart clicked, axis clicked and point clicked (which itself consists of price and time, both are valid only for the given axis).