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 FUiCtrlLabel.h
20 * @brief This is the header file for the %Label class.
22 * This header file contains the declarations of the %Label class and its helper classes.
25 #ifndef _FUI_CTRL_LABEL_H_
26 #define _FUI_CTRL_LABEL_H_
28 #include <FBaseObject.h>
29 #include <FBaseTypes.h>
30 #include <FBaseResult.h>
31 #include <FBaseString.h>
32 #include <FGrpBitmap.h>
33 #include <FGrpColor.h>
34 #include <FGrpPoint.h>
35 #include <FGrpRectangle.h>
36 #include <FUiControl.h>
37 #include <FUiContainer.h>
38 #include <FUiCtrlLabelTypes.h>
39 #include <FUiCtrlControlsTypes.h>
42 namespace Tizen { namespace Ui { namespace Controls
46 * @brief This class defines the common behavior of a %Label control.
50 * The %Label class displays a non-editable text field and does not accept any input from the user.
52 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_label.htm">Label</a>.
54 * The following example demonstrates how to use the %Label class.
57 // Sample code for LabelSample.h
61 : public Tizen::Ui::Controls::Form
67 bool Initialize(void);
68 virtual result OnInitializing(void);
71 Tizen::Ui::Controls::Label *__pLabel;
76 // Sample code for LabelSample.cpp
77 #include <FGraphics.h>
79 #include "LabelSample.h"
81 using namespace Tizen::Graphics;
82 using namespace Tizen::Ui::Controls;
85 LabelSample::Initialize(void)
87 Construct(FORM_STYLE_NORMAL);
92 LabelSample::OnInitializing(void)
96 // Creates an instance of Label
97 __pLabel = new Label();
98 __pLabel->Construct(Rectangle(100, 100, 200, 50), L"Label Text");
99 __pLabel->SetTextConfig(30, LABEL_TEXT_STYLE_BOLD);
100 __pLabel->SetBackgroundColor(Color::GetColor(COLOR_ID_BLUE));
102 // Adds the label to the form
103 AddControl(*__pLabel);
110 class _OSP_EXPORT_ Label
111 : public Tizen::Ui::Control
115 * This is the default constructor for this class.
122 * This is the destructor for this class.
126 virtual ~Label(void);
129 * Initializes this instance of %Label with the specified parameters.
133 * @return An error code
134 * @param[in] rect An instance of the Rectangle class @n
135 * This instance represents the x and y coordinates of the top-left corner of the created window along with
136 * the width and height of the window.
137 * @param[in] text The text for this label instance
138 * @exception E_SUCCESS The method is successful.
139 * @exception E_INVALID_ARG A specified input parameter is invalid.
140 * @exception E_SYSTEM A system error has occurred.
141 * @remarks A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
142 * To display text in multi-lines or to denote the end of line use '\\n'. @n
143 * The size of the control must be within the range defined by the minimum size and the maximum size.
145 result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text);
148 * Initializes this instance of %Label with the specified parameters.
152 * @return An error code
153 * @param[in] rect An instance of the Rectangle class @n
154 * This instance represents the x and y coordinates of the top-left corner of the created window along with
155 * the width and height of the window.
156 * @param[in] text The text for this label instance
157 * @exception E_SUCCESS The method is successful.
158 * @exception E_INVALID_ARG A specified input parameter is invalid.
159 * @exception E_SYSTEM A system error has occurred.
160 * @remarks A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
161 * To display text in multi-lines or to denote the end of line use '\\n'. @n
162 * The size of the control must be within the range defined by the minimum size and the maximum size.
164 result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text);
168 * Sets the specified text for the %Label control.
172 * @param[in] text The string to set
173 * @remarks To display text in multi-lines or to denote the end of line use '\\n'.
175 void SetText(const Tizen::Base::String& text);
178 * Gets the text of the %Label control.
182 * @return The text of the %Label control, @n
183 * else an empty string if an error occurs
185 Tizen::Base::String GetText(void) const;
188 * Sets the background bitmap of the %Label control.
192 * @param[in] bitmap The background bitmap
194 void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
197 * Sets the horizontal alignment of the text of the %Label control.
201 * @param[in] alignment The horizontal text alignment
203 void SetTextHorizontalAlignment(HorizontalAlignment alignment);
206 * Gets the horizontal alignment of the text of the %Label control.
210 * @return The horizontal text alignment, @n
211 * else @c ALIGNMENT_LEFT if the instance is invalid
213 HorizontalAlignment GetTextHorizontalAlignment(void) const;
216 * Sets the vertical alignment of the text of the %Label control.
220 * @param[in] alignment The vertical text alignment
222 void SetTextVerticalAlignment(VerticalAlignment alignment);
225 * Gets the vertical alignment of the text of the %Label control.
229 * @return The vertical text alignment, @n
230 * else @c ALIGNMENT_TOP if the instance is invalid
232 VerticalAlignment GetTextVerticalAlignment(void) const;
235 * Sets the background color of the %Label control.
239 * @param[in] color The normal background color
241 void SetBackgroundColor(const Tizen::Graphics::Color& color);
244 * Gets the background color of the %Label control.
248 * @return The background color
250 Tizen::Graphics::Color GetBackgroundColor(void) const;
253 * Sets the text color of the %Label control.
257 * @param[in] color The color to set
259 virtual void SetTextColor(const Tizen::Graphics::Color& color);
262 * Gets the text color of the %Label control.
266 * @return The text color
268 virtual Tizen::Graphics::Color GetTextColor(void) const;
271 * Sets the text attributes of the %Label control.
275 * @param[in] size The size of the text
276 * @param[in] style The style of the text
277 * @exception E_SUCCESS The method is successful.
278 * @exception E_INVALID_ARG A specified input parameter is invalid.
279 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
280 * If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
282 void SetTextConfig(int size, LabelTextStyle style);
285 * Sets the text attributes of the %Label control.
289 * @param[in] size The size of the text
290 * @param[in] style The style of the text
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_INVALID_ARG A specified input parameter is invalid.
293 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
294 * If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
296 void SetTextConfig(float size, LabelTextStyle style);
299 * Gets the text size of the %Label control.
303 * @return The size of the text, @n
304 * else @c -1 if an error occurs
306 int GetTextSize(void) const;
309 * Gets the text size of the %Label control.
313 * @return The size of the text, @n
314 * else @c -1.0f if an error occurs
316 float GetTextSizeF(void) const;
319 * Gets the text style of the %Label control.
323 * @return The style of the text, @n
324 * else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
326 LabelTextStyle GetTextStyle(void) const;
329 * Sets the top and left margins.
333 * @return An error code
334 * @param[in] topMargin The top margin.
335 * @param[in] leftMargin The left margin.
336 * @exception E_SUCCESS The method is successful.
337 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
338 * The specified @c size must be greater than @c 0.
339 * @see GetTopMargin()
340 * @see GetLeftMargin()
342 result SetMargin(int topMargin, int leftMargin);
345 * Sets the top and left margins.
349 * @return An error code
350 * @param[in] topMargin The top margin.
351 * @param[in] leftMargin The left margin.
352 * @exception E_SUCCESS The method is successful.
353 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
354 * The specified @c size must be greater than @c 0.
355 * @see GetTopMargin()
356 * @see GetLeftMargin()
358 result SetMargin(float topMargin, float leftMargin);
361 * Gets the top margin.
365 * @return The size of the top margin, @n
366 * else @c -1 if an error occurs
369 int GetTopMargin(void) const;
372 * Gets the top margin.
376 * @return The size of the top margin, @n
377 * else @c -1.0f if an error occurs
380 float GetTopMarginF(void) const;
383 * Gets the left margin.
387 * @return The size of the left margin, @n
388 * else @c -1 if an error occurs.
391 int GetLeftMargin(void) const;
394 * Gets the left margin.
398 * @return The size of the left margin, @n
399 * else @c -1.0f if an error occurs.
402 float GetLeftMarginF(void) const;
405 friend class _LabelImpl;
409 // This is the copy constructor for this class.
411 Label(const Label& rhs);
414 // Assigns the value of the specified instance to the current instance of %Label.
416 Label& operator =(const Label& rhs);
420 }}} // Tizen::Ui::Controls
422 #endif // _FUI_CTRL_LABEL_H_