Merge branch 'blender-v2.93-release'
[blender.git] / source / blender / windowmanager / WM_types.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2007 Blender Foundation.
17  * All rights reserved.
18  */
19
20 /** \file
21  * \ingroup wm
22  *
23  *
24  * Overview of WM structs
25  * ======================
26  *
27  * - #wmWindowManager.windows -> #wmWindow <br>
28  *   Window manager stores a list of windows.
29  *
30  *   - #wmWindow.screen -> #bScreen <br>
31  *     Window has an active screen.
32  *
33  *     - #bScreen.areabase -> #ScrArea <br>
34  *       Link to #ScrArea.
35  *
36  *       - #ScrArea.spacedata <br>
37  *         Stores multiple spaces via space links.
38  *
39  *         - #SpaceLink <br>
40  *           Base struct for space data for all different space types.
41  *
42  *       - #ScrArea.regionbase -> #ARegion <br>
43  *         Stores multiple regions.
44  *
45  *     - #bScreen.regionbase -> #ARegion <br>
46  *       Global screen level regions, e.g. popups, popovers, menus.
47  *
48  *   - #wmWindow.global_areas -> #ScrAreaMap <br>
49  *     Global screen via 'areabase', e.g. top-bar & status-bar.
50  *
51  *
52  * Window Layout
53  * =============
54  *
55  * <pre>
56  * wmWindow -> bScreen
57  * +----------------------------------------------------------+
58  * |+-----------------------------------------+-------------+ |
59  * ||ScrArea (links to 3D view)               |ScrArea      | |
60  * ||+-------++----------+-------------------+|(links to    | |
61  * |||ARegion||          |ARegion (quad view)|| properties) | |
62  * |||(tools)||          |                   ||             | |
63  * |||       ||          |                   ||             | |
64  * |||       ||          |                   ||             | |
65  * |||       ||          |                   ||             | |
66  * |||       |+----------+-------------------+|             | |
67  * |||       ||          |                   ||             | |
68  * |||       ||          |                   ||             | |
69  * |||       ||          |                   ||             | |
70  * |||       ||          |                   ||             | |
71  * |||       ||          |                   ||             | |
72  * ||+-------++----------+-------------------+|             | |
73  * |+-----------------------------------------+-------------+ |
74  * +----------------------------------------------------------+
75  * </pre>
76  *
77  * Space Data
78  * ==========
79  *
80  * <pre>
81  * ScrArea's store a list of space data (SpaceLinks), each of unique type.
82  * The first one is the displayed in the UI, others are added as needed.
83  *
84  * +----------------------------+  <-- area->spacedata.first;
85  * |                            |
86  * |                            |---+  <-- other inactive SpaceLink's stored.
87  * |                            |   |
88  * |                            |   |---+
89  * |                            |   |   |
90  * |                            |   |   |
91  * |                            |   |   |
92  * |                            |   |   |
93  * +----------------------------+   |   |
94  *    |                             |   |
95  *    +-----------------------------+   |
96  *       |                              |
97  *       +------------------------------+
98  * </pre>
99  *
100  * A common way to get the space from the ScrArea:
101  * \code{.c}
102  * if (area->spacetype == SPACE_VIEW3D) {
103  *     View3D *v3d = area->spacedata.first;
104  *     ...
105  * }
106  * \endcode
107  */
108
109 #pragma once
110
111 struct ID;
112 struct ImBuf;
113 struct bContext;
114 struct wmEvent;
115 struct wmOperator;
116 struct wmWindowManager;
117
118 #include "BLI_compiler_attrs.h"
119 #include "DNA_listBase.h"
120 #include "DNA_vec_types.h"
121 #include "RNA_types.h"
122
123 /* exported types for WM */
124 #include "gizmo/WM_gizmo_types.h"
125 #include "wm_cursors.h"
126 #include "wm_event_types.h"
127
128 /* Include external gizmo API's */
129 #include "gizmo/WM_gizmo_api.h"
130
131 #ifdef __cplusplus
132 extern "C" {
133 #endif
134
135 typedef void (*wmGenericUserDataFreeFn)(void *data);
136
137 typedef struct wmGenericUserData {
138   void *data;
139   /** When NULL, use #MEM_freeN. */
140   wmGenericUserDataFreeFn free_fn;
141   bool use_free;
142 } wmGenericUserData;
143
144 typedef void (*wmGenericCallbackFn)(struct bContext *C, void *user_data);
145
146 typedef struct wmGenericCallback {
147   wmGenericCallbackFn exec;
148   void *user_data;
149   wmGenericUserDataFreeFn free_user_data;
150 } wmGenericCallback;
151
152 /* ************** wmOperatorType ************************ */
153
154 /** #wmOperatorType.flag */
155 enum {
156   /** Register operators in stack after finishing (needed for redo). */
157   OPTYPE_REGISTER = (1 << 0),
158   /** Do an undo push after the operator runs. */
159   OPTYPE_UNDO = (1 << 1),
160   /** Let Blender grab all input from the WM (X11). */
161   OPTYPE_BLOCKING = (1 << 2),
162   OPTYPE_MACRO = (1 << 3),
163
164   /** Grabs the cursor and optionally enables continuous cursor wrapping. */
165   OPTYPE_GRAB_CURSOR_XY = (1 << 4),
166   /** Only warp on the X axis. */
167   OPTYPE_GRAB_CURSOR_X = (1 << 5),
168   /** Only warp on the Y axis. */
169   OPTYPE_GRAB_CURSOR_Y = (1 << 6),
170
171   /** Show preset menu. */
172   OPTYPE_PRESET = (1 << 7),
173
174   /**
175    * Some operators are mainly for internal use and don't make sense
176    * to be accessed from the search menu, even if poll() returns true.
177    * Currently only used for the search toolbox.
178    */
179   OPTYPE_INTERNAL = (1 << 8),
180
181   /** Allow operator to run when interface is locked. */
182   OPTYPE_LOCK_BYPASS = (1 << 9),
183   /** Special type of undo which doesn't store itself multiple times. */
184   OPTYPE_UNDO_GROUPED = (1 << 10),
185 };
186
187 /** For #WM_cursor_grab_enable wrap axis. */
188 enum {
189   WM_CURSOR_WRAP_NONE = 0,
190   WM_CURSOR_WRAP_X,
191   WM_CURSOR_WRAP_Y,
192   WM_CURSOR_WRAP_XY,
193 };
194
195 /**
196  * Context to call operator in for #WM_operator_name_call.
197  * rna_ui.c contains EnumPropertyItem's of these, keep in sync.
198  */
199 enum {
200   /* if there's invoke, call it, otherwise exec */
201   WM_OP_INVOKE_DEFAULT,
202   WM_OP_INVOKE_REGION_WIN,
203   WM_OP_INVOKE_REGION_CHANNELS,
204   WM_OP_INVOKE_REGION_PREVIEW,
205   WM_OP_INVOKE_AREA,
206   WM_OP_INVOKE_SCREEN,
207   /* only call exec */
208   WM_OP_EXEC_DEFAULT,
209   WM_OP_EXEC_REGION_WIN,
210   WM_OP_EXEC_REGION_CHANNELS,
211   WM_OP_EXEC_REGION_PREVIEW,
212   WM_OP_EXEC_AREA,
213   WM_OP_EXEC_SCREEN,
214 };
215
216 /* property tags for RNA_OperatorProperties */
217 typedef enum eOperatorPropTags {
218   OP_PROP_TAG_ADVANCED = (1 << 0),
219 } eOperatorPropTags;
220 #define OP_PROP_TAG_ADVANCED ((eOperatorPropTags)OP_PROP_TAG_ADVANCED)
221
222 /* ************** wmKeyMap ************************ */
223
224 /* modifier */
225 #define KM_SHIFT 1
226 #define KM_CTRL 2
227 #define KM_ALT 4
228 #define KM_OSKEY 8
229 /* means modifier should be pressed 2nd */
230 #define KM_SHIFT2 16
231 #define KM_CTRL2 32
232 #define KM_ALT2 64
233 #define KM_OSKEY2 128
234
235 /* KM_MOD_ flags for wmKeyMapItem and wmEvent.alt/shift/oskey/ctrl  */
236 /* note that KM_ANY and KM_NOTHING are used with these defines too */
237 #define KM_MOD_FIRST 1
238 #define KM_MOD_SECOND 2
239
240 /* type: defined in wm_event_types.c */
241 #define KM_TEXTINPUT -2
242
243 /* val */
244 #define KM_ANY -1
245 #define KM_NOTHING 0
246 #define KM_PRESS 1
247 #define KM_RELEASE 2
248 #define KM_CLICK 3
249 #define KM_DBL_CLICK 4
250 #define KM_CLICK_DRAG 5
251
252 /* ************** UI Handler ***************** */
253
254 #define WM_UI_HANDLER_CONTINUE 0
255 #define WM_UI_HANDLER_BREAK 1
256
257 /* ************** Notifiers ****************** */
258
259 typedef struct wmNotifier {
260   struct wmNotifier *next, *prev;
261
262   const struct wmWindow *window;
263
264   unsigned int category, data, subtype, action;
265
266   void *reference;
267
268 } wmNotifier;
269
270 /* 4 levels
271  *
272  * 0xFF000000; category
273  * 0x00FF0000; data
274  * 0x0000FF00; data subtype (unused?)
275  * 0x000000FF; action
276  */
277
278 /* category */
279 #define NOTE_CATEGORY 0xFF000000
280 #define NC_WM (1 << 24)
281 #define NC_WINDOW (2 << 24)
282 #define NC_SCREEN (3 << 24)
283 #define NC_SCENE (4 << 24)
284 #define NC_OBJECT (5 << 24)
285 #define NC_MATERIAL (6 << 24)
286 #define NC_TEXTURE (7 << 24)
287 #define NC_LAMP (8 << 24)
288 #define NC_GROUP (9 << 24)
289 #define NC_IMAGE (10 << 24)
290 #define NC_BRUSH (11 << 24)
291 #define NC_TEXT (12 << 24)
292 #define NC_WORLD (13 << 24)
293 #define NC_ANIMATION (14 << 24)
294 /* When passing a space as reference data with this (e.g. `WM_event_add_notifier(..., space)`),
295  * the notifier will only be sent to this space. That avoids unnecessary updates for unrelated
296  * spaces. */
297 #define NC_SPACE (15 << 24)
298 #define NC_GEOM (16 << 24)
299 #define NC_NODE (17 << 24)
300 #define NC_ID (18 << 24)
301 #define NC_PAINTCURVE (19 << 24)
302 #define NC_MOVIECLIP (20 << 24)
303 #define NC_MASK (21 << 24)
304 #define NC_GPENCIL (22 << 24)
305 #define NC_LINESTYLE (23 << 24)
306 #define NC_CAMERA (24 << 24)
307 #define NC_LIGHTPROBE (25 << 24)
308 /* Changes to asset data in the current .blend. */
309 #define NC_ASSET (26 << 24)
310
311 /* data type, 256 entries is enough, it can overlap */
312 #define NOTE_DATA 0x00FF0000
313
314 /* NC_WM windowmanager */
315 #define ND_FILEREAD (1 << 16)
316 #define ND_FILESAVE (2 << 16)
317 #define ND_DATACHANGED (3 << 16)
318 #define ND_HISTORY (4 << 16)
319 #define ND_JOB (5 << 16)
320 #define ND_UNDO (6 << 16)
321 #define ND_XR_DATA_CHANGED (7 << 16)
322 #define ND_LIB_OVERRIDE_CHANGED (8 << 16)
323
324 /* NC_SCREEN */
325 #define ND_LAYOUTBROWSE (1 << 16)
326 #define ND_LAYOUTDELETE (2 << 16)
327 #define ND_ANIMPLAY (4 << 16)
328 #define ND_GPENCIL (5 << 16)
329 #define ND_EDITOR_CHANGED (6 << 16) /*sent to new editors after switching to them*/
330 #define ND_LAYOUTSET (7 << 16)
331 #define ND_SKETCH (8 << 16)
332 #define ND_WORKSPACE_SET (9 << 16)
333 #define ND_WORKSPACE_DELETE (10 << 16)
334
335 /* NC_SCENE Scene */
336 #define ND_SCENEBROWSE (1 << 16)
337 #define ND_MARKERS (2 << 16)
338 #define ND_FRAME (3 << 16)
339 #define ND_RENDER_OPTIONS (4 << 16)
340 #define ND_NODES (5 << 16)
341 #define ND_SEQUENCER (6 << 16)
342 /* Note: If an object was added, removed, merged/joined, ..., it is not enough to notify with
343  * this. This affects the layer so also send a layer change notifier (e.g. ND_LAYER_CONTENT)! */
344 #define ND_OB_ACTIVE (7 << 16)
345 /* See comment on ND_OB_ACTIVE. */
346 #define ND_OB_SELECT (8 << 16)
347 #define ND_OB_VISIBLE (9 << 16)
348 #define ND_OB_RENDER (10 << 16)
349 #define ND_MODE (11 << 16)
350 #define ND_RENDER_RESULT (12 << 16)
351 #define ND_COMPO_RESULT (13 << 16)
352 #define ND_KEYINGSET (14 << 16)
353 #define ND_TOOLSETTINGS (15 << 16)
354 #define ND_LAYER (16 << 16)
355 #define ND_FRAME_RANGE (17 << 16)
356 #define ND_TRANSFORM_DONE (18 << 16)
357 #define ND_WORLD (92 << 16)
358 #define ND_LAYER_CONTENT (101 << 16)
359
360 /* NC_OBJECT Object */
361 #define ND_TRANSFORM (18 << 16)
362 #define ND_OB_SHADING (19 << 16)
363 #define ND_POSE (20 << 16)
364 #define ND_BONE_ACTIVE (21 << 16)
365 #define ND_BONE_SELECT (22 << 16)
366 #define ND_DRAW (23 << 16)
367 #define ND_MODIFIER (24 << 16)
368 #define ND_KEYS (25 << 16)
369 #define ND_CONSTRAINT (26 << 16)
370 #define ND_PARTICLE (27 << 16)
371 #define ND_POINTCACHE (28 << 16)
372 #define ND_PARENT (29 << 16)
373 #define ND_LOD (30 << 16)
374 #define ND_DRAW_RENDER_VIEWPORT \
375   (31 << 16) /* for camera & sequencer viewport update, also /w NC_SCENE */
376 #define ND_SHADERFX (32 << 16)
377 /* For updating motion paths in 3dview. */
378 #define ND_DRAW_ANIMVIZ (33 << 16)
379
380 /* NC_MATERIAL Material */
381 #define ND_SHADING (30 << 16)
382 #define ND_SHADING_DRAW (31 << 16)
383 #define ND_SHADING_LINKS (32 << 16)
384 #define ND_SHADING_PREVIEW (33 << 16)
385
386 /* NC_LAMP Light */
387 #define ND_LIGHTING (40 << 16)
388 #define ND_LIGHTING_DRAW (41 << 16)
389
390 /* NC_WORLD World */
391 #define ND_WORLD_DRAW (45 << 16)
392
393 /* NC_TEXT Text */
394 #define ND_CURSOR (50 << 16)
395 #define ND_DISPLAY (51 << 16)
396
397 /* NC_ANIMATION Animato */
398 #define ND_KEYFRAME (70 << 16)
399 #define ND_KEYFRAME_PROP (71 << 16)
400 #define ND_ANIMCHAN (72 << 16)
401 #define ND_NLA (73 << 16)
402 #define ND_NLA_ACTCHANGE (74 << 16)
403 #define ND_FCURVES_ORDER (75 << 16)
404 #define ND_NLA_ORDER (76 << 16)
405
406 /* NC_GPENCIL */
407 #define ND_GPENCIL_EDITMODE (85 << 16)
408
409 /* NC_GEOM Geometry */
410 /* Mesh, Curve, MetaBall, Armature, .. */
411 #define ND_SELECT (90 << 16)
412 #define ND_DATA (91 << 16)
413 #define ND_VERTEX_GROUP (92 << 16)
414
415 /* NC_NODE Nodes */
416
417 /* NC_SPACE */
418 #define ND_SPACE_CONSOLE (1 << 16)     /* general redraw */
419 #define ND_SPACE_INFO_REPORT (2 << 16) /* update for reports, could specify type */
420 #define ND_SPACE_INFO (3 << 16)
421 #define ND_SPACE_IMAGE (4 << 16)
422 #define ND_SPACE_FILE_PARAMS (5 << 16)
423 #define ND_SPACE_FILE_LIST (6 << 16)
424 #define ND_SPACE_ASSET_PARAMS (7 << 16)
425 #define ND_SPACE_NODE (8 << 16)
426 #define ND_SPACE_OUTLINER (9 << 16)
427 #define ND_SPACE_VIEW3D (10 << 16)
428 #define ND_SPACE_PROPERTIES (11 << 16)
429 #define ND_SPACE_TEXT (12 << 16)
430 #define ND_SPACE_TIME (13 << 16)
431 #define ND_SPACE_GRAPH (14 << 16)
432 #define ND_SPACE_DOPESHEET (15 << 16)
433 #define ND_SPACE_NLA (16 << 16)
434 #define ND_SPACE_SEQUENCER (17 << 16)
435 #define ND_SPACE_NODE_VIEW (18 << 16)
436 #define ND_SPACE_CHANGED (19 << 16) /*sent to a new editor type after it's replaced an old one*/
437 #define ND_SPACE_CLIP (20 << 16)
438 #define ND_SPACE_FILE_PREVIEW (21 << 16)
439 #define ND_SPACE_SPREADSHEET (22 << 16)
440
441 /* subtype, 256 entries too */
442 #define NOTE_SUBTYPE 0x0000FF00
443
444 /* subtype scene mode */
445 #define NS_MODE_OBJECT (1 << 8)
446
447 #define NS_EDITMODE_MESH (2 << 8)
448 #define NS_EDITMODE_CURVE (3 << 8)
449 #define NS_EDITMODE_SURFACE (4 << 8)
450 #define NS_EDITMODE_TEXT (5 << 8)
451 #define NS_EDITMODE_MBALL (6 << 8)
452 #define NS_EDITMODE_LATTICE (7 << 8)
453 #define NS_EDITMODE_ARMATURE (8 << 8)
454 #define NS_MODE_POSE (9 << 8)
455 #define NS_MODE_PARTICLE (10 << 8)
456
457 /* subtype 3d view editing */
458 #define NS_VIEW3D_GPU (16 << 8)
459 #define NS_VIEW3D_SHADING (17 << 8)
460
461 /* subtype layer editing */
462 #define NS_LAYER_COLLECTION (24 << 8)
463
464 /* action classification */
465 #define NOTE_ACTION (0x000000FF)
466 #define NA_EDITED 1
467 #define NA_EVALUATED 2
468 #define NA_ADDED 3
469 #define NA_REMOVED 4
470 #define NA_RENAME 5
471 #define NA_SELECTED 6
472 #define NA_ACTIVATED 7
473 #define NA_PAINTING 8
474 #define NA_JOB_FINISHED 9
475
476 /* ************** Gesture Manager data ************** */
477
478 /* wmGesture->type */
479 #define WM_GESTURE_TWEAK 0
480 #define WM_GESTURE_LINES 1
481 #define WM_GESTURE_RECT 2
482 #define WM_GESTURE_CROSS_RECT 3
483 #define WM_GESTURE_LASSO 4
484 #define WM_GESTURE_CIRCLE 5
485 #define WM_GESTURE_STRAIGHTLINE 6
486
487 /**
488  * wmGesture is registered to #wmWindow.gesture, handled by operator callbacks.
489  * Tweak gesture is builtin feature.
490  */
491 typedef struct wmGesture {
492   struct wmGesture *next, *prev;
493   /** #wmEvent.type */
494   int event_type;
495   /** Gesture type define. */
496   int type;
497   /** bounds of region to draw gesture within. */
498   rcti winrct;
499   /** optional, amount of points stored. */
500   int points;
501   /** optional, maximum amount of points stored. */
502   int points_alloc;
503   int modal_state;
504   /** optional, draw the active side of the straightline gesture. */
505   bool draw_active_side;
506
507   /**
508    * For modal operators which may be running idle, waiting for an event to activate the gesture.
509    * Typically this is set when the user is click-dragging the gesture
510    * (box and circle select for eg).
511    */
512   uint is_active : 1;
513   /** Previous value of is-active (use to detect first run & edge cases). */
514   uint is_active_prev : 1;
515   /** Use for gestures that support both immediate or delayed activation. */
516   uint wait_for_input : 1;
517   /** Use for gestures that can be moved, like box selection */
518   uint move : 1;
519   /** For gestures that support snapping, stores if snapping is enabled using the modal keymap
520    * toggle. */
521   uint use_snap : 1;
522   /** For gestures that support flip, stores if flip is enabled using the modal keymap
523    * toggle. */
524   uint use_flip : 1;
525
526   /**
527    * customdata
528    * - for border is a #rcti.
529    * - for circle is recti, (xmin, ymin) is center, xmax radius.
530    * - for lasso is short array.
531    * - for straight line is a recti: (xmin,ymin) is start, (xmax, ymax) is end.
532    */
533   void *customdata;
534
535   /** Free pointer to use for operator allocs (if set, its freed on exit). */
536   wmGenericUserData user_data;
537 } wmGesture;
538
539 /* ************** wmEvent ************************ */
540
541 typedef struct wmTabletData {
542   /** 0=EVT_TABLET_NONE, 1=EVT_TABLET_STYLUS, 2=EVT_TABLET_ERASER. */
543   int active;
544   /** range 0.0 (not touching) to 1.0 (full pressure). */
545   float pressure;
546   /** range 0.0 (upright) to 1.0 (tilted fully against the tablet surface). */
547   float x_tilt;
548   /** as above. */
549   float y_tilt;
550   /** Interpret mouse motion as absolute as typical for tablets. */
551   char is_motion_absolute;
552 } wmTabletData;
553
554 /**
555  * Each event should have full modifier state.
556  * event comes from event manager and from keymap.
557  *
558  *
559  * Previous State
560  * ==============
561  *
562  * Events hold information about the previous event,
563  * this is used for detecting click and double-click events (the timer is needed for double-click).
564  * See #wm_event_add_ghostevent for implementation details.
565  *
566  * Notes:
567  *
568  * - The previous values are only set for mouse button and keyboard events.
569  *   See: #ISMOUSE_BUTTON & #ISKEYBOARD macros.
570  *
571  * - Previous x/y are exceptions: #wmEvent.prevx & #wmEvent.prevy
572  *   these are set on mouse motion, see #MOUSEMOVE & track-pad events.
573  *
574  * - Modal key-map handling sets `prevval` & `prevtype` to `val` & `type`,
575  *   this allows modal keys-maps to check the original values (needed in some cases).
576  */
577 typedef struct wmEvent {
578   struct wmEvent *next, *prev;
579
580   /** Event code itself (short, is also in key-map). */
581   short type;
582   /** Press, release, scroll-value. */
583   short val;
584   /** Mouse pointer position, screen coord. */
585   int x, y;
586   /** Region relative mouse position (name convention before Blender 2.5). */
587   int mval[2];
588   /**
589    * From, ghost if utf8 is enabled for the platform,
590    * #BLI_str_utf8_size() must _always_ be valid, check
591    * when assigning s we don't need to check on every access after.
592    */
593   char utf8_buf[6];
594   /** From ghost, fallback if utf8 isn't set. */
595   char ascii;
596
597   /**
598    * Generated by auto-repeat, note that this must only ever be set for keyboard events
599    * where `ISKEYBOARD(event->type) == true`.
600    *
601    * See #KMI_REPEAT_IGNORE for details on how key-map handling uses this.
602    */
603   char is_repeat;
604
605   /** The previous value of `type`. */
606   short prevtype;
607   /** The previous value of `val`. */
608   short prevval;
609   /** The time when the key is pressed, see #PIL_check_seconds_timer. */
610   double prevclicktime;
611   /** The location when the key is pressed (used to enforce drag thresholds). */
612   int prevclickx, prevclicky;
613   /**
614    * The previous value of #wmEvent.x #wmEvent.y,
615    * Unlike other previous state variables, this is set on any mouse motion.
616    * Use `prevclickx` & `prevclicky` for the value at time of pressing.
617    */
618   int prevx, prevy;
619
620   /** Modifier states. */
621   /** 'oskey' is apple or windows-key, value denotes order of pressed. */
622   short shift, ctrl, alt, oskey;
623   /** Raw-key modifier (allow using any key as a modifier). */
624   short keymodifier;
625
626   /** Tablet info, available for mouse move and button events. */
627   wmTabletData tablet;
628
629   /* Custom data. */
630   /** Custom data type, stylus, 6dof, see wm_event_types.h */
631   short custom;
632   short customdatafree;
633   int pad2;
634   /** Ascii, unicode, mouse-coords, angles, vectors, NDOF data, drag-drop info. */
635   void *customdata;
636
637   /**
638    * True if the operating system inverted the delta x/y values and resulting
639    * `prevx`, `prevy` values, for natural scroll direction.
640    * For absolute scroll direction, the delta must be negated again.
641    */
642   char is_direction_inverted;
643 } wmEvent;
644
645 /**
646  * Values below are ignored when detecting if the user intentionally moved the cursor.
647  * Keep this very small since it's used for selection cycling for eg,
648  * where we want intended adjustments to pass this threshold and select new items.
649  *
650  * Always check for <= this value since it may be zero.
651  */
652 #define WM_EVENT_CURSOR_MOTION_THRESHOLD ((float)U.move_threshold * U.dpi_fac)
653
654 /** Motion progress, for modal handlers. */
655 typedef enum {
656   P_NOT_STARTED,
657   P_STARTING,    /* <-- */
658   P_IN_PROGRESS, /* <-- only these are sent for NDOF motion. */
659   P_FINISHING,   /* <-- */
660   P_FINISHED,
661 } wmProgress;
662
663 #ifdef WITH_INPUT_NDOF
664 typedef struct wmNDOFMotionData {
665   /* awfully similar to GHOST_TEventNDOFMotionData... */
666   /**
667    * Each component normally ranges from -1 to +1, but can exceed that.
668    * These use blender standard view coordinates,
669    * with positive rotations being CCW about the axis.
670    */
671   /** Translation. */
672   float tvec[3];
673   /** Rotation.
674    * <pre>
675    * axis = (rx,ry,rz).normalized.
676    * amount = (rx,ry,rz).magnitude [in revolutions, 1.0 = 360 deg]
677    * </pre>
678    */
679   float rvec[3];
680   /** Time since previous NDOF Motion event. */
681   float dt;
682   /** Is this the first event, the last, or one of many in between? */
683   wmProgress progress;
684 } wmNDOFMotionData;
685 #endif /* WITH_INPUT_NDOF */
686
687 /** Timer flags. */
688 typedef enum {
689   /** Do not attempt to free customdata pointer even if non-NULL. */
690   WM_TIMER_NO_FREE_CUSTOM_DATA = 1 << 0,
691 } wmTimerFlags;
692
693 typedef struct wmTimer {
694   struct wmTimer *next, *prev;
695
696   /** Window this timer is attached to (optional). */
697   struct wmWindow *win;
698
699   /** Set by timer user. */
700   double timestep;
701   /** Set by timer user, goes to event system. */
702   int event_type;
703   /** Various flags controlling timer options, see below. */
704   wmTimerFlags flags;
705   /** Set by timer user, to allow custom values. */
706   void *customdata;
707
708   /** Total running time in seconds. */
709   double duration;
710   /** Time since previous step in seconds. */
711   double delta;
712
713   /** Internal, last time timer was activated. */
714   double ltime;
715   /** Internal, next time we want to activate the timer. */
716   double ntime;
717   /** Internal, when the timer started. */
718   double stime;
719   /** Internal, put timers to sleep when needed. */
720   bool sleep;
721 } wmTimer;
722
723 typedef struct wmOperatorType {
724   /** Text for UI, undo. */
725   const char *name;
726   /** Unique identifier. */
727   const char *idname;
728   const char *translation_context;
729   /** Use for tool-tips and Python docs. */
730   const char *description;
731   /** Identifier to group operators together. */
732   const char *undo_group;
733
734   /**
735    * This callback executes the operator without any interactive input,
736    * parameters may be provided through operator properties. cannot use
737    * any interface code or input device state.
738    * See defines below for return values.
739    */
740   int (*exec)(struct bContext *, struct wmOperator *) ATTR_WARN_UNUSED_RESULT;
741
742   /**
743    * This callback executes on a running operator whenever as property
744    * is changed. It can correct its own properties or report errors for
745    * invalid settings in exceptional cases.
746    * Boolean return value, True denotes a change has been made and to redraw.
747    */
748   bool (*check)(struct bContext *, struct wmOperator *);
749
750   /**
751    * For modal temporary operators, initially invoke is called. then
752    * any further events are handled in modal. if the operation is
753    * canceled due to some external reason, cancel is called
754    * See defines below for return values.
755    */
756   int (*invoke)(struct bContext *,
757                 struct wmOperator *,
758                 const struct wmEvent *) ATTR_WARN_UNUSED_RESULT;
759
760   /**
761    * Called when a modal operator is canceled (not used often).
762    * Internal cleanup can be done here if needed.
763    */
764   void (*cancel)(struct bContext *, struct wmOperator *);
765
766   /**
767    * Modal is used for operators which continuously run, eg:
768    * fly mode, knife tool, circle select are all examples of modal operators.
769    * Modal operators can handle events which would normally access other operators,
770    * they keep running until they don't return `OPERATOR_RUNNING_MODAL`.
771    */
772   int (*modal)(struct bContext *,
773                struct wmOperator *,
774                const struct wmEvent *) ATTR_WARN_UNUSED_RESULT;
775
776   /**
777    * Verify if the operator can be executed in the current context, note
778    * that the operator might still fail to execute even if this return true.
779    */
780   bool (*poll)(struct bContext *) ATTR_WARN_UNUSED_RESULT;
781
782   /**
783    * Use to check if properties should be displayed in auto-generated UI.
784    * Use 'check' callback to enforce refreshing.
785    */
786   bool (*poll_property)(const struct bContext *C,
787                         struct wmOperator *op,
788                         const PropertyRNA *prop) ATTR_WARN_UNUSED_RESULT;
789
790   /** Optional panel for redo and repeat, auto-generated if not set. */
791   void (*ui)(struct bContext *, struct wmOperator *);
792
793   /**
794    * Return a different name to use in the user interface, based on property values.
795    * The returned string does not need to be freed.
796    */
797   const char *(*get_name)(struct wmOperatorType *, struct PointerRNA *);
798
799   /**
800    * Return a different description to use in the user interface, based on property values.
801    * The returned string must be freed by the caller, unless NULL.
802    */
803   char *(*get_description)(struct bContext *C, struct wmOperatorType *, struct PointerRNA *);
804
805   /** rna for properties */
806   struct StructRNA *srna;
807
808   /** previous settings - for initializing on re-use */
809   struct IDProperty *last_properties;
810
811   /**
812    * Default rna property to use for generic invoke functions.
813    * menus, enum search... etc. Example: Enum 'type' for a Delete menu.
814    *
815    * When assigned a string/number property,
816    * immediately edit the value when used in a popup. see: #UI_BUT_ACTIVATE_ON_INIT.
817    */
818   PropertyRNA *prop;
819
820   /** struct wmOperatorTypeMacro */
821   ListBase macro;
822
823   /** pointer to modal keymap, do not free! */
824   struct wmKeyMap *modalkeymap;
825
826   /** python needs the operator type as well */
827   bool (*pyop_poll)(struct bContext *, struct wmOperatorType *ot) ATTR_WARN_UNUSED_RESULT;
828
829   /** RNA integration */
830   ExtensionRNA rna_ext;
831
832   /** Flag last for padding */
833   short flag;
834
835 } wmOperatorType;
836
837 /**
838  * Wrapper to reference a #wmOperatorType together with some set properties and other relevant
839  * information to invoke the operator in a customizable way.
840  */
841 typedef struct wmOperatorCallParams {
842   struct wmOperatorType *optype;
843   struct PointerRNA *opptr;
844   short opcontext;
845 } wmOperatorCallParams;
846
847 #ifdef WITH_INPUT_IME
848 /* *********** Input Method Editor (IME) *********** */
849 /**
850  * \note similar to #GHOST_TEventImeData.
851  */
852 typedef struct wmIMEData {
853   size_t result_len, composite_len;
854
855   /** utf8 encoding */
856   char *str_result;
857   /** utf8 encoding */
858   char *str_composite;
859
860   /** Cursor position in the IME composition. */
861   int cursor_pos;
862   /** Beginning of the selection. */
863   int sel_start;
864   /** End of the selection. */
865   int sel_end;
866
867   bool is_ime_composing;
868 } wmIMEData;
869 #endif
870
871 /* **************** Paint Cursor ******************* */
872
873 typedef void (*wmPaintCursorDraw)(struct bContext *C, int, int, void *customdata);
874
875 /* *************** Drag and drop *************** */
876
877 #define WM_DRAG_ID 0
878 #define WM_DRAG_ASSET 1
879 #define WM_DRAG_RNA 2
880 #define WM_DRAG_PATH 3
881 #define WM_DRAG_NAME 4
882 #define WM_DRAG_VALUE 5
883 #define WM_DRAG_COLOR 6
884 #define WM_DRAG_DATASTACK 7
885
886 typedef enum wmDragFlags {
887   WM_DRAG_NOP = 0,
888   WM_DRAG_FREE_DATA = 1,
889 } wmDragFlags;
890
891 /* note: structs need not exported? */
892
893 typedef struct wmDragID {
894   struct wmDragID *next, *prev;
895   struct ID *id;
896   struct ID *from_parent;
897 } wmDragID;
898
899 typedef struct wmDragAsset {
900   char name[64]; /* MAX_NAME */
901   /* Always freed. */
902   const char *path;
903   int id_type;
904 } wmDragAsset;
905
906 typedef struct wmDrag {
907   struct wmDrag *next, *prev;
908
909   int icon;
910   /** See 'WM_DRAG_' defines above. */
911   int type;
912   void *poin;
913   char path[1024]; /* FILE_MAX */
914   double value;
915
916   /** If no icon but imbuf should be drawn around cursor. */
917   struct ImBuf *imb;
918   float scale;
919   int sx, sy;
920
921   /** If set, draws operator name. */
922   char opname[200];
923   unsigned int flags;
924
925   /** List of wmDragIDs, all are guaranteed to have the same ID type. */
926   ListBase ids;
927 } wmDrag;
928
929 /**
930  * Dropboxes are like keymaps, part of the screen/area/region definition.
931  * Allocation and free is on startup and exit.
932  */
933 typedef struct wmDropBox {
934   struct wmDropBox *next, *prev;
935
936   /** Test if the dropbox is active, then can print optype name. */
937   bool (*poll)(struct bContext *, struct wmDrag *, const wmEvent *, const char **);
938
939   /** Before exec, this copies drag info to #wmDrop properties. */
940   void (*copy)(struct wmDrag *, struct wmDropBox *);
941
942   /**
943    * If the operator is cancelled (returns `OPERATOR_CANCELLED`), this can be used for cleanup of
944    * `copy()` resources.
945    */
946   void (*cancel)(struct Main *, struct wmDrag *, struct wmDropBox *);
947
948   /**
949    * If poll succeeds, operator is called.
950    * Not saved in file, so can be pointer.
951    */
952   wmOperatorType *ot;
953
954   /** Operator properties, assigned to ptr->data and can be written to a file. */
955   struct IDProperty *properties;
956   /** RNA pointer to access properties. */
957   struct PointerRNA *ptr;
958
959   /** Default invoke. */
960   short opcontext;
961
962 } wmDropBox;
963
964 /**
965  * Struct to store tool-tip timer and possible creation if the time is reached.
966  * Allows UI code to call #WM_tooltip_timer_init without each user having to handle the timer.
967  */
968 typedef struct wmTooltipState {
969   /** Create tooltip on this event. */
970   struct wmTimer *timer;
971   /** The area the tooltip is created in. */
972   struct ScrArea *area_from;
973   /** The region the tooltip is created in. */
974   struct ARegion *region_from;
975   /** The tooltip region. */
976   struct ARegion *region;
977   /** Create the tooltip region (assign to 'region'). */
978   struct ARegion *(*init)(struct bContext *C,
979                           struct ARegion *region,
980                           int *pass,
981                           double *pass_delay,
982                           bool *r_exit_on_event);
983   /** Exit on any event, not needed for buttons since their highlight state is used. */
984   bool exit_on_event;
985   /** Cursor location at the point of tooltip creation. */
986   int event_xy[2];
987   /** Pass, use when we want multiple tips, count down to zero. */
988   int pass;
989 } wmTooltipState;
990
991 /* *************** migrated stuff, clean later? ************** */
992
993 typedef struct RecentFile {
994   struct RecentFile *next, *prev;
995   char *filepath;
996 } RecentFile;
997
998 /* Logging */
999 struct CLG_LogRef;
1000 /* wm_init_exit.c */
1001 extern struct CLG_LogRef *WM_LOG_OPERATORS;
1002 extern struct CLG_LogRef *WM_LOG_HANDLERS;
1003 extern struct CLG_LogRef *WM_LOG_EVENTS;
1004 extern struct CLG_LogRef *WM_LOG_KEYMAPS;
1005 extern struct CLG_LogRef *WM_LOG_TOOLS;
1006 extern struct CLG_LogRef *WM_LOG_MSGBUS_PUB;
1007 extern struct CLG_LogRef *WM_LOG_MSGBUS_SUB;
1008
1009 #ifdef __cplusplus
1010 }
1011 #endif