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 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 Tizen::Graphics::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.
142 * - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
143 * - To display text in multi-lines or to denote the end of line use '\\n'.
144 * - The size of the control must be within the range defined by the minimum size and the maximum size.
146 result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text);
149 * Initializes this instance of %Label with the specified parameters.
153 * @return An error code
154 * @param[in] rect An instance of the Tizen::Graphics::FloatRectangle class @n
155 * This instance represents the x and y coordinates of the top-left corner of the created window along with
156 * the width and height of the window.
157 * @param[in] text The text for this label instance
158 * @exception E_SUCCESS The method is successful.
159 * @exception E_INVALID_ARG A specified input parameter is invalid.
160 * @exception E_SYSTEM A system error has occurred.
162 * - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
163 * - To display text in multi-lines or to denote the end of line use '\\n'.
164 * - The size of the control must be within the range defined by the minimum size and the maximum size.
166 result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text);
170 * Sets the specified text for the %Label control.
174 * @param[in] text The string to set
175 * @remarks To display text in multi-lines or to denote the end of line use '\\n'.
177 void SetText(const Tizen::Base::String& text);
180 * Gets the text of the %Label control.
184 * @return The text of the %Label control, @n
185 * else an empty string if an error occurs
187 Tizen::Base::String GetText(void) const;
190 * Sets the background bitmap of the %Label control.
194 * @param[in] bitmap The background bitmap
196 void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
199 * Sets the horizontal alignment of the text of the %Label control.
203 * @param[in] alignment The horizontal text alignment
205 void SetTextHorizontalAlignment(HorizontalAlignment alignment);
208 * Gets the horizontal alignment of the text of the %Label control.
212 * @return The horizontal text alignment, @n
213 * else @c ALIGNMENT_LEFT if the instance is invalid
215 HorizontalAlignment GetTextHorizontalAlignment(void) const;
218 * Sets the vertical alignment of the text of the %Label control.
222 * @param[in] alignment The vertical text alignment
224 void SetTextVerticalAlignment(VerticalAlignment alignment);
227 * Gets the vertical alignment of the text of the %Label control.
231 * @return The vertical text alignment, @n
232 * else @c ALIGNMENT_TOP if the instance is invalid
234 VerticalAlignment GetTextVerticalAlignment(void) const;
237 * Sets the background color of the %Label control.
241 * @param[in] color The normal background color
243 void SetBackgroundColor(const Tizen::Graphics::Color& color);
246 * Gets the background color of the %Label control.
250 * @return The background color
252 Tizen::Graphics::Color GetBackgroundColor(void) const;
255 * Sets the text color of the %Label control.
259 * @param[in] color The color to set
261 virtual void SetTextColor(const Tizen::Graphics::Color& color);
264 * Gets the text color of the %Label control.
268 * @return The text color
270 virtual Tizen::Graphics::Color GetTextColor(void) const;
273 * Sets the text attributes of the %Label control.
277 * @param[in] size The size of the text
278 * @param[in] style The style of the text
279 * @exception E_SUCCESS The method is successful.
280 * @exception E_INVALID_ARG A specified input parameter is invalid.
282 * - The specific error code can be accessed using the GetLastResult() method.
283 * - If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
285 void SetTextConfig(int size, LabelTextStyle style);
288 * Sets the text attributes of the %Label control.
292 * @param[in] size The size of the text
293 * @param[in] style The style of the text
294 * @exception E_SUCCESS The method is successful.
295 * @exception E_INVALID_ARG A specified input parameter is invalid.
297 * - The specific error code can be accessed using the GetLastResult() method.
298 * - If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
300 void SetTextConfig(float size, LabelTextStyle style);
303 * Gets the text size of the %Label control.
307 * @return The size of the text, @n
308 * else @c -1 if an error occurs
310 int GetTextSize(void) const;
313 * Gets the text size of the %Label control.
317 * @return The size of the text, @n
318 * else @c -1.0f if an error occurs
320 float GetTextSizeF(void) const;
323 * Gets the text style of the %Label control.
327 * @return The style of the text, @n
328 * else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
330 LabelTextStyle GetTextStyle(void) const;
333 * Sets the top and left margins.
337 * @return An error code
338 * @param[in] topMargin The top margin.
339 * @param[in] leftMargin The left margin.
340 * @exception E_SUCCESS The method is successful.
341 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
342 * The specified @c size must be greater than @c 0.
343 * @see GetTopMargin()
344 * @see GetLeftMargin()
346 result SetMargin(int topMargin, int leftMargin);
349 * Sets the top and left margins.
353 * @return An error code
354 * @param[in] topMargin The top margin.
355 * @param[in] leftMargin The left margin.
356 * @exception E_SUCCESS The method is successful.
357 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
358 * The specified @c size must be greater than @c 0.
359 * @see GetTopMargin()
360 * @see GetLeftMargin()
362 result SetMargin(float topMargin, float leftMargin);
365 * Gets the top margin.
369 * @return The size of the top margin, @n
370 * else @c -1 if an error occurs
373 int GetTopMargin(void) const;
376 * Gets the top margin.
380 * @return The size of the top margin, @n
381 * else @c -1.0f if an error occurs
384 float GetTopMarginF(void) const;
387 * Gets the left margin.
391 * @return The size of the left margin, @n
392 * else @c -1 if an error occurs.
395 int GetLeftMargin(void) const;
398 * Gets the left margin.
402 * @return The size of the left margin, @n
403 * else @c -1.0f if an error occurs.
406 float GetLeftMarginF(void) const;
409 friend class _LabelImpl;
413 // This is the copy constructor for this class.
415 Label(const Label& rhs);
418 // Assigns the value of the specified instance to the current instance of %Label.
420 Label& operator =(const Label& rhs);
424 }}} // Tizen::Ui::Controls
426 #endif // _FUI_CTRL_LABEL_H_