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.
201 * @param[in] text The text to display on the button
202 * @exception E_SUCCESS The method is successful.
203 * @exception E_INVALID_ARG A specified input parameter is invalid.
204 * @exception E_SYSTEM A system error has occurred.
206 * - A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
207 * adding the control to the container.
208 * - To display the text in multi-lines or to denote the end of line, use '\\n'.
209 * - The size of the control must be within the range defined by the minimum and maximum sizes.
211 result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text = L"");
214 * Initializes this instance of %Button with the specified parameters.
218 * @return An error code
219 * @param[in] rect An instance of the Tizen::Graphics::FloatRectangle class @n
220 * This instance represents the x and y coordinates of the top-left corner
221 * of the created window along with its width and height.
222 * @param[in] text The text to display on the button
223 * @exception E_SUCCESS The method is successful.
224 * @exception E_INVALID_ARG A specified input parameter is invalid.
225 * @exception E_SYSTEM A system error has occurred.
227 * - A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
228 * adding the control to the container.
229 * - To display the text in multi-lines or to denote the end of line, use '\\n'.
230 * - The size of the control must be within the range defined by the minimum and maximum sizes.
232 result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text = L"");
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.
240 * @param[in] listener The event listener to add
242 void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
245 * Removes a listener instance. @n
246 * The removed listener cannot listen to events when they are fired.
250 * @param[in] listener The event listener to remove
252 void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
255 * Sets the action ID of the button.
259 * @param[in] actionId The action ID
261 void SetActionId(int actionId);
264 * Gets the action ID of the button.
268 * @return An integer value representing the action ID
270 int GetActionId(void) const;
274 * Sets the text that the button displays.
278 * @param[in] text The text of the button
279 * @remarks To display text in multi-lines or to denote the end of line, use '\\n'.
281 void SetText(const Tizen::Base::String& text);
284 * Sets the horizontal alignment of the text of the button.
288 * @param[in] alignment The horizontal text alignment
290 void SetTextHorizontalAlignment(HorizontalAlignment alignment);
293 * Sets the vertical alignment of the text of the button.
297 * @param[in] alignment The vertical text alignment
299 void SetTextVerticalAlignment(VerticalAlignment alignment);
303 * Gets the text displayed by the button.
307 * @return The text of the button
309 Tizen::Base::String GetText(void) const;
312 * Gets the horizontal alignment of the text of the button.
316 * @return The horizontal text alignment
318 HorizontalAlignment GetTextHorizontalAlignment(void) const;
321 * Gets the vertical alignment of the text of the button.
325 * @return The vertical text alignment
327 VerticalAlignment GetTextVerticalAlignment(void) const;
331 * Sets the color of the text to be displayed on the button.
335 * @param[in] color The text color to set
337 virtual void SetTextColor(const Tizen::Graphics::Color& color);
340 * Gets the color of the text to be displayed on the button.
344 * @return The text color
346 virtual Tizen::Graphics::Color GetTextColor(void) const;
350 * Sets the text color of the button for the pressed state.
354 * @param[in] color The color to set
356 void SetPressedTextColor(const Tizen::Graphics::Color& color);
359 * Gets the text color of the button for the pressed state.
363 * @return The text color when the button is pressed
365 Tizen::Graphics::Color GetPressedTextColor(void) const;
369 * Sets the text color of the button for the disabled state.
373 * @param[in] color The color to set
375 void SetDisabledTextColor(const Tizen::Graphics::Color& color);
378 * Gets the text color of the button for the disabled state.
382 * @return The disabled text color
384 Tizen::Graphics::Color GetDisabledTextColor(void) const;
387 * Sets the text color of the button for the highlighted state.
391 * @param[in] color The color to set
392 * @remarks While navigating the user interface using the directional keys, the focused UI control is highlighted.
394 void SetHighlightedTextColor(const Tizen::Graphics::Color& color);
397 * Gets the text color of the button for the highlighted state.
401 * @return The highlighted text color
402 * @remarks While navigating the user interface using the directional keys, the selected UI control is highlighted and takes the focus.
404 Tizen::Graphics::Color GetHighlightedTextColor(void) const;
407 * Sets a bitmap that is to be displayed when the button is not pressed.
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
414 void SetNormalBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
417 * Sets a bitmap that is to be displayed when the button is not pressed.
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
424 void SetNormalBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
427 * Sets the disabled bitmap of the button.
431 * @param[in] position The location of disabled bitmap
432 * @param[in] bitmap The disabled bitmap of the button
434 void SetDisabledBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
437 * Sets the disabled bitmap of the button.
441 * @param[in] position The location of disabled bitmap
442 * @param[in] bitmap The disabled bitmap of the button
444 void SetDisabledBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
447 * Sets the bitmap that is to be displayed on the button when it is pressed.
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
454 void SetPressedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
457 * Sets the bitmap that is to be displayed on the button when it is pressed.
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
464 void SetPressedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
467 * Sets the highlighted bitmap of the button.
471 * @param[in] position The location of highlighted bitmap
472 * @param[in] bitmap The highlighted bitmap of the button
474 void SetHighlightedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
477 * Sets the highlighted bitmap of the button.
481 * @param[in] position The location of highlighted bitmap
482 * @param[in] bitmap The highlighted bitmap of the button
484 void SetHighlightedBitmap(const Tizen::Graphics::FloatPoint& position, const Tizen::Graphics::Bitmap& bitmap);
487 * Sets the normal background bitmap of the button.
491 * @param[in] bitmap The normal background image
493 void SetNormalBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
496 * Sets the disabled background bitmap of the button.
500 * @param[in] bitmap The disabled background image
502 void SetDisabledBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
505 * Sets the pressed background bitmap of the button.
509 * @param[in] bitmap The pressed background bitmap
511 void SetPressedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
514 * Sets the highlighted background bitmap of the button.
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.
521 void SetHighlightedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
524 * Gets the color of the button for the specified status.
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.
534 Tizen::Graphics::Color GetColor(ButtonStatus status) const;
537 * Sets the color of the button for the specified status.
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.
547 result SetColor(ButtonStatus status, const Tizen::Graphics::Color& color);
550 * Gets the text size.
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.
561 int GetTextSize(void) const;
564 * Gets the text size.
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.
575 float GetTextSizeF(void) const;
578 * Sets the text size.
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.
590 result SetTextSize(int size);
593 * Sets the text size.
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.
605 result SetTextSize(float size);
608 friend class _ButtonImpl;
612 // This is the copy constructor for this class.
614 Button(const Button& rhs);
617 // Assigns the value of the specified instance to the current instance of %Button.
619 Button& operator =(const Button& rhs);
623 }}} // Tizen::Ui::Controls
625 #endif // _FUI_CTRL_BUTTON_H_