2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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.
19 * @file FUiCtrlButton.h
20 * @brief This is the header file for the %Button class.
22 * This header file contains the declarations of the %Button class and its helper classes.
25 #ifndef _FUI_CTRL_BUTTON_H_
26 #define _FUI_CTRL_BUTTON_H_
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>
37 namespace Tizen { namespace Ui { namespace Controls
42 * Defines the %Button control status.
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 */
56 * @brief This class defines the common behavior of a %Button control.
60 * The %Button class displays a rectangular area that can be pressed.
62 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_button.htm">Buttons</a>.
64 * The following example demonstrates how to use the %Button class.
68 // Sample code for ButtonSample.h
72 : public Tizen::Ui::Controls::Form
73 , public Tizen::Ui::IActionEventListener
78 , __pBitmapButton(null){}
80 bool Initialize(void);
81 virtual result OnInitializing(void);
83 // IActionEventListener
84 virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
87 static const int ID_BUTTON = 101;
88 static const int ID_BITMAP_BUTTON = 102;
90 Tizen::Ui::Controls::Button* __pButton;
91 Tizen::Ui::Controls::Button* __pBitmapButton;
96 // Sample code for ButtonSample.cpp
98 #include <FGraphics.h>
100 #include "ButtonSample.h"
102 using namespace Tizen::App;
103 using namespace Tizen::Graphics;
104 using namespace Tizen::Ui::Controls;
107 ButtonSample::Initialize(void)
109 Construct(FORM_STYLE_NORMAL);
114 ButtonSample::OnInitializing(void)
116 result r = E_SUCCESS;
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);
124 AddControl(*__pButton);
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);
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");
137 // Sets the bitmaps to the bitmap button
138 __pBitmapButton->SetNormalBackgroundBitmap(*pBitmapNormal);
139 __pBitmapButton->SetPressedBackgroundBitmap(*pBitmapPressed);
141 // Deallocates bitmaps
142 delete pBitmapNormal;
143 delete pBitmapPressed;
145 // Adds the bitmap button to the form
146 AddControl(*__pBitmapButton);
151 // IActionEventListener implementation
153 ButtonSample::OnActionPerformed(const Control& source, int actionId)
162 case ID_BITMAP_BUTTON:
174 class _OSP_EXPORT_ Button
175 : public Tizen::Ui::Control
179 * This is the default constructor for this class.
186 * This is the destructor for this class.
190 virtual ~Button(void);
193 * Initializes this instance of %Button with the specified parameters.
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.
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.
212 result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text = L"");
215 * Initializes this instance of %Button with the specified parameters.
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.
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'.
234 result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text = L"");
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.
242 * @param[in] listener The event listener to add
244 void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
247 * Removes a listener instance. @n
248 * The removed listener cannot listen to events when they are fired.
252 * @param[in] listener The event listener to remove
254 void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
257 * Sets the action ID of the button.
261 * @param[in] actionId The action ID
263 void SetActionId(int actionId);
266 * Gets the action ID of the button.
270 * @return An integer value representing the action ID
272 int GetActionId(void) const;
276 * Sets the text that the button displays.
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'.
283 void SetText(const Tizen::Base::String& text);
286 * Sets the horizontal alignment of the text of the button.
290 * @param[in] alignment The horizontal text alignment
292 void SetTextHorizontalAlignment(HorizontalAlignment alignment);
295 * Sets the vertical alignment of the text of the button.
299 * @param[in] alignment The vertical text alignment
301 void SetTextVerticalAlignment(VerticalAlignment alignment);
305 * Gets the text displayed by the button.
309 * @return The text of the button
311 Tizen::Base::String GetText(void) const;
314 * Gets the horizontal alignment of the text of the button.
318 * @return The horizontal text alignment
320 HorizontalAlignment GetTextHorizontalAlignment(void) const;
323 * Gets the vertical alignment of the text of the button.
327 * @return The vertical text alignment
329 VerticalAlignment GetTextVerticalAlignment(void) const;
333 * Sets the color of the text to be displayed on the button.
337 * @param[in] color The text color to set
339 virtual void SetTextColor(const Tizen::Graphics::Color& color);
342 * Gets the color of the text to be displayed on the button.
346 * @return The text color
348 virtual Tizen::Graphics::Color GetTextColor(void) const;
352 * Sets the text color of the button for the pressed state.
356 * @param[in] color The color to set
358 void SetPressedTextColor(const Tizen::Graphics::Color& color);
361 * Gets the text color of the button for the pressed state.
365 * @return The text color when the button is pressed
367 Tizen::Graphics::Color GetPressedTextColor(void) const;
371 * Sets the text color of the button for the disabled state.
375 * @param[in] color The color to set
377 void SetDisabledTextColor(const Tizen::Graphics::Color& color);
380 * Gets the text color of the button for the disabled state.
384 * @return The disabled text color
386 Tizen::Graphics::Color GetDisabledTextColor(void) const;
389 * Sets the text color of the button for the highlighted state.
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.
396 void SetHighlightedTextColor(const Tizen::Graphics::Color& color);
399 * Gets the text color of the button for the highlighted state.
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.
406 Tizen::Graphics::Color GetHighlightedTextColor(void) const;
409 * Sets a bitmap that is to be displayed when the button is not pressed.
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
416 void SetNormalBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
419 * Sets a bitmap that is to be displayed when the button is not pressed.
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
426 void SetNormalBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
429 * Sets the disabled bitmap of the button.
433 * @param[in] position The location of disabled bitmap
434 * @param[in] bitmap The disabled bitmap of the button
436 void SetDisabledBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
439 * Sets the disabled bitmap of the button.
443 * @param[in] position The location of disabled bitmap
444 * @param[in] bitmap The disabled bitmap of the button
446 void SetDisabledBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
449 * Sets the bitmap that is to be displayed on the button when it is pressed.
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
456 void SetPressedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
459 * Sets the bitmap that is to be displayed on the button when it is pressed.
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
466 void SetPressedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
469 * Sets the highlighted bitmap of the button.
473 * @param[in] position The location of highlighted bitmap
474 * @param[in] bitmap The highlighted bitmap of the button
476 void SetHighlightedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
479 * Sets the highlighted bitmap of the button.
483 * @param[in] position The location of highlighted bitmap
484 * @param[in] bitmap The highlighted bitmap of the button
486 void SetHighlightedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
489 * Sets the normal background bitmap of the button.
493 * @param[in] bitmap The normal background image
495 void SetNormalBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
498 * Sets the disabled background bitmap of the button.
502 * @param[in] bitmap The disabled background image
504 void SetDisabledBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
507 * Sets the pressed background bitmap of the button.
511 * @param[in] bitmap The pressed background bitmap
513 void SetPressedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
516 * Sets the highlighted background bitmap of the button.
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.
523 void SetHighlightedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
526 * Gets the color of the button for the specified status.
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.
536 Tizen::Graphics::Color GetColor(ButtonStatus status) const;
539 * Sets the color of the button for the specified status.
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.
549 result SetColor(ButtonStatus status, const Tizen::Graphics::Color& color);
552 * Gets the text size.
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.
563 int GetTextSize(void) const;
566 * Gets the text size.
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.
577 float GetTextSizeF(void) const;
580 * Sets the text size.
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.
592 result SetTextSize(int size);
595 * Sets the text size.
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.
607 result SetTextSize(float size);
610 friend class _ButtonImpl;
614 // This is the copy constructor for this class.
616 Button(const Button& rhs);
619 // Assigns the value of the specified instance to the current instance of %Button.
621 Button& operator =(const Button& rhs);
625 }}} // Tizen::Ui::Controls
627 #endif // _FUI_CTRL_BUTTON_H_