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. @n
 194          * A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
 195          * adding the control to the container.
 196          *
 197          * @since                       2.0
 198          *
 199          * @return              An error code
 200          * @param[in]   rect                    An instance of the Tizen::Graphics::Rectangle class @n
 201          *                                                              This instance represents the x and y coordinates of the top-left corner
 202          *                              of the created window along with its width and height.@n
 203          *                                                              The optimal size of the control is defined in
 204          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 205          * @param[in]   text                    The text to display on the button
 206          *                                                              To display the text in multi-lines or to denote the end of line, use '\\n'.
 207          * @exception   E_SUCCESS                       The method is successful.
 208          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 209          * @exception   E_SYSTEM                        A system error has occurred.
 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. @n
 215          * A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
 216          * adding the control to the container.
 217          *
 218          * @since                       2.1
 219          *
 220          * @return              An error code
 221          * @param[in]   rect                    An instance of the Tizen::Graphics::FloatRectangle class @n
 222          *                                                              This instance represents the x and y coordinates of the top-left corner
 223          *                              of the created window along with its width and height.@n
 224          *                                                              The optimal size of the control is defined in
 225          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 226          * @param[in]   text                    The text to display on the button @n
 227          *                                              To display the text in multi-lines or to denote the end of line, use '\\n'.
 228          * @exception   E_SUCCESS                       The method is successful.
 229          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 230          * @exception   E_SYSTEM                        A system error has occurred.
 231          */
 232         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text = L"");
 233
 234         /**
 235          * Adds a listener instance. @n
 236          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 237          *
 238          * @since                       2.0
 239          *
 240          * @param[in]   listener        The event listener to add
 241          */
 242         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 243
 244         /**
 245          * Removes a listener instance. @n
 246          * The removed listener cannot listen to events when they are fired.
 247          *
 248          * @since                       2.0
 249          *
 250          * @param[in]   listener        The event listener to remove
 251          */
 252         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 253
 254         /**
 255          * Sets the action ID of the button.
 256          *
 257          * @since               2.0
 258          *
 259          * @param[in]   actionId                The action ID
 260          */
 261         void SetActionId(int actionId);
 262
 263         /**
 264           * Gets the action ID of the button.
 265           *
 266           * @since              2.0
 267           *
 268           * @return             An integer value representing the action ID
 269           */
 270         int GetActionId(void) const;
 271
 272 public:
 273         /**
 274          * Sets the text that the button displays.
 275          *
 276          * @since               2.0
 277          *
 278          * @param[in]   text    The text of the button @n
 279          *                              To display text in multi-lines or to denote the end of line, use '\\n'.
 280          */
 281         void SetText(const Tizen::Base::String& text);
 282
 283         /**
 284          * Sets the horizontal alignment of the text of the button.
 285          *
 286          * @since               2.0
 287          *
 288          * @param[in]   alignment       The horizontal text alignment
 289          */
 290         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 291
 292         /**
 293          * Sets the vertical alignment of the text of the button.
 294          *
 295          * @since               2.0
 296          *
 297          * @param[in]   alignment       The vertical text alignment
 298          */
 299         void SetTextVerticalAlignment(VerticalAlignment alignment);
 300
 301 public:
 302         /**
 303          * Gets the text displayed by the button.
 304          *
 305          * @since       2.0
 306          *
 307          * @return      The text of the button
 308          */
 309         Tizen::Base::String GetText(void) const;
 310
 311         /**
 312          * Gets the horizontal alignment of the text of the button.
 313          *
 314          * @since       2.0
 315          *
 316          * @return      The horizontal text alignment
 317          */
 318         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 319
 320         /**
 321          * Gets the vertical alignment of the text of the button.
 322          *
 323          * @since       2.0
 324          *
 325          * @return      The vertical text alignment
 326          */
 327         VerticalAlignment GetTextVerticalAlignment(void) const;
 328
 329         //Normal color
 330         /**
 331          * Sets the color of the text to be displayed on the button.
 332          *
 333          * @since                       2.0
 334          *
 335          * @param[in]   color   The text color to set
 336          */
 337         virtual void SetTextColor(const Tizen::Graphics::Color& color);
 338
 339         /**
 340          * Gets the color of the text to be displayed on the button.
 341          *
 342          * @since                       2.0
 343          *
 344          * @return      The text color
 345          */
 346         virtual Tizen::Graphics::Color GetTextColor(void) const;
 347
 348         //Pressed color
 349         /**
 350          * Sets the text color of the button for the pressed state.
 351          *
 352          * @since                       2.0
 353          *
 354          * @param[in]   color   The color to set
 355          */
 356         void SetPressedTextColor(const Tizen::Graphics::Color& color);
 357
 358         /**
 359          * Gets the text color of the button for the pressed state.
 360          *
 361          * @since                       2.0
 362          *
 363          * @return      The text color when the button is pressed
 364          */
 365         Tizen::Graphics::Color GetPressedTextColor(void) const;
 366
 367         //Disabled color
 368         /**
 369          * Sets the text color of the button for the disabled state.
 370          *
 371          * @since                       2.0
 372          *
 373          * @param[in]   color   The color to set
 374          */
 375         void SetDisabledTextColor(const Tizen::Graphics::Color& color);
 376
 377         /**
 378          * Gets the text color of the button for the disabled state.
 379          *
 380          * @since                       2.0
 381          *
 382          * @return              The disabled text color
 383          */
 384         Tizen::Graphics::Color GetDisabledTextColor(void) const;
 385
 386         /**
 387          * Sets the text color of the button for the highlighted state.
 388          *
 389          * @since           2.0
 390          *
 391          * @param[in]   color   The color to set
 392          * @remarks     When a user navigates the user interface using the directional keys, the focused UI control is highlighted.
 393          */
 394         void SetHighlightedTextColor(const Tizen::Graphics::Color& color);
 395
 396         /**
 397          * Gets the text color of the button for the highlighted state.
 398          *
 399          * @since           2.0
 400          *
 401          * @return    The highlighted text color
 402          * @remarks    When a user navigates the user interface using the directional keys, the focused UI control is highlighted.
 403          */
 404         Tizen::Graphics::Color GetHighlightedTextColor(void) const;
 405
 406         /**
 407          * Sets a bitmap that is to be displayed when the button is not pressed.
 408          *
 409          * @since           2.0
 410          *
 411          * @param[in]   position        The location of a bitmap where it is to display on the button
 412          * @param[in]   bitmap          The bitmap to set
 413          */
 414         void SetNormalBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 415
 416         /**
 417          * Sets a bitmap that is to be displayed when the button is not pressed.
 418          *
 419          * @since           2.1
 420          *
 421          * @param[in]   position        The location of a bitmap where it is to display on the button
 422          * @param[in]   bitmap          The bitmap to set
 423          */
 424         void SetNormalBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 425
 426         /**
 427          * Sets the disabled bitmap of the button.
 428          *
 429          * @since               2.0
 430          *
 431          * @param[in]   position        The location of disabled bitmap
 432          * @param[in]   bitmap          The disabled bitmap of the button
 433          */
 434         void SetDisabledBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 435
 436         /**
 437          * Sets the disabled bitmap of the button.
 438          *
 439          * @since               2.1
 440          *
 441          * @param[in]   position        The location of disabled bitmap
 442          * @param[in]   bitmap          The disabled bitmap of the button
 443          */
 444         void SetDisabledBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 445
 446         /**
 447          * Sets the bitmap that is to be displayed on the button when it is pressed.
 448          *
 449          * @since               2.0
 450          *
 451          * @param[in]   position        The location of a bitmap where it is to display on the Button control
 452          * @param[in]   bitmap          The bitmap to set
 453          */
 454         void SetPressedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 455
 456         /**
 457          * Sets the bitmap that is to be displayed on the button when it is pressed.
 458          *
 459          * @since               2.1
 460          *
 461          * @param[in]   position        The location of a bitmap where it is to display on the Button control
 462          * @param[in]   bitmap          The bitmap to set
 463          */
 464         void SetPressedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 465
 466         /**
 467          * Sets the highlighted bitmap of the button.
 468          *
 469          * @since       2.1
 470          *
 471          * @param[in]   position     The location of highlighted bitmap
 472          * @param[in]   bitmap       The highlighted bitmap of the button
 473          */
 474         void SetHighlightedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
 475
 476         /**
 477          * Sets the highlighted bitmap of the button.
 478          *
 479          * @since       2.1
 480          *
 481          * @param[in]   position     The location of highlighted bitmap
 482          * @param[in]   bitmap       The highlighted bitmap of the button
 483          */
 484         void SetHighlightedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
 485
 486         /**
 487          * Sets the normal background bitmap of the button.
 488          *
 489          * @since               2.0
 490          *
 491          * @param[in]   bitmap                  The normal background image
 492          */
 493         void SetNormalBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 494
 495         /**
 496          * Sets the disabled background bitmap of the button.
 497          *
 498          * @since       2.1
 499          *
 500          * @param[in]   bitmap          The disabled background image
 501          */
 502         void SetDisabledBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 503
 504         /**
 505          * Sets the pressed background bitmap of the button.
 506          *
 507          * @since               2.0
 508          *
 509          * @param[in]   bitmap                  The pressed background bitmap
 510          */
 511         void SetPressedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 512
 513         /**
 514          * Sets the highlighted background bitmap of the button.
 515          *
 516          * @since               2.0
 517          *
 518          * @param[in]   bitmap    The highlighted background bitmap
 519          * @remarks             When a user navigates the user interface using the directional keys, the focused UI control is highlighted.
 520          */
 521         void SetHighlightedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 522
 523         /**
 524          * Gets the color of the button for the specified status.
 525          *
 526          * @since       2.0
 527          *
 528          * @return      The color, @n
 529          *                              else RGBA(0, 0, 0, 0) if an error occurs
 530          * @param[in]   status               The status
 531          * @exception   E_SUCCESS            The method is successful.
 532          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 533          */
 534         Tizen::Graphics::Color GetColor(ButtonStatus status) const;
 535
 536         /**
 537          * Sets the color of the button for the specified status.
 538          *
 539          * @since       2.0
 540          *
 541          * @return      An error code
 542          * @param[in]   status               The status
 543          * @param[in]   color                The button color
 544          * @exception   E_SUCCESS            The method is successful.
 545          * @exception   E_SYSTEM             A system error has occurred.
 546          */
 547         result SetColor(ButtonStatus status, const Tizen::Graphics::Color& color);
 548
 549         /**
 550          * Gets the text size.
 551          *
 552          * @since       2.0
 553          *
 554          * @return      The size of the text, @n
 555          *              else @c -1 if an error occurs
 556          * @exception   E_SUCCESS                 The method is successful.
 557          * @exception   E_SYSTEM                  A system error has occurred.
 558          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 559          * @see         SetTextSize()
 560          */
 561         int GetTextSize(void) const;
 562
 563         /**
 564          * Gets the text size.
 565          *
 566          * @since       2.1
 567          *
 568          * @return      The size of the text, @n
 569          *              else @c -1.0f if an error occurs
 570          * @exception   E_SUCCESS                 The method is successful.
 571          * @exception   E_SYSTEM                  A system error has occurred.
 572          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 573          * @see         SetTextSize()
 574          */
 575         float GetTextSizeF(void) const;
 576
 577         /**
 578          * Sets the text size.
 579          *
 580          * @since       2.0
 581          *
 582          * @return      An error code
 583          * @param[in]   size              The text size
 584          * @exception   E_SUCCESS         The method is successful.
 585          * @exception   E_INVALID_ARG     The specified input parameter is invalid. @n
 586          *                                The specified @c size must be greater than @c 0.
 587          * @exception   E_SYSTEM          A system error has occurred.
 588          * @see                           GetTextSize()
 589          */
 590         result SetTextSize(int size);
 591
 592         /**
 593         * Sets the text size.
 594         *
 595         * @since       2.1
 596         *
 597         * @return      An error code
 598         * @param[in]   size              The text size
 599         * @exception   E_SUCCESS         The method is successful.
 600         * @exception   E_INVALID_ARG     The specified input parameter is invalid. @n
 601         *                                The specified @c size must be greater than @c 0.
 602         * @exception   E_SYSTEM          A system error has occurred.
 603         * @see                           GetTextSize()
 604         */
 605         result SetTextSize(float size);
 606
 607 protected:
 608         friend class _ButtonImpl;
 609
 610 private:
 611         //
 612         // This is the copy constructor for this class.
 613         //
 614         Button(const Button& rhs);
 615
 616         //
 617         // Assigns the value of the specified instance to the current instance of %Button.
 618         //
 619         Button& operator =(const Button& rhs);
 620
 621 }; // Button
 622
 623 }}} // Tizen::Ui::Controls
 624
 625 #endif // _FUI_CTRL_BUTTON_H_