2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
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;
97 // Sample code for ButtonSample.cpp
99 #include <FGraphics.h>
101 #include "ButtonSample.h"
103 using namespace Tizen::App;
104 using namespace Tizen::Graphics;
105 using namespace Tizen::Ui::Controls;
108 ButtonSample::Initialize(void)
110 Construct(FORM_STYLE_NORMAL);
115 ButtonSample::OnInitializing(void)
117 result r = E_SUCCESS;
119 // Creates an instance of Button
120 __pButton = new Button();
121 __pButton->Construct(Rectangle(50, 50, 200, 200), L"Button");
122 __pButton->SetActionId(ID_BUTTON);
123 __pButton->AddActionEventListener(*this);
125 AddControl(*__pButton);
127 // Creates an instance of Button for bitmap button
128 __pBitmapButton = new Button();
129 __pBitmapButton->Construct(Rectangle(260, 50, 200, 200));
130 __pBitmapButton->SetActionId(ID_BITMAP_BUTTON);
131 __pBitmapButton->AddActionEventListener(*this);
133 // Gets instances of Bitmap
134 AppResource *pAppResource = Application::GetInstance()->GetAppResource();
135 Bitmap* pBitmapNormal = pAppResource->GetBitmapN(L"tizen.png");
136 Bitmap* pBitmapPressed = pAppResource->GetBitmapN(L"tizen.png");
138 // Sets the bitmaps to the bitmap button
139 __pBitmapButton->SetNormalBackgroundBitmap(*pBitmapNormal);
140 __pBitmapButton->SetPressedBackgroundBitmap(*pBitmapPressed);
142 // Deallocates bitmaps
143 delete pBitmapNormal;
144 delete pBitmapPressed;
146 // Adds the bitmap button to the form
147 AddControl(*__pBitmapButton);
152 // IActionEventListener implementation
154 ButtonSample::OnActionPerformed(const Control& source, int actionId)
163 case ID_BITMAP_BUTTON:
175 class _OSP_EXPORT_ Button
176 : public Tizen::Ui::Control
180 * This is the default constructor for this class.
187 * This is the destructor for this class.
191 virtual ~Button(void);
194 * Initializes this instance of %Button with the specified parameters.
198 * @return An error code
199 * @param[in] rect An instance of the Rectangle class @n
200 * This instance represents the x and y coordinates of the top-left corner @n
201 * of the created window along with its width and height. @n
202 * @param[in] text The text to be displayed on the button
203 * @exception E_SUCCESS The method is successful.
204 * @exception E_INVALID_ARG A specified input parameter is invalid.
205 * @exception E_SYSTEM A system error has occurred.
206 * @remarks 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 * @remarks To display the text in multi-lines or to denote the end of line, use '\\n'.
209 * @remarks 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 * Adds a listener instance. @n
215 * The added listener can listen to events on the given event dispatcher's context when they are fired.
219 * @param[in] listener The event listener to be added
221 void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
224 * Removes a listener instance. @n
225 * The removed listener cannot listen to events when they are fired.
229 * @param[in] listener The event listener to be removed
231 void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
234 * Sets the action ID of the button.
238 * @param[in] actionId The action ID
240 void SetActionId(int actionId);
243 * Gets the action ID of the button.
247 * @return An integer value representing the action ID
249 int GetActionId(void) const;
253 * Sets the text that the button displays.
257 * @param[in] text The text of the button
258 * @remarks To display text in multi-lines or to denote the end of line, use '\\n'.
260 void SetText(const Tizen::Base::String& text);
263 * Sets the horizontal alignment of the text of the button.
267 * @param[in] alignment The horizontal text alignment
269 void SetTextHorizontalAlignment(HorizontalAlignment alignment);
272 * Sets the vertical alignment of the text of the button.
276 * @param[in] alignment The vertical text alignment
278 void SetTextVerticalAlignment(VerticalAlignment alignment);
282 * Gets the text displayed by the button.
286 * @return The text of the button
288 Tizen::Base::String GetText(void) const;
291 * Gets the horizontal alignment of the text of the button.
295 * @return The horizontal text alignment
297 HorizontalAlignment GetTextHorizontalAlignment(void) const;
300 * Gets the vertical alignment of the text of the button.
304 * @return The vertical text alignment
306 VerticalAlignment GetTextVerticalAlignment(void) const;
310 * Sets the color of the text to be displayed on the button.
314 * @param[in] color The text color to be set
316 virtual void SetTextColor(const Tizen::Graphics::Color& color);
319 * Gets the color of the text to be displayed on the button.
323 * @return The text color
325 virtual Tizen::Graphics::Color GetTextColor(void) const;
329 * Sets the text color of the button for the pressed state.
333 * @param[in] color The color to be set
335 void SetPressedTextColor(const Tizen::Graphics::Color& color);
338 * Gets the text color of the button for the pressed state.
342 * @return The text color when the button is pressed
344 Tizen::Graphics::Color GetPressedTextColor(void) const;
348 * Sets the text color of the button for the disabled state.
352 * @param[in] color The color to be set
354 void SetDisabledTextColor(const Tizen::Graphics::Color& color);
357 * Gets the text color of the button for the disabled state.
361 * @return The disabled text color
363 Tizen::Graphics::Color GetDisabledTextColor(void) const;
366 * Sets the text color of the button for the highlighted state.
370 * @param[in] color The color to be set
371 * @remarks While navigating the user interface using the directional keys, the focused UI control is highlighted.
373 void SetHighlightedTextColor(const Tizen::Graphics::Color& color);
376 * Gets the text color of the button for the highlighted state.
380 * @return The highlighted text color
381 * @remarks While navigating the user interface using the directional keys, the selected UI control is highlighted and takes the focus.
383 Tizen::Graphics::Color GetHighlightedTextColor(void) const;
386 * Sets a bitmap that is to be displayed when the button is not pressed.
390 * @param[in] position The location of a bitmap where it is to be displayed on the button
391 * @param[in] bitmap The bitmap of to be set
393 void SetNormalBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
396 * Sets the bitmap that is to be displayed on the button when it is pressed.
400 * @param[in] position The location of a bitmap where it is to be displayed on the Button control
401 * @param[in] bitmap The bitmap to be set
403 void SetPressedBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
406 * Sets the disabled bitmap of the button.
410 * @param[in] position The location of disabled bitmap
411 * @param[in] bitmap The disabled bitmap of the button
413 void SetDisabledBitmap(const Tizen::Graphics::Point& position, const Tizen::Graphics::Bitmap& bitmap);
416 * Sets the normal background bitmap of the button.
420 * @param[in] bitmap The normal background image
422 void SetNormalBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
425 * Sets the pressed background bitmap of the button.
429 * @param[in] bitmap The pressed background bitmap
431 void SetPressedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
434 * Sets the highlighted background bitmap of the button.
438 * @param[in] bitmap The highlighted background bitmap
439 * @remarks When a user navigates the user interface using the directional keys, the focused UI control is highlighted.
441 void SetHighlightedBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
444 * Gets the color of the button for the specified status.
448 * @return The color, @n
449 * else RGBA(0, 0, 0, 0) if an error occurs
450 * @param[in] status The status
451 * @exception E_SUCCESS The method is successful.
452 * @remarks The specific error code can be accessed using the GetLastResult() method.
454 Tizen::Graphics::Color GetColor(ButtonStatus status) const;
457 * Sets the color of the button for the specified status.
461 * @return An error code
462 * @param[in] status The status
463 * @param[in] color The button color
464 * @exception E_SUCCESS The method is successful.
465 * @exception E_SYSTEM A system error has occurred.
467 result SetColor(ButtonStatus status, const Tizen::Graphics::Color& color);
470 * Gets the text size.
474 * @return The size of the text, @n
475 * else @c -1 if an error occurs
476 * @exception E_SUCCESS The method is successful.
477 * @exception E_SYSTEM A system error has occurred.
478 * @remarks The specific error code can be accessed using the GetLastResult() method.
481 int GetTextSize(void) const;
484 * Sets the text size.
488 * @return An error code
489 * @param[in] size The text size
490 * @exception E_SUCCESS The method is successful.
491 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
492 * The specified @c size must be greater than @c 0.
493 * @exception E_SYSTEM A system error has occurred.
496 result SetTextSize(int size);
499 friend class _ButtonImpl;
503 // This is the copy constructor for this class.
505 Button(const Button& rhs);
508 // Assigns the value of the specified instance to the current instance of %Button.
510 Button& operator =(const Button& rhs);
514 }}} // Tizen::Ui::Controls
516 #endif // _FUI_CTRL_BUTTON_H_