[Bf-blender-cvs] [375ede0f3f] master: Comments: wmOperator.cancel & modal

[Campbell Barton]

Commit: 375ede0f3fdef936d5712968143e06c846c8d6d6
Author: Campbell Barton
Date:   Thu Mar 16 06:37:09 2017 +1100
Branches: master
https://developer.blender.org/rB375ede0f3fdef936d5712968143e06c846c8d6d6

Comments: wmOperator.cancel & modal

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

M	source/blender/windowmanager/WM_types.h

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

diff --git a/source/blender/windowmanager/WM_types.h b/source/blender/windowmanager/WM_types.h
index cd46e24264..97f9257b4c 100644
--- a/source/blender/windowmanager/WM_types.h
+++ b/source/blender/windowmanager/WM_types.h
@@ -542,7 +542,15 @@ typedef struct wmOperatorType {
 	 * canceled due to some external reason, cancel is called
 	 * - see defines below for return values */
 	int (*invoke)(struct bContext *, struct wmOperator *, const struct wmEvent *) ATTR_WARN_UNUSED_RESULT;
+
+	/* Called when a modal operator is canceled (not used often).
+	 * Internal cleanup can be done here if needed. */
 	void (*cancel)(struct bContext *, struct wmOperator *);
+
+	/* Modal is used for operators which continuously run, eg:
+	 * fly mode, knife tool, circle select are all examples of modal operators.
+	 * Modal operators can handle events which would normally access other operators,
+	 * they keep running until they don't return `OPERATOR_RUNNING_MODAL`. */
 	int (*modal)(struct bContext *, struct wmOperator *, const struct wmEvent *) ATTR_WARN_UNUSED_RESULT;
 
 	/* verify if the operator can be executed in the current context, note