diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-03-02 09:02:54 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-03-02 09:02:54 +0300 |
commit | 92dac21e6b4e6d53417484513d9e3c016f7dbba7 (patch) | |
tree | 3fbd4dfdb9bf40111dcecd5b578754ad78371dc1 | |
parent | 7093e8b40a732fabf067acaefbb37f2b151519ee (diff) |
Docs: notes on wmEvent previous state struct member use
-rw-r--r-- | source/blender/windowmanager/WM_types.h | 49 |
1 files changed, 39 insertions, 10 deletions
diff --git a/source/blender/windowmanager/WM_types.h b/source/blender/windowmanager/WM_types.h index d40c0715a09..863a4436e04 100644 --- a/source/blender/windowmanager/WM_types.h +++ b/source/blender/windowmanager/WM_types.h @@ -543,17 +543,36 @@ typedef struct wmTabletData { /** * Each event should have full modifier state. * event comes from event manager and from keymap. + * + * + * Previous State + * ============== + * + * Events hold information about the previous event, + * this is used for detecting click and double-click events (the timer is needed for double-click). + * See #wm_event_add_ghostevent for implementation details. + * + * Notes: + * + * - The previous values are only set for mouse button and keyboard events. + * See: #ISMOUSE_BUTTON & #ISKEYBOARD macros. + * + * - Previous x/y are exceptions: #wmEvent.prevx & #wmEvent.prevy + * these are set on mouse motion, see #MOUSEMOVE & track-pad events. + * + * - Modal key-map handling sets `prevval` & `prevtype` to `val` & `type`, + * this allows modal keys-maps to check the original values (needed in some cases). */ typedef struct wmEvent { struct wmEvent *next, *prev; - /** Event code itself (short, is also in keymap). */ + /** Event code itself (short, is also in key-map). */ short type; /** Press, release, scroll-value. */ short val; /** Mouse pointer position, screen coord. */ int x, y; - /** Region mouse position, name convention pre 2.5 :). */ + /** Region relative mouse position (name convention before Blender 2.5). */ int mval[2]; /** * From, ghost if utf8 is enabled for the platform, @@ -572,17 +591,25 @@ typedef struct wmEvent { */ char is_repeat; - /** Previous state, used for double click and the 'click'. */ + /** The previous value of `type`. */ short prevtype; + /** The previous value of `val`. */ short prevval; - int prevx, prevy; + /** The time when the key is pressed, see #PIL_check_seconds_timer. */ double prevclicktime; + /** The location when the key is pressed (used to enforce drag thresholds). */ int prevclickx, prevclicky; + /** + * The previous value of #wmEvent.x #wmEvent.y, + * Unlike other previous state variables, this is set on any mouse motion. + * Use `prevclickx` & `prevclicky` for the value at time of pressing. + */ + int prevx, prevy; /** Modifier states. */ /** 'oskey' is apple or windows-key, value denotes order of pressed. */ short shift, ctrl, alt, oskey; - /** rawkey modifier. */ + /** Raw-key modifier (allow using any key as a modifier). */ short keymodifier; /** Set in case a #KM_PRESS went by unhandled. */ @@ -592,17 +619,19 @@ typedef struct wmEvent { /** Tablet info, available for mouse move and button events. */ wmTabletData tablet; - /* custom data */ + /* Custom data. */ /** Custom data type, stylus, 6dof, see wm_event_types.h */ short custom; short customdatafree; int pad2; - /** Ascii, unicode, mouse coords, angles, vectors, dragdrop info. */ + /** Ascii, unicode, mouse-coords, angles, vectors, NDOF data, drag-drop info. */ void *customdata; - /* True if the operating system inverted the delta x/y values and resulting - * prev x/y values, for natural scroll direction. For absolute scroll direction, - * the delta must be negated again. */ + /** + * True if the operating system inverted the delta x/y values and resulting + * `prevx`, `prevy` values, for natural scroll direction. + * For absolute scroll direction, the delta must be negated again. + */ char is_direction_inverted; } wmEvent; |