code cleanup: use const events for modal and invoke operators.
[blender.git] / source / blender / windowmanager / WM_types.h
index 4aa2c3f64057a99cd7946ab84842a7c7a6c8f8fc..f2750aa6d99385e732f915e35df7a308e9b0ff10 100644 (file)
 #ifndef __WM_TYPES_H__
 #define __WM_TYPES_H__
 
+/**
+ * Overview of WM structs
+ * ======================
+ *
+ * <pre>
+ * > wmWindowManager    (window manager stores a list of windows)
+ * > > wmWindow         (window has an active screen)
+ * > > > bScreen        (link to ScrAreas via 'areabase')
+ * > > > > ScrArea      (stores multiple spaces via space links via 'spacedata')
+ * > > > > > SpaceLink  (base struct for space data for all different space types)
+ * > > > > ScrArea      (stores multiple regions via 'regionbase')
+ * > > > > > ARegion
+ * </pre>
+ *
+ * Window Layout
+ * =============
+ *
+ * <pre>
+ * wmWindow -> bScreen
+ * +----------------------------------------------------------+
+ * |+-----------------------------------------+-------------+ |
+ * ||ScrArea (links to 3D view)               |ScrArea      | |
+ * ||+-------++----------+-------------------+|(links to    | |
+ * |||ARegion||          |ARegion (quad view)|| properties) | |
+ * |||(tools)||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * |||       |+----------+-------------------+|             | |
+ * |||       ||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * |||       ||          |                   ||             | |
+ * ||+-------++----------+-------------------+|             | |
+ * |+-----------------------------------------+-------------+ |
+ * +----------------------------------------------------------+
+ * </pre>
+ *
+ * Space Data
+ * ==========
+ *
+ * <pre>
+ * ScrArea's store a list of space data (SpaceLinks), each of unique type.
+ * The first one is the displayed in the UI, others are added as needed.
+ *
+ * +----------------------------+  <-- sa->spacedata.first;
+ * |                            |
+ * |                            |---+  <-- other inactive SpaceLink's stored.
+ * |                            |   |
+ * |                            |   |---+
+ * |                            |   |   |
+ * |                            |   |   |
+ * |                            |   |   |
+ * |                            |   |   |
+ * +----------------------------+   |   |
+ *    |                             |   |
+ *    +-----------------------------+   |
+ *       |                              |
+ *       +------------------------------+
+ * </pre>
+ *
+ * A common way to get the space from the ScrArea:
+ * <pre>
+ *     if (sa->spacetype == SPACE_VIEW3D) {
+ *         View3D *v3d = sa->spacedata.first;
+ *         ...
+ *     }
+ * </pre>
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -44,7 +115,6 @@ struct ImBuf;
 
 #include "RNA_types.h"
 #include "DNA_listBase.h"
-#include "BKE_utildefines.h" /* FILE_MAX */
 
 /* exported types for WM */
 #include "wm_cursors.h"
@@ -118,7 +188,7 @@ enum {
 #define WM_UI_HANDLER_CONTINUE 0
 #define WM_UI_HANDLER_BREAK            1
 
-typedef int (*wmUIHandlerFunc)(struct bContext *C, struct wmEvent *event, void *userdata);
+typedef int (*wmUIHandlerFunc)(struct bContext *C, const struct wmEvent *event, void *userdata);
 typedef void (*wmUIHandlerRemoveFunc)(struct bContext *C, void *userdata);
 
 /* ************** Notifiers ****************** */
@@ -167,6 +237,8 @@ typedef struct wmNotifier {
 #define NC_ID                          (18<<24)
 #define NC_LOGIC                       (19<<24)
 #define NC_MOVIECLIP                   (20<<24)
+#define NC_MASK                                (21<<24)
+#define NC_GPENCIL                     (22<<24)
 
 /* data type, 256 entries is enough, it can overlap */
 #define NOTE_DATA                      0x00FF0000
@@ -228,6 +300,7 @@ typedef struct wmNotifier {
        /* NC_MATERIAL Material */
 #define        ND_SHADING                      (30<<16)
 #define        ND_SHADING_DRAW         (31<<16)
+#define        ND_SHADING_LINKS        (32<<16)
 
        /* NC_LAMP Lamp */
 #define        ND_LIGHTING                     (40<<16)
@@ -254,6 +327,7 @@ typedef struct wmNotifier {
        /* Mesh, Curve, MetaBall, Armature, .. */
 #define ND_SELECT                      (90<<16)
 #define ND_DATA                                (91<<16)
+#define ND_VERTEX_GROUP                (92<<16)
 
        /* NC_NODE Nodes */
 
@@ -333,6 +407,9 @@ typedef struct wmGesture {
        /* customdata for circle is recti, (xmin, ymin) is center, xmax radius */
        /* customdata for lasso is short array */
        /* customdata for straight line is a recti: (xmin,ymin) is start, (xmax, ymax) is end */
+
+       /* free pointer to use for operator allocs (if set, its freed on exit)*/
+       void *userdata;
 } wmGesture;
 
 /* ************** wmEvent ************************ */
@@ -352,7 +429,7 @@ typedef struct wmEvent {
        char ascii;                     /* from ghost, fallback if utf8 isn't set */
        char pad;
 
-       /* previous state */
+       /* previous state, used for double click and the 'click' */
        short prevtype;
        short prevval;
        int prevx, prevy;
@@ -363,11 +440,15 @@ typedef struct wmEvent {
        short shift, ctrl, alt, oskey;  /* oskey is apple or windowskey, value denotes order of pressed */
        short keymodifier;                              /* rawkey modifier */
        
-       short pad1;
+       /* set in case a KM_PRESS went by unhandled */
+       short check_click;
        
        /* keymap item, set by handler (weak?) */
        const char *keymap_idname;
-       
+
+       /* tablet info, only use when the tablet is active */
+       struct wmTabletData *tablet_data;
+
        /* custom data */
        short custom;           /* custom data type, stylus, 6dof, see wm_event_types.h */
        short customdatafree;
@@ -384,30 +465,30 @@ typedef struct wmTabletData {
        float Ytilt;            /* as above */
 } wmTabletData;
 
-typedef enum { // motion progress, for modal handlers
+typedef enum {  /* motion progress, for modal handlers */
        P_NOT_STARTED,
-       P_STARTING,    // <--
-       P_IN_PROGRESS, // <-- only these are sent for NDOF motion
-       P_FINISHING,   // <--
+       P_STARTING,    /* <-- */
+       P_IN_PROGRESS, /* <-- only these are sent for NDOF motion*/
+       P_FINISHING,   /* <-- */
        P_FINISHED
-       } wmProgress;
+} wmProgress;
 
 typedef struct wmNDOFMotionData {
        /* awfully similar to GHOST_TEventNDOFMotionData... */
-       // Each component normally ranges from -1 to +1, but can exceed that.
-       // These use blender standard view coordinates, with positive rotations being CCW about the axis.
+       /* Each component normally ranges from -1 to +1, but can exceed that.
+        * These use blender standard view coordinates, with positive rotations being CCW about the axis. */
        union {
-               float tvec[3]; // translation
+               float tvec[3]; /* translation */
                struct { float tx, ty, tz; };
-               };
+       };
        union {
-               float rvec[3]; // rotation:
+               float rvec[3]; /* rotation: */
                struct { float rx, ry, rz; };
-               };
-               // axis = (rx,ry,rz).normalized
-               // amount = (rx,ry,rz).magnitude [in revolutions, 1.0 = 360 deg]
-       float dt; // time since previous NDOF Motion event
-       wmProgress progress; // is this the first event, the last, or one of many in between?
+       };
+       /* axis = (rx,ry,rz).normalized */
+       /* amount = (rx,ry,rz).magnitude [in revolutions, 1.0 = 360 deg] */
+       float dt; /* time since previous NDOF Motion event */
+       wmProgress progress; /* is this the first event, the last, or one of many in between? */
 } wmNDOFMotionData;
 
 typedef struct wmTimer {
@@ -428,9 +509,6 @@ typedef struct wmTimer {
        int sleep;                              /* internal, put timers to sleep when needed */
 } wmTimer;
 
-/* Default context for operator names/labels. */
-#define WM_OPERATOR_DEFAULT_I18NCONTEXT "Operator"
-
 typedef struct wmOperatorType {
        const char *name;               /* text for ui, undo */
        const char *idname;             /* unique identifier */
@@ -440,7 +518,11 @@ typedef struct wmOperatorType {
         * parameters may be provided through operator properties. cannot use
         * any interface code or input device state.
         * - see defines below for return values */
-       int (*exec)(struct bContext *, struct wmOperator *);
+       int (*exec)(struct bContext *, struct wmOperator *)
+#ifdef __GNUC__
+       __attribute__((warn_unused_result))
+#endif
+       ;
        
        /* this callback executes on a running operator whenever as property
         * is changed. It can correct its own properties or report errors for
@@ -452,13 +534,25 @@ typedef struct wmOperatorType {
         * any further events are handled in modal. if the operation is
         * canceled due to some external reason, cancel is called
         * - see defines below for return values */
-       int (*invoke)(struct bContext *, struct wmOperator *, struct wmEvent *);
+       int (*invoke)(struct bContext *, struct wmOperator *, const struct wmEvent *)
+#ifdef __GNUC__
+       __attribute__((warn_unused_result))
+#endif
+       ;
        int (*cancel)(struct bContext *, struct wmOperator *);
-       int (*modal)(struct bContext *, struct wmOperator *, struct wmEvent *);
+       int (*modal)(struct bContext *, struct wmOperator *, const struct wmEvent *)
+#ifdef __GNUC__
+       __attribute__((warn_unused_result))
+#endif
+       ;
 
        /* verify if the operator can be executed in the current context, note
         * that the operator might still fail to execute even if this return true */
-       int (*poll)(struct bContext *);
+       int (*poll)(struct bContext *)
+#ifdef __GNUC__
+       __attribute__((warn_unused_result))
+#endif
+       ;
 
        /* optional panel for redo and repeat, autogenerated if not set */
        void (*ui)(struct bContext *, struct wmOperator *);
@@ -469,8 +563,8 @@ typedef struct wmOperatorType {
        /* previous settings - for initializing on re-use */
        struct IDProperty *last_properties;
 
-       /* rna property to use for generic invoke functions.
-        * menus, enum search... etc */
+       /* Default rna property to use for generic invoke functions.
+        * menus, enum search... etc. Example: Enum 'type' for a Delete menu */
        PropertyRNA *prop;
 
        /* struct wmOperatorTypeMacro */
@@ -482,7 +576,11 @@ typedef struct wmOperatorType {
        /* only used for operators defined with python
         * use to store pointers to python functions */
        void *pyop_data;
-       int (*pyop_poll)(struct bContext *, struct wmOperatorType *ot);
+       int (*pyop_poll)(struct bContext *, struct wmOperatorType *ot)
+#ifdef __GNUC__
+       __attribute__((warn_unused_result))
+#endif
+       ;
 
        /* RNA integration */
        ExtensionRNA ext;
@@ -547,7 +645,7 @@ typedef struct wmDropBox {
        struct wmDropBox *next, *prev;
        
        /* test if the dropbox is active, then can print optype name */
-       int (*poll)(struct bContext *, struct wmDrag *, wmEvent *);
+       int (*poll)(struct bContext *, struct wmDrag *, const wmEvent *);
 
        /* before exec, this copies drag info to wmDrop properties */
        void (*copy)(struct wmDrag *, struct wmDropBox *);