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 public:
 148         /**
 149          * Sets the specified text for the %Label control.
 150          *
 151          * @since               2.0
 152          *
 153          * @param[in]   text            The string to set
 154          * @remarks             To display text in multi-lines or to denote the end of line use '\\n'.
 155          */
 156         void SetText(const Tizen::Base::String& text);
 157
 158         /**
 159          * Gets the text of the %Label control.
 160          *
 161          * @since       2.0
 162          *
 163          * @return      The text of the %Label control, @n
 164          *                      else an empty string if an error occurs
 165          */
 166         Tizen::Base::String GetText(void) const;
 167
 168         /**
 169          * Sets the background bitmap of the %Label control.
 170          *
 171          * @since               2.0
 172          *
 173          * @param[in]   bitmap   The background bitmap
 174          */
 175         void SetBackgroundBitmap(const Tizen::Graphics::Bitmap& bitmap);
 176
 177         /**
 178          * Sets the horizontal alignment of the text of the %Label control.
 179          *
 180          * @since               2.0
 181          *
 182          * @param[in]   alignment       The horizontal text alignment
 183          */
 184         void SetTextHorizontalAlignment(HorizontalAlignment alignment);
 185
 186         /**
 187          * Gets the horizontal alignment of the text of the %Label control.
 188          *
 189          * @since       2.0
 190          *
 191          * @return      The horizontal text alignment, @n
 192          *                      else @c ALIGNMENT_LEFT if the instance is invalid
 193          */
 194         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 195
 196         /**
 197          * Sets the vertical alignment of the text of the %Label control.
 198          *
 199          * @since               2.0
 200          *
 201          * @param[in]   alignment       The vertical text alignment
 202          */
 203         void SetTextVerticalAlignment(VerticalAlignment alignment);
 204
 205         /**
 206          * Gets the vertical alignment of the text of the %Label control.
 207          *
 208          * @since       2.0
 209          *
 210          * @return      The vertical text alignment, @n
 211          *                      else @c ALIGNMENT_TOP if the instance is invalid
 212          */
 213         VerticalAlignment GetTextVerticalAlignment(void) const;
 214
 215         /**
 216          * Sets the background color of the %Label control.
 217          *
 218          * @since               2.0
 219          *
 220          * @param[in]   color           The normal background color
 221          */
 222         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 223
 224         /**
 225          * Gets the background color of the %Label control.
 226          *
 227          * @since               2.0
 228          *
 229          * @return              The background color
 230          */
 231         Tizen::Graphics::Color GetBackgroundColor(void) const;
 232
 233         /**
 234          * Sets the text color of the %Label control.
 235          *
 236          * @since               2.0
 237          *
 238          * @param[in]   color           The color to be set
 239          */
 240         virtual void SetTextColor(const Tizen::Graphics::Color& color);
 241
 242         /**
 243          * Gets the text color of the %Label control.
 244          *
 245          * @since               2.0
 246          *
 247          * @return              The text color
 248          */
 249         virtual Tizen::Graphics::Color GetTextColor(void) const;
 250
 251         /**
 252          * Sets the text attributes of the %Label control.
 253          *
 254          * @since                       2.0
 255          *
 256          * @param[in]   size                    The size of the text
 257          * @param[in]   style                   The style of the text
 258          * @exception   E_SUCCESS               The method is successful.
 259          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 260          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 261          *                              If @c size is less than the minimum size, this method fails. The minimum font size is 6 on devices of high screen density.
 262          */
 263         void SetTextConfig(int size, LabelTextStyle style);
 264
 265         /**
 266          * Gets the text size of the %Label control.
 267          *
 268          * @since       2.0
 269          *
 270          * @return      The size of the text, @n
 271          *                      else @c -1 if an error occurs
 272          */
 273         int GetTextSize(void) const;
 274
 275         /**
 276          * Gets the text style of the %Label control.
 277          *
 278          * @since       2.0
 279          *
 280          * @return  The style of the text, @n
 281          *                      else @c LABEL_TEXT_STYLE_NORMAL if the instance is invalid
 282          */
 283         LabelTextStyle GetTextStyle(void) const;
 284
 285         /**
 286          * Sets the top and left margins.
 287          *
 288          * @since       2.0
 289          *
 290          * @return      An error code
 291          * @param[in]   topMargin         The top margin.
 292          * @param[in]   leftMargin        The left margin.
 293          * @exception   E_SUCCESS         The method is successful.
 294          * @exception   E_INVALID_ARG     The specified input parameter is invalid. @n
 295          *                                The specified @c size must be greater than @c 0.
 296
 297          * @see                           GetTopMargin(), GetLeftMargin()
 298          */
 299         result SetMargin(int topMargin, int leftMargin);
 300
 301         /**
 302          * Gets the top margin.
 303          *
 304          * @since       2.0
 305          *
 306          * @return      The size of the top margin, @n
 307          *              else @c -1 if an error occurs
 308          * @see         SetMargin()
 309          */
 310         int GetTopMargin(void) const;
 311
 312     /**
 313      * Gets the left margin.
 314      *
 315      * @since   2.0
 316      *
 317      * @return      The size of the left margin, @n
 318      *              else @c -1 if an error occurs.
 319      * @see         SetMargin()
 320      */
 321         int GetLeftMargin(void) const;
 322
 323 protected:
 324         friend class _LabelImpl;
 325
 326 private:
 327         //
 328         // This is the copy constructor for this class.
 329         //
 330         Label(const Label& rhs);
 331
 332         //
 333         // Assigns the value of the specified instance to the current instance of %Label.
 334         //
 335         Label& operator =(const Label& rhs);
 336
 337 }; // Label
 338
 339 }}} // Tizen::Ui::Controls
 340
 341 #endif // _FUI_CTRL_LABEL_H_