Item Paths

To access a specific item in the parameter tree, all interface functions require the item’s path. The tree root is denoted by the path string “/” or the empty string “”.

  • Subitems are separated from the path to its parent by the slash character:
    #define NxLibItemSeparator '/'
  • Paths to elements of an Array are prefixed with a backslash, followed by the element index:
    #define NxLibIndexEscapeChar '\\'
  • Due to obvious reasons, there are a few characters that cannot be used in a node name:
    #define NxLibItemForbiddenChars "/\\\\r\n\0"

Examples

  • To specify an item “Test” on the top-most tree level the path should be “/Test” or “Test”

  • If the item “Test” is an array, you can access its 5th element using the path “/Test/5” / Note that the “" character is a real backslash! When specifying this inside the C/C++ or HDevelop language you need to escape the backslash, effectively typing “/Test/\5”

  • The named member items of an Object can also be accessed via the index notation. If “/Test” is an Object with the members “Size” with value 5 and “Name” with value “HelloWorld” (in JSON notation: “Test”:{“Size”:5,”Name”:”HelloWorld”}), the application can access “Size” and “Name” via the paths “Test/\0” and “Test/\1”. The order of the members when accessing via indices is not defined and can be arbitrary. The application should use nxLibGetName to query the actual item name. nxLibGetCount can be used to retrieve the number of member items.

Item Name Constants

All built-in item names have predefined constants within nxLibConstants.h. The constant name simply consists of the item name, prefixed with “itm”. Example: The Cameras item can be access via the path:

itmCameras

The path to the camera with EEPROM ID 1 is simply constructed as:

itmCameras "/" itmByEepromId "\\1"

or more elegantly using the C++ NxLibItem object:

NxLibItem()[itmCameras][itmByEepromId][1]

Access Rights

  • Items provided by the library itself are read-only if they serve for informational purpose only.

  • The libraries own items might be read or written, but cannot be deleted.

  • At the root tree level, new items are created on demand by just writing to a value to an item path.

  • Accessing an inexistent item in a reading fashion will fail with the error code nxLibItemInexistent.