.. include:: ../../vars.rst
.. _section-data-visualization-sample-inspector:

Sample Inspector
================

.. figure:: ../../_static/datavisualization/sample_inspector.png
    :alt: Sample Inspector
    :name: Sample Inspector
    :align: center
    :figWidth: 100%

The Sample Inspector provides the full structure and current value of a sample,
based on the selected entity. Two kind of entities can be selected: 
an instance (e.g., from the Instance Table), or a static sample 
(e.g., from the Sample Log). 

* If the selection is an instance, the value column will automatically be
  updated with the latest value of the instance. 
* If the selection is a static sample, the value will not be updated, and the
  Sample Inspector will show the content of the selected sample.

The Instance Table and Sample Log are referred to as *sample providers*.
Each of these tables provides a mechanism to select a sample,
which will then "drive" the Sample Inspector to display that sample's
data (and sample info).

===============
Toolbar Actions
===============

.. |ICON_CONNECTED| image:: ../../_static/datavisualization/icons/connected.png
.. |ICON_PAUSE| image:: ../../_static/datavisualization/icons/pause.png
.. |ICON_EXPORT_TO_FILE| image:: ../../_static/datavisualization/icons/exportToFile.png
.. |ICON_TREE_EXPAND| image:: ../../_static/datavisualization/icons/tree_expand_all.gif
.. |ICON_TREE_COLLAPSE| image:: ../../_static/datavisualization/icons/tree_collapse_all.gif
.. |ICON_CLEAN_UP| image:: ../../_static/datavisualization/icons/cleanup.gif

* |ICON_CONNECTED| **Link with selection**: When pressed (the default), the
  Sample Inspector will switch to the newly selected sample provider
  when you select a new sample provider (such as the Instance Table or Sample Log).
  
  .. tip:: 
      This feature can be used to "freeze" the display of interesting data. 
      Another Sample Inspector could then be created and populated with data
      from a later or different sample provider and then compared to this one.

* |ICON_PAUSE| **Pause UI updating**: Pause/Resume live display updates. If
  a new sample provider is selected, the display will update to show that data,
  but live updates will still be paused. Data is still being received in the
  background, regardless of the state of this button.
* |ICON_EXPORT_TO_FILE| **Export Sample Data to file**: Opens a file dialog
  and exports the sample data and SampleInfo fields into a text file.
* |ICON_TREE_EXPAND| **Expand Structural Fields**: Expands fields that are
  structures. Array fields will not be expanded.
* |ICON_TREE_COLLAPSE| **Collapse the tree**: Collapses all expanded fields.
* |ICON_CLEAN_UP| **Clear Contents**: Disconnects the Sample Inspector
  from the sample provider.

====================
Context Menu Actions
====================

.. |ICON_UNSUBSCRIBE| image:: ../../_static/datavisualization/icons/unsubscribe.png
.. |ICON_VISUALIZE_16| image:: ../../_static/datavisualization/icons/visualize_16.png
.. |ICON_ADD_TO_VIZ| image:: ../../_static/datavisualization/icons/addToVizView.png
.. |ICON_SUBSCRIPTION_PROPERTIES| image:: ../../_static/datavisualization/icons/subscription_properties.png

The following context menu actions are only available for an instance sample provider.
Some of these actions are available for multiple selections.

* |ICON_UNSUBSCRIBE| **Unsubscribe**: Unsubscribes from the Topic.
* |ICON_VISUALIZE_16| **Visualize**: Visualizes the selected fields in a new
  data visualization view.
* |ICON_ADD_TO_VIZ| **Add to existing view**: Adds the selected fields to an
  existing data visualization view. Note that this item is only available
  if there are already data visualization views open.
* |ICON_SUBSCRIPTION_PROPERTIES| **Subscription Properties**: Opens the
  subscription properties dialog.

===========
Drag & Drop
===========

You can add one or multiple selected fields to an existing data
visualization view by using drag-and-drop. The data visualization view
that receives the drop will react corresponding to the dropped
field's type and definition. For example, the Sample Log view
will only get the Topic info from the dropped fields and only add the
same Topic once. The Time Chart view will ignore non-numeric fields
and the same fields can be added more than once.