inc/FUiCtrlLabel.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlLabel.h
  20  * @brief       This is the header file for the %Label class.
  21  *
  22  * This header file contains the declarations of the %Label class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_LABEL_H_
  26 #define _FUI_CTRL_LABEL_H_
  27
  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>
  40 #include <FUi.h>
  41
  42 namespace Tizen { namespace Ui { namespace Controls
  43 {
  44 /**
  45  * @class       Label
  46  * @brief   This class defines the common behavior of a %Label control.
  47  *
  48  * @since       2.0
  49  *
  50  * The %Label class displays a non-editable text field and does not accept any input from the user.
  51  *
  52  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_label.htm">Label</a>.
  53  *
  54  * The following example demonstrates how to use the %Label class.
  55  *
  56  * @code
  57 // Sample code for LabelSample.h
  58 #include <FUi.h>
  59
  60 class LabelSample
  61         : public Tizen::Ui::Controls::Form
  62 {
  63 public:
  64         LabelSample(void)
  65         : __pLabel(null){}
  66
  67         bool Initialize(void);
  68         virtual result OnInitializing(void);
  69
  70 private:
  71         Tizen::Ui::Controls::Label *__pLabel;
  72 };
  73 *       @endcode
  74 *
  75 *       @code
  76 // Sample code for LabelSample.cpp
  77 #include <FGraphics.h>
  78
  79 #include "LabelSample.h"
  80
  81 using namespace Tizen::Graphics;
  82 using namespace Tizen::Ui::Controls;
  83
  84 bool
  85 LabelSample::Initialize(void)
  86 {
  87         Construct(FORM_STYLE_NORMAL);
  88         return true;
  89 }
  90
  91 result
  92 LabelSample::OnInitializing(void)
  93 {
  94         result r = E_SUCCESS;
  95
  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));
 101
 102         // Adds the label to the form
 103         AddControl(*__pLabel);
 104
 105         return r;
 106 }
 107  * @endcode
 108  *
 109  */
 110 class _OSP_EXPORT_ Label
 111         : public Tizen::Ui::Control
 112 {
 113 public:
 114         /**
 115          * This is the default constructor for this class.
 116          *
 117          * @since       2.0
 118          */
 119         Label(void);
 120
 121         /**
 122          * This is the destructor for this class.
 123          *
 124          * @since       2.0
 125          */
 126         virtual ~Label(void);
 127
 128         /**
 129          * Initializes this instance of %Label with the specified parameters.
 130          *
 131          * @since               2.0
 132          *
 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.
 141          * @remarks
 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.
 145          */
 146         result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text);
 147
 148         /**
 149          * Initializes this instance of %Label with the specified parameters.
 150      *
 151          * @since               2.1
 152          *
 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.
 161          * @remarks
 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.
 165          */
 166         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text);
 167
 168 public:
 169         /**
 170          * Sets the specified text for the %Label control.
 171          *
 172          * @since               2.0
 173          *
 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'.
 176          */
 177         void SetText(const Tizen::Base::String& text);
 178
 179         /**
 180          * Gets the text of the %Label control.
 181          *
 182          * @since       2.0
 183          *
 184          * @return      The text of the %Label control, @n
 185          *                      else an empty string if an error occurs
 186          */
 187         Tizen::Base::String GetText(void) const;
 188
 189         /**
 190          * Sets the background bitmap of the %Label control.
 191          *
 192          * @since               2.0
 193          *
 194          * @param[in]   bitmap   The background bitmap
 195          */
 196         void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 197
 198         /**
 199          * Sets the horizontal alignment of the text of the %Label control.
 200          *
 201          * @since               2.0
 202          *
 203          * @param[in]   alignment       The horizontal text alignment
 204          */
 205         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 206
 207         /**
 208          * Gets the horizontal alignment of the text of the %Label control.
 209          *
 210          * @since       2.0
 211          *
 212          * @return      The horizontal text alignment, @n
 213          *                      else @c ALIGNMENT_LEFT if the instance is invalid
 214          */
 215         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 216
 217         /**
 218          * Sets the vertical alignment of the text of the %Label control.
 219          *
 220          * @since               2.0
 221          *
 222          * @param[in]   alignment       The vertical text alignment
 223          */
 224         void SetTextVerticalAlignment(VerticalAlignment alignment);
 225
 226         /**
 227          * Gets the vertical alignment of the text of the %Label control.
 228          *
 229          * @since       2.0
 230          *
 231          * @return      The vertical text alignment, @n
 232          *                      else @c ALIGNMENT_TOP if the instance is invalid
 233          */
 234         VerticalAlignment GetTextVerticalAlignment(void) const;
 235
 236         /**
 237          * Sets the background color of the %Label control.
 238          *
 239          * @since               2.0
 240          *
 241          * @param[in]   color           The normal background color
 242          */
 243         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 244
 245         /**
 246         * Gets the background color of the %Label control.
 247         *
 248         * @since                2.0
 249         *
 250         * @return               The background color
 251         */
 252         Tizen::Graphics::Color GetBackgroundColor(void) const;
 253
 254         /**
 255          * Sets the text color of the %Label control.
 256          *
 257          * @since               2.0
 258          *
 259          * @param[in]   color           The color to set
 260          */
 261         virtual void SetTextColor(const Tizen::Graphics::Color& color);
 262
 263         /**
 264          * Gets the text color of the %Label control.
 265          *
 266          * @since               2.0
 267          *
 268          * @return              The text color
 269          */
 270         virtual Tizen::Graphics::Color GetTextColor(void) const;
 271
 272         /**
 273          * Sets the text attributes of the %Label control.
 274          *
 275          * @since                       2.0
 276          *
 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.
 281          * @remarks
 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.
 284          */
 285         void SetTextConfig(int size, LabelTextStyle style);
 286
 287         /**
 288          * Sets the text attributes of the %Label control.
 289          *
 290          * @since                       2.1
 291          *
 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.
 296          * @remarks
 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.
 299          */
 300         void SetTextConfig(float size, LabelTextStyle style);
 301
 302         /**
 303          * Gets the text size of the %Label control.
 304          *
 305          * @since       2.0
 306          *
 307          * @return      The size of the text, @n
 308          *                      else @c -1 if an error occurs
 309          */
 310         int GetTextSize(void) const;
 311
 312         /**
 313          * Gets the text size of the %Label control.
 314          *
 315          * @since       2.1
 316          *
 317          * @return      The size of the text, @n
 318          *                      else @c -1.0f if an error occurs
 319          */
 320         float GetTextSizeF(void) const;
 321
 322         /**
 323          * Gets the text style of the %Label control.
 324          *
 325          * @since       2.0
 326          *
 327          * @return  The style of the text, @n
 328          *                      else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
 329          */
 330         LabelTextStyle GetTextStyle(void) const;
 331
 332         /**
 333          * Sets the top and left margins.
 334          *
 335          * @since       2.0
 336          *
 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()
 345          */
 346         result SetMargin(int topMargin, int leftMargin);
 347
 348         /**
 349          * Sets the top and left margins.
 350          *
 351          * @since       2.1
 352          *
 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()
 361          */
 362         result SetMargin(float topMargin, float leftMargin);
 363
 364         /**
 365          * Gets the top margin.
 366          *
 367          * @since       2.0
 368          *
 369          * @return      The size of the top margin, @n
 370          *              else @c -1 if an error occurs
 371          * @see         SetMargin()
 372          */
 373         int GetTopMargin(void) const;
 374
 375         /**
 376          * Gets the top margin.
 377          *
 378          * @since       2.1
 379          *
 380          * @return      The size of the top margin, @n
 381          *              else @c -1.0f if an error occurs
 382          * @see         SetMargin()
 383          */
 384         float GetTopMarginF(void) const;
 385
 386     /**
 387      * Gets the left margin.
 388      *
 389      * @since   2.0
 390      *
 391      * @return      The size of the left margin, @n
 392      *              else @c -1 if an error occurs.
 393      * @see         SetMargin()
 394      */
 395         int GetLeftMargin(void) const;
 396
 397         /**
 398          * Gets the left margin.
 399          *
 400          * @since       2.1
 401          *
 402          * @return      The size of the left margin, @n
 403          *              else @c -1.0f if an error occurs.
 404          * @see         SetMargin()
 405          */
 406         float GetLeftMarginF(void) const;
 407
 408 protected:
 409         friend class _LabelImpl;
 410
 411 private:
 412         //
 413         // This is the copy constructor for this class.
 414         //
 415         Label(const Label& rhs);
 416
 417         //
 418         // Assigns the value of the specified instance to the current instance of %Label.
 419         //
 420         Label& operator =(const Label& rhs);
 421
 422 }; // Label
 423
 424 }}} // Tizen::Ui::Controls
 425
 426 #endif // _FUI_CTRL_LABEL_H_