Bugfix #33032
[blender.git] / source / blender / windowmanager / WM_types.h
index 5048166c8b7cfd04c127adbaf8b74ca97084a946..094df73bbd98cb66fca99050f78527e376c45e0e 100644 (file)
@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * ***** BEGIN GPL LICENSE BLOCK *****
  *
  * This program is free software; you can redistribute it and/or
  *  \ingroup wm
  */
 
-#ifndef WM_TYPES_H
-#define WM_TYPES_H
+#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" {
@@ -46,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"
@@ -139,13 +207,13 @@ typedef struct wmNotifier {
 } wmNotifier;
 
 
-/* 4 levels 
-
-0xFF000000; category
-0x00FF0000; data
-0x0000FF00; data subtype (unused?)
-0x000000FF; action
-*/
+/* 4 levels
+ *
+ * 0xFF000000; category
+ * 0x00FF0000; data
+ * 0x0000FF00; data subtype (unused?)
+ * 0x000000FF; action
+ */
 
 /* category */
 #define NOTE_CATEGORY          0xFF000000
@@ -168,6 +236,9 @@ typedef struct wmNotifier {
 #define NC_NODE                                (17<<24)
 #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
@@ -277,6 +348,7 @@ typedef struct wmNotifier {
 #define ND_SPACE_SEQUENCER             (16<<16)
 #define ND_SPACE_NODE_VIEW             (17<<16)
 #define ND_SPACE_CHANGED               (18<<16) /*sent to a new editor type after it's replaced an old one*/
+#define ND_SPACE_CLIP                  (19<<16)
 
 /* subtype, 256 entries too */
 #define NOTE_SUBTYPE           0x0000FF00
@@ -346,11 +418,13 @@ typedef struct wmEvent {
        short val;                      /* press, release, scrollvalue */
        int x, y;                       /* mouse pointer position, screen coord */
        int mval[2];            /* region mouse position, name convention pre 2.5 :) */
-       char utf8_buf[6];       /* from, ghost if utf8 is enabled for the platform */
-       char ascii;                     /* from ghost, fallback if utf8 isnt set */
+       char utf8_buf[6];       /* from, ghost if utf8 is enabled for the platform,
+                                                * BLI_str_utf8_size() must _always_ be valid, check
+                                                * when assigning s we don't need to check on every access after */
+       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;
@@ -361,7 +435,8 @@ 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;
@@ -382,30 +457,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 {
@@ -426,7 +501,6 @@ typedef struct wmTimer {
        int sleep;                              /* internal, put timers to sleep when needed */
 } wmTimer;
 
-
 typedef struct wmOperatorType {
        const char *name;               /* text for ui, undo */
        const char *idname;             /* unique identifier */
@@ -436,7 +510,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
@@ -446,15 +524,27 @@ typedef struct wmOperatorType {
 
        /* for modal temporary operators, initially invoke is called. then
         * any further events are handled in modal. if the operation is
-        * cancelled due to some external reason, cancel is called
+        * 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 *, 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 *, 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 *);
@@ -462,8 +552,11 @@ typedef struct wmOperatorType {
        /* rna for properties */
        struct StructRNA *srna;
 
-       /* rna property to use for generic invoke functions.
-        * menus, enum search... etc */
+       /* previous settings - for initializing on re-use */
+       struct IDProperty *last_properties;
+
+       /* Default rna property to use for generic invoke functions.
+        * menus, enum search... etc. Example: Enum 'type' for a Delete menu */
        PropertyRNA *prop;
 
        /* struct wmOperatorTypeMacro */
@@ -475,7 +568,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;
@@ -524,14 +621,14 @@ typedef struct wmDrag {
        
        int icon, type;                                 /* type, see WM_DRAG defines above */
        void *poin;
-       char path[240]; /* FILE_MAX */
+       char path[1024]; /* FILE_MAX */
        double value;
        
        struct ImBuf *imb;                                              /* if no icon but imbuf should be drawn around cursor */
        float scale;
        int sx, sy;
        
-       char opname[240]; /* FILE_MAX */                        /* if set, draws operator name*/
+       char opname[200]; /* if set, draws operator name*/
 } wmDrag;
 
 /* dropboxes are like keymaps, part of the screen/area/region definition */
@@ -567,5 +664,5 @@ typedef struct RecentFile {
 }
 #endif
 
-#endif /* WM_TYPES_H */
+#endif /* __WM_TYPES_H__ */