include/IGUIButton.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_GUI_BUTTON_H_INCLUDED__\r
   6 #define __I_GUI_BUTTON_H_INCLUDED__\r
   7 \r
   8 #include "IGUIElement.h"\r
   9 \r
  10 namespace irr\r
  11 {\r
  12 \r
  13 namespace video\r
  14 {\r
  15         class ITexture;\r
  16 } // end namespace video\r
  17 \r
  18 namespace gui\r
  19 {\r
  20         class IGUIFont;\r
  21         class IGUISpriteBank;\r
  22 \r
  23         //! Current state of buttons used for drawing sprites.\r
  24         //! Note that up to 3 states can be active at the same time:\r
  25         //! EGBS_BUTTON_UP or EGBS_BUTTON_DOWN\r
  26         //! EGBS_BUTTON_MOUSE_OVER or EGBS_BUTTON_MOUSE_OFF\r
  27         //! EGBS_BUTTON_FOCUSED or EGBS_BUTTON_NOT_FOCUSED\r
  28         enum EGUI_BUTTON_STATE\r
  29         {\r
  30                 //! The button is not pressed.\r
  31                 EGBS_BUTTON_UP=0,\r
  32                 //! The button is currently pressed down.\r
  33                 EGBS_BUTTON_DOWN,\r
  34                 //! The mouse cursor is over the button\r
  35                 EGBS_BUTTON_MOUSE_OVER,\r
  36                 //! The mouse cursor is not over the button\r
  37                 EGBS_BUTTON_MOUSE_OFF,\r
  38                 //! The button has the focus\r
  39                 EGBS_BUTTON_FOCUSED,\r
  40                 //! The button doesn't have the focus\r
  41                 EGBS_BUTTON_NOT_FOCUSED,\r
  42                 //! The button is disabled All other states are ignored in that case.\r
  43                 EGBS_BUTTON_DISABLED,\r
  44                 //! not used, counts the number of enumerated items\r
  45                 EGBS_COUNT\r
  46         };\r
  47 \r
  48         //! Names for gui button state icons\r
  49         const c8* const GUIButtonStateNames[EGBS_COUNT+1] =\r
  50         {\r
  51                 "buttonUp",\r
  52                 "buttonDown",\r
  53                 "buttonMouseOver",\r
  54                 "buttonMouseOff",\r
  55                 "buttonFocused",\r
  56                 "buttonNotFocused",\r
  57                 "buttonDisabled",\r
  58                 0       // count\r
  59         };\r
  60 \r
  61         //! State of buttons used for drawing texture images.\r
  62         //! Note that only a single state is active at a time\r
  63         //! Also when no image is defined for a state it will use images from another state\r
  64         //! and if that state is not set from the replacement for that,etc.\r
  65         //! So in many cases setting EGBIS_IMAGE_UP and EGBIS_IMAGE_DOWN is sufficient.\r
  66         enum EGUI_BUTTON_IMAGE_STATE\r
  67         {\r
  68                 //! When no other states have images they will all use this one.\r
  69                 EGBIS_IMAGE_UP,\r
  70                 //! When not set EGBIS_IMAGE_UP is used.\r
  71                 EGBIS_IMAGE_UP_MOUSEOVER,\r
  72                 //! When not set EGBIS_IMAGE_UP_MOUSEOVER is used.\r
  73                 EGBIS_IMAGE_UP_FOCUSED,\r
  74                 //! When not set EGBIS_IMAGE_UP_FOCUSED is used.\r
  75                 EGBIS_IMAGE_UP_FOCUSED_MOUSEOVER,\r
  76                 //! When not set EGBIS_IMAGE_UP is used.\r
  77                 EGBIS_IMAGE_DOWN,\r
  78                 //! When not set EGBIS_IMAGE_DOWN is used.\r
  79                 EGBIS_IMAGE_DOWN_MOUSEOVER,\r
  80                 //! When not set EGBIS_IMAGE_DOWN_MOUSEOVER is used.\r
  81                 EGBIS_IMAGE_DOWN_FOCUSED,\r
  82                 //! When not set EGBIS_IMAGE_DOWN_FOCUSED is used.\r
  83                 EGBIS_IMAGE_DOWN_FOCUSED_MOUSEOVER,\r
  84                 //! When not set EGBIS_IMAGE_UP or EGBIS_IMAGE_DOWN are used (depending on button state).\r
  85                 EGBIS_IMAGE_DISABLED,\r
  86                 //! not used, counts the number of enumerated items\r
  87                 EGBIS_COUNT\r
  88         };\r
  89 \r
  90         //! Names for gui button image states\r
  91         const c8* const GUIButtonImageStateNames[EGBIS_COUNT+1] =\r
  92         {\r
  93                 "Image",        // not "ImageUp" as it otherwise breaks serialization of old files\r
  94                 "ImageUpOver",\r
  95                 "ImageUpFocused",\r
  96                 "ImageUpFocusedOver",\r
  97                 "PressedImage", // not "ImageDown" as it otherwise breaks serialization of old files\r
  98                 "ImageDownOver",\r
  99                 "ImageDownFocused",\r
 100                 "ImageDownFocusedOver",\r
 101                 "ImageDisabled",\r
 102                 0       // count\r
 103         };\r
 104 \r
 105         //! GUI Button interface.\r
 106         /** \par This element can create the following events of type EGUI_EVENT_TYPE:\r
 107         \li EGET_BUTTON_CLICKED\r
 108         */\r
 109         class IGUIButton : public IGUIElement\r
 110         {\r
 111         public:\r
 112 \r
 113                 //! constructor\r
 114                 IGUIButton(IGUIEnvironment* environment, IGUIElement* parent, s32 id, core::rect<s32> rectangle)\r
 115                         : IGUIElement(EGUIET_BUTTON, environment, parent, id, rectangle) {}\r
 116 \r
 117                 //! Sets another skin independent font.\r
 118                 /** If this is set to zero, the button uses the font of the skin.\r
 119                 \param font: New font to set. */\r
 120                 virtual void setOverrideFont(IGUIFont* font=0) = 0;\r
 121 \r
 122                 //! Gets the override font (if any)\r
 123                 /** \return The override font (may be 0) */\r
 124                 virtual IGUIFont* getOverrideFont(void) const = 0;\r
 125 \r
 126                 //! Get the font which is used right now for drawing\r
 127                 /** Currently this is the override font when one is set and the\r
 128                 font of the active skin otherwise */\r
 129                 virtual IGUIFont* getActiveFont() const = 0;\r
 130 \r
 131                 //! Sets another color for the button text.\r
 132                 /** When set, this color is used instead of EGDC_BUTTON_TEXT/EGDC_GRAY_TEXT.\r
 133                 You don't need to call enableOverrideColor(true), that's done by this function.\r
 134                 If you want the the color of the skin back, call enableOverrideColor(false);\r
 135                 \param color: New color of the text. */\r
 136                 virtual void setOverrideColor(video::SColor color) = 0;\r
 137 \r
 138                 //! Gets the override color\r
 139                 /** \return: The override color */\r
 140                 virtual video::SColor getOverrideColor(void) const = 0;\r
 141 \r
 142                 //! Gets the currently used text color\r
 143                 /** Either a skin-color for the current state or the override color */\r
 144                 virtual video::SColor getActiveColor() const = 0;\r
 145 \r
 146                 //! Sets if the button text should use the override color or the color in the gui skin.\r
 147                 /** \param enable: If set to true, the override color, which can be set\r
 148                 with IGUIStaticText::setOverrideColor is used, otherwise the\r
 149                 EGDC_BUTTON_TEXT or EGDC_GRAY_TEXT color of the skin. */\r
 150                 virtual void enableOverrideColor(bool enable) = 0;\r
 151 \r
 152                 //! Checks if an override color is enabled\r
 153                 /** \return true if the override color is enabled, false otherwise */\r
 154                 virtual bool isOverrideColorEnabled(void) const = 0;\r
 155 \r
 156                 //! Sets an image which should be displayed on the button when it is in the given state.\r
 157                 /** Only one image-state can be active at a time. Images are drawn below sprites.\r
 158                 If a state is without image it will try to use images from other states as described\r
 159                 in ::EGUI_BUTTON_IMAGE_STATE.\r
 160                 Images are a little less flexible than sprites, but easier to use.\r
 161                 \param state: One of ::EGUI_BUTTON_IMAGE_STATE\r
 162                 \param image: Image to be displayed or NULL to remove the image\r
 163                 \param sourceRect: Source rectangle on the image texture. When width or height are 0 then the full texture-size is used (default). */\r
 164                 virtual void setImage(EGUI_BUTTON_IMAGE_STATE state, video::ITexture* image=0, const core::rect<s32>& sourceRect=core::rect<s32>(0,0,0,0)) = 0;\r
 165 \r
 166                 //! Sets an image which should be displayed on the button when it is in normal state.\r
 167                 /** This is identical to calling setImage(EGBIS_IMAGE_UP, image); and might be deprecated in future revisions.\r
 168                 \param image: Image to be displayed */\r
 169                 virtual void setImage(video::ITexture* image=0) = 0;\r
 170 \r
 171                 //! Sets a background image for the button when it is in normal state.\r
 172                 /** This is identical to calling setImage(EGBIS_IMAGE_UP, image, sourceRect); and might be deprecated in future revisions.\r
 173                 \param image: Texture containing the image to be displayed\r
 174                 \param sourceRect: Position in the texture, where the image is located.\r
 175                 When width or height are 0 then the full texture-size is used */\r
 176                 virtual void setImage(video::ITexture* image, const core::rect<s32>& sourceRect) = 0;\r
 177 \r
 178                 //! Sets a background image for the button when it is in pressed state.\r
 179                 /** This is identical to calling setImage(EGBIS_IMAGE_DOWN, image); and might be deprecated in future revisions.\r
 180                 If no images is specified for the pressed state via\r
 181                 setPressedImage(), this image is also drawn in pressed state.\r
 182                 \param image: Image to be displayed */\r
 183                 virtual void setPressedImage(video::ITexture* image=0) = 0;\r
 184 \r
 185                 //! Sets an image which should be displayed on the button when it is in pressed state.\r
 186                 /** This is identical to calling setImage(EGBIS_IMAGE_DOWN, image, sourceRect); and might be deprecated in future revisions.\r
 187                 \param image: Texture containing the image to be displayed\r
 188                 \param sourceRect: Position in the texture, where the image is located */\r
 189                 virtual void setPressedImage(video::ITexture* image, const core::rect<s32>& sourceRect) = 0;\r
 190 \r
 191 \r
 192                 //! Sets the sprite bank used by the button\r
 193                 /** NOTE: The spritebank itself is _not_ serialized so far. The sprites are serialized.\r
 194                 Which means after loading the gui you still have to set the spritebank manually. */\r
 195                 virtual void setSpriteBank(IGUISpriteBank* bank=0) = 0;\r
 196 \r
 197                 //! Sets the animated sprite for a specific button state\r
 198                 /** Several sprites can be drawn at the same time.\r
 199                 Sprites can be animated.\r
 200                 Sprites are drawn above the images.\r
 201                 \param index: Number of the sprite within the sprite bank, use -1 for no sprite\r
 202                 \param state: State of the button to set the sprite for\r
 203                 \param index: The sprite number from the current sprite bank\r
 204                 \param color: The color of the sprite\r
 205                 \param loop: True if the animation should loop, false if not\r
 206                 \param scale: True if the sprite should scale to button size, false if not      */\r
 207                 virtual void setSprite(EGUI_BUTTON_STATE state, s32 index,\r
 208                                 video::SColor color=video::SColor(255,255,255,255), bool loop=false, bool scale=false) = 0;\r
 209 \r
 210                 //! Get the sprite-index for the given state or -1 when no sprite is set\r
 211                 virtual s32 getSpriteIndex(EGUI_BUTTON_STATE state) const = 0;\r
 212 \r
 213                 //! Get the sprite color for the given state. Color is only used when a sprite is set.\r
 214                 virtual video::SColor getSpriteColor(EGUI_BUTTON_STATE state) const = 0;\r
 215 \r
 216                 //! Returns if the sprite in the given state does loop\r
 217                 virtual bool getSpriteLoop(EGUI_BUTTON_STATE state) const = 0;\r
 218 \r
 219                 //! Returns if the sprite in the given state is scaled\r
 220                 virtual bool getSpriteScale(EGUI_BUTTON_STATE state) const = 0;\r
 221 \r
 222                 //! Sets if the button should behave like a push button.\r
 223                 /** Which means it can be in two states: Normal or Pressed. With a click on the button,\r
 224                 the user can change the state of the button. */\r
 225                 virtual void setIsPushButton(bool isPushButton=true) = 0;\r
 226 \r
 227                 //! Sets the pressed state of the button if this is a pushbutton\r
 228                 virtual void setPressed(bool pressed=true) = 0;\r
 229 \r
 230                 //! Returns if the button is currently pressed\r
 231                 virtual bool isPressed() const = 0;\r
 232 \r
 233                 //! Sets if the alpha channel should be used for drawing background images on the button (default is false)\r
 234                 virtual void setUseAlphaChannel(bool useAlphaChannel=true) = 0;\r
 235 \r
 236                 //! Returns if the alpha channel should be used for drawing background images on the button\r
 237                 virtual bool isAlphaChannelUsed() const = 0;\r
 238 \r
 239                 //! Returns whether the button is a push button\r
 240                 virtual bool isPushButton() const = 0;\r
 241 \r
 242                 //! Sets if the button should use the skin to draw its border and button face (default is true)\r
 243                 virtual void setDrawBorder(bool border=true) = 0;\r
 244 \r
 245                 //! Returns if the border and button face are being drawn using the skin\r
 246                 virtual bool isDrawingBorder() const = 0;\r
 247 \r
 248                 //! Sets if the button should scale the button images to fit\r
 249                 virtual void setScaleImage(bool scaleImage=true) = 0;\r
 250 \r
 251                 //! Checks whether the button scales the used images\r
 252                 virtual bool isScalingImage() const = 0;\r
 253 \r
 254                 //! Get if the shift key was pressed in last EGET_BUTTON_CLICKED event\r
 255                 /** Generated together with event, so info is available in the event-receiver.  */\r
 256                 virtual bool getClickShiftState() const = 0;\r
 257 \r
 258                 //! Get if the control key was pressed in last EGET_BUTTON_CLICKED event\r
 259                 /** Generated together with event, so info is available in the event-receiver.  */\r
 260                 virtual bool getClickControlState() const = 0;\r
 261         };\r
 262 \r
 263 \r
 264 } // end namespace gui\r
 265 } // end namespace irr\r
 266 \r
 267 #endif\r
 268 \r