UI support for showing candidates for string properties

Currently strings are used for cases where a list of identifiers would
be useful to show.

Add support for string properties to reference a callback to populate
candidates to show when editing a string. The user isn't prevented from
typing in text not found in this list, it's just useful as a reference.

Support for expanding the following strings has been added:

- Operator, menu & panel identifiers in the keymap editor.
- WM operators that reference data-paths expand using the
  Python-consoles auto-complete functionality.
- Names of keying sets for insert/delete keyframe operators.

Details:

- `bpy.props.StringProperty` takes an option `search` callback.

- A new string callback has been added, set via
  `RNA_def_property_string_search_func` or
  `RNA_def_property_string_search_func_runtime`.

- Addresses usability issue highlighted by T89560,
  where setting keying set identifiers as strings isn't practical.

- Showing additional right-aligned text in the search results is
  supported but disabled by default as the text is too cramped in most
  string search popups where the feature would make sense. It could be
  enabled as part of other layout tweaks.

Reviewed By: brecht

Ref D14986

5 files changed, 231 insertions, 57 deletions

diff --git a/source/blender/editors/animation/keyframing.c b/source/blender/editors/animation/keyframing.c
index 14a3b958ea6..941125b9ad5 100644
--- a/source/blender/editors/animation/keyframing.c
+++ b/source/blender/editors/animation/keyframing.c
@@ -2051,6 +2051,8 @@ void ANIM_OT_keyframe_insert_by_name(wmOperatorType *ot)
   /* keyingset to use (idname) */
   prop = RNA_def_string(
       ot->srna, "type", NULL, MAX_ID_NAME - 2, "Keying Set", "The Keying Set to use");
+  RNA_def_property_string_search_func_runtime(
+      prop, ANIM_keyingset_visit_for_search_no_poll, PROP_STRING_SEARCH_SUGGESTION);
   RNA_def_property_flag(prop, PROP_HIDDEN);
   ot->prop = prop;
 }
@@ -2246,6 +2248,8 @@ void ANIM_OT_keyframe_delete_by_name(wmOperatorType *ot)
   /* keyingset to use (idname) */
   prop = RNA_def_string(
       ot->srna, "type", NULL, MAX_ID_NAME - 2, "Keying Set", "The Keying Set to use");
+  RNA_def_property_string_search_func_runtime(
+      prop, ANIM_keyingset_visit_for_search_no_poll, PROP_STRING_SEARCH_SUGGESTION);
   RNA_def_property_flag(prop, PROP_HIDDEN);
   ot->prop = prop;
 }
diff --git a/source/blender/editors/animation/keyingsets.c b/source/blender/editors/animation/keyingsets.c
index 6fcdd21bad8..97b81277008 100644
--- a/source/blender/editors/animation/keyingsets.c
+++ b/source/blender/editors/animation/keyingsets.c
@@ -708,6 +708,72 @@ KeyingSet *ANIM_get_keyingset_for_autokeying(const Scene *scene, const char *tra
   return ANIM_builtin_keyingset_get_named(NULL, transformKSName);
 }
 
+static void anim_keyingset_visit_for_search_impl(const bContext *C,
+                                                 StringPropertySearchVisitFunc visit_fn,
+                                                 void *visit_user_data,
+                                                 const bool use_poll)
+{
+  /* Poll requires context.  */
+  if (use_poll && (C == NULL)) {
+    return;
+  }
+
+  Scene *scene = C ? CTX_data_scene(C) : NULL;
+  KeyingSet *ks;
+
+  /* Active Keying Set. */
+  if (!use_poll || (scene && scene->active_keyingset)) {
+    StringPropertySearchVisitParams visit_params = {NULL};
+    visit_params.text = "__ACTIVE__";
+    visit_params.info = "Active Keying Set";
+    visit_fn(visit_user_data, &visit_params);
+  }
+
+  /* User-defined Keying Sets. */
+  if (scene && scene->keyingsets.first) {
+    for (ks = scene->keyingsets.first; ks; ks = ks->next) {
+      if (use_poll && !ANIM_keyingset_context_ok_poll((bContext *)C, ks)) {
+        continue;
+      }
+      StringPropertySearchVisitParams visit_params = {NULL};
+      visit_params.text = ks->idname;
+      visit_params.info = ks->name;
+      visit_fn(visit_user_data, &visit_params);
+    }
+  }
+
+  /* Builtin Keying Sets. */
+  for (ks = builtin_keyingsets.first; ks; ks = ks->next) {
+    if (use_poll && !ANIM_keyingset_context_ok_poll((bContext *)C, ks)) {
+      continue;
+    }
+    StringPropertySearchVisitParams visit_params = {NULL};
+    visit_params.text = ks->idname;
+    visit_params.info = ks->name;
+    visit_fn(visit_user_data, &visit_params);
+  }
+}
+
+void ANIM_keyingset_visit_for_search(const bContext *C,
+                                     PointerRNA *UNUSED(ptr),
+                                     PropertyRNA *UNUSED(prop),
+                                     const char *UNUSED(edit_text),
+                                     StringPropertySearchVisitFunc visit_fn,
+                                     void *visit_user_data)
+{
+  anim_keyingset_visit_for_search_impl(C, visit_fn, visit_user_data, false);
+}
+
+void ANIM_keyingset_visit_for_search_no_poll(const bContext *C,
+                                             PointerRNA *UNUSED(ptr),
+                                             PropertyRNA *UNUSED(prop),
+                                             const char *UNUSED(edit_text),
+                                             StringPropertySearchVisitFunc visit_fn,
+                                             void *visit_user_data)
+{
+  anim_keyingset_visit_for_search_impl(C, visit_fn, visit_user_data, true);
+}
+
 /* Menu of All Keying Sets ----------------------------- */
 
 const EnumPropertyItem *ANIM_keying_sets_enum_itemf(bContext *C,
diff --git a/source/blender/editors/include/ED_keyframing.h b/source/blender/editors/include/ED_keyframing.h
index 6a730225da9..8c0147612fb 100644
--- a/source/blender/editors/include/ED_keyframing.h
+++ b/source/blender/editors/include/ED_keyframing.h
@@ -351,6 +351,19 @@ int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
 struct KeyingSet *ANIM_get_keyingset_for_autokeying(const struct Scene *scene,
                                                     const char *transformKSName);
 
+void ANIM_keyingset_visit_for_search(const struct bContext *C,
+                                     struct PointerRNA *ptr,
+                                     struct PropertyRNA *prop,
+                                     const char *edit_text,
+                                     StringPropertySearchVisitFunc visit_fn,
+                                     void *visit_user_data);
+
+void ANIM_keyingset_visit_for_search_no_poll(const struct bContext *C,
+                                             struct PointerRNA *ptr,
+                                             struct PropertyRNA *prop,
+                                             const char *edit_text,
+                                             StringPropertySearchVisitFunc visit_fn,
+                                             void *visit_user_data);
 /**
  * Dynamically populate an enum of Keying Sets.
  */
diff --git a/source/blender/editors/interface/interface_layout.c b/source/blender/editors/interface/interface_layout.c
index 933d7efb4d6..3465373c85d 100644
--- a/source/blender/editors/interface/interface_layout.c
+++ b/source/blender/editors/interface/interface_layout.c
@@ -2338,7 +2338,14 @@ void uiItemFullR(uiLayout *layout,
   /* property with separate label */
   else if (ELEM(type, PROP_ENUM, PROP_STRING, PROP_POINTER)) {
     but = ui_item_with_label(layout, block, name, icon, ptr, prop, index, 0, 0, w, h, flag);
-    but = ui_but_add_search(but, ptr, prop, NULL, NULL, false);
+    bool results_are_suggestions = false;
+    if (type == PROP_STRING) {
+      const eStringPropertySearchFlag search_flag = RNA_property_string_search_flag(prop);
+      if (search_flag & PROP_STRING_SEARCH_SUGGESTION) {
+        results_are_suggestions = true;
+      }
+    }
+    but = ui_but_add_search(but, ptr, prop, NULL, NULL, results_are_suggestions);
 
     if (layout->redalert) {
       UI_but_flag_enable(but, UI_BUT_REDALERT);
@@ -2711,11 +2718,16 @@ uiBut *ui_but_add_search(uiBut *but,
                          PropertyRNA *prop,
                          PointerRNA *searchptr,
                          PropertyRNA *searchprop,
-                         bool results_are_suggestions)
+                         const bool results_are_suggestions)
 {
   /* for ID's we do automatic lookup */
+  bool has_search_fn = false;
+
   PointerRNA sptr;
   if (!searchprop) {
+    if (RNA_property_type(prop) == PROP_STRING) {
+      has_search_fn = (RNA_property_string_search_flag(prop) != 0);
+    }
     if (RNA_property_type(prop) == PROP_POINTER) {
       StructRNA *ptype = RNA_property_pointer_type(ptr, prop);
       search_id_collection(ptype, &sptr, &searchprop);
@@ -2724,14 +2736,18 @@ uiBut *ui_but_add_search(uiBut *but,
   }
 
   /* turn button into search button */
-  if (searchprop) {
+  if (has_search_fn || searchprop) {
     uiRNACollectionSearch *coll_search = MEM_mallocN(sizeof(*coll_search), __func__);
     uiButSearch *search_but;
 
     but = ui_but_change_type(but, UI_BTYPE_SEARCH_MENU);
     search_but = (uiButSearch *)but;
-    search_but->rnasearchpoin = *searchptr;
-    search_but->rnasearchprop = searchprop;
+
+    if (searchptr) {
+      search_but->rnasearchpoin = *searchptr;
+      search_but->rnasearchprop = searchprop;
+    }
+
     but->hardmax = MAX2(but->hardmax, 256.0f);
     but->drawflag |= UI_BUT_ICON_LEFT | UI_BUT_TEXT_LEFT;
     if (RNA_property_is_unlink(prop)) {
@@ -2740,8 +2756,17 @@ uiBut *ui_but_add_search(uiBut *but,
 
     coll_search->target_ptr = *ptr;
     coll_search->target_prop = prop;
-    coll_search->search_ptr = *searchptr;
-    coll_search->search_prop = searchprop;
+
+    if (searchptr) {
+      coll_search->search_ptr = *searchptr;
+      coll_search->search_prop = searchprop;
+    }
+    else {
+      /* Rely on `has_search_fn`. */
+      coll_search->search_ptr = PointerRNA_NULL;
+      coll_search->search_prop = NULL;
+    }
+
     coll_search->search_but = but;
     coll_search->butstore_block = but->block;
     coll_search->butstore = UI_butstore_create(coll_search->butstore_block);
diff --git a/source/blender/editors/interface/interface_utils.cc b/source/blender/editors/interface/interface_utils.cc
index 993ccdf92f7..b7ca2d9aa11 100644
--- a/source/blender/editors/interface/interface_utils.cc
+++ b/source/blender/editors/interface/interface_utils.cc
@@ -24,6 +24,7 @@
 #include "BLT_translation.h"
 
 #include "BKE_context.h"
+#include "BKE_global.h"
 #include "BKE_lib_id.h"
 #include "BKE_report.h"
 
@@ -516,71 +517,136 @@ void ui_rna_collection_search_update_fn(
 
   StringSearch *search = skip_filter ? nullptr : BLI_string_search_new();
 
-  /* build a temporary list of relevant items first */
-  int item_index = 0;
-  RNA_PROP_BEGIN (&data->search_ptr, itemptr, data->search_prop) {
+  if (data->search_prop != nullptr) {
+    /* build a temporary list of relevant items first */
+    int item_index = 0;
+    RNA_PROP_BEGIN (&data->search_ptr, itemptr, data->search_prop) {
 
-    if (flag & PROP_ID_SELF_CHECK) {
-      if (itemptr.data == data->target_ptr.owner_id) {
-        continue;
+      if (flag & PROP_ID_SELF_CHECK) {
+        if (itemptr.data == data->target_ptr.owner_id) {
+          continue;
+        }
       }
-    }
 
-    /* use filter */
-    if (is_ptr_target) {
-      if (RNA_property_pointer_poll(&data->target_ptr, data->target_prop, &itemptr) == 0) {
-        continue;
+      /* use filter */
+      if (is_ptr_target) {
+        if (RNA_property_pointer_poll(&data->target_ptr, data->target_prop, &itemptr) == 0) {
+          continue;
+        }
       }
-    }
 
-    int name_prefix_offset = 0;
-    int iconid = ICON_NONE;
-    bool has_sep_char = false;
-    const bool is_id = itemptr.type && RNA_struct_is_ID(itemptr.type);
+      int name_prefix_offset = 0;
+      int iconid = ICON_NONE;
+      bool has_sep_char = false;
+      const bool is_id = itemptr.type && RNA_struct_is_ID(itemptr.type);
 
-    if (is_id) {
-      iconid = ui_id_icon_get(C, static_cast<ID *>(itemptr.data), false);
-      if (!ELEM(iconid, 0, ICON_BLANK1)) {
-        has_id_icon = true;
-      }
+      if (is_id) {
+        iconid = ui_id_icon_get(C, static_cast<ID *>(itemptr.data), false);
+        if (!ELEM(iconid, 0, ICON_BLANK1)) {
+          has_id_icon = true;
+        }
 
-      if (requires_exact_data_name) {
-        name = RNA_struct_name_get_alloc(&itemptr, name_buf, sizeof(name_buf), nullptr);
+        if (requires_exact_data_name) {
+          name = RNA_struct_name_get_alloc(&itemptr, name_buf, sizeof(name_buf), nullptr);
+        }
+        else {
+          const ID *id = static_cast<ID *>(itemptr.data);
+          BKE_id_full_name_ui_prefix_get(name_buf, id, true, UI_SEP_CHAR, &name_prefix_offset);
+          BLI_STATIC_ASSERT(sizeof(name_buf) >= MAX_ID_FULL_NAME_UI,
+                            "Name string buffer should be big enough to hold full UI ID name");
+          name = name_buf;
+          has_sep_char = ID_IS_LINKED(id);
+        }
       }
       else {
-        const ID *id = static_cast<ID *>(itemptr.data);
-        BKE_id_full_name_ui_prefix_get(name_buf, id, true, UI_SEP_CHAR, &name_prefix_offset);
-        BLI_STATIC_ASSERT(sizeof(name_buf) >= MAX_ID_FULL_NAME_UI,
-                          "Name string buffer should be big enough to hold full UI ID name");
-        name = name_buf;
-        has_sep_char = ID_IS_LINKED(id);
+        name = RNA_struct_name_get_alloc(&itemptr, name_buf, sizeof(name_buf), nullptr);
       }
-    }
-    else {
-      name = RNA_struct_name_get_alloc(&itemptr, name_buf, sizeof(name_buf), nullptr);
-    }
 
-    if (name) {
-      CollItemSearch *cis = MEM_cnew<CollItemSearch>(__func__);
-      cis->data = itemptr.data;
-      cis->name = BLI_strdup(name);
-      cis->index = item_index;
-      cis->iconid = iconid;
-      cis->is_id = is_id;
-      cis->name_prefix_offset = name_prefix_offset;
-      cis->has_sep_char = has_sep_char;
-      if (!skip_filter) {
-        BLI_string_search_add(search, name, cis, 0);
+      if (name) {
+        CollItemSearch *cis = MEM_cnew<CollItemSearch>(__func__);
+        cis->data = itemptr.data;
+        cis->name = BLI_strdup(name);
+        cis->index = item_index;
+        cis->iconid = iconid;
+        cis->is_id = is_id;
+        cis->name_prefix_offset = name_prefix_offset;
+        cis->has_sep_char = has_sep_char;
+        if (!skip_filter) {
+          BLI_string_search_add(search, name, cis, 0);
+        }
+        BLI_addtail(items_list, cis);
+        if (name != name_buf) {
+          MEM_freeN(name);
+        }
       }
-      BLI_addtail(items_list, cis);
-      if (name != name_buf) {
-        MEM_freeN(name);
+
+      item_index++;
+    }
+    RNA_PROP_END;
+  }
+  else {
+    BLI_assert(RNA_property_type(data->target_prop) == PROP_STRING);
+    const eStringPropertySearchFlag search_flag = RNA_property_string_search_flag(
+        data->target_prop);
+    BLI_assert(search_flag & PROP_STRING_SEARCH_SUPPORTED);
+
+    struct SearchVisitUserData {
+      StringSearch *search;
+      bool skip_filter;
+      int item_index;
+      ListBase *items_list;
+      const char *func_id;
+    } user_data = {nullptr};
+
+    user_data.search = search;
+    user_data.skip_filter = skip_filter;
+    user_data.items_list = items_list;
+    user_data.func_id = __func__;
+
+    RNA_property_string_search(
+        C,
+        &data->target_ptr,
+        data->target_prop,
+        str,
+        [](void *user_data, const StringPropertySearchVisitParams *visit_params) {
+          const bool show_extra_info = (G.debug_value == 102);
+
+          SearchVisitUserData *search_data = (struct SearchVisitUserData *)user_data;
+          CollItemSearch *cis = MEM_cnew<CollItemSearch>(search_data->func_id);
+          cis->data = nullptr;
+          if (visit_params->info && show_extra_info) {
+            cis->name = BLI_sprintfN(
+                "%s" UI_SEP_CHAR_S "%s", visit_params->text, visit_params->info);
+          }
+          else {
+            cis->name = BLI_strdup(visit_params->text);
+          }
+          cis->index = search_data->item_index;
+          cis->iconid = ICON_NONE;
+          cis->is_id = false;
+          cis->name_prefix_offset = 0;
+          cis->has_sep_char = visit_params->info != nullptr;
+          if (!search_data->skip_filter) {
+            BLI_string_search_add(search_data->search, visit_params->text, cis, 0);
+          }
+          BLI_addtail(search_data->items_list, cis);
+          search_data->item_index++;
+        },
+        (void *)&user_data);
+
+    if (search_flag & PROP_STRING_SEARCH_SORT) {
+      BLI_listbase_sort(items_list, [](const void *a_, const void *b_) -> int {
+        const CollItemSearch *cis_a = (const CollItemSearch *)a_;
+        const CollItemSearch *cis_b = (const CollItemSearch *)b_;
+        return BLI_strcasecmp_natural(cis_a->name, cis_b->name);
+      });
+      int i = 0;
+      LISTBASE_FOREACH (CollItemSearch *, cis, items_list) {
+        cis->index = i;
+        i++;
       }
     }
-
-    item_index++;
   }
-  RNA_PROP_END;
 
   if (skip_filter) {
     LISTBASE_FOREACH (CollItemSearch *, cis, items_list) {