inc/FUiCtrlCheckButton.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        FUiCtrlCheckButton.h
  20  * @brief       This is the header file for the %CheckButton class.
  21  *
  22  * This header file contains the declarations of the %CheckButton class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_CHECK_BUTTON_H_
  26 #define _FUI_CTRL_CHECK_BUTTON_H_
  27
  28 #include <FBaseResult.h>
  29 #include <FBaseObject.h>
  30 #include <FBaseTypes.h>
  31 #include <FUiControl.h>
  32 #include <FUiContainer.h>
  33 #include <FUiCtrlButton.h>
  34 #include <FUiCtrlControlsTypes.h>
  35
  36 namespace Tizen { namespace Ui { namespace Controls
  37 {
  38 /**
  39  * @enum CheckButtonStatus
  40  *
  41  * Defines the %CheckButton status.
  42  *
  43  * @since       2.0
  44  */
  45 enum CheckButtonStatus
  46 {
  47         CHECK_BUTTON_STATUS_NORMAL,         /**< The normal status */
  48         CHECK_BUTTON_STATUS_DISABLED,       /**< The disabled status */
  49         CHECK_BUTTON_STATUS_PRESSED,        /**< The pressed status */
  50         CHECK_BUTTON_STATUS_HIGHLIGHTED     /**< The highlighted status */
  51 };
  52
  53 /**
  54  * @enum CheckButtonStyle
  55  *
  56  * Defines the %CheckButton style.
  57  *
  58  * @since       2.0
  59  */
  60 enum CheckButtonStyle
  61 {
  62         CHECK_BUTTON_STYLE_MARK,                        /**< The mark style for multiple selection */
  63         CHECK_BUTTON_STYLE_MARK_WITH_DIVIDER,           /**< @if OSPDEPREC @deprecated This enum value is deprecated because the use of the divider style is no longer recommended @n
  64                                                                              Instead of using the divider style, use the detailed button style. @endif */
  65         CHECK_BUTTON_STYLE_ONOFF,                       /**< @if OSPDEPREC @deprecated This enum value is deprecated because the use of the on-off style is no longer recommended @n
  66                                                                              Instead of using the on-off style, use the on-off sliding style @endif*/
  67         CHECK_BUTTON_STYLE_ONOFF_WITH_DIVIDER,          /**< @if OSPDEPREC @deprecated This enum value is deprecated because the use of the on-off style is no longer recommended @endif */
  68         CHECK_BUTTON_STYLE_RADIO,                       /**< The radio style for single selection */
  69         CHECK_BUTTON_STYLE_RADIO_WITH_DIVIDER,          /**< @if OSPDEPREC @deprecated This enum value is deprecated because the use of the divider style is no longer recommended @n
  70                                                                              Instead of using the divider style, use the detailed button style @endif*/
  71         CHECK_BUTTON_STYLE_ONOFF_SLIDING,               /**< The slider style on/off */
  72         CHECK_BUTTON_STYLE_MARK_WITH_DETAILED_BUTTON,   /**< The mark style with detail button */
  73         CHECK_BUTTON_STYLE_RADIO_WITH_DETAILED_BUTTON,  /**< The radio style with detail button */
  74         CHECK_BUTTON_STYLE_ONOFF_SLIDING_WITH_DIVIDER,  /**< The slider style On/Off with divider @b Since: @b 2.1 */
  75 };
  76
  77 /**
  78  * @class       CheckButton
  79  * @brief       This class defines the common behavior of a %CheckButton control.
  80  *
  81  * @since       2.0
  82  *
  83  * The %CheckButton class displays a rectangular area, which can be selected, and shows the current selection.
  84  *
  85  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_button.htm">Buttons</a>.
  86  *
  87  * The following example demonstrates how to use the %CheckButton class.
  88  *
  89  *
  90  * @code
  91 // Sample code for CheckButtonSample.h
  92 #include <FUi.h>
  93
  94 class CheckButtonSample
  95         : public Tizen::Ui::Controls::Form
  96         , public Tizen::Ui::IActionEventListener
  97 {
  98 public:
  99         CheckButtonSample(void)
 100         : __pCheckButton(null){}
 101
 102         bool Initialize(void);
 103         virtual result OnInitializing(void);
 104
 105         // IActionEventListener
 106         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
 107
 108 private :
 109         static const int ID_BUTTON_CHECKED   = 101;
 110         static const int ID_BUTTON_UNCHECKED = 102;
 111         static const int ID_BUTTON_SELECTED  = 103;
 112
 113         Tizen::Ui::Controls::CheckButton* __pCheckButton;
 114 };
 115
 116  *      @endcode
 117  *
 118  *      @code
 119 // Sample Code for CheckButtonSample.cpp
 120 #include <FGraphics.h>
 121
 122 #include "CheckButtonSample.h"
 123
 124 using namespace Tizen::Graphics;
 125 using namespace Tizen::Ui::Controls;
 126
 127 bool
 128 CheckButtonSample::Initialize(void)
 129 {
 130         Construct(FORM_STYLE_NORMAL);
 131         return true;
 132 }
 133
 134 result
 135 CheckButtonSample::OnInitializing(void)
 136 {
 137         result r = E_SUCCESS;
 138
 139         // Creates a CheckButton
 140         __pCheckButton = new CheckButton();
 141         __pCheckButton->Construct(Rectangle(50, 50, 400, 100),
 142                         CHECK_BUTTON_STYLE_RADIO_WITH_DIVIDER, BACKGROUND_STYLE_DEFAULT, false, L"CheckButton");
 143         __pCheckButton->SetActionId(ID_BUTTON_CHECKED, ID_BUTTON_UNCHECKED, ID_BUTTON_SELECTED);
 144         __pCheckButton->AddActionEventListener(*this);
 145
 146         // Add a CheckButton to the Form
 147         AddControl(__pCheckButton);
 148
 149         return r;
 150 }
 151
 152 // Implements an IActionEventListener
 153 void
 154 CheckButtonSample::OnActionPerformed(const Control& source, int actionId)
 155 {
 156         switch (actionId)
 157         {
 158         case ID_BUTTON_CHECKED:
 159                 // Todo:
 160                 break;
 161         case ID_BUTTON_UNCHECKED:
 162                 // Todo:
 163                 break;
 164         case ID_BUTTON_SELECTED:
 165                 // Todo:
 166                 break;
 167         default:
 168                 break;
 169         }
 170 }
 171
 172  * @endcode
 173  *
 174  */
 175 class _OSP_EXPORT_ CheckButton
 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         CheckButton(void);
 185
 186         /**
 187          * This is the destructor for this class.
 188          *
 189          * @since       2.0
 190          */
 191         virtual ~CheckButton(void);
 192
 193         /**
 194          * Initializes this instance of %CheckButton with the specified parameters.
 195          *
 196          * @since               2.0
 197          *
 198          * @return              An error code
 199          * @param[in]   rect                    An instance of the Tizen::Graphics::Rectangle class @n
 200          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created window
 201          *                                                                      along with the width and height of the window.@n
 202          *                                                                      The optimal size of the control is defined in
 203          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 204          * @param[in]   style                           The style of the %CheckButton control
 205          * @param[in]   backgroundStyle         The background style set of the %CheckButton control
 206          * @param[in]   showTitle               Set to @c true to enable the title, @n
 207          *                                                              else @c false
 208          * @param[in]   text                            The text of the %CheckButton control
 209          * @param[in]   groupStyle                      The group style of the %CheckButton control
 210          * @exception   E_SUCCESS                       The method is successful.
 211          * @exception   E_INVALID_ARG       A specified input parameter is invalid.@n
 212          *                                                                      The specified size is less than the minimum size of the control.
 213          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 214          *                                  The background style of @c BACKGROUND_STYLE_NONE does not work with group styles except ::GROUP_STYLE_NONE.
 215          * @exception   E_SYSTEM                        A system error has occurred.
 216          * @remarks             A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 217          */
 218         result Construct(const Tizen::Graphics::Rectangle& rect, CheckButtonStyle style, BackgroundStyle backgroundStyle =
 219                                                  BACKGROUND_STYLE_DEFAULT, bool showTitle = false, const Tizen::Base::String& text = L"", GroupStyle groupStyle = GROUP_STYLE_NONE);
 220
 221         /**
 222          * Initializes this instance of %CheckButton with the specified parameters.
 223          *
 224      * @since           2.1
 225          *
 226          * @return              An error code
 227          * @param[in]   rect                    An instance of the Tizen::Graphics::FloatRectangle class @n
 228          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created window
 229          *                                                                      along with the width and height of the window.@n
 230          *                                                                      The optimal size of the control is defined in
 231          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 232          * @param[in]   style                           The style of the %CheckButton control
 233          * @param[in]   backgroundStyle         The background style set of the %CheckButton control
 234          * @param[in]   showTitle               Set to @c true to enable the title, @n
 235          *                                                              else @c false
 236          * @param[in]   text                            The text of the %CheckButton control
 237          * @param[in]   groupStyle                      The group style of the %CheckButton control
 238          * @exception   E_SUCCESS                       The method is successful.
 239          * @exception   E_INVALID_ARG       A specified input parameter is invalid.@n
 240          *                                                                      The specified size is less than the minimum size of the control.
 241          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 242          *                                  The background style of @c BACKGROUND_STYLE_NONE does not work with group styles except ::GROUP_STYLE_NONE.
 243          * @exception   E_SYSTEM                        A system error has occurred.
 244          * @remarks             A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 245          */
 246         result Construct(const Tizen::Graphics::FloatRectangle& rect, CheckButtonStyle style, BackgroundStyle backgroundStyle =
 247                                                          BACKGROUND_STYLE_DEFAULT, bool showTitle = false, const Tizen::Base::String& text = L"", GroupStyle groupStyle = GROUP_STYLE_NONE);
 248
 249         /**
 250          * Sets the selected status of the %CheckButton control.
 251          *
 252          * @since               2.0
 253          *
 254          * @param[in]   select  Set to @c true if the %CheckButton control is selected, @n
 255          *                              else @c false
 256          */
 257         void SetSelected(bool select);
 258
 259         /**
 260          * Checks whether the %CheckButton control has been selected.
 261          *
 262          * @since               2.0
 263          *
 264          * @return              @c true if the %CheckButton is selected, @n
 265          *                              else @c false
 266          */
 267         bool IsSelected(void) const;
 268
 269 public:
 270         /**
 271          * Adds an IActionEventListener instance. @n
 272          * The added listener can listen to events on the context of the given event dispatcher when they are fired.
 273          *
 274          * @since               2.0
 275          *
 276          * @param[in]   listener        The event listener to add
 277          */
 278         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 279
 280         /**
 281          * Removes an IActionEventListener instance. @n
 282          * The removed listener cannot listen to events when they are fired.
 283          *
 284          * @since               2.0
 285          *
 286          * @param[in]   listener        The event listener to remove
 287          */
 288         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 289
 290         /**
 291          * Sets the action IDs for the %CheckButton control.
 292          *
 293          * @since               2.0
 294          *
 295          * @param[in]   checkedActionId                 The action ID for the checked state
 296          * @param[in]   uncheckedActionId               The action ID for the unchecked state
 297          * @param[in]   selectedActionId                The action ID for the selected state
 298          */
 299         void SetActionId(int checkedActionId, int uncheckedActionId, int selectedActionId = -1);
 300
 301         /**
 302          * Gets the action ID for the checked state.
 303          *
 304          * @since               2.0
 305          *
 306          * @return              An integer value representing the action ID
 307          */
 308         int GetCheckedActionId(void) const;
 309
 310         /**
 311          * Gets the action ID for the unchecked state.
 312          *
 313          * @since               2.0
 314          *
 315          * @return              An integer value representing the action ID
 316          */
 317         int GetUncheckedActionId(void) const;
 318
 319         /**
 320          * Gets the action ID for the selected state.
 321          *
 322          * @since               2.0
 323          *
 324          * @return              An integer value representing the action ID
 325          */
 326         int GetSelectedActionId(void) const;
 327
 328 public:
 329         /**
 330          * Sets the text that the %CheckButton control displays.
 331          *
 332          * @since               2.0
 333          *
 334          * @param[in]   text    The text of the %CheckButton control
 335          */
 336         void SetText(const Tizen::Base::String& text);
 337
 338         /**
 339          * Sets the horizontal alignment of the text of the %CheckButton control.
 340          *
 341          * @since               2.0
 342          *
 343          * @param[in]   alignment       The horizontal text alignment
 344          */
 345         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 346
 347         /**
 348          * Sets the vertical alignment of the text of the %CheckButton control.
 349          *
 350          * @since               2.0
 351          *
 352          * @param[in]   alignment       The vertical text alignment
 353          */
 354         void SetTextVerticalAlignment(VerticalAlignment alignment);
 355
 356 public:
 357         /**
 358          * Gets the text of the %CheckButton control.
 359          *
 360          * @since       2.0
 361          *
 362          * @return      The text of the %CheckButton control
 363          */
 364         Tizen::Base::String GetText(void) const;
 365
 366         /**
 367          * Gets the horizontal alignment of the text of the %CheckButton control.
 368          *
 369          * @since       2.0
 370          * @return      The horizontal text alignment
 371          */
 372         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 373
 374         /**
 375          * Gets the vertical alignment of the text of the %CheckButton control.
 376          *
 377          * @since       2.0
 378          * @return      The vertical text alignment
 379          */
 380         VerticalAlignment GetTextVerticalAlignment(void) const;
 381
 382         /**
 383          * Sets the title text of the %CheckButton control.
 384          *
 385          * @since               2.0
 386          * @return              An error code
 387          * @param[in]   title                           The title text to set
 388          * @exception   E_SUCCESS                       The method is successful.
 389          * @exception   E_SYSTEM                        A system error has occurred.
 390          */
 391         result SetTitleText(const Tizen::Base::String& title);
 392
 393         /**
 394          * Gets the title text of the %CheckButton control.
 395          *
 396          * @since               2.0
 397          * @return              The title text
 398          */
 399         Tizen::Base::String GetTitleText(void) const;
 400
 401         //Normal color
 402         /**
 403          * Sets the text color of the %CheckButton control.
 404          *
 405          * @since                       2.0
 406          *
 407          * @param[in]   color   The text color to set
 408          */
 409         void SetTextColor(const Tizen::Graphics::Color& color);
 410
 411         /**
 412          * Gets the text color of the %CheckButton control.
 413          *
 414          * @since                       2.0
 415          *
 416          * @return    The text color
 417          */
 418         Tizen::Graphics::Color GetTextColor(void) const;
 419
 420         //Normal color
 421         /**
 422          * Sets the title text color of the %CheckButton control.
 423          *
 424          * @since                       2.0
 425          *
 426          * @param[in]   color   The text color to set
 427          */
 428         void SetTitleTextColor(const Tizen::Graphics::Color& color);
 429
 430         /**
 431          * Gets the title text color of the %CheckButton control.
 432          *
 433          * @since                       2.0
 434          *
 435          * @return              The text color
 436          */
 437         Tizen::Graphics::Color GetTitleTextColor(void) const;
 438
 439         /**
 440          * Sets the color of the %CheckButton control for the specified status.
 441          *
 442          * @since       2.0
 443          * @return      An error code
 444          * @param[in]   color                                   The color to set
 445          * @param[in]   status                  The status
 446          * @exception   E_SUCCESS                               The method is successful.
 447          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.@n
 448          *                                                                              The operation is not supported if the background style is ::BACKGROUND_STYLE_NONE.
 449          * @exception   E_SYSTEM                A system error has occurred.
 450          */
 451         result SetColor(CheckButtonStatus status, const Tizen::Graphics::Color& color);
 452
 453         /**
 454          * Gets the color of the %CheckButton control for the specified status.
 455          *
 456          * @since       2.0
 457          * @return      The color, @n
 458          *                              else RGBA (0, 0, 0, 0) if an error occurs
 459          * @param[in]   status              The status
 460          * @exception   E_SUCCESS           The method is successful.
 461          * @exception   E_INVALID_OPERATION The background style is not proper.
 462          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 463          */
 464         Tizen::Graphics::Color GetColor(CheckButtonStatus status) const;
 465
 466         /**
 467          * Sets the text color of the %CheckButton control for the pressed status.
 468          *
 469          * @since     2.0
 470          *
 471          * @return    An error code
 472          * @param[in]   color                           The text color to set
 473          * @exception   E_SUCCESS                       The method is successful.
 474          * @exception   E_SYSTEM                        A system error has occurred.
 475          */
 476         result SetPressedTextColor(const Tizen::Graphics::Color& color);
 477
 478         /**
 479          * Gets the text color of the %CheckButton control for the pressed status.
 480          *
 481          * @since      2.0
 482          * @return     The text color, @n
 483          *                         else RGBA (0, 0, 0, 0) if an error occurs
 484          * @exception   E_SUCCESS                       The method is successful.
 485          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 486          */
 487         Tizen::Graphics::Color GetPressedTextColor(void) const;
 488
 489         /**
 490          * Sets the title text color of the %CheckButton control for the pressed status.
 491          *
 492          * @since     2.0
 493          *
 494          * @return    An error code
 495          * @param[in] color                             The pressed title text color
 496          * @exception   E_SUCCESS                       The method is successful.
 497          * @exception   E_SYSTEM                        A system error has occurred.
 498          */
 499         result SetPressedTitleTextColor(const Tizen::Graphics::Color& color);
 500
 501         /**
 502          * Gets the title text color of the %CheckButton for the pressed status.
 503          *
 504          * @since      2.0
 505          *
 506          * @return     The title text color, @n
 507          *                         else RGBA (0, 0, 0, 0) if an error occurs
 508          * @exception   E_SUCCESS                       The method is successful.
 509          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 510          */
 511         Tizen::Graphics::Color GetPressedTitleTextColor(void) const;
 512
 513         /**
 514          * Sets the text color of the %CheckButton control for the highlighted status.
 515          *
 516          * @since     2.0
 517          *
 518          * @return    An error code
 519          * @param[in]   color                           The text color to set
 520          * @exception   E_SUCCESS                       The method is successful.
 521          * @exception   E_SYSTEM                        A system error has occurred.
 522          */
 523         result SetHighlightedTextColor(const Tizen::Graphics::Color& color);
 524
 525         /**
 526          * Gets the text color of the %CheckButton control for the highlighted status.
 527          *
 528          * @since      2.0
 529          *
 530          * @return     The text color, @n
 531          *                         else RGBA (0, 0, 0, 0) if an error occurs
 532          * @exception   E_SUCCESS                       The method is successful.
 533          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 534          */
 535         Tizen::Graphics::Color GetHighlightedTextColor(void) const;
 536
 537         /**
 538          * Sets the title text color of the %CheckButton control for the highlighted status.
 539          *
 540          * @since     2.0
 541          *
 542          * @return    An error code
 543          * @param[in] color                             The highlighted title text color
 544          * @exception   E_SUCCESS                       The method is successful.
 545          * @exception   E_SYSTEM                        A system error has occurred.
 546          */
 547         result SetHighlightedTitleTextColor(const Tizen::Graphics::Color& color);
 548
 549         /**
 550          * Gets the title text color of the %CheckButton control for the highlighted status.
 551          *
 552          * @since      2.0
 553          *
 554          * @return     The title text color, @n
 555          *                         else RGBA (0, 0, 0, 0) if an error occurs
 556          * @exception   E_SUCCESS                       The method is successful.
 557          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 558          */
 559         Tizen::Graphics::Color GetHighlightedTitleTextColor(void) const;
 560
 561         /**
 562          * Sets the text color of the %CheckButton control for the disabled status.
 563          *
 564          * @since     2.0
 565          *
 566          * @return    An error code
 567          * @param[in]   color                           The text color to set
 568          * @exception   E_SUCCESS                       The method is successful.
 569          * @exception   E_SYSTEM                        A system error has occurred.
 570          */
 571         result SetDisabledTextColor(const Tizen::Graphics::Color& color);
 572
 573         /**
 574          * Gets the text color of the %CheckButton control for the disabled status.
 575          *
 576          * @since      2.0
 577          *
 578          * @return     The text color, @n
 579          *                         else RGBA (0, 0, 0, 0) if an error occurs
 580          * @exception   E_SUCCESS                       The method is successful.
 581          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 582          */
 583         Tizen::Graphics::Color GetDisabledTextColor(void) const;
 584
 585         /**
 586          * Sets the title text color of the %CheckButton control for the disabled status.
 587          *
 588          * @since     2.0
 589          *
 590          * @return    An error code
 591          * @param[in] color                The disabled title text color
 592          * @exception   E_SUCCESS                       The method is successful.
 593          * @exception   E_SYSTEM                        A system error has occurred.
 594          */
 595         result SetDisabledTitleTextColor(const Tizen::Graphics::Color& color);
 596
 597         /**
 598          * Gets the title text color of %CheckButton for the disabled status.
 599          *
 600          * @since      2.0
 601          *
 602          * @return     The title text color, @n
 603          *                         else RGBA (0, 0, 0, 0) if an error occurs
 604          * @exception   E_SUCCESS                       The method is successful.
 605          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 606          */
 607         Tizen::Graphics::Color GetDisabledTitleTextColor(void) const;
 608
 609 protected:
 610         friend class _CheckButtonImpl;
 611
 612 private:
 613         friend class RadioGroup;
 614
 615         //
 616         // This is the copy constructor for this class.
 617         //
 618         CheckButton(const CheckButton& rhs);
 619
 620         //
 621         // Assigns the value of the specified instance to the current instance of %CheckButton.
 622         //
 623         CheckButton& operator =(const CheckButton& rhs);
 624
 625 }; // CheckButton
 626
 627 }}} // Tizen::Ui::Controls
 628
 629 #endif // _FUI_CTRL_CHECK_BUTTON_H_