include/ICursorControl.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_CURSOR_CONTROL_H_INCLUDED__\r
   6 #define __I_CURSOR_CONTROL_H_INCLUDED__\r
   7 \r
   8 #include "IReferenceCounted.h"\r
   9 #include "position2d.h"\r
  10 #include "rect.h"\r
  11 \r
  12 namespace irr\r
  13 {\r
  14 namespace gui\r
  15 {\r
  16 \r
  17         class IGUISpriteBank;\r
  18 \r
  19         //! Default icons for cursors\r
  20         enum ECURSOR_ICON\r
  21         {\r
  22                 // Following cursors might be system specific, or might use an Irrlicht icon-set. No guarantees so far.\r
  23                 ECI_NORMAL,     // arrow\r
  24                 ECI_CROSS,      // Crosshair\r
  25                 ECI_HAND,       // Hand\r
  26                 ECI_HELP,       // Arrow and question mark\r
  27                 ECI_IBEAM,      // typical text-selection cursor\r
  28                 ECI_NO,         // should not click icon\r
  29                 ECI_WAIT,       // hourclass\r
  30                 ECI_SIZEALL,    // arrow in all directions\r
  31                 ECI_SIZENESW,   // resizes in direction north-east or south-west\r
  32                 ECI_SIZENWSE,   // resizes in direction north-west or south-east\r
  33                 ECI_SIZENS,     // resizes in direction north or south\r
  34                 ECI_SIZEWE,     // resizes in direction west or east\r
  35                 ECI_UP,         // up-arrow\r
  36 \r
  37                 // Implementer note: Should we add system specific cursors, which use guaranteed the system icons,\r
  38                 // then I would recommend using a naming scheme like ECI_W32_CROSS, ECI_X11_CROSSHAIR and adding those\r
  39                 // additionally.\r
  40 \r
  41                 ECI_COUNT               // maximal of defined cursors. Note that higher values can be created at runtime\r
  42         };\r
  43 \r
  44         //! Names for ECURSOR_ICON\r
  45         const c8* const GUICursorIconNames[ECI_COUNT+1] =\r
  46         {\r
  47                 "normal",\r
  48                 "cross",\r
  49                 "hand",\r
  50                 "help",\r
  51                 "ibeam",\r
  52                 "no",\r
  53                 "wait",\r
  54                 "sizeall",\r
  55                 "sizenesw",\r
  56                 "sizenwse",\r
  57                 "sizens",\r
  58                 "sizewe",\r
  59                 "sizeup",\r
  60                 0\r
  61         };\r
  62 \r
  63         //! structure used to set sprites as cursors.\r
  64         struct SCursorSprite\r
  65         {\r
  66                 SCursorSprite()\r
  67                 : SpriteBank(0), SpriteId(-1)\r
  68                 {\r
  69                 }\r
  70 \r
  71                 SCursorSprite( gui::IGUISpriteBank * spriteBank, s32 spriteId, const core::position2d<s32> &hotspot=(core::position2d<s32>(0,0)) )\r
  72                 : SpriteBank(spriteBank), SpriteId(spriteId), HotSpot(hotspot)\r
  73                 {\r
  74                 }\r
  75 \r
  76                 IGUISpriteBank * SpriteBank;\r
  77                 s32 SpriteId;\r
  78                 core::position2d<s32> HotSpot;\r
  79         };\r
  80 \r
  81         //! platform specific behavior flags for the cursor\r
  82         enum ECURSOR_PLATFORM_BEHAVIOR\r
  83         {\r
  84                 //! default - no platform specific behavior\r
  85                 ECPB_NONE = 0,\r
  86 \r
  87                 //! On X11 try caching cursor updates as XQueryPointer calls can be expensive.\r
  88                 /** Update cursor positions only when the irrlicht timer has been updated or the timer is stopped.\r
  89                         This means you usually get one cursor update per device->run() which will be fine in most cases.\r
  90                         See this forum-thread for a more detailed explanation:\r
  91                         http://irrlicht.sourceforge.net/forum/viewtopic.php?f=7&t=45525\r
  92                 */\r
  93                 ECPB_X11_CACHE_UPDATES = 1\r
  94         };\r
  95 \r
  96         //! Interface to manipulate the mouse cursor.\r
  97         class ICursorControl : public virtual IReferenceCounted\r
  98         {\r
  99         public:\r
 100 \r
 101                 //! Changes the visible state of the mouse cursor.\r
 102                 /** \param visible: The new visible state. If true, the cursor will be visible,\r
 103                 if false, it will be invisible. */\r
 104                 virtual void setVisible(bool visible) = 0;\r
 105 \r
 106                 //! Returns if the cursor is currently visible.\r
 107                 /** \return True if the cursor flag is set to visible, false if not. */\r
 108                 virtual bool isVisible() const = 0;\r
 109 \r
 110                 //! Sets the new position of the cursor.\r
 111                 /** The position must be\r
 112                 between (0.0f, 0.0f) and (1.0f, 1.0f), where (0.0f, 0.0f) is\r
 113                 the top left corner and (1.0f, 1.0f) is the bottom right corner of the\r
 114                 render window.\r
 115                 \param pos New position of the cursor. */\r
 116                 virtual void setPosition(const core::position2d<f32> &pos) = 0;\r
 117 \r
 118                 //! Sets the new position of the cursor.\r
 119                 /** The position must be\r
 120                 between (0.0f, 0.0f) and (1.0f, 1.0f), where (0.0f, 0.0f) is\r
 121                 the top left corner and (1.0f, 1.0f) is the bottom right corner of the\r
 122                 render window.\r
 123                 \param x New x-coord of the cursor.\r
 124                 \param y New x-coord of the cursor. */\r
 125                 virtual void setPosition(f32 x, f32 y) = 0;\r
 126 \r
 127                 //! Sets the new position of the cursor.\r
 128                 /** \param pos: New position of the cursor. The coordinates are pixel units. */\r
 129                 virtual void setPosition(const core::position2d<s32> &pos) = 0;\r
 130 \r
 131                 //! Sets the new position of the cursor.\r
 132                 /** \param x New x-coord of the cursor. The coordinates are pixel units.\r
 133                 \param y New y-coord of the cursor. The coordinates are pixel units. */\r
 134                 virtual void setPosition(s32 x, s32 y) = 0;\r
 135 \r
 136                 //! Returns the current position of the mouse cursor.\r
 137                 /** \param updateCursor When true ask system/OS for current cursor position. \r
 138                         When false return the last known (buffered) position ( this is useful to \r
 139                         check what has become of a setPosition call with float numbers).\r
 140                 \return Returns the current position of the cursor. The returned position\r
 141                 is the position of the mouse cursor in pixel units. */\r
 142                 virtual const core::position2d<s32>& getPosition(bool updateCursor=true) = 0;\r
 143 \r
 144                 //! Returns the current position of the mouse cursor.\r
 145                 /** \param updateCursor When true ask system/OS for current cursor position. \r
 146                         When false return the last known (buffered) position (this is \r
 147                         useful to check what has become of a setPosition call with float numbers\r
 148                         and is often different from the values you passed in setPosition).\r
 149                 \return Returns the current position of the cursor. The returned position\r
 150                 is a value between (0.0f, 0.0f) and (1.0f, 1.0f), where (0.0f, 0.0f) is\r
 151                 the top left corner and (1.0f, 1.0f) is the bottom right corner of the\r
 152                 render window. */\r
 153                 virtual core::position2d<f32> getRelativePosition(bool updateCursor=true) = 0;\r
 154 \r
 155                 //! Sets an absolute reference rect for setting and retrieving the cursor position.\r
 156                 /** If this rect is set, the cursor position is not being calculated relative to\r
 157                 the rendering window but to this rect. You can set the rect pointer to 0 to disable\r
 158                 this feature again. This feature is useful when rendering into parts of foreign windows\r
 159                 for example in an editor.\r
 160                 \param rect: A pointer to an reference rectangle or 0 to disable the reference rectangle.*/\r
 161                 virtual void setReferenceRect(core::rect<s32>* rect=0) = 0;\r
 162 \r
 163                 //! Internally fixes the mouse position, and reports relative mouse movement compared to the old position \r
 164                 /** Specific to SDL */\r
 165                 virtual void setRelativeMode(bool relative) {};\r
 166 \r
 167                 //! Sets the active cursor icon\r
 168                 /** Setting cursor icons is so far only supported on Win32 and Linux */\r
 169                 virtual void setActiveIcon(ECURSOR_ICON iconId) {}\r
 170 \r
 171                 //! Gets the currently active icon\r
 172                 virtual ECURSOR_ICON getActiveIcon() const { return gui::ECI_NORMAL; }\r
 173 \r
 174                 //! Add a custom sprite as cursor icon.\r
 175                 /** \return Identification for the icon */\r
 176                 virtual ECURSOR_ICON addIcon(const gui::SCursorSprite& icon) { return gui::ECI_NORMAL; }\r
 177 \r
 178                 //! replace a cursor icon.\r
 179                 /** Changing cursor icons is so far only supported on Win32 and Linux\r
 180                         Note that this only changes the icons within your application, system cursors outside your\r
 181                         application will not be affected.\r
 182                 */\r
 183                 virtual void changeIcon(ECURSOR_ICON iconId, const gui::SCursorSprite& sprite) {}\r
 184 \r
 185                 //! Return a system-specific size which is supported for cursors. Larger icons will fail, smaller icons might work.\r
 186                 virtual core::dimension2di getSupportedIconSize() const { return core::dimension2di(0,0); }\r
 187 \r
 188                 //! Set platform specific behavior flags.\r
 189                 virtual void setPlatformBehavior(ECURSOR_PLATFORM_BEHAVIOR behavior) {}\r
 190 \r
 191                 //! Return platform specific behavior.\r
 192                 /** \return Behavior set by setPlatformBehavior or ECPB_NONE for platforms not implementing specific behaviors.\r
 193                 */\r
 194                 virtual ECURSOR_PLATFORM_BEHAVIOR getPlatformBehavior() const { return ECPB_NONE; }\r
 195         };\r
 196 \r
 197 \r
 198 } // end namespace gui\r
 199 } // end namespace irr\r
 200 \r
 201 #endif\r
 202 \r