diff options
Diffstat (limited to 'source/blender/makesrna/RNA_access.h')
| -rw-r--r-- | source/blender/makesrna/RNA_access.h | 258 |
1 files changed, 251 insertions, 7 deletions
diff --git a/source/blender/makesrna/RNA_access.h b/source/blender/makesrna/RNA_access.h index 188f933dba5..7fa7405add1 100644 --- a/source/blender/makesrna/RNA_access.h +++ b/source/blender/makesrna/RNA_access.h @@ -801,6 +801,11 @@ PropertyRNA *RNA_struct_name_property(const StructRNA *type); const EnumPropertyItem *RNA_struct_property_tag_defines(const StructRNA *type); PropertyRNA *RNA_struct_iterator_property(StructRNA *type); StructRNA *RNA_struct_base(StructRNA *type); +/** + * Use to find the sub-type directly below a base-type. + * + * So if type were `RNA_SpotLight`, `RNA_struct_base_of(type, &RNA_ID)` would return `&RNA_Light`. + */ const StructRNA *RNA_struct_base_child_of(const StructRNA *type, const StructRNA *parent_type); bool RNA_struct_is_ID(const StructRNA *type); @@ -823,16 +828,32 @@ struct IDProperty *RNA_struct_idprops(PointerRNA *ptr, bool create); bool RNA_struct_idprops_check(StructRNA *srna); bool RNA_struct_idprops_register_check(const StructRNA *type); bool RNA_struct_idprops_datablock_allowed(const StructRNA *type); +/** + * Whether given type implies datablock usage by IDProperties. + * This is used to prevent classes allowed to have IDProperties, + * but not datablock ones, to indirectly use some + * (e.g. by assigning an IDP_GROUP containing some IDP_ID pointers...). + */ bool RNA_struct_idprops_contains_datablock(const StructRNA *type); +/** + * Remove an id-property. + */ bool RNA_struct_idprops_unset(PointerRNA *ptr, const char *identifier); PropertyRNA *RNA_struct_find_property(PointerRNA *ptr, const char *identifier); bool RNA_struct_contains_property(PointerRNA *ptr, PropertyRNA *prop_test); unsigned int RNA_struct_count_properties(StructRNA *srna); -/* lower level functions for access to type properties */ +/** + * Low level direct access to type->properties, + * note this ignores parent classes so should be used with care. + */ const struct ListBase *RNA_struct_type_properties(StructRNA *srna); PropertyRNA *RNA_struct_type_find_property_no_base(StructRNA *srna, const char *identifier); +/** + * \note #RNA_struct_find_property is a higher level alternative to this function + * which takes a #PointerRNA instead of a #StructRNA. + */ PropertyRNA *RNA_struct_type_find_property(StructRNA *srna, const char *identifier); FunctionRNA *RNA_struct_find_function(StructRNA *srna, const char *identifier); @@ -840,6 +861,9 @@ const struct ListBase *RNA_struct_type_functions(StructRNA *srna); char *RNA_struct_name_get_alloc(PointerRNA *ptr, char *fixedbuf, int fixedlen, int *r_len); +/** + * Use when registering structs with the #STRUCT_PUBLIC_NAMESPACE flag. + */ bool RNA_struct_available_or_report(struct ReportList *reports, const char *identifier); bool RNA_struct_bl_idname_ok_or_report(struct ReportList *reports, const char *identifier, @@ -861,17 +885,32 @@ PropertyUnit RNA_property_unit(PropertyRNA *prop); PropertyScaleType RNA_property_ui_scale(PropertyRNA *prop); int RNA_property_flag(PropertyRNA *prop); int RNA_property_override_flag(PropertyRNA *prop); +/** + * Get the tags set for \a prop as int bitfield. + * \note Doesn't perform any validity check on the set bits. #RNA_def_property_tags does this + * in debug builds (to avoid performance issues in non-debug builds), which should be + * the only way to set tags. Hence, at this point we assume the tag bitfield to be valid. + */ int RNA_property_tags(PropertyRNA *prop); bool RNA_property_builtin(PropertyRNA *prop); void *RNA_property_py_data_get(PropertyRNA *prop); int RNA_property_array_length(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_array_check(PropertyRNA *prop); +/** + * Return the size of Nth dimension. + */ int RNA_property_multi_array_length(PointerRNA *ptr, PropertyRNA *prop, int dimension); +/** + * Used by BPY to make an array from the python object. + */ int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[]); char RNA_property_array_item_char(PropertyRNA *prop, int index); int RNA_property_array_item_index(PropertyRNA *prop, char name); +/** + * \return the maximum length including the \0 terminator. '0' is used when there is no maximum. + */ int RNA_property_string_maxlength(PropertyRNA *prop); const char *RNA_property_ui_name(const PropertyRNA *prop); @@ -906,6 +945,10 @@ bool RNA_enum_name(const EnumPropertyItem *item, const int value, const char **r bool RNA_enum_description(const EnumPropertyItem *item, const int value, const char **description); int RNA_enum_from_value(const EnumPropertyItem *item, const int value); int RNA_enum_from_identifier(const EnumPropertyItem *item, const char *identifier); +/** + * Take care using this with translated enums, + * prefer #RNA_enum_from_identifier where possible. + */ int RNA_enum_from_name(const EnumPropertyItem *item, const char *name); unsigned int RNA_enum_items_count(const EnumPropertyItem *item); @@ -967,27 +1010,54 @@ StructRNA *RNA_property_pointer_type(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_pointer_poll(PointerRNA *ptr, PropertyRNA *prop, PointerRNA *value); bool RNA_property_editable(PointerRNA *ptr, PropertyRNA *prop); +/** + * Version of #RNA_property_editable that tries to return additional info in \a r_info + * that can be exposed in UI. + */ bool RNA_property_editable_info(PointerRNA *ptr, PropertyRNA *prop, const char **r_info); +/** + * Same as RNA_property_editable(), except this checks individual items in an array. + */ bool RNA_property_editable_index(PointerRNA *ptr, PropertyRNA *prop, int index); -/* without lib check, only checks the flag */ +/** + * Without lib check, only checks the flag. + */ bool RNA_property_editable_flag(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_animateable(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_animated(PointerRNA *ptr, PropertyRNA *prop); +/** + * \note Does not take into account editable status, this has to be checked separately + * (using #RNA_property_editable_flag() usually). + */ bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop); +/** + * Should only be used for custom properties. + */ bool RNA_property_overridable_library_set(PointerRNA *ptr, PropertyRNA *prop, const bool is_overridable); bool RNA_property_overridden(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_comparable(PointerRNA *ptr, PropertyRNA *prop); +/** + * This function is to check if its possible to create a valid path from the ID + * its slow so don't call in a loop. + */ bool RNA_property_path_from_ID_check(PointerRNA *ptr, PropertyRNA *prop); /* slow, use with care */ void RNA_property_update(struct bContext *C, PointerRNA *ptr, PropertyRNA *prop); +/** + * \param scene: may be NULL. + */ void RNA_property_update_main(struct Main *bmain, struct Scene *scene, PointerRNA *ptr, PropertyRNA *prop); +/** + * \note its possible this returns a false positive in the case of #PROP_CONTEXT_UPDATE + * but this isn't likely to be a performance problem. + */ bool RNA_property_update_check(struct PropertyRNA *prop); /* Property Data */ @@ -1031,15 +1101,28 @@ 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); +/** + * \return the length without `\0` terminator. + */ int RNA_property_string_length(PointerRNA *ptr, PropertyRNA *prop); void RNA_property_string_get_default(PropertyRNA *prop, char *value, int max_len); char *RNA_property_string_get_default_alloc( PointerRNA *ptr, PropertyRNA *prop, char *fixedbuf, int fixedlen, int *r_len); +/** + * \return the length without `\0` terminator. + */ int RNA_property_string_default_length(PointerRNA *ptr, PropertyRNA *prop); int RNA_property_enum_get(PointerRNA *ptr, PropertyRNA *prop); void RNA_property_enum_set(PointerRNA *ptr, PropertyRNA *prop, int value); int RNA_property_enum_get_default(PointerRNA *ptr, PropertyRNA *prop); +/** + * Get the value of the item that is \a step items away from \a from_value. + * + * \param from_value: Item value to start stepping from. + * \param step: Absolute value defines step size, sign defines direction. + * E.g to get the next item, pass 1, for the previous -1. + */ int RNA_property_enum_step( const struct bContext *C, PointerRNA *ptr, PropertyRNA *prop, int from_value, int step); @@ -1068,6 +1151,9 @@ int RNA_property_collection_lookup_string(PointerRNA *ptr, PointerRNA *r_ptr); int RNA_property_collection_lookup_string_index( PointerRNA *ptr, PropertyRNA *prop, const char *key, PointerRNA *r_ptr, int *r_index); +/** + * Zero return is an assignment error. + */ int RNA_property_collection_assign_int(PointerRNA *ptr, PropertyRNA *prop, const int key, @@ -1125,31 +1211,99 @@ char *RNA_path_append( char *RNA_path_back(const char *path); #endif -/* path_resolve() variants only ensure that a valid pointer (and optionally property) exist */ +/* RNA_path_resolve() variants only ensure that a valid pointer (and optionally property) exist. */ + +/** + * Resolve the given RNA Path to find the pointer and/or property + * indicated by fully resolving the path. + * + * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers, + * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr, + * and a NULL \a r_prop... + * + * \note Assumes all pointers provided are valid + * \return True if path can be resolved to a valid "pointer + property" OR "pointer only" + */ bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop); +/** + * Resolve the given RNA Path to find the pointer and/or property + array index + * indicated by fully resolving the path. + * + * \note Assumes all pointers provided are valid. + * \return True if path can be resolved to a valid "pointer + property" OR "pointer only" + */ bool RNA_path_resolve_full( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index); +/** + * A version of #RNA_path_resolve_full doesn't check the value of #PointerRNA.data. + * + * \note While it's correct to ignore the value of #PointerRNA.data + * most callers need to know if the resulting pointer was found and not null. + */ bool RNA_path_resolve_full_maybe_null( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index); -/* path_resolve_property() variants ensure that pointer + property both exist */ +/* RNA_path_resolve_property() variants ensure that pointer + property both exist. */ + +/** + * Resolve the given RNA Path to find both the pointer AND property + * indicated by fully resolving the path. + * + * This is a convenience method to avoid logic errors and ugly syntax. + * \note Assumes all pointers provided are valid + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop); +/** + * Resolve the given RNA Path to find the pointer AND property (as well as the array index) + * indicated by fully resolving the path. + * + * This is a convenience method to avoid logic errors and ugly syntax. + * \note Assumes all pointers provided are valid + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property_full( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index); -/* path_resolve_property_and_item_pointer() variants ensure that pointer + property both exist, +/* RNA_path_resolve_property_and_item_pointer() variants ensure that pointer + property both exist, * and resolve last Pointer value if possible (Pointer prop or item of a Collection prop). */ + +/** + * Resolve the given RNA Path to find both the pointer AND property + * indicated by fully resolving the path, and get the value of the Pointer property + * (or item of the collection). + * + * This is a convenience method to avoid logic errors and ugly syntax, + * it combines both \a RNA_path_resolve and #RNA_path_resolve_property in a single call. + * \note Assumes all pointers provided are valid. + * \param r_item_ptr: The final Pointer or Collection item value. + * You must check for its validity before use! + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property_and_item_pointer(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, PointerRNA *r_item_ptr); +/** + * Resolve the given RNA Path to find both the pointer AND property (as well as the array index) + * indicated by fully resolving the path, + * and get the value of the Pointer property (or item of the collection). + * + * This is a convenience method to avoid logic errors and ugly syntax, + * it combines both \a RNA_path_resolve_full and + * \a RNA_path_resolve_property_full in a single call. + * \note Assumes all pointers provided are valid. + * \param r_item_ptr: The final Pointer or Collection item value. + * You must check for its validity before use! + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property_and_item_pointer_full(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, @@ -1164,10 +1318,36 @@ struct PropertyElemRNA { PropertyRNA *prop; int index; }; +/** + * Resolve the given RNA Path into a linked list of #PropertyElemRNA's. + * + * To be used when complex operations over path are needed, like e.g. get relative paths, + * to avoid too much string operations. + * + * \return True if there was no error while resolving the path + * \note Assumes all pointers provided are valid + */ bool RNA_path_resolve_elements(PointerRNA *ptr, const char *path, struct ListBase *r_elements); +/** + * Find the path from the structure referenced by the pointer to the runtime RNA-defined + * #IDProperty object. + * + * \note Does *not* handle pure user-defined IDProperties (a.k.a. custom properties). + * + * \param ptr: Reference to the object owning the custom property storage. + * \param needle: Custom property object to find. + * \return Relative path or NULL. + */ char *RNA_path_from_struct_to_idproperty(PointerRNA *ptr, struct IDProperty *needle); +/** + * Find the actual ID pointer and path from it to the given ID. + * + * \param id: ID reference to search the global owner for. + * \param[out] r_path: Path from the real ID to the initial ID. + * \return The ID pointer, or NULL in case of failure. + */ struct ID *RNA_find_real_ID_and_path(struct Main *bmain, struct ID *id, const char **r_path); char *RNA_path_from_ID_to_struct(const PointerRNA *ptr); @@ -1175,6 +1355,11 @@ char *RNA_path_from_ID_to_struct(const PointerRNA *ptr); char *RNA_path_from_real_ID_to_struct(struct Main *bmain, PointerRNA *ptr, struct ID **r_real); char *RNA_path_from_ID_to_property(PointerRNA *ptr, PropertyRNA *prop); +/** + * \param index_dim: The dimension to show, 0 disables. 1 for 1d array, 2 for 2d. etc. + * \param index: The *flattened* index to use when \a `index_dim > 0`, + * this is expanded when used with multi-dimensional arrays. + */ char *RNA_path_from_ID_to_property_index(PointerRNA *ptr, PropertyRNA *prop, int index_dim, @@ -1187,19 +1372,43 @@ char *RNA_path_from_real_ID_to_property_index(struct Main *bmain, int index, struct ID **r_real_id); +/** + * \return the path to given ptr/prop from the closest ancestor of given type, + * if any (else return NULL). + */ char *RNA_path_resolve_from_type_to_property(struct PointerRNA *ptr, struct PropertyRNA *prop, const struct StructRNA *type); +/** + * Get the ID as a python representation, eg: + * bpy.data.foo["bar"] + */ char *RNA_path_full_ID_py(struct Main *bmain, struct ID *id); +/** + * Get the ID.struct as a python representation, eg: + * bpy.data.foo["bar"].some_struct + */ char *RNA_path_full_struct_py(struct Main *bmain, struct PointerRNA *ptr); +/** + * Get the ID.struct.property as a python representation, eg: + * bpy.data.foo["bar"].some_struct.some_prop[10] + */ char *RNA_path_full_property_py_ex( struct Main *bmain, PointerRNA *ptr, PropertyRNA *prop, int index, bool use_fallback); char *RNA_path_full_property_py(struct Main *bmain, struct PointerRNA *ptr, struct PropertyRNA *prop, int index); +/** + * Get the struct.property as a python representation, eg: + * some_struct.some_prop[10] + */ char *RNA_path_struct_property_py(struct PointerRNA *ptr, struct PropertyRNA *prop, int index); +/** + * Get the struct.property as a python representation, eg: + * some_prop[10] + */ char *RNA_path_property_py(const struct PointerRNA *ptr, struct PropertyRNA *prop, int index); /* Quick name based property access @@ -1314,24 +1523,38 @@ void RNA_collection_clear(PointerRNA *ptr, const char *name); } \ ((void)0) -/* check if the idproperty exists, for operators */ +/** + * Check if the #IDproperty exists, for operators. + */ bool RNA_property_is_set_ex(PointerRNA *ptr, PropertyRNA *prop, bool use_ghost); bool RNA_property_is_set(PointerRNA *ptr, PropertyRNA *prop); void RNA_property_unset(PointerRNA *ptr, PropertyRNA *prop); bool RNA_struct_property_is_set_ex(PointerRNA *ptr, const char *identifier, bool use_ghost); bool RNA_struct_property_is_set(PointerRNA *ptr, const char *identifier); bool RNA_property_is_idprop(const PropertyRNA *prop); +/** + * \note Mainly for the UI. + */ bool RNA_property_is_unlink(PropertyRNA *prop); void RNA_struct_property_unset(PointerRNA *ptr, const char *identifier); -/* python compatible string representation of this property, (must be freed!) */ +/** + * Python compatible string representation of this property, (must be freed!). + */ char *RNA_property_as_string( struct bContext *C, PointerRNA *ptr, PropertyRNA *prop, int index, int max_prop_length); +/** + * String representation of a property, Python compatible but can be used for display too. + * \param C: can be NULL. + */ char *RNA_pointer_as_string_id(struct bContext *C, PointerRNA *ptr); char *RNA_pointer_as_string(struct bContext *C, PointerRNA *ptr, PropertyRNA *prop_ptr, PointerRNA *ptr_prop); +/** + * \param C: can be NULL. + */ char *RNA_pointer_as_string_keywords_ex(struct bContext *C, PointerRNA *ptr, const bool as_function, @@ -1383,7 +1606,9 @@ void RNA_parameter_get(ParameterList *parms, PropertyRNA *parm, void **value); void RNA_parameter_get_lookup(ParameterList *parms, const char *identifier, void **value); void RNA_parameter_set(ParameterList *parms, PropertyRNA *parm, const void *value); void RNA_parameter_set_lookup(ParameterList *parms, const char *identifier, const void *value); + /* Only for PROP_DYNAMIC properties! */ + int RNA_parameter_dynamic_length_get(ParameterList *parms, PropertyRNA *parm); int RNA_parameter_dynamic_length_get_data(ParameterList *parms, PropertyRNA *parm, void *data); void RNA_parameter_dynamic_length_set(ParameterList *parms, PropertyRNA *parm, int length); @@ -1454,6 +1679,7 @@ StructRNA *ID_code_to_RNA_type(short idcode); # define RNA_warning(format, ...) _RNA_warning("%s: " format "\n", __FUNCTION__, __VA_ARGS__) #endif +/** Use to implement the #RNA_warning macro which includes `__func__` suffix. */ void _RNA_warning(const char *format, ...) ATTR_PRINTF_FORMAT(1, 2); /* Equals test. */ @@ -1520,6 +1746,16 @@ typedef enum eRNAOverrideStatus { RNA_OVERRIDE_STATUS_LOCKED = 1 << 3, } eRNAOverrideStatus; +/** + * Check whether reference and local overridden data match (are the same), + * with respect to given restrictive sets of properties. + * If requested, will generate needed new property overrides, and/or restore values from reference. + * + * \param r_report_flags: If given, + * will be set with flags matching actions taken by the function on \a ptr_local. + * + * \return True if _resulting_ \a ptr_local does match \a ptr_reference. + */ bool RNA_struct_override_matches(struct Main *bmain, struct PointerRNA *ptr_local, struct PointerRNA *ptr_reference, @@ -1529,6 +1765,10 @@ bool RNA_struct_override_matches(struct Main *bmain, const eRNAOverrideMatch flags, eRNAOverrideMatchResult *r_report_flags); +/** + * Store needed second operands into \a storage data-block + * for differential override operations. + */ bool RNA_struct_override_store(struct Main *bmain, struct PointerRNA *ptr_local, struct PointerRNA *ptr_reference, @@ -1544,6 +1784,10 @@ typedef enum eRNAOverrideApplyFlag { RNA_OVERRIDE_APPLY_FLAG_IGNORE_ID_POINTERS = 1 << 0, } eRNAOverrideApplyFlag; +/** + * Apply given \a override operations on \a ptr_dst, using \a ptr_src + * (and \a ptr_storage for differential ops) as source. + */ void RNA_struct_override_apply(struct Main *bmain, struct PointerRNA *ptr_dst, struct PointerRNA *ptr_src, |