usdUI: Add UI hints metadata and API

usdUI now creates a dictionary-valued plugin metadata field called
`uiHints` for holding presentation metadata. "Schema-like" access classes
are provided to read and write dictionary entries for the hints that are
relevant to the repsective core object type: UsdUIObjectHints,
UsdUIPrimHints, UsdUIPropertyHints, and UsdUIAttributeHints. There are no
relationship-specific UI hints, thus no UsdUIRelationshipHints.

(Internal change: 2373053)
(Internal change: 2373124)

Author: agb63

pxr/usd/usdUI/CMakeLists.txt

@@ -10,9 +10,21 @@ pxr_library(usdUI
         sdf
         usd
 
+    PUBLIC_CLASSES
+        attributeHints
+        objectHints
+        primHints
+        propertyHints
+
     PUBLIC_HEADERS
         api.h
-    
+
+    PYMODULE_CPPFILES
+        wrapAttributeHints.cpp
+        wrapObjectHints.cpp
+        wrapPrimHints.cpp
+        wrapPropertyHints.cpp
+
     PYMODULE_FILES
         __init__.py
 
@@ -21,10 +33,16 @@ pxr_library(usdUI
 )
 
 pxr_test_scripts(
+    testenv/testUsdUIHints.py
     testenv/testUsdUINodeGraphNode.py
     testenv/testUsdUISceneGraphPrim.py
 )
 
+pxr_install_test_dir(
+    SRC testenv/testUsdUIHints
+    DEST testUsdUIHints
+)
+
 pxr_install_test_dir(
     SRC testenv/testUsdUINodeGraphNode
     DEST testUsdUINodeGraphNode
@@ -34,6 +52,10 @@ pxr_install_test_dir(
     DEST testUsdUISceneGraphPrim
 )
 
+pxr_register_test(testUsdUIHints
+    PYTHON
+    COMMAND "${CMAKE_INSTALL_PREFIX}/tests/testUsdUIHints"
+)
 pxr_register_test(testUsdUINodeGraphNode
     PYTHON
     COMMAND "${CMAKE_INSTALL_PREFIX}/tests/testUsdUINodeGraphNode"

pxr/usd/usdUI/attributeHints.cpp

@@ -0,0 +1,105 @@
+//
+// Copyright 2025 Pixar
+//
+// Licensed under the terms set forth in the LICENSE.txt file available at
+// https://openusd.org/license.
+//
+
+#include "pxr/usd/usdUI/attributeHints.h"
+#include "pxr/base/tf/diagnostic.h"
+
+PXR_NAMESPACE_OPEN_SCOPE
+
+UsdUIAttributeHints::UsdUIAttributeHints() = default;
+
+UsdUIAttributeHints::UsdUIAttributeHints(const UsdAttribute& attr)
+    : UsdUIPropertyHints(attr),
+      _attr(attr)
+{
+}
+
+VtDictionary
+UsdUIAttributeHints::GetValueLabels() const
+{
+    if (!_attr) {
+        return {};
+    }
+
+    VtDictionary labels;
+    if (_attr.GetMetadataByDictKey(
+            UsdUIHintKeys->UIHints,
+            UsdUIHintKeys->ValueLabels,
+            &labels)) {
+        return labels;
+    }
+
+    return {};
+}
+
+bool
+UsdUIAttributeHints::SetValueLabels(const VtDictionary& labels)
+{
+    if (!_attr) {
+        TF_CODING_ERROR("Invalid attribute");
+        return false;
+    }
+
+    return _attr.SetMetadataByDictKey(
+        UsdUIHintKeys->UIHints,
+        UsdUIHintKeys->ValueLabels,
+        labels);
+}
+
+VtTokenArray
+UsdUIAttributeHints::GetValueLabelsOrder() const
+{
+    if (!_attr) {
+        return {};
+    }
+
+    VtTokenArray order;
+    if (_attr.GetMetadataByDictKey(
+            UsdUIHintKeys->UIHints,
+            UsdUIHintKeys->ValueLabelsOrder,
+            &order)) {
+        return order;
+    }
+
+    return {};
+}
+
+bool
+UsdUIAttributeHints::SetValueLabelsOrder(const VtTokenArray& order)
+{
+    if (!_attr) {
+        TF_CODING_ERROR("Invalid attribute");
+        return false;
+    }
+
+    return _attr.SetMetadataByDictKey(
+        UsdUIHintKeys->UIHints,
+        UsdUIHintKeys->ValueLabelsOrder,
+        order);
+}
+
+bool
+UsdUIAttributeHints::ApplyValueLabel(const std::string& label)
+{
+    if (!_attr) {
+        TF_CODING_ERROR("Invalid attribute");
+        return false;
+    }
+
+    const TfToken keyPath =
+        _MakeKeyPath(UsdUIHintKeys->ValueLabels, TfToken(label));
+    VtValue value;
+
+    if (_attr.GetMetadataByDictKey(
+            UsdUIHintKeys->UIHints, keyPath, &value)) {
+        return _attr.Set(value);
+    }
+
+    return false;
+}
+
+PXR_NAMESPACE_CLOSE_SCOPE

pxr/usd/usdUI/attributeHints.h

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 Pixar
+//
+// Licensed under the terms set forth in the LICENSE.txt file available at
+// https://openusd.org/license.
+//
+
+#ifndef PXR_USD_USDUI_ATTRIBUTE_HINTS_H
+#define PXR_USD_USDUI_ATTRIBUTE_HINTS_H
+
+#include "pxr/usd/usdUI/propertyHints.h"
+#include "pxr/usd/usd/attribute.h"
+
+#include "pxr/base/vt/dictionary.h"
+#include "pxr/base/vt/value.h"
+
+#include <string>
+
+PXR_NAMESPACE_OPEN_SCOPE
+
+/// \class UsdUIAttributeHints
+///
+/// A "schema-like" wrapper that provides API for retrieving and authoring UI
+/// hint values within the \c uiHints dictionary field on a UsdAttribute
+/// instance.
+///
+/// UsdUIAttributeHints is "schema-like" in that it interprets fields belonging
+/// to a core object type (in this case UsdAttribute, but see also
+/// UsdUIObjectHints, UsdUIPrimHints, and UsdUIPropertyHints), and provides
+/// convenient API for using those fields. However, it is not formally a schema
+/// and does not derive from UsdSchemaBase.
+class UsdUIAttributeHints : public UsdUIPropertyHints
+{
+public:
+    /// Default constructor that creates an invalid hints object.
+    ///
+    /// Calling "set" operations on this object will post errors. "Get"
+    /// operations will return fallback values.
+    USDUI_API
+    UsdUIAttributeHints();
+
+    /// Construct a hints object for the given UsdAttribute \p attr.
+    USDUI_API
+    explicit UsdUIAttributeHints(const UsdAttribute& attr);
+
+    /// Return the attribute that this hints instance is interpreting.
+    UsdAttribute GetAttribute() const { return _attr; }
+
+    /// Return the attribute's value labels dictionary.
+    ///
+    /// This dictionary associates user-facing labels for display in the UI with
+    /// underlying values to be authored to the attribute when selected.
+    USDUI_API
+    VtDictionary GetValueLabels() const;
+
+    /// Set the attribute's value labels dictionary. Return \c true if
+    /// successful.
+    ///
+    /// Note that since this field is dictionary-valued, its composed value will
+    /// be the combination of all its entries as specified across all relevant
+    /// edit targets. Overrides occur per-entry rather than the dictionary as a
+    /// whole.
+    USDUI_API
+    bool SetValueLabels(const VtDictionary& labels);
+
+    /// Return the value labels order, indicating the order in which value
+    /// labels should appear.
+    USDUI_API
+    VtTokenArray GetValueLabelsOrder() const;
+
+    /// Set the attribute's value labels order. Return \c true if successful.
+    USDUI_API
+    bool SetValueLabelsOrder(const VtTokenArray& order);
+
+    /// Author the value associated with the given \p label to the attribute.
+    /// If \p label is not a key in the attribute's value labels dictionary,
+    /// return \c false. Otherwise return \c true if \p label was successfully
+    /// applied.
+    USDUI_API
+    bool ApplyValueLabel(const std::string& label);
+
+private:
+    UsdAttribute _attr;
+};
+
+PXR_NAMESPACE_CLOSE_SCOPE
+
+#endif

pxr/usd/usdUI/module.cpp

@@ -11,6 +11,11 @@ PXR_NAMESPACE_USING_DIRECTIVE
 
 TF_WRAP_MODULE
 {
+    TF_WRAP(UsdUIObjectHints);
+    TF_WRAP(UsdUIPrimHints);
+    TF_WRAP(UsdUIPropertyHints);
+    TF_WRAP(UsdUIAttributeHints);
+
     // Generated Schema classes.  Do not remove or edit the following line.
     #include "generatedSchema.module.h"
 }

pxr/usd/usdUI/objectHints.cpp

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 Pixar
+//
+// Licensed under the terms set forth in the LICENSE.txt file available at
+// https://openusd.org/license.
+//
+
+#include "pxr/usd/usdUI/objectHints.h"
+#include "pxr/base/tf/stringUtils.h"
+
+PXR_NAMESPACE_OPEN_SCOPE
+
+TF_DEFINE_PUBLIC_TOKENS(UsdUIHintKeys, USDUI_HINT_KEYS);
+
+UsdUIObjectHints::UsdUIObjectHints() = default;
+
+UsdUIObjectHints::UsdUIObjectHints(const UsdObject& obj)
+    : _obj(obj)
+{
+}
+
+std::string
+UsdUIObjectHints::GetDisplayName() const
+{
+    if (!_obj) {
+        return {};
+    }
+
+    std::string name;
+    if (_obj.GetMetadataByDictKey(
+            UsdUIHintKeys->UIHints,
+            UsdUIHintKeys->DisplayName,
+            &name)) {
+        return name;
+    }
+
+    // XXX: Fall back to legacy field
+    return _obj.GetDisplayName();
+}
+
+bool
+UsdUIObjectHints::SetDisplayName(const std::string& name)
+{
+    if (!_obj) {
+        TF_CODING_ERROR("Invalid object");
+        return false;
+    }
+
+    return _obj.SetMetadataByDictKey(
+        UsdUIHintKeys->UIHints,
+        UsdUIHintKeys->DisplayName,
+        name);
+}
+
+bool
+UsdUIObjectHints::GetHidden() const
+{
+    if (!_obj) {
+        return false;
+    }
+
+    bool hidden = false;
+    if (_obj.GetMetadataByDictKey(
+            UsdUIHintKeys->UIHints,
+            UsdUIHintKeys->Hidden,
+            &hidden)) {
+        return hidden;
+    }
+
+    // XXX: Fall back to legacy field
+    return _obj.IsHidden();
+}
+
+bool
+UsdUIObjectHints::SetHidden(bool hidden)
+{
+    if (!_obj) {
+        TF_CODING_ERROR("Invalid object");
+        return false;
+    }
+
+    return _obj.SetMetadataByDictKey(
+        UsdUIHintKeys->UIHints,
+        UsdUIHintKeys->Hidden,
+        hidden);
+}
+
+/* static */
+TfToken
+UsdUIObjectHints::_MakeKeyPath(
+    const TfToken& key1,
+    const TfToken& key2)
+{
+    return TfToken(
+        TfStringPrintf("%s%c%s",
+                       key1.GetText(),
+                       UsdObject::GetNamespaceDelimiter(),
+                       key2.GetText()));
+}
+
+PXR_NAMESPACE_CLOSE_SCOPE