inc/FUiCtrlButton.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlButton.h
  20  * @brief       This is the header file for the %Button class.
  21  *
  22  * This header file contains the declarations of the %Button class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_BUTTON_H_
  26 #define _FUI_CTRL_BUTTON_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FGrpRectangle.h>
  31 #include <FGrpColor.h>
  32 #include <FUiIActionEventListener.h>
  33 #include <FUiControl.h>
  34 #include <FUiContainer.h>
  35 #include <FUiCtrlControlsTypes.h>
  36
  37 namespace Tizen { namespace Ui { namespace Controls
  38 {
  39 /**
  40  * @enum ButtonStatus
  41  *
  42  * Defines the %Button control status.
  43  *
  44  * @since       2.0
  45  */
  46 enum ButtonStatus
  47 {
  48         BUTTON_STATUS_NORMAL,          /**< The normal status */
  49         BUTTON_STATUS_DISABLED,        /**< The disabled status */
  50         BUTTON_STATUS_PRESSED,         /**< The pressed status */
  51         BUTTON_STATUS_HIGHLIGHTED      /**< The highlighted status */
  52 };
  53
  54 /**
  55  * @class       Button
  56  * @brief This class defines the common behavior of a %Button control.
  57  *
  58  * @since 2.0
  59  *
  60  * The %Button class displays a rectangular area that can be pressed.
  61  *
  62  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_button.htm">Buttons</a>.
  63  *
  64  * The following example demonstrates how to use the %Button class.
  65  *
  66  *
  67  * @code
  68 // Sample code for ButtonSample.h
  69 #include <FUi.h>
  70
  71 class ButtonSample
  72         : public Tizen::Ui::Controls::Form
  73         , public Tizen::Ui::IActionEventListener
  74 {
  75 public:
  76         ButtonSample(void)
  77         : __pButton(null)
  78         , __pBitmapButton(null){}
  79
  80         bool Initialize(void);
  81         virtual result OnInitializing(void);
  82
  83         // IActionEventListener
  84         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  85
  86 private:
  87         static const int ID_BUTTON  = 101;
  88         static const int ID_BITMAP_BUTTON = 102;
  89
  90         Tizen::Ui::Controls::Button* __pButton;
  91         Tizen::Ui::Controls::Button* __pBitmapButton;
  92 };
  93
  94  *      @endcode
  95  *
  96  *      @code
  97 // Sample code for ButtonSample.cpp
  98 #include <FApp.h>
  99 #include <FGraphics.h>
 100
 101 #include "ButtonSample.h"
 102
 103 using namespace Tizen::App;
 104 using namespace Tizen::Graphics;
 105 using namespace Tizen::Ui::Controls;
 106
 107 bool
 108 ButtonSample::Initialize(void)
 109 {
 110         Construct(FORM_STYLE_NORMAL);
 111         return true;
 112 }
 113
 114 result
 115 ButtonSample::OnInitializing(void)
 116 {
 117         result r = E_SUCCESS;
 118
 119         // Creates an instance of Button
 120         __pButton = new Button();
 121         __pButton->Construct(Rectangle(50, 50, 200, 200), L"Button");
 122         __pButton->SetActionId(ID_BUTTON);
 123         __pButton->AddActionEventListener(*this);
 124
 125         AddControl(*__pButton);
 126
 127         // Creates an instance of Button for bitmap button
 128         __pBitmapButton = new Button();
 129         __pBitmapButton->Construct(Rectangle(260, 50, 200, 200));
 130         __pBitmapButton->SetActionId(ID_BITMAP_BUTTON);
 131         __pBitmapButton->AddActionEventListener(*this);
 132
 133         // Gets instances of Bitmap
 134         AppResource *pAppResource = Application::GetInstance()->GetAppResource();
 135         Bitmap* pBitmapNormal = pAppResource->GetBitmapN(L"tizen.png");
 136         Bitmap* pBitmapPressed = pAppResource->GetBitmapN(L"tizen.png");
 137
 138         // Sets the bitmaps to the bitmap button
 139         __pBitmapButton->SetNormalBackgroundBitmap(*pBitmapNormal);
 140         __pBitmapButton->SetPressedBackgroundBitmap(*pBitmapPressed);
 141
 142         // Deallocates bitmaps
 143         delete pBitmapNormal;
 144         delete pBitmapPressed;
 145
 146         // Adds the bitmap button to the form
 147         AddControl(*__pBitmapButton);
 148
 149         return r;
 150 }
 151
 152 // IActionEventListener implementation
 153 void
 154 ButtonSample::OnActionPerformed(const Control& source, int actionId)
 155 {
 156         switch (actionId)
 157         {
 158         case ID_BUTTON:
 159                 {
 160                         // ....
 161                 }
 162                 break;
 163         case ID_BITMAP_BUTTON:
 164                 {
 165                         // ....
 166                 }
 167                 break;
 168         default:
 169                 break;
 170         }
 171 }
 172  * @endcode
 173  *
 174  */
 175 class _OSP_EXPORT_ Button
 176         : public Tizen::Ui::Control
 177 {
 178 public:
 179         /**
 180          * This is the default constructor for this class.
 181          *
 182          * @since               2.0
 183          */
 184         Button(void);
 185
 186         /**
 187          * This is the destructor for this class.
 188          *
 189          * @since               2.0
 190          */
 191         virtual ~Button(void);
 192
 193         /**
 194          * Initializes this instance of %Button with the specified parameters.
 195          *
 196          * @since                       2.0
 197          *
 198          * @return              An error code
 199          * @param[in]   rect                    An instance of the Rectangle class @n
 200          *                                                              This instance represents the x and y coordinates of the top-left corner @n
 201          *                              of the created window along with its width and height. @n
 202          * @param[in]   text                    The text to display on the button
 203          * @exception   E_SUCCESS                       The method is successful.
 204          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 205          * @exception   E_SYSTEM                        A system error has occurred.
 206          * @remarks             A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
 207          *                              adding the control to the container.
 208          * @remarks             To display the text in multi-lines or to denote the end of line, use '\\n'.
 209          * @remarks             The size of the control must be within the range defined by the minimum and maximum sizes.
 210          */
 211         result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text = L"");
 212
 213         /**
 214          * Initializes this instance of %Button with the specified parameters.
 215          *
 216          * @since                       2.1
 217          *
 218          * @return              An error code
 219          * @param[in]   rect                    An instance of the Rectangle class @n
 220          *                                                              This instance represents the x and y coordinates of the top-left corner @n
 221          *                              of the created window along with its width and height. @n
 222          * @param[in]   text                    The text to display on the button
 223          * @exception   E_SUCCESS                       The method is successful.
 224          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 225          * @exception   E_SYSTEM                        A system error has occurred.
 226          * @remarks             A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
 227          *                              adding the control to the container.
 228          * @remarks             To display the text in multi-lines or to denote the end of line, use '\\n'.
 229          * @remarks             The size of the control must be within the range defined by the minimum and maximum sizes.
 230          */
 231         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text = L"");
 232
 233         /**
 234          * Adds a listener instance. @n
 235          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 236          *
 237          * @since                       2.0
 238          *
 239          * @param[in]   listener        The event listener to add
 240          */
 241         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 242
 243         /**
 244          * Removes a listener instance. @n
 245          * The removed listener cannot listen to events when they are fired.
 246          *
 247          * @since                       2.0
 248          *
 249          * @param[in]   listener        The event listener to remove
 250          */
 251         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 252
 253         /**
 254          * Sets the action ID of the button.
 255          *
 256          * @since               2.0
 257          *
 258          * @param[in]   actionId                The action ID
 259          */
 260         void SetActionId(int actionId);
 261
 262         /**
 263           * Gets the action ID of the button.
 264           *
 265           * @since              2.0
 266           *
 267           * @return             An integer value representing the action ID
 268           */
 269         int GetActionId(void) const;
 270
 271 public:
 272         /**
 273          * Sets the text that the button displays.
 274          *
 275          * @since               2.0
 276          *
 277          * @param[in]   text    The text of the button
 278          * @remarks             To display text in multi-lines or to denote the end of line, use '\\n'.
 279          */
 280         void SetText(const Tizen::Base::String& text);
 281
 282         /**
 283          * Sets the horizontal alignment of the text of the button.
 284          *
 285          * @since               2.0
 286          *
 287          * @param[in]   alignment       The horizontal text alignment
 288          */
 289         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 290
 291         /**
 292          * Sets the vertical alignment of the text of the button.
 293          *
 294          * @since               2.0
 295          *
 296          * @param[in]   alignment       The vertical text alignment
 297          */
 298         void SetTextVerticalAlignment(VerticalAlignment alignment);
 299
 300 public:
 301         /**
 302          * Gets the text displayed by the button.
 303          *
 304          * @since       2.0
 305          *
 306          * @return      The text of the button
 307          */
 308         Tizen::Base::String GetText(void) const;
 309
 310         /**
 311          * Gets the horizontal alignment of the text of the button.
 312          *
 313          * @since       2.0
 314          *
 315          * @return      The horizontal text alignment
 316          */
 317         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 318
 319         /**
 320          * Gets the vertical alignment of the text of the button.
 321          *
 322          * @since       2.0
 323          *
 324          * @return      The vertical text alignment
 325          */
 326         VerticalAlignment GetTextVerticalAlignment(void) const;
 327
 328         //Normal color
 329         /**
 330          * Sets the color of the text to be displayed on the button.
 331          *
 332          * @since                       2.0
 333          *
 334          * @param[in]   color   The text color to set
 335          */
 336         virtual void SetTextColor(const Tizen::Graphics::Color& color);
 337
 338         /**
 339          * Gets the color of the text to be displayed on the button.
 340          *
 341          * @since                       2.0
 342          *
 343          * @return      The text color
 344          */
 345         virtual Tizen::Graphics::Color GetTextColor(void) const;
 346
 347         //Pressed color
 348         /**
 349          * Sets the text color of the button for the pressed state.
 350          *
 351          * @since                       2.0
 352          *
 353          * @param[in]   color   The color to set
 354          */
 355         void SetPressedTextColor(const Tizen::Graphics::Color& color);
 356
 357         /**
 358          * Gets the text color of the button for the pressed state.
 359          *
 360          * @since                       2.0
 361          *
 362          * @return      The text color when the button is pressed
 363          */
 364         Tizen::Graphics::Color GetPressedTextColor(void) const;
 365
 366         //Disabled color
 367         /**
 368          * Sets the text color of the button for the disabled state.
 369          *
 370          * @since                       2.0
 371          *
 372          * @param[in]   color   The color to set
 373          */
 374         void SetDisabledTextColor(const Tizen::Graphics::Color& color);
 375
 376         /**
 377          * Gets the text color of the button for the disabled state.
 378          *
 379          * @since                       2.0
 380          *
 381          * @return              The disabled text color
 382          */
 383         Tizen::Graphics::Color GetDisabledTextColor(void) const;
 384
 385         /**
 386          * Sets the text color of the button for the highlighted state.
 387          *
 388          * @since           2.0
 389          *
 390          * @param[in]   color   The color to set
 391          * @remarks     While navigating the user interface using the directional keys, the focused UI control is highlighted.
 392          */
 393         void SetHighlightedTextColor(const Tizen::Graphics::Color& color);
 394
 395         /**
 396          * Gets the text color of the button for the highlighted state.
 397          *
 398          * @since           2.0
 399          *
 400          * @return    The highlighted text color
 401          * @remarks    While navigating the user interface using the directional keys, the selected UI control is highlighted and takes the focus.
 402          */
 403         Tizen::Graphics::Color GetHighlightedTextColor(void) const;
 404
 405         /**
 406          * Sets a bitmap that is to be displayed when the button is not pressed.
 407          *
 408          * @since           2.0
 409          *
 410          * @param[in]   position        The location of a bitmap where it is to display on the button
 411          * @param[in]   bitmap          The bitmap to set
 412          */
 413         void SetNormalBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 414
 415         /**
 416          * Sets a bitmap that is to be displayed when the button is not pressed.
 417          *
 418          * @since           2.1
 419          *
 420          * @param[in]   position        The location of a bitmap where it is to display on the button
 421          * @param[in]   bitmap          The bitmap to set
 422          */
 423         void SetNormalBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 424
 425         /**
 426          * Sets the disabled bitmap of the button.
 427          *
 428          * @since               2.0
 429          *
 430          * @param[in]   position        The location of disabled bitmap
 431          * @param[in]   bitmap          The disabled bitmap of the button
 432          */
 433         void SetDisabledBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 434
 435         /**
 436          * Sets the disabled bitmap of the button.
 437          *
 438          * @since               2.1
 439          *
 440          * @param[in]   position        The location of disabled bitmap
 441          * @param[in]   bitmap          The disabled bitmap of the button
 442          */
 443         void SetDisabledBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 444
 445         /**
 446          * Sets the bitmap that is to be displayed on the button when it is pressed.
 447          *
 448          * @since               2.0
 449          *
 450          * @param[in]   position        The location of a bitmap where it is to display on the Button control
 451          * @param[in]   bitmap          The bitmap to set
 452          */
 453         void SetPressedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 454
 455         /**
 456          * Sets the bitmap that is to be displayed on the button when it is pressed.
 457          *
 458          * @since               2.1
 459          *
 460          * @param[in]   position        The location of a bitmap where it is to display on the Button control
 461          * @param[in]   bitmap          The bitmap to set
 462          */
 463         void SetPressedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 464
 465         /**
 466          * Sets the highlighted bitmap of the button.
 467          *
 468          * @since       2.1
 469          *
 470          * @param[in]   position     The location of highlighted bitmap
 471          * @param[in]   bitmap       The highlighted bitmap of the button
 472          */
 473         void SetHighlightedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 474
 475         /**
 476          * Sets the highlighted bitmap of the button.
 477          *
 478          * @since       2.1
 479          *
 480          * @param[in]   position     The location of highlighted bitmap
 481          * @param[in]   bitmap       The highlighted bitmap of the button
 482          */
 483         void SetHighlightedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 484
 485         /**
 486          * Sets the normal background bitmap of the button.
 487          *
 488          * @since               2.0
 489          *
 490          * @param[in]   bitmap                  The normal background image
 491          */
 492         void SetNormalBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 493
 494         /**
 495          * Sets the disabled background bitmap of the button.
 496          *
 497          * @since       2.1
 498          *
 499          * @param[in]   bitmap          The disabled background image
 500          */
 501         void SetDisabledBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 502
 503         /**
 504          * Sets the pressed background bitmap of the button.
 505          *
 506          * @since               2.0
 507          *
 508          * @param[in]   bitmap                  The pressed background bitmap
 509          */
 510         void SetPressedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 511
 512         /**
 513          * Sets the highlighted background bitmap of the button.
 514          *
 515          * @since               2.0
 516          *
 517          * @param[in]   bitmap    The highlighted background bitmap
 518          * @remarks             When a user navigates the user interface using the directional keys, the focused UI control is highlighted.
 519          */
 520         void SetHighlightedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 521
 522         /**
 523          * Gets the color of the button for the specified status.
 524          *
 525          * @since       2.0
 526          *
 527          * @return      The color, @n
 528          *                              else RGBA(0, 0, 0, 0) if an error occurs
 529          * @param[in]   status               The status
 530          * @exception   E_SUCCESS            The method is successful.
 531          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 532          */
 533         Tizen::Graphics::Color GetColor(ButtonStatus status) const;
 534
 535         /**
 536          * Sets the color of the button for the specified status.
 537          *
 538          * @since       2.0
 539          *
 540          * @return      An error code
 541          * @param[in]   status               The status
 542          * @param[in]   color                The button color
 543          * @exception   E_SUCCESS            The method is successful.
 544          * @exception   E_SYSTEM             A system error has occurred.
 545          */
 546         result SetColor(ButtonStatus status, const Tizen::Graphics::Color& color);
 547
 548         /**
 549          * Gets the text size.
 550          *
 551          * @since       2.0
 552          *
 553          * @return      The size of the text, @n
 554          *              else @c -1 if an error occurs
 555          * @exception   E_SUCCESS                 The method is successful.
 556          * @exception   E_SYSTEM                  A system error has occurred.
 557          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 558          * @see         SetTextSize()
 559          */
 560         int GetTextSize(void) const;
 561
 562         /**
 563          * Gets the text size.
 564          *
 565          * @since       2.1
 566          *
 567          * @return      The size of the text, @n
 568          *              else @c -1.0f if an error occurs
 569          * @exception   E_SUCCESS                 The method is successful.
 570          * @exception   E_SYSTEM                  A system error has occurred.
 571          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 572          * @see         SetTextSize()
 573          */
 574         float GetTextSizeF(void) const;
 575
 576         /**
 577          * Sets the text size.
 578          *
 579          * @since       2.0
 580          *
 581          * @return      An error code
 582          * @param[in]   size              The text size
 583          * @exception   E_SUCCESS         The method is successful.
 584          * @exception   E_INVALID_ARG     The specified input parameter is invalid. @n
 585          *                                The specified @c size must be greater than @c 0.
 586          * @exception   E_SYSTEM          A system error has occurred.
 587          * @see                           GetTextSize()
 588          */
 589         result SetTextSize(int size);
 590
 591         /**
 592         * Sets the text size.
 593     *
 594         * @since       2.1
 595         *
 596         * @return      An error code
 597         * @param[in]   size              The text size
 598         * @exception   E_SUCCESS         The method is successful.
 599         * @exception   E_INVALID_ARG     The specified input parameter is invalid. @n
 600         *                                The specified @c size must be greater than @c 0.
 601         * @exception   E_SYSTEM          A system error has occurred.
 602         * @see                           GetTextSize()
 603         */
 604         result SetTextSize(float size);
 605
 606 protected:
 607         friend class _ButtonImpl;
 608
 609 private:
 610         //
 611         // This is the copy constructor for this class.
 612         //
 613         Button(const Button& rhs);
 614
 615         //
 616         // Assigns the value of the specified instance to the current instance of %Button.
 617         //
 618         Button& operator =(const Button& rhs);
 619
 620 }; // Button
 621
 622 }}} // Tizen::Ui::Controls
 623
 624 #endif // _FUI_CTRL_BUTTON_H_