[Bf-blender-cvs] [af5706c9606] master: Docs: improve doc-string for WM_operator_flag_only_pass_through_on_press

[Campbell Barton]

Commit: af5706c9606970b2e0a577ee99a720e91c010bca
Author: Campbell Barton
Date:   Tue Feb 7 14:18:59 2023 +1100
Branches: master
https://developer.blender.org/rBaf5706c9606970b2e0a577ee99a720e91c010bca

Docs: improve doc-string for WM_operator_flag_only_pass_through_on_press

The doc-string didn't provide any context for how the funciton is
intended to be used.

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

M	source/blender/windowmanager/WM_api.h

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

diff --git a/source/blender/windowmanager/WM_api.h b/source/blender/windowmanager/WM_api.h
index 02f465c319a..faa22e6216e 100644
--- a/source/blender/windowmanager/WM_api.h
+++ b/source/blender/windowmanager/WM_api.h
@@ -1257,7 +1257,26 @@ void WM_event_fileselect_event(struct wmWindowManager *wm, void *ophandle, int e
 void WM_operator_region_active_win_set(struct bContext *C);
 
 /**
- * Only finish + pass through for press events (allowing press-tweak).
+ * Indented for use in a selection (picking) operators #wmOperatorType::invoke callback
+ * to implement click-drag, where the initial click selects and the drag action
+ * grabs or performs box-select (for example).
+ *
+ * - In this case, returning `OPERATOR_FINISHED` causes the PRESS event
+ *   to be handled and prevents further CLICK (on release) or DRAG (on cursor motion)
+ *   from being generated & handled.
+ *
+ * - Returning `OPERATOR_FINISHED | OPERATOR_PASS_THROUGH` allows for CLICK/DRAG but only makes
+ *   sense if the event's value is PRESS. If the operator was already mapped to a CLICK/DRAG event,
+ *   a single CLICK/DRAG could invoke multiple operators.
+ *
+ * This function handles the details of checking the operator return value,
+ * clearing #OPERATOR_PASS_THROUGH when the #wmEvent::val is not #KM_PRESS.
+ *
+ * \note Combining selection with other actions should only be used
+ * in situations where selecting doesn't change the visibility of other items.
+ * Since it means for example click-drag to box select could hide-show elements the user
+ * intended to box-select. In this case it's preferred to select on CLICK instead of PRESS
+ * (see the Outliner use of click-drag).
  */
 int WM_operator_flag_only_pass_through_on_press(int retval, const struct wmEvent *event);