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.@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.
 143          * @remarks
 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.
 147          */
 148         result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Base::String& text);
 149
 150         /**
 151          * Initializes this instance of %Label with the specified parameters.
 152      *
 153          * @since               2.1
 154          *
 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.
 165          * @remarks
 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.
 169          */
 170         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Base::String& text);
 171
 172 public:
 173         /**
 174          * Sets the specified text for the %Label control.
 175          *
 176          * @since               2.0
 177          *
 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'.
 180          */
 181         void SetText(const Tizen::Base::String& text);
 182
 183         /**
 184          * Gets the text of the %Label control.
 185          *
 186          * @since       2.0
 187          *
 188          * @return      The text of the %Label control, @n
 189          *                      else an empty string if an error occurs
 190          */
 191         Tizen::Base::String GetText(void) const;
 192
 193         /**
 194          * Sets the background bitmap of the %Label control.
 195          *
 196          * @since               2.0
 197          *
 198          * @param[in]   bitmap   The background bitmap
 199          */
 200         void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 201
 202         /**
 203          * Sets the horizontal alignment of the text of the %Label control.
 204          *
 205          * @since               2.0
 206          *
 207          * @param[in]   alignment       The horizontal text alignment
 208          */
 209         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 210
 211         /**
 212          * Gets the horizontal alignment of the text of the %Label control.
 213          *
 214          * @since       2.0
 215          *
 216          * @return      The horizontal text alignment, @n
 217          *                      else @c ALIGNMENT_LEFT if the instance is invalid
 218          */
 219         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 220
 221         /**
 222          * Sets the vertical alignment of the text of the %Label control.
 223          *
 224          * @since               2.0
 225          *
 226          * @param[in]   alignment       The vertical text alignment
 227          */
 228         void SetTextVerticalAlignment(VerticalAlignment alignment);
 229
 230         /**
 231          * Gets the vertical alignment of the text of the %Label control.
 232          *
 233          * @since       2.0
 234          *
 235          * @return      The vertical text alignment, @n
 236          *                      else @c ALIGNMENT_TOP if the instance is invalid
 237          */
 238         VerticalAlignment GetTextVerticalAlignment(void) const;
 239
 240         /**
 241          * Sets the background color of the %Label control.
 242          *
 243          * @since               2.0
 244          *
 245          * @param[in]   color           The normal background color
 246          */
 247         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 248
 249         /**
 250         * Gets the background color of the %Label control.
 251         *
 252         * @since                2.0
 253         *
 254         * @return               The background color
 255         */
 256         Tizen::Graphics::Color GetBackgroundColor(void) const;
 257
 258         /**
 259          * Sets the text color of the %Label control.
 260          *
 261          * @since               2.0
 262          *
 263          * @param[in]   color           The color to set
 264          */
 265         virtual void SetTextColor(const Tizen::Graphics::Color& color);
 266
 267         /**
 268          * Gets the text color of the %Label control.
 269          *
 270          * @since               2.0
 271          *
 272          * @return              The text color
 273          */
 274         virtual Tizen::Graphics::Color GetTextColor(void) const;
 275
 276         /**
 277          * Sets the text attributes of the %Label control.
 278          *
 279          * @since                       2.0
 280          *
 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.
 285          * @remarks
 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.
 288          */
 289         void SetTextConfig(int size, LabelTextStyle style);
 290
 291         /**
 292          * Sets the text attributes of the %Label control.
 293          *
 294          * @since                       2.1
 295          *
 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.
 300          * @remarks
 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.
 303          */
 304         void SetTextConfig(float size, LabelTextStyle style);
 305
 306         /**
 307          * Gets the text size of the %Label control.
 308          *
 309          * @since       2.0
 310          *
 311          * @return      The size of the text, @n
 312          *                      else @c -1 if an error occurs
 313          */
 314         int GetTextSize(void) const;
 315
 316         /**
 317          * Gets the text size of the %Label control.
 318          *
 319          * @since       2.1
 320          *
 321          * @return      The size of the text, @n
 322          *                      else @c -1.0f if an error occurs
 323          */
 324         float GetTextSizeF(void) const;
 325
 326         /**
 327          * Gets the text style of the %Label control.
 328          *
 329          * @since       2.0
 330          *
 331          * @return  The style of the text, @n
 332          *                      else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
 333          */
 334         LabelTextStyle GetTextStyle(void) const;
 335
 336         /**
 337          * Sets the top and left margins.
 338          *
 339          * @since       2.0
 340          *
 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()
 349          */
 350         result SetMargin(int topMargin, int leftMargin);
 351
 352         /**
 353          * Sets the top and left margins.
 354          *
 355          * @since       2.1
 356          *
 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()
 365          */
 366         result SetMargin(float topMargin, float leftMargin);
 367
 368         /**
 369          * Gets the top margin.
 370          *
 371          * @since       2.0
 372          *
 373          * @return      The size of the top margin, @n
 374          *              else @c -1 if an error occurs
 375          * @see         SetMargin()
 376          */
 377         int GetTopMargin(void) const;
 378
 379         /**
 380          * Gets the top margin.
 381          *
 382          * @since       2.1
 383          *
 384          * @return      The size of the top margin, @n
 385          *              else @c -1.0f if an error occurs
 386          * @see         SetMargin()
 387          */
 388         float GetTopMarginF(void) const;
 389
 390     /**
 391      * Gets the left margin.
 392      *
 393      * @since   2.0
 394      *
 395      * @return      The size of the left margin, @n
 396      *              else @c -1 if an error occurs.
 397      * @see         SetMargin()
 398      */
 399         int GetLeftMargin(void) const;
 400
 401         /**
 402          * Gets the left margin.
 403          *
 404          * @since       2.1
 405          *
 406          * @return      The size of the left margin, @n
 407          *              else @c -1.0f if an error occurs.
 408          * @see         SetMargin()
 409          */
 410         float GetLeftMarginF(void) const;
 411
 412 protected:
 413         friend class _LabelImpl;
 414
 415 private:
 416         //
 417         // This is the copy constructor for this class.
 418         //
 419         Label(const Label& rhs);
 420
 421         //
 422         // Assigns the value of the specified instance to the current instance of %Label.
 423         //
 424         Label& operator =(const Label& rhs);
 425
 426 }; // Label
 427
 428 }}} // Tizen::Ui::Controls
 429
 430 #endif // _FUI_CTRL_LABEL_H_