Node Metadata

From K-3D

Overview

Starting in K-3D 0.7.6.0, document nodes store "metadata", an arbitrary collection of name-value string pairs that can be written / read by any part of the system. The interpretation of specific names and values is left to the caller, such as the UI layer. By definition, metadata name-value pairs are modeled on XML attributes, including the use of namespaces. Metadata is is serialized as part of the owning node, and thus provides a sort-of "scratchpad" where you can store arbitrary data as part of a node for later retrieval. Some anticipated use-cases include:

• Tagging nodes created by a component so they can be identified later-on.
• Marking nodes for special treatment by the UI layer - e.g. creating "hidden" nodes, nodes that shouldn't be deleted, etc.
• Whatever else you like!

Working With Metadata

Any part of the system can read/write metadata on an existing node. Currently there is access via C++ and Python:

C++:

if(k3d::imetadata* const metadata = dynamic_cast<k3d::imetadata*>(node))
{
  metadata->set_metadata("my_name", "my_value");
  k3d::string_t value = metadata->get_metadata()["my_name"];
  metadata->erase_metadata("my_name");
}

Python:

m = k3d.dynamic_cast(node, "imetadata")
m.set_metadata("my_name", "my_value")
m.get_metadata()["my_name"]
m.erase_metadata("my_name")

Important Note: plugins that define their own metadata should use their plugin name as the "namespace". For example, a plugin named "FooPanel" that wants to store "author" metadata should do so as:

metadata->set_metadata("FooPanel:author", "Fred");

... this will ensure that there are no name-clashes between plugins that manipulate metadata.

Currently Defined Namespaces/Names

k3d

The k3d namespace is reserved for use by the K-3D application:

ngui

The ngui namespace is reserved for use by the standard graphical user interface layer: