Context menu API reference
==========================

CSS
---

Classes
```````

* :ref:`center-bottom <positioning>`
* :ref:`center-center <positioning>`
* :ref:`center-content-x <steps>`
* :ref:`center-content-y <steps>`
* :ref:`center-top <positioning>`
* :ref:`dark-gray <coloring>`
* :ref:`flex-column <steps>`
* :ref:`flex-row <steps>`
* :ref:`highlighted <coloring>`
* :ref:`left-center <positioning>`
* :ref:`left-bottom <positioning>`
* :ref:`left-top <positioning>`
* :ref:`light-gray <coloring>`
* :ref:`margin-bottom-xx <steps>`
* :ref:`margin-left-xx <steps>`
* :ref:`margin-top-xx <steps>`
* :ref:`right-bottom <positioning>`
* :ref:`right-center <positioning>`
* :ref:`right-top <positioning>`
* :ref:`static-dark-gray <coloring>`
* :ref:`static-highlighted <coloring>`
* :ref:`static-light-gray <coloring>`

Variables
`````````

* :ref:`$active.color <template>`
* :ref:`$activeAccent.color <template>`
* :ref:`$activeSubtle.color <template>`
* :ref:`$circle.color <template>`
* :ref:`$check.color <template>`
* :ref:`$cross.color <template>`
* :ref:`$error.color <template>`
* :ref:`$focused.color <template>`
* :ref:`$focusedAccent.color <template>`
* :ref:`$inactive.color <template>`
* :ref:`$inactiveAccent.color <template>`
* :ref:`$inactiveSubtle.color <template>`
* :ref:`$warning.color <template>`


JavaScript
----------

Modules
```````

* `lodash 3.10.1 <https://lodash.com/docs/3.10.1>`_
* `jquery 3.4.1 <http://api.jquery.com/>`_
* `knockout 3.4.2 <http://knockoutjs.com/documentation/introduction.html>`_
* :ref:`matrix <matrix>`
* :ref:`component_util <component_util>`

.. warning::

  Some of the values returned by the API are Knockout ``ko.observable`` values.
  It is encouraged to react to these changes by using a ``ko.pureComputed`` (check
  the :ref:`corresponding section<reacting-to-changes-using-pure-computed>`
  for details).

  Usage of ``subscribe`` or ``ko.computed`` to listen to changes
  in observable values is **heavily discouraged** and can cause memory leaks and
  loss of data. Subscriptions using these methods must always be properly
  disposed (see :ref:`using-subscribe`).

DeskAPI
```````

- ``sound`` Object: contains URLs for sound files, available sounds are

  * ``sound.attention``
  * ``sound.confirm``
  * ``sound.exit``
  * ``sound.finish``
  * ``sound.navigate``
  * ``sound.save``
  * ``sound.set``
  * ``sound.error``

- ``playSound`` Function ( url: String ): takes an URL of a sound file
- ``robotConfiguration`` ko.observable( { estimatedForces: Array[Number], estimatedTorques: Array[Number], jointAngles: Array[Number], pose: Array[Number] } ): current robot configuration

  * ``estimatedForces``: Estimated external wrench (force, torque) acting on stiffness frame, expressed relative to the stiffness frame [N, N, N, Nm, Nm, Nm]
  * ``estimatedTorques``: External torque [Nm]
  * ``jointAngles``: Measured joint position [rad]
  * ``pose``: Measured end effector pose in base frame. Pose is represented as a 4x4 matrix in column-major format.

- ``gripperState`` ko.observable( { width: Number, maxWidth: Number } ): current gripper state
- ``relativeGripperWidth`` ko.pureComputed() { return Number }: gripper width from 0 (closed) to 1 (open)
- ``modbus`` Object:

  * ``configuration``: current modbus configuration values
  * ``data``: modbus data uploaded in JSON file

- ``adjustPose`` Function ({ joint_angles: Array[Number], pose: Array[Number]}, motionType: "cartesian" | "joint"): takes pose and an optional motionType "joint" (default: "cartesian"), then returns a promise that is either resolved with new adjusted pose or rejected. If the user saves Fine-adjustment pose dialog, the resolved value is the adjusted pose.

.. _elementAPI:

ElementAPI
``````````

- ``path`` ko.pureComputed({ id: String, indices: Array[Number] }): path to the element
- ``children`` ko.pureComputed(Array(:ref:`Element <elementAPI>`)): direct children of the element
- ``parameter`` Function (expression: String) { return ko.observable }: takes an expression and returns an observable with the app's (scoped) parameter
- ``hasParentComponent`` Function (name: String, stepID: String) { return Boolean }

- ``model`` Object:

    * ``id`` String
    * ``name`` ko.pureComputed(String)
    * ``color`` ko.pureComputed(String)
    * ``tags`` ko.pureComputedArray(Array)
    * ``image`` ko.pureComputed(Object)
    * ``contextMenu`` ko.pureComputed(Array)
    * ``components`` ko.pureComputed(String)
    * ``hiddenInLibrary`` ko.pureComputed(Boolean)
    * ``extraClientData`` ko.pureComputed(Object)


.. caution::

   The following properties are **experimental** and might have **breaking changes in the future**:

    - ``childAppIds`` ko.pureComputed(Array(String)): returns a list of the IDs of child apps in a group
    - ``traverse`` Function (callback: Function (:ref:`Element <elementAPI>`)): takes a callback function
      that will be called for every descendant element (including current element itself)

:ref:`StepAPI <step-api>`
`````````````````````````

- ``id`` String
- ``name`` ko.observable(String)
- ``label`` ko.observable(String)
- ``pilot`` ko.observable(Object): the pilot configuration
- ``focused`` ko.observable(Boolean)
- ``available`` ko.observable(Boolean)
- ``configured`` ko.observable(Boolean)
- ``steps`` ko.observableArray(): child steps
- ``focus`` Function ( ): focus the step
- ``done`` Function ( ): mark step as done and focus next step
- ``parent`` Object: points to the parent step
- ``next`` Object: points to the next step
- ``prev`` Object: points to the previous step
- ``update`` Function ( Object ): update any of the step's observable
  properties by passing an Object with the names of the observables to
  be modified as keys

ParameterAPI
````````````

- ``reset`` Function ( ): reset parameter to the default value
- ``isDirty`` Function ( ) { return Boolean }: returns true, if parameter was modified
- ``accessPath`` Function ( ) { return Array(String) }: returns the access path of the parameter
- ``parameter`` Function (String): returns a subtree of the parameter by passing an expression