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.@n
137 * The optimal size of the control is defined in
138 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
139 * @param[in] text The text for this label instance
140 * @exception E_SUCCESS The method is successful.
141 * @exception E_INVALID_ARG A specified input parameter is invalid.
142 * @exception E_SYSTEM A system error has occurred.
144 * - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
145 * - To display text in multi-lines or to denote the end of line use '\\n'.
146 * - The size of the control must be within the range defined by the minimum size and the maximum size.
148 result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text);
151 * Initializes this instance of %Label with the specified parameters.
155 * @return An error code
156 * @param[in] rect An instance of the Tizen::Graphics::FloatRectangle class @n
157 * This instance represents the x and y coordinates of the top-left corner of the created window along with
158 * the width and height of the window.@n
159 * The optimal size of the control is defined in
160 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
161 * @param[in] text The text for this label instance
162 * @exception E_SUCCESS The method is successful.
163 * @exception E_INVALID_ARG A specified input parameter is invalid.
164 * @exception E_SYSTEM A system error has occurred.
166 * - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
167 * - To display text in multi-lines or to denote the end of line use '\\n'.
168 * - The size of the control must be within the range defined by the minimum size and the maximum size.
170 result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text);
174 * Sets the specified text for the %Label control.
178 * @param[in] text The string to set
179 * @remarks To display text in multi-lines or to denote the end of line use '\\n'.
181 void SetText(const Tizen::Base::String& text);
184 * Gets the text of the %Label control.
188 * @return The text of the %Label control, @n
189 * else an empty string if an error occurs
191 Tizen::Base::String GetText(void) const;
194 * Sets the background bitmap of the %Label control.
198 * @param[in] bitmap The background bitmap
200 void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
203 * Sets the horizontal alignment of the text of the %Label control.
207 * @param[in] alignment The horizontal text alignment
209 void SetTextHorizontalAlignment(HorizontalAlignment alignment);
212 * Gets the horizontal alignment of the text of the %Label control.
216 * @return The horizontal text alignment, @n
217 * else @c ALIGNMENT_LEFT if the instance is invalid
219 HorizontalAlignment GetTextHorizontalAlignment(void) const;
222 * Sets the vertical alignment of the text of the %Label control.
226 * @param[in] alignment The vertical text alignment
228 void SetTextVerticalAlignment(VerticalAlignment alignment);
231 * Gets the vertical alignment of the text of the %Label control.
235 * @return The vertical text alignment, @n
236 * else @c ALIGNMENT_TOP if the instance is invalid
238 VerticalAlignment GetTextVerticalAlignment(void) const;
241 * Sets the background color of the %Label control.
245 * @param[in] color The normal background color
247 void SetBackgroundColor(const Tizen::Graphics::Color& color);
250 * Gets the background color of the %Label control.
254 * @return The background color
256 Tizen::Graphics::Color GetBackgroundColor(void) const;
259 * Sets the text color of the %Label control.
263 * @param[in] color The color to set
265 virtual void SetTextColor(const Tizen::Graphics::Color& color);
268 * Gets the text color of the %Label control.
272 * @return The text color
274 virtual Tizen::Graphics::Color GetTextColor(void) const;
277 * Sets the text attributes of the %Label control.
281 * @param[in] size The size of the text
282 * @param[in] style The style of the text
283 * @exception E_SUCCESS The method is successful.
284 * @exception E_INVALID_ARG A specified input parameter is invalid.
286 * - The specific error code can be accessed using the GetLastResult() method.
287 * - If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
289 void SetTextConfig(int size, LabelTextStyle style);
292 * Sets the text attributes of the %Label control.
296 * @param[in] size The size of the text
297 * @param[in] style The style of the text
298 * @exception E_SUCCESS The method is successful.
299 * @exception E_INVALID_ARG A specified input parameter is invalid.
301 * - The specific error code can be accessed using the GetLastResult() method.
302 * - If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
304 void SetTextConfig(float size, LabelTextStyle style);
307 * Gets the text size of the %Label control.
311 * @return The size of the text, @n
312 * else @c -1 if an error occurs
314 int GetTextSize(void) const;
317 * Gets the text size of the %Label control.
321 * @return The size of the text, @n
322 * else @c -1.0f if an error occurs
324 float GetTextSizeF(void) const;
327 * Gets the text style of the %Label control.
331 * @return The style of the text, @n
332 * else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
334 LabelTextStyle GetTextStyle(void) const;
337 * Sets the top and left margins.
341 * @return An error code
342 * @param[in] topMargin The top margin.
343 * @param[in] leftMargin The left margin.
344 * @exception E_SUCCESS The method is successful.
345 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
346 * The specified @c size must be greater than @c 0.
347 * @see GetTopMargin()
348 * @see GetLeftMargin()
350 result SetMargin(int topMargin, int leftMargin);
353 * Sets the top and left margins.
357 * @return An error code
358 * @param[in] topMargin The top margin.
359 * @param[in] leftMargin The left margin.
360 * @exception E_SUCCESS The method is successful.
361 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
362 * The specified @c size must be greater than @c 0.
363 * @see GetTopMargin()
364 * @see GetLeftMargin()
366 result SetMargin(float topMargin, float leftMargin);
369 * Gets the top margin.
373 * @return The size of the top margin, @n
374 * else @c -1 if an error occurs
377 int GetTopMargin(void) const;
380 * Gets the top margin.
384 * @return The size of the top margin, @n
385 * else @c -1.0f if an error occurs
388 float GetTopMarginF(void) const;
391 * Gets the left margin.
395 * @return The size of the left margin, @n
396 * else @c -1 if an error occurs.
399 int GetLeftMargin(void) const;
402 * Gets the left margin.
406 * @return The size of the left margin, @n
407 * else @c -1.0f if an error occurs.
410 float GetLeftMarginF(void) const;
413 friend class _LabelImpl;
417 // This is the copy constructor for this class.
419 Label(const Label& rhs);
422 // Assigns the value of the specified instance to the current instance of %Label.
424 Label& operator =(const Label& rhs);
428 }}} // Tizen::Ui::Controls
430 #endif // _FUI_CTRL_LABEL_H_