Commit: 97597ed6002211d55565d2a281da3c3fc1098ebb
Author: Bastien Montagne
Date:   Fri Feb 9 12:04:29 2018 +0100
Branches: master
https://developer.blender.org/rB97597ed6002211d55565d2a281da3c3fc1098ebb

Doc: attempt to document RNA's FunctionFlag.

Tired of searching through code to find which is what, and how to use it
in the C callback, everytime I need anot-so-common option...

===================================================================

M       source/blender/makesrna/RNA_types.h

===================================================================

diff --git a/source/blender/makesrna/RNA_types.h 
b/source/blender/makesrna/RNA_types.h
index ce2ca01ccfe..705d3914a52 100644
--- a/source/blender/makesrna/RNA_types.h
+++ b/source/blender/makesrna/RNA_types.h
@@ -398,22 +398,46 @@ typedef struct ParameterDynAlloc {
 /* Function */
 
 typedef enum FunctionFlag {
-       FUNC_NO_SELF           = (1 << 0), /* for static functions */
-       FUNC_USE_SELF_TYPE     = (1 << 1), /* for class methods, only used when 
FUNC_NO_SELF is set */
+       /***** Options affecting callback signature. *****/
+       /* Those add additionnal parameters at the beginning of the C callback, 
like that:
+        *     rna_my_func([ID *_selfid],
+        *                 [<DNA_STRUCT> *self|StructRNA *type],
+        *                 [Main *bmain],
+        *                 [bContext *C],
+        *                 [ReportList *reports],
+        *                 <other RNA-defined parameters>);
+        */
+       /* Pass ID owning 'self' data (i.e. ptr->id.data, might be same as self 
in case data is an ID...). */
+       FUNC_USE_SELF_ID       = (1 << 11),
+
+       /* Do not pass the object (DNA struct pointer) from which it is called, 
used to define static or class functions. */
+       FUNC_NO_SELF           = (1 << 0),
+       /* Pass RNA type, used to define class functions, only valid when 
FUNC_NO_SELF is set. */
+       FUNC_USE_SELF_TYPE     = (1 << 1),
+
+       /* Pass Main, bContext and/or ReportList. */
        FUNC_USE_MAIN          = (1 << 2),
        FUNC_USE_CONTEXT       = (1 << 3),
        FUNC_USE_REPORTS       = (1 << 4),
-       FUNC_USE_SELF_ID       = (1 << 11),
-       FUNC_ALLOW_WRITE       = (1 << 12),
 
-       /* registering */
+
+       /***** Registering of python subclasses. *****/
+       /* This function is part of the registerable class' interface, and can 
be implemented/redefined in python. */
        FUNC_REGISTER          = (1 << 5),
+       /* Subclasses can choose not to implement this function. */
        FUNC_REGISTER_OPTIONAL = FUNC_REGISTER | (1 << 6),
+       /* If not set, the python function implementing this call is not 
allowed to write into data-blocks.
+        * Except for WindowManager and Screen currently, see 
rna_id_write_error() in bpy_rna.c */
+       FUNC_ALLOW_WRITE       = (1 << 12),
 
-       /* internal flags */
+       /***** Internal flags. *****/
+       /* UNUSED CURRENTLY? ??? */
        FUNC_BUILTIN           = (1 << 7),
+       /* UNUSED CURRENTLY. ??? */
        FUNC_EXPORT            = (1 << 8),
+       /* Function has been defined at runtime, not statically in RNA source 
code. */
        FUNC_RUNTIME           = (1 << 9),
+       /* UNUSED CURRENTLY? Function owns its identifier and description 
strings, and has to free them when deleted. */
        FUNC_FREE_POINTERS     = (1 << 10),
 } FunctionFlag;

_______________________________________________
Bf-blender-cvs mailing list
Bf-blender-cvs@blender.org
https://lists.blender.org/mailman/listinfo/bf-blender-cvs

Reply via email to