inc/FUiCtrlButton.h

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