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

8 files changed, 186 insertions, 1 deletions

diff --git a/source/blender/makesrna/RNA_access.h b/source/blender/makesrna/RNA_access.h
index f0a60929431..4267ce47d81 100644
--- a/source/blender/makesrna/RNA_access.h
+++ b/source/blender/makesrna/RNA_access.h
@@ -358,6 +358,21 @@ char *RNA_property_string_get_alloc(
     PointerRNA *ptr, PropertyRNA *prop, char *fixedbuf, int fixedlen, int *r_len);
 void RNA_property_string_set(PointerRNA *ptr, PropertyRNA *prop, const char *value);
 void RNA_property_string_set_bytes(PointerRNA *ptr, PropertyRNA *prop, const char *value, int len);
+
+eStringPropertySearchFlag RNA_property_string_search_flag(PropertyRNA *prop);
+/**
+ * Search candidates for string `prop` by calling `visit_fn` with each string.
+ * Typically these strings are collected in `visit_user_data` in a format defined by the caller.
+ *
+ * See #PropStringSearchFunc for details.
+ */
+void RNA_property_string_search(const struct bContext *C,
+                                PointerRNA *ptr,
+                                PropertyRNA *prop,
+                                const char *edit_text,
+                                StringPropertySearchVisitFunc visit_fn,
+                                void *visit_user_data);
+
 /**
  * \return the length without `\0` terminator.
  */
diff --git a/source/blender/makesrna/RNA_define.h b/source/blender/makesrna/RNA_define.h
index 13a5ec66a16..0389d1b3b16 100644
--- a/source/blender/makesrna/RNA_define.h
+++ b/source/blender/makesrna/RNA_define.h
@@ -446,6 +446,9 @@ void RNA_def_property_string_funcs(PropertyRNA *prop,
                                    const char *get,
                                    const char *length,
                                    const char *set);
+void RNA_def_property_string_search_func(PropertyRNA *prop,
+                                         const char *search,
+                                         eStringPropertySearchFlag search_flag);
 void RNA_def_property_pointer_funcs(
     PropertyRNA *prop, const char *get, const char *set, const char *type_fn, const char *poll);
 void RNA_def_property_collection_funcs(PropertyRNA *prop,
@@ -490,6 +493,9 @@ void RNA_def_property_string_funcs_runtime(PropertyRNA *prop,
                                            StringPropertyGetFunc getfunc,
                                            StringPropertyLengthFunc lengthfunc,
                                            StringPropertySetFunc setfunc);
+void RNA_def_property_string_search_func_runtime(PropertyRNA *prop,
+                                                 StringPropertySearchFunc search_fn,
+                                                 eStringPropertySearchFlag search_flag);
 
 void RNA_def_property_translation_context(PropertyRNA *prop, const char *context);
 
diff --git a/source/blender/makesrna/RNA_types.h b/source/blender/makesrna/RNA_types.h
index 3ebcae5f947..75b514cdb13 100644
--- a/source/blender/makesrna/RNA_types.h
+++ b/source/blender/makesrna/RNA_types.h
@@ -515,6 +515,55 @@ typedef int (*StringPropertyLengthFunc)(struct PointerRNA *ptr, struct PropertyR
 typedef void (*StringPropertySetFunc)(struct PointerRNA *ptr,
                                       struct PropertyRNA *prop,
                                       const char *value);
+
+typedef struct StringPropertySearchVisitParams {
+  /** Text being searched for (never NULL). */
+  const char *text;
+  /** Additional information to display (optional, may be NULL). */
+  const char *info;
+} StringPropertySearchVisitParams;
+
+typedef enum eStringPropertySearchFlag {
+  /**
+   * Used so the result of #RNA_property_string_search_flag can be used to check
+   * if search is supported.
+   */
+  PROP_STRING_SEARCH_SUPPORTED = (1 << 0),
+  /** Items resulting from  the search must be sorted. */
+  PROP_STRING_SEARCH_SORT = (1 << 1),
+  /**
+   * Allow members besides the ones listed to be entered.
+   *
+   * \warning disabling this options causes the search callback to run on redraw and should
+   * only be enabled this doesn't cause performance issues.
+   */
+  PROP_STRING_SEARCH_SUGGESTION = (1 << 2),
+} eStringPropertySearchFlag;
+
+/**
+ * Visit string search candidates, `text` may be freed once this callback has finished,
+ * so references to it should not be held.
+ */
+typedef void (*StringPropertySearchVisitFunc)(void *visit_user_data,
+                                              const StringPropertySearchVisitParams *params);
+/**
+ * \param C: context, may be NULL (in this case all available items should be shown).
+ * \param ptr: RNA pointer.
+ * \param prop: RNA property. This must have it's #StringPropertyRNA.search callback set,
+ * to check this use `RNA_property_string_search_flag(prop) & PROP_STRING_SEARCH_SUPPORTED`.
+ * \param edit_text: Optionally use the string being edited by the user as a basis
+ * for the search results (auto-complete Python attributes for e.g.).
+ * \param visit_fn: This function is called with every search candidate and is typically
+ * responsible for storing the search results.
+ * \param visit_user_data: Caller defined data, passed to `visit_fn`.
+ */
+typedef void (*StringPropertySearchFunc)(const struct bContext *C,
+                                         struct PointerRNA *ptr,
+                                         struct PropertyRNA *prop,
+                                         const char *edit_text,
+                                         StringPropertySearchVisitFunc visit_fn,
+                                         void *visit_user_data);
+
 typedef int (*EnumPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop);
 typedef void (*EnumPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int value);
 /* same as PropEnumItemFunc */
diff --git a/source/blender/makesrna/intern/makesrna.c b/source/blender/makesrna/intern/makesrna.c
index c3ca57b38bf..400944d60d4 100644
--- a/source/blender/makesrna/intern/makesrna.c
+++ b/source/blender/makesrna/intern/makesrna.c
@@ -1039,6 +1039,38 @@ static void rna_clamp_value(FILE *f, PropertyRNA *prop, int array)
   }
 }
 
+static char *rna_def_property_search_func(FILE *f,
+                                          StructRNA *srna,
+                                          PropertyRNA *prop,
+                                          PropertyDefRNA *UNUSED(dp),
+                                          const char *manualfunc)
+{
+  char *func;
+
+  if (prop->flag & PROP_IDPROPERTY && manualfunc == NULL) {
+    return NULL;
+  }
+  if (!manualfunc) {
+    return NULL;
+  }
+
+  func = rna_alloc_function_name(srna->identifier, rna_safe_id(prop->identifier), "search");
+
+  fprintf(f,
+          "void %s("
+          "const bContext *C, "
+          "PointerRNA *ptr, "
+          "PropertyRNA *prop, "
+          "const char *edit_text, "
+          "StringPropertySearchVisitFunc visit_fn, "
+          "void *visit_user_data)\n",
+          func);
+  fprintf(f, "{\n");
+  fprintf(f, "\n    %s(C, ptr, prop, edit_text, visit_fn, visit_user_data);\n", manualfunc);
+  fprintf(f, "}\n\n");
+  return func;
+}
+
 static char *rna_def_property_set_func(
     FILE *f, StructRNA *srna, PropertyRNA *prop, PropertyDefRNA *dp, const char *manualfunc)
 {
@@ -1895,6 +1927,8 @@ static void rna_def_property_funcs(FILE *f, StructRNA *srna, PropertyDefRNA *dp)
       sprop->length = (void *)rna_def_property_length_func(
           f, srna, prop, dp, (const char *)sprop->length);
       sprop->set = (void *)rna_def_property_set_func(f, srna, prop, dp, (const char *)sprop->set);
+      sprop->search = (void *)rna_def_property_search_func(
+          f, srna, prop, dp, (const char *)sprop->search);
       break;
     }
     case PROP_POINTER: {
@@ -4081,13 +4115,15 @@ static void rna_generate_property(FILE *f, StructRNA *srna, const char *nest, Pr
     case PROP_STRING: {
       StringPropertyRNA *sprop = (StringPropertyRNA *)prop;
       fprintf(f,
-              "\t%s, %s, %s, %s, %s, %s, %d, ",
+              "\t%s, %s, %s, %s, %s, %s, %s, %d, %d, ",
               rna_function_string(sprop->get),
               rna_function_string(sprop->length),
               rna_function_string(sprop->set),
               rna_function_string(sprop->get_ex),
               rna_function_string(sprop->length_ex),
               rna_function_string(sprop->set_ex),
+              rna_function_string(sprop->search),
+              (int)sprop->search_flag,
               sprop->maxlength);
       rna_print_c_string(f, sprop->defaultvalue);
       fprintf(f, "\n");
diff --git a/source/blender/makesrna/intern/rna_access.c b/source/blender/makesrna/intern/rna_access.c
index ccb7e1c69bc..c8cb0b7ffb8 100644
--- a/source/blender/makesrna/intern/rna_access.c
+++ b/source/blender/makesrna/intern/rna_access.c
@@ -3369,6 +3369,34 @@ int RNA_property_string_default_length(PointerRNA *UNUSED(ptr), PropertyRNA *pro
   return strlen(sprop->defaultvalue);
 }
 
+eStringPropertySearchFlag RNA_property_string_search_flag(PropertyRNA *prop)
+{
+  StringPropertyRNA *sprop = (StringPropertyRNA *)rna_ensure_property(prop);
+  if (prop->magic != RNA_MAGIC) {
+    return false;
+  }
+  BLI_assert(RNA_property_type(prop) == PROP_STRING);
+  if (sprop->search) {
+    BLI_assert(sprop->search_flag & PROP_STRING_SEARCH_SUPPORTED);
+  }
+  else {
+    BLI_assert(sprop->search_flag == 0);
+  }
+  return sprop->search_flag;
+}
+
+void RNA_property_string_search(const bContext *C,
+                                PointerRNA *ptr,
+                                PropertyRNA *prop,
+                                const char *edit_text,
+                                StringPropertySearchVisitFunc visit_fn,
+                                void *visit_user_data)
+{
+  BLI_assert(RNA_property_string_search_flag(prop) & PROP_STRING_SEARCH_SUPPORTED);
+  StringPropertyRNA *sprop = (StringPropertyRNA *)rna_ensure_property(prop);
+  sprop->search(C, ptr, prop, edit_text, visit_fn, visit_user_data);
+}
+
 int RNA_property_enum_get(PointerRNA *ptr, PropertyRNA *prop)
 {
   EnumPropertyRNA *eprop = (EnumPropertyRNA *)prop;
diff --git a/source/blender/makesrna/intern/rna_define.c b/source/blender/makesrna/intern/rna_define.c
index 1e950b883ab..dfb551fcb05 100644
--- a/source/blender/makesrna/intern/rna_define.c
+++ b/source/blender/makesrna/intern/rna_define.c
@@ -3316,6 +3316,33 @@ void RNA_def_property_string_funcs(PropertyRNA *prop,
   }
 }
 
+void RNA_def_property_string_search_func(PropertyRNA *prop,
+                                         const char *search,
+                                         const eStringPropertySearchFlag search_flag)
+{
+  StructRNA *srna = DefRNA.laststruct;
+
+  if (!DefRNA.preprocess) {
+    CLOG_ERROR(&LOG, "only during preprocessing.");
+    return;
+  }
+
+  switch (prop->type) {
+    case PROP_STRING: {
+      StringPropertyRNA *sprop = (StringPropertyRNA *)prop;
+      sprop->search = (StringPropertySearchFunc)search;
+      if (search != NULL) {
+        sprop->search_flag = search_flag | PROP_STRING_SEARCH_SUPPORTED;
+      }
+      break;
+    }
+    default:
+      CLOG_ERROR(&LOG, "\"%s.%s\", type is not string.", srna->identifier, prop->identifier);
+      DefRNA.error = true;
+      break;
+  }
+}
+
 void RNA_def_property_string_funcs_runtime(PropertyRNA *prop,
                                            StringPropertyGetFunc getfunc,
                                            StringPropertyLengthFunc lengthfunc,
@@ -3343,6 +3370,18 @@ void RNA_def_property_string_funcs_runtime(PropertyRNA *prop,
   }
 }
 
+void RNA_def_property_string_search_func_runtime(PropertyRNA *prop,
+                                                 StringPropertySearchFunc search_fn,
+                                                 const eStringPropertySearchFlag search_flag)
+{
+  StringPropertyRNA *sprop = (StringPropertyRNA *)prop;
+
+  sprop->search = search_fn;
+  if (search_fn != NULL) {
+    sprop->search_flag = search_flag | PROP_STRING_SEARCH_SUPPORTED;
+  }
+}
+
 void RNA_def_property_pointer_funcs(
     PropertyRNA *prop, const char *get, const char *set, const char *type_fn, const char *poll)
 {
diff --git a/source/blender/makesrna/intern/rna_internal_types.h b/source/blender/makesrna/intern/rna_internal_types.h
index a5b719cf753..4f88959b5ba 100644
--- a/source/blender/makesrna/intern/rna_internal_types.h
+++ b/source/blender/makesrna/intern/rna_internal_types.h
@@ -440,6 +440,15 @@ typedef struct StringPropertyRNA {
   PropStringLengthFuncEx length_ex;
   PropStringSetFuncEx set_ex;
 
+  /**
+   * Optional callback to list candidates for a string.
+   * This is only for use as suggestions in UI, other values may be assigned.
+   *
+   * \note The callback type is public, hence the difference in naming convention.
+   */
+  StringPropertySearchFunc search;
+  eStringPropertySearchFlag search_flag;
+
   int maxlength; /* includes string terminator! */
 
   const char *defaultvalue;
diff --git a/source/blender/makesrna/intern/rna_wm.c b/source/blender/makesrna/intern/rna_wm.c
index ac1b7e53a9b..c80d0e2da39 100644
--- a/source/blender/makesrna/intern/rna_wm.c
+++ b/source/blender/makesrna/intern/rna_wm.c
@@ -2599,6 +2599,9 @@ static void rna_def_keyconfig(BlenderRNA *brna)
                                 "rna_wmKeyMapItem_idname_get",
                                 "rna_wmKeyMapItem_idname_length",
                                 "rna_wmKeyMapItem_idname_set");
+  RNA_def_property_string_search_func(prop,
+                                      "WM_operatortype_idname_visit_for_search",
+                                      PROP_STRING_SEARCH_SORT | PROP_STRING_SEARCH_SUGGESTION);
   RNA_def_struct_name_property(srna, prop);
   RNA_def_property_update(prop, 0, "rna_KeyMapItem_update");