org.firstinspires.ftc.robotcore.external

## Interface Telemetry

-     public interface Telemetry

  Instances of `Telemetry` provide a means by which data can be transmitted from the robot controller to the driver station and displayed on the driver station screen.

  Simple use of `Telemetry` consists of a series of `addData()` calls, followed by a call to `update()`. For example:

           // LinearOpMode
           telemetry.addData("count", currentCount);
           telemetry.addData("elapsedTime", "%.3f", elapsedSeconds);
           telemetry.update();

  In the 2015/16 season, the call to `update()` was not required; now, however, in a `LinearOpMode`, unless `update()` is called, nothing will appear on the driver station screen. In other, loop-based opmodes, `update()` continues to be called automatically at the end of `OpMode.loop()` and `OpMode.init_loop()`; no call to `update()` is required in loop-based opmodes.

           // loop-based opmode
           telemetry.addData("count", currentCount);
           telemetry.addData("elapsedTime", "%.3f", elapsedSeconds);

  By default (but see `setAutoClear()`), data is cleared from the telemetry after each call to `update()`; thus, you need to issue `addData()` for the entire contents of the telemetry screen on each update cycle. This behavior is just as it was in the 2015/16 season.

  A more complicated use of `Telemetry` might have different parts of the program update different items on the display in a decoupled, decentralized manner. Such situations might usefully avail themselves of turning off the auto-clear setting. For example:

           telemetry.setAutoClear(false);
           Telemetry.Item countItem = telemetry.addData("count", 0);
           Telemetry.Item elapsedItem = telemetry.addData("elapsedTime", 0);

           void onePartOfYourCode() {
               ...
               countItem.setValue(0);
               telemetry.update();
               ...
           }

           void anotherPartOfYourCode() {
               ...
               elapsedItem.setValue("%.3f", elapsedSeconds);
               telemetry.update();
               ...
           }

  In this way different parts of the code can update only a portion of the telemetry screen without disturbing other parts.

  Below the list of caption, value, pairs, on the screen a `Telemetry` also displays a short, unstructured log of messages. Use `log().add()` to add to the log. See also `log()`.

  Actual transmission to the driver station is throttled to avoid use of excessive bandwidth. By default, transmission will occur at most every 250ms. This interval can be controlled with `setMsTransmissionInterval()`. Any `update()`s which occur more frequently will not be transmitted if superseded by a subsequent `update()` before the transmission interval expires.

  As mentioned above, by default, after each call to `update()`, the method `clear()` is automatically called. Thus, in simple usage, after each `update()`, you'll want to issue `addData()` calls to rebuild the entire driver station telemetry screen that you wish to observe. This simple usage can be modified in two ways.

  First, the automatic issuance of calls to `clear()` can be altered by means of `setAutoClear(boolean)`. If auto clearing is set to false, previously added telemetry items remain present from `update()` to `update()`, but their value can still be altered using `Item.setValue()`, items can be removed using `removeItem(Item)`, and new items can be added using `addData()` and `Item.addData()`.

  Second, telemetry items created in a functional form using `addData(String, Func)` or `Telemetry.Item.addData(String, Func)` are not automatically removed when `clear()` is called, either implicitly or explicitly (though they are removed when `clearAll()` is called). The intent of such items is allow a one-time specification of telemetry items by providing a function that can produce a value to be displayed rather than providing the actual value itself. Such functions are evaluated only when it is known that telemetry is going to be transmitted to the driver station (and so a value is required). This approach can be particularly useful if the acquisition of the data to be displayed is relatively expensive or time consuming, as that cost is only expended when actually useful. In addition to one-item-per-line display on the driver station, multiple items per line can be displayed by starting with a call to `addLine()` and then following up with one or more `addData(String, Object)` calls. For example:

           telemetry.addLine()
                .addData("count", currentCount)
                .addData("elapsedTime", "%.3f", seconds);
           telemetry.addLine()
                .addData("voltage", "%.1f", getCurrentVoltage())
                .addData("orientation", "%s", getOrientation());
           telemetry.update();

  Items on the same line are separated by the `item separator`. Caption and value within an item are separated by the `caption value separator`.

  Note: in the 2015/16 season, it was possible for `Telemetry` instances to be automatically sorted in alphabetical order by caption. This functionality is no longer supported.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Telemetry.Item` Instances of `Telemetry.Item` represent an item of data on the drive station telemetry display.
    `static interface` | `Telemetry.Line` Instances of `Telemetry.Line` build lines of data on the driver station telemetry display.
    `static interface` | `Telemetry.Log` The `Telemetry.Log` in a `Telemetry` instance provides an append-only list of messages that appear on the driver station below the `Telemetry.Item`s of the `Telemetry`.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `addAction(java.lang.Runnable action)` In addition to items and lines, a telemetry may also contain a list of actions.
    `<T> Telemetry.Item` | `addData(java.lang.String caption, Func<T> valueProducer)` Adds an item to the end of the telemetry being built for driver station display.
    `Telemetry.Item` | `addData(java.lang.String caption, java.lang.Object value)` Adds an item to the end if the telemetry being built for driver station display.
    `<T> Telemetry.Item` | `addData(java.lang.String caption, java.lang.String format, Func<T> valueProducer)` Adds an item to the end of the telemetry being built for driver station display.
    `Telemetry.Item` | `addData(java.lang.String caption, java.lang.String format, java.lang.Object... args)` Adds an item to the end of the telemetry being built for driver station display.
    `Telemetry.Line` | `addLine()` Creates and returns a new line in the receiver `Telemetry`.
    `Telemetry.Line` | `addLine(java.lang.String lineCaption)` Creates and returns a new line in the receiver `Telemetry`.
    `void` | `clear()` Removes all items from the receiver whose value is not to be retained.
    `void` | `clearAll()` Removes all items, lines, and actions from the receiver
    `java.lang.String` | `getCaptionValueSeparator()` Returns the string which is used to separate caption from value within a `Telemetry` `Telemetry.Item`.
    `java.lang.String` | `getItemSeparator()` Returns the string which is used to separate `Telemetry.Item`s contained within a line.
    `int` | `getMsTransmissionInterval()` Returns the minimum interval between `Telemetry` transmissions from the robot controller to the driver station
    `boolean` | `isAutoClear()` Answers whether `clear()` is automatically called after each call to `update()`.
    `Telemetry.Log` | `log()` Returns the log of this `Telemetry` to which log entries may be appended.
    `boolean` | `removeAction(java.lang.Object token)` Removes a previously added action from the receiver.
    `boolean` | `removeItem(Telemetry.Item item)` Removes an item from the receiver telemetry, if present.
    `boolean` | `removeLine(Telemetry.Line line)` Removes a line from the receiver telemetry, if present.
    `void` | `setAutoClear(boolean autoClear)` Sets whether `clear()` is automatically called after each call to `update()`.
    `void` | `setCaptionValueSeparator(java.lang.String captionValueSeparator)`
    `void` | `setItemSeparator(java.lang.String itemSeparator)`
    `void` | `setMsTransmissionInterval(int msTransmissionInterval)` Sets the minimum interval between `Telemetry` transmissions from the robot controller to the driver station.
    `boolean` | `update()` Sends the receiver `Telemetry` to the driver station if more than the `transmission interval` has elapsed since the last transmission, or schedules the transmission of the receiver should no subsequent `Telemetry` state be scheduled for transmission before the `transmission interval` expires.

- - ### Method Detail

    - #### addData

          Telemetry.Item addData(java.lang.String caption,
                                 java.lang.String format,
                                 java.lang.Object... args)

      Adds an item to the end of the telemetry being built for driver station display. The value shown will be the result of calling `String.format()` with the indicated format and arguments. The caption and value are shown on the driver station separated by the `caption value separator`. The item is removed if `clear()` or `clearAll()` is called.
      Parameters:
        `caption` - the caption to use
        `format` - the string by which the arguments are to be formatted
        `args` - the arguments to format
      Returns:
        an `Telemetry.Item` that can be used to update the value or append further `Telemetry.Item`s
      See Also:
        `addData(String, Object)`, `addData(String, Func)`

    - #### addData

          Telemetry.Item addData(java.lang.String caption,
                                 java.lang.Object value)

      Adds an item to the end if the telemetry being built for driver station display. The value shown will be the result of calling `toString()` on the provided value object. The caption and value are shown on the driver station separated by the `caption value separator`. The item is removed if `clear()` or `clearAll()` is called.
      Parameters:
        `caption` - the caption to use
        `value` - the value to display
      Returns:
        an `Telemetry.Item` that can be used to update the value or append further `Telemetry.Item`s
      See Also:
        `addData(String, String, Object...)`, `addData(String, Func)`

    - #### addData

          <T> Telemetry.Item addData(java.lang.String caption,
                                     Func<T> valueProducer)

      Adds an item to the end of the telemetry being built for driver station display. The value shown will be the result of calling `toString()` on the object which is returned from invoking valueProducer.`Func.value()` value()}. The caption and value are shown on the driver station separated by the `caption value separator`. The item is removed if `clearAll()` is called, but not if `clear()` is called.

      The valueProducer is evaluated only if actual transmission to the driver station is to occur. This is important, as it provides a means of displaying telemetry which is relatively expensive to evaluate while avoiding computation or delay on evaluations which won't be transmitted due to transmission interval throttling.

      Parameters:
        `caption` - the caption to use
        `valueProducer` - the object which will provide the value to display
      Returns:
        an `Telemetry.Item` that can be used to update the value or append further `Telemetry.Item`s
      See Also:
        `addData(String, String, Object...)`, `addData(String, Object)`, `addData(String, String, Func)`, `getMsTransmissionInterval()`

    - #### addData

          <T> Telemetry.Item addData(java.lang.String caption,
                                     java.lang.String format,
                                     Func<T> valueProducer)

      Adds an item to the end of the telemetry being built for driver station display. The value shown will be the result of calling `String.format(java.lang.String, java.lang.Object...)` on the object which is returned from invoking valueProducer.`Func.value()` value()}. The caption and value are shown on the driver station separated by the `caption value separator`. The item is removed if `clearAll()` is called, but not if `clear()` is called.

      The valueProducer is evaluated only if actual transmission to the driver station is to occur. This is important, as it provides a means of displaying telemetry which is relatively expensive to evaluate while avoiding computation or delay on evaluations which won't be transmitted due to transmission interval throttling.

      Parameters:
        `caption` - the caption to use
        `valueProducer` - the object which will provide the value to display
      Returns:
        an `Telemetry.Item` that can be used to update the value or append further `Telemetry.Item`s
      See Also:
        `addData(String, String, Object...)`, `addData(String, Object)`, `addData(String, Func)`, `getMsTransmissionInterval()`

    - #### removeItem

          boolean removeItem(Telemetry.Item item)

      Removes an item from the receiver telemetry, if present.
      Parameters:
        `item` - the item to remove
      Returns:
        true if any change was made to the receive (ie: the item was present); false otherwise

    - #### clear

          void clear()

      Removes all items from the receiver whose value is not to be retained.
      See Also:
        `Telemetry.Item.setRetained(Boolean)`, `Telemetry.Item.isRetained()`, `clearAll()`, `addData(String, Func)`

    - #### clearAll

          void clearAll()

      Removes all items, lines, and actions from the receiver
      See Also:
        `clear()`

    - #### addAction

          java.lang.Object addAction(java.lang.Runnable action)

      In addition to items and lines, a telemetry may also contain a list of actions. When the telemetry is to be updated, these actions are evaluated before the telemetry lines are composed just prior to transmission. A typical use of such actions is to initialize some state variable, parts of which are subsequently displayed in items. This can help avoid needless re-evaluation.

      Actions are cleared with `clearAll()`, and can be removed with `removeAction()`.

      Parameters:
        `action` - the action to execute before composing the lines telemetry
      Returns:
        a token by which the action can be later removed.
      See Also:
        `addData(String, Object)`, `removeAction(Object)`, `addLine()`, `update()`

    - #### removeAction

          boolean removeAction(java.lang.Object token)

      Removes a previously added action from the receiver.
      Parameters:
        `token` - the token previously returned from `addAction()`.
      Returns:
        whether any change was made to the receiver

    - #### update

          boolean update()

      Sends the receiver `Telemetry` to the driver station if more than the `transmission interval` has elapsed since the last transmission, or schedules the transmission of the receiver should no subsequent `Telemetry` state be scheduled for transmission before the `transmission interval` expires.
      Returns:
        whether a transmission to the driver station occurred or not

    - #### addLine

          Telemetry.Line addLine()

      Creates and returns a new line in the receiver `Telemetry`.
      Returns:
        a new line in the receiver `Telemetry`

    - #### addLine

          Telemetry.Line addLine(java.lang.String lineCaption)

      Creates and returns a new line in the receiver `Telemetry`.
      Parameters:
        `lineCaption` - the caption for the line
      Returns:
        a new line in the receiver `Telemetry`

    - #### removeLine

          boolean removeLine(Telemetry.Line line)

      Removes a line from the receiver telemetry, if present.
      Parameters:
        `line` - the line to be removed
      Returns:
        whether any change was made to the receiver

    - #### isAutoClear

          boolean isAutoClear()

      Answers whether `clear()` is automatically called after each call to `update()`.
      Returns:
        whether `clear()` is automatically called after each call to `update()`.
      See Also:
        `setAutoClear(boolean)`

    - #### setAutoClear

          void setAutoClear(boolean autoClear)

      Sets whether `clear()` is automatically called after each call to `update()`.
      Parameters:
        `autoClear` - if true, `clear()` is automatically called after each call to `update()`.

    - #### getMsTransmissionInterval

          int getMsTransmissionInterval()

      Returns the minimum interval between `Telemetry` transmissions from the robot controller to the driver station
      Returns:
        the minimum interval between `Telemetry` transmissions from the robot controller to the diver station
      See Also:
        `setMsTransmissionInterval(int)`

    - #### setMsTransmissionInterval

          void setMsTransmissionInterval(int msTransmissionInterval)

      Sets the minimum interval between `Telemetry` transmissions from the robot controller to the driver station.
      Parameters:
        `msTransmissionInterval` - the minimum interval between `Telemetry` transmissions from the robot controller to the driver station
      See Also:
        `getMsTransmissionInterval()`

    - #### getItemSeparator

          java.lang.String getItemSeparator()

      Returns the string which is used to separate `Telemetry.Item`s contained within a line. The default separator is " | ".
      Returns:
        the string which is use to separate `Telemetry.Item`s contained within a line.
      See Also:
        `setItemSeparator(String)`, `addLine()`

    - #### setItemSeparator

          void setItemSeparator(java.lang.String itemSeparator)

      See Also:
        `setItemSeparator(String)`

    - #### getCaptionValueSeparator

          java.lang.String getCaptionValueSeparator()

      Returns the string which is used to separate caption from value within a `Telemetry` `Telemetry.Item`. The default separator is " : ";
      Returns:
        the string which is used to separate caption from value within a `Telemetry` `Telemetry.Item`.

    - #### setCaptionValueSeparator

          void setCaptionValueSeparator(java.lang.String captionValueSeparator)

      See Also:
        `getCaptionValueSeparator()`

    - #### log

          Telemetry.Log log()

      Returns the log of this `Telemetry` to which log entries may be appended.
      Returns:
        the log of this `Telemetry` to which log entries may be appended.
      See Also:
        `addData(String, Object)`