inc/FUiCtrlLabel.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://floralicense.org/license/
  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 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.
 144          */
 145         result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text);
 146
 147         /**
 148          * Initializes this instance of %Label with the specified parameters.
 149      *
 150          * @since               2.1
 151          *
 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.
 163          */
 164         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text);
 165
 166 public:
 167         /**
 168          * Sets the specified text for the %Label control.
 169          *
 170          * @since               2.0
 171          *
 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'.
 174          */
 175         void SetText(const Tizen::Base::String& text);
 176
 177         /**
 178          * Gets the text of the %Label control.
 179          *
 180          * @since       2.0
 181          *
 182          * @return      The text of the %Label control, @n
 183          *                      else an empty string if an error occurs
 184          */
 185         Tizen::Base::String GetText(void) const;
 186
 187         /**
 188          * Sets the background bitmap of the %Label control.
 189          *
 190          * @since               2.0
 191          *
 192          * @param[in]   bitmap   The background bitmap
 193          */
 194         void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 195
 196         /**
 197          * Sets the horizontal alignment of the text of the %Label control.
 198          *
 199          * @since               2.0
 200          *
 201          * @param[in]   alignment       The horizontal text alignment
 202          */
 203         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 204
 205         /**
 206          * Gets the horizontal alignment of the text of the %Label control.
 207          *
 208          * @since       2.0
 209          *
 210          * @return      The horizontal text alignment, @n
 211          *                      else @c ALIGNMENT_LEFT if the instance is invalid
 212          */
 213         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 214
 215         /**
 216          * Sets the vertical alignment of the text of the %Label control.
 217          *
 218          * @since               2.0
 219          *
 220          * @param[in]   alignment       The vertical text alignment
 221          */
 222         void SetTextVerticalAlignment(VerticalAlignment alignment);
 223
 224         /**
 225          * Gets the vertical alignment of the text of the %Label control.
 226          *
 227          * @since       2.0
 228          *
 229          * @return      The vertical text alignment, @n
 230          *                      else @c ALIGNMENT_TOP if the instance is invalid
 231          */
 232         VerticalAlignment GetTextVerticalAlignment(void) const;
 233
 234         /**
 235          * Sets the background color of the %Label control.
 236          *
 237          * @since               2.0
 238          *
 239          * @param[in]   color           The normal background color
 240          */
 241         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 242
 243         /**
 244         * Gets the background color of the %Label control.
 245         *
 246         * @since                2.0
 247         *
 248         * @return               The background color
 249         */
 250         Tizen::Graphics::Color GetBackgroundColor(void) const;
 251
 252         /**
 253          * Sets the text color of the %Label control.
 254          *
 255          * @since               2.0
 256          *
 257          * @param[in]   color           The color to set
 258          */
 259         virtual void SetTextColor(const Tizen::Graphics::Color& color);
 260
 261         /**
 262          * Gets the text color of the %Label control.
 263          *
 264          * @since               2.0
 265          *
 266          * @return              The text color
 267          */
 268         virtual Tizen::Graphics::Color GetTextColor(void) const;
 269
 270         /**
 271          * Sets the text attributes of the %Label control.
 272          *
 273          * @since                       2.0
 274          *
 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.
 281          */
 282         void SetTextConfig(int size, LabelTextStyle style);
 283
 284         /**
 285          * Sets the text attributes of the %Label control.
 286          *
 287          * @since                       2.1
 288          *
 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.
 295          */
 296         void SetTextConfig(float size, LabelTextStyle style);
 297
 298         /**
 299          * Gets the text size of the %Label control.
 300          *
 301          * @since       2.0
 302          *
 303          * @return      The size of the text, @n
 304          *                      else @c -1 if an error occurs
 305          */
 306         int GetTextSize(void) const;
 307
 308         /**
 309          * Gets the text size of the %Label control.
 310          *
 311          * @since       2.1
 312          *
 313          * @return      The size of the text, @n
 314          *                      else @c -1.0f if an error occurs
 315          */
 316         float GetTextSizeF(void) const;
 317
 318         /**
 319          * Gets the text style of the %Label control.
 320          *
 321          * @since       2.0
 322          *
 323          * @return  The style of the text, @n
 324          *                      else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
 325          */
 326         LabelTextStyle GetTextStyle(void) const;
 327
 328         /**
 329          * Sets the top and left margins.
 330          *
 331          * @since       2.0
 332          *
 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()
 341          */
 342         result SetMargin(int topMargin, int leftMargin);
 343
 344         /**
 345          * Sets the top and left margins.
 346          *
 347          * @since       2.1
 348          *
 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()
 357          */
 358         result SetMargin(float topMargin, float leftMargin);
 359
 360         /**
 361          * Gets the top margin.
 362          *
 363          * @since       2.0
 364          *
 365          * @return      The size of the top margin, @n
 366          *              else @c -1 if an error occurs
 367          * @see         SetMargin()
 368          */
 369         int GetTopMargin(void) const;
 370
 371         /**
 372          * Gets the top margin.
 373          *
 374          * @since       2.1
 375          *
 376          * @return      The size of the top margin, @n
 377          *              else @c -1.0f if an error occurs
 378          * @see         SetMargin()
 379          */
 380         float GetTopMarginF(void) const;
 381
 382     /**
 383      * Gets the left margin.
 384      *
 385      * @since   2.0
 386      *
 387      * @return      The size of the left margin, @n
 388      *              else @c -1 if an error occurs.
 389      * @see         SetMargin()
 390      */
 391         int GetLeftMargin(void) const;
 392
 393         /**
 394          * Gets the left margin.
 395          *
 396          * @since       2.1
 397          *
 398          * @return      The size of the left margin, @n
 399          *              else @c -1.0f if an error occurs.
 400          * @see         SetMargin()
 401          */
 402         float GetLeftMarginF(void) const;
 403
 404 protected:
 405         friend class _LabelImpl;
 406
 407 private:
 408         //
 409         // This is the copy constructor for this class.
 410         //
 411         Label(const Label& rhs);
 412
 413         //
 414         // Assigns the value of the specified instance to the current instance of %Label.
 415         //
 416         Label& operator =(const Label& rhs);
 417
 418 }; // Label
 419
 420 }}} // Tizen::Ui::Controls
 421
 422 #endif // _FUI_CTRL_LABEL_H_