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 "/" 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 named "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 node 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 accessed via the path:

itmCameras

The node containing the model name of the camera with serial number 123456 is simply constructed as:

itmCameras "/" "123456" "/" itmModelName

or more elegantly using the C++ NxLibItem object:

NxLibItem()[itmCameras]["123456"][itmModelName]

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, the user can create new items on demand by just writing a value to an item path.

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