1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (developer.feedback@nokia.com)

     6 **

     7 ** This file is part of the HbWidgets module of the UI Extensions for Mobile.

     8 **

     9 ** GNU Lesser General Public License Usage

    10 ** This file may be used under the terms of the GNU Lesser General Public

    11 ** License version 2.1 as published by the Free Software Foundation and

    12 ** appearing in the file LICENSE.LGPL included in the packaging of this file.

    13 ** Please review the following information to ensure the GNU Lesser General

    14 ** Public License version 2.1 requirements will be met:

    15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    16 **

    17 ** In addition, as a special exception, Nokia gives you certain additional

    18 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    20 **

    21 ** If you have questions regarding the use of this file, please contact

    22 ** Nokia at developer.feedback@nokia.com.

    23 **

    24 ****************************************************************************/

    25 

    26 #include <QPalette>

    27 #include <QPainter>

    28 #include <QStyle>

    29 #include <QDebug>

    30 #include <QTextDocument>

    31 #include <QGraphicsSceneResizeEvent>

    32 

    33 #include "hblabel.h"

    34 #include "hbiconitem.h"

    35 #include "hbinstance.h"

    36 #include "hbcolorscheme.h"

    37 #include "hbwidget_p.h"

    38 #include "hbstyleoptionlabel.h"

    39 #include "hbwidgetbase.h"

    40 

    41 /*!

    42     @alpha

    43     @hbcore

    44 

    45     \class HbLabel

    46     \brief HbLabel is a label widget for showing a text or an icon.

    47 

    48     HbLabel supports the following content types

    49     \li plain text

    50     \li html (rich text)

    51     \li icon

    52 

    53     A label can show only one type of content at a time.

    54 

    55     The following is an example of how to create an icon and add it to a label using the HbLabel API.

    56     As the label is not managed by a layout, it must be positioned and sized.

    57     \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,5}

    58 

    59     An example how to add labels into a layout. Explicit positioning and

    60     sizing of the HbLabel objects are not needed.

    61     \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,6}

    62 

    63     The following is an example how to set the color of plain text label. This is a special case

    64     because of colors are usually set by layout system and there is no need to set colors explicitly.

    65     \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,7}

    66 

    67     \sa HbIcon

    68  */

    69 

    70 /*!

    71     \var HbLabel::PlainText

    72 

    73     Text in plain text format.

    74  */

    75 

    76 /*!

    77     \var HbLabel::RichText

    78 

    79     Text in rich text format.

    80  */

    81 

    82 /*!

    83     \var HbLabel::Icon

    84 

    85     Icon.

    86  */

    87 

    88 class HbLabelPrivate: public HbWidgetPrivate {

    89     Q_DECLARE_PUBLIC(HbLabel)

    90 

    91 public:

    92             HbLabelPrivate ();

    93     ~HbLabelPrivate ();

    94 

    95     void clearAll();

    96 

    97     void setText(const QString &text, HbStyle::Primitive primitiveId);

    98     void setIcon(const HbIcon &icon);

    99 

   100     void updatePrimitives ();

   101     void createPrimitives ();

   102 

   103     //shared between icon and text

   104     Qt::Alignment mAlignment;

   105 

   106     // text section

   107     QString mText;

   108     Qt::TextElideMode mElideMode;

   109     Hb::TextWrapping mTextWrapping;

   110     QColor mColor;

   111 

   112     // icon section

   113     HbIcon mIcon;

   114     Qt::AspectRatioMode mAspectRatioMode;

   115 

   116     // primitive handling

   117     QGraphicsItem *mPrimitiveItem;

   118     HbStyle::Primitive mActivePrimitive;

   119 };

   120 

   121 HbLabelPrivate::HbLabelPrivate() :

   122         HbWidgetPrivate(),

   123         mAlignment(Qt::AlignLeft | Qt::AlignVCenter),

   124         mText(QString()),

   125         mElideMode(Qt::ElideRight),

   126         mTextWrapping(Hb::TextNoWrap),

   127         mAspectRatioMode(Qt::KeepAspectRatio),

   128         mPrimitiveItem(NULL),

   129         mActivePrimitive(HbStyle::P_None)

   130 {

   131 }

   132 

   133 void HbLabelPrivate::clearAll()

   134 {

   135     if (mPrimitiveItem) {

   136         delete mPrimitiveItem;

   137         mPrimitiveItem = NULL;

   138         mActivePrimitive = HbStyle::P_None;

   139     }

   140 

   141     mText.clear();

   142     mIcon.clear();

   143 }

   144 

   145 void HbLabelPrivate::setText(const QString &text, HbStyle::Primitive primitiveId)

   146 {

   147     Q_Q(HbLabel);

   148 

   149     if (text.isNull()) {

   150         clearAll();

   151         return;

   152     }

   153 

   154     if (mActivePrimitive != primitiveId) {

   155         clearAll();

   156     }

   157 

   158     if (mText != text || mText.isNull()) {

   159         mText = text;

   160         if (mActivePrimitive != primitiveId) {

   161             mActivePrimitive = primitiveId;

   162             createPrimitives();

   163             q->repolish(); // reconecting new primitive to HbMeshLayout so it is really needed!

   164         }

   165         q->updatePrimitives();

   166     }

   167 }

   168 

   169 void HbLabelPrivate::setIcon(const HbIcon &icon)

   170 {

   171     Q_Q(HbLabel);

   172 

   173     if (icon.isNull()) {

   174         clearAll();

   175         return;

   176     }

   177 

   178     if (mActivePrimitive != HbStyle::P_Label_icon) {

   179         clearAll();

   180     }

   181 

   182     if (mIcon != icon) {

   183         mIcon = icon;

   184 

   185         if (mActivePrimitive != HbStyle::P_Label_icon) {

   186             mActivePrimitive = HbStyle::P_Label_icon;

   187             createPrimitives();

   188             q->repolish(); // reconecting new primitive to HbMeshLayout so it is really needed!

   189         }

   190         q->updatePrimitives();

   191     }

   192 }

   193 

   194 HbLabelPrivate::~HbLabelPrivate()

   195 {

   196 }

   197 

   198 void HbLabelPrivate::createPrimitives()

   199 {

   200     Q_Q(HbLabel);

   201 

   202     Q_ASSERT(mPrimitiveItem==NULL);

   203 

   204     if (mActivePrimitive != HbStyle::P_None) {

   205         mPrimitiveItem = q->style()->createPrimitive(mActivePrimitive, q);

   206     }

   207 }

   208 

   209 void HbLabelPrivate::updatePrimitives()

   210 {

   211     Q_Q(HbLabel);

   212 

   213     if (mActivePrimitive != HbStyle::P_None) {

   214         Q_ASSERT(mActivePrimitive == HbStyle::P_Label_icon

   215                  || mActivePrimitive == HbStyle::P_Label_richtext

   216                  || mActivePrimitive == HbStyle::P_Label_text);

   217 

   218         HbStyleOptionLabel option;

   219         q->initStyleOption(&option);

   220         q->style()->updatePrimitive(mPrimitiveItem, mActivePrimitive, &option);

   221     }

   222 }

   223 

   224 /*!

   225     Constructs the label with a given \a parent.

   226     \param parent - the parent graphics item.

   227  */

   228 HbLabel::HbLabel(QGraphicsItem *parent) :

   229         HbWidget(*new HbLabelPrivate, parent)

   230 {

   231     setFlag(QGraphicsItem::ItemClipsChildrenToShape, true);

   232 }

   233 

   234 /*!

   235     \internal

   236  */

   237 HbLabel::HbLabel(HbLabelPrivate &dd, QGraphicsItem * parent) :

   238         HbWidget(dd, parent)

   239 {

   240     setFlag(QGraphicsItem::ItemClipsChildrenToShape, true);

   241 }

   242 

   243 /*!

   244     Constructs the label with a given \a text and \a parent. This constructor is a convenience for

   245     common use case to have a label with plain text content. Using this contructor you do not need

   246     to call setPlainText() separately in initialization.

   247     \param displayText - the plain text that is shown in the label.

   248     \param parent - the parent graphics item.

   249  */

   250 HbLabel::HbLabel(const QString &displayText, QGraphicsItem *parent) :

   251         HbWidget(*new HbLabelPrivate, parent)

   252 {

   253     setFlag(QGraphicsItem::ItemClipsChildrenToShape, true);

   254     setPlainText(displayText);

   255 }

   256 

   257 /*!

   258     Label destructor.

   259  */

   260 HbLabel::~HbLabel ()

   261 {

   262 }

   263 

   264 /*!

   265     Sets the label contents to plain text containing the textual

   266     representation of integer \a num. Any previous content is cleared.

   267     Does nothing if the integer's string representation is the same as

   268     the current contents of the label.

   269     \param num - the number that is shown in the label.

   270 

   271     \sa setPlainText()

   272  */

   273 void HbLabel::setNumber(int number)

   274 {

   275     QString str;

   276     str.setNum(number);

   277     setPlainText(str);

   278 }

   279 

   280 /*!

   281     \overload

   282 

   283     Sets the label contents to plain text containing the textual

   284     representation of double \a num. Any previous content is cleared.

   285     Does nothing if the double's string representation is the same as

   286     the current contents of the label.

   287     \param num - the number that is shown in the label.

   288 

   289     \sa setPlainText()

   290  */

   291 void HbLabel::setNumber(qreal number)

   292 {

   293     QString str;

   294     str.setNum(number);

   295     setPlainText(str);

   296 }

   297 

   298 /*!

   299     Sets the text elide mode to \a elideMode.

   300     The elide mode specifies where text tructation and ellipsis "..." are applied if the label text

   301     is too large to fit the label's dimensions.

   302     \param elideMode - the new elide mode.

   303 

   304     \sa elideMode

   305     \sa Qt::TextElideMode

   306  */

   307 void HbLabel::setElideMode (Qt::TextElideMode elideMode)

   308 {

   309     Q_D(HbLabel);

   310     if (elideMode != d->mElideMode) {

   311         d->mElideMode = elideMode;

   312         if (!d->mText.isNull()) {

   313             updatePrimitives();

   314         }

   315     }

   316 }

   317 

   318 /*!

   319     Default elide mode is Qt::ElideRight.

   320     \return the elide mode of the text.

   321 

   322     \sa HbLabel::setElideMode()

   323  */

   324 Qt::TextElideMode HbLabel::elideMode() const

   325 {

   326     Q_D(const HbLabel);

   327     return d->mElideMode;

   328 }

   329 

   330 /*!

   331     Sets the text wrapping mode to \a mode.

   332     \param mode - wrapping mode

   333 

   334     \sa Hb::TextWrapping

   335  */

   336 void HbLabel::setTextWrapping(Hb::TextWrapping mode)

   337 {

   338     Q_D(HbLabel);

   339     if (d->mTextWrapping != mode) {

   340         d->mTextWrapping = mode;

   341         if (!d->mText.isNull()) {

   342             updatePrimitives();

   343         }

   344     }

   345 }

   346 

   347 /*!

   348     \return the label's current text wrapping mode.

   349     Default value is NoWrap.

   350 

   351     \sa setTextWrapping()

   352  */

   353 Hb::TextWrapping HbLabel::textWrapping() const

   354 {

   355     Q_D(const HbLabel);

   356     return d->mTextWrapping;

   357 }

   358 

   359 /*!

   360     Sets the icon displayed by this label.

   361     Removes any existing text from the label.

   362     \param icon - the icon that this label displays.

   363 

   364     \sa icon

   365  */

   366 void HbLabel::setIcon(const HbIcon &icon)

   367 {

   368     Q_D(HbLabel);

   369 

   370     d->setIcon(icon);

   371 }

   372 

   373 /*!

   374     \return the icon displayed by this label.

   375 

   376     \sa setIcon

   377  */

   378 HbIcon HbLabel::icon() const

   379 {

   380     Q_D(const HbLabel);

   381     return d->mIcon;

   382 }

   383 

   384 /*!

   385     Clears the content of the label. After this the label is empty.

   386 

   387     \sa isEmpty()

   388  */

   389 void HbLabel::clear()

   390 {

   391     Q_D(HbLabel);

   392     d->clearAll();

   393 }

   394 

   395 /*!

   396     Sets the aspect ratio mode for the icon. The default aspect ratio is Qt::KeepAspectRatio.

   397     \param aspectRatioMode - the new aspect ration mode.

   398 

   399     \sa aspectRatioMode()

   400  */

   401 void HbLabel::setAspectRatioMode(Qt::AspectRatioMode aspectRatioMode)

   402 {

   403     Q_D(HbLabel);

   404     if (d->mAspectRatioMode != aspectRatioMode) {

   405         d->mAspectRatioMode = aspectRatioMode;

   406         if (!d->mIcon.isNull()) {

   407             updatePrimitives();

   408         }

   409     }

   410 }

   411 

   412 /*!

   413     \return the aspect ratio set for the icon. The default aspect ratio is

   414     Qt::KeepAspectRatio.

   415 

   416     \sa setAspectRatio()

   417  */

   418 Qt::AspectRatioMode HbLabel::aspectRatioMode() const

   419 {

   420     Q_D(const HbLabel);

   421     return d->mAspectRatioMode;

   422 }

   423 

   424 /*!

   425     Sets the label contents to plain text containing \a text. Any previous content is cleared.

   426     Does nothing if the string representation is the same as the current contents of the label.

   427     \param text - the plain text that is shown in the label.

   428 

   429     \sa setHtml()

   430     \sa setIcon()

   431  */

   432 void HbLabel::setPlainText(const QString &text)

   433 {

   434     Q_D(HbLabel);

   435     d->setText(text, HbStyle::P_Label_text);

   436 }

   437 

   438 /*!

   439     Sets the label contents to html text containing \a text. Any previous content is cleared.

   440     Does nothing if the string representation is the same as the current contents of the label.

   441     \param text - the html text that is shown in the label.

   442 

   443     \sa setPlainText()

   444     \sa setIcon()

   445  */

   446 void HbLabel::setHtml(const QString &text)

   447 {

   448     Q_D(HbLabel);

   449     d->setText(text, HbStyle::P_Label_richtext);

   450 }

   451 

   452 /*!

   453     Sets the \a alignment of the label.

   454     \param alignment - the new alignment.

   455 

   456     \sa alignment

   457  */

   458 void HbLabel::setAlignment(Qt::Alignment alignment)

   459 {

   460     Q_D(HbLabel);

   461     if (d->mAlignment != alignment) {

   462         d->mAlignment = alignment;

   463         if (d->mActivePrimitive!=HbStyle::P_None) {

   464             updatePrimitives();

   465         }

   466     }

   467 }

   468 

   469 /*!

   470     \return the alignment. Default alignment is 'Qt::AlignLeft | Qt::AlignVCenter'

   471 

   472     \sa HbLabel::setAlignment()

   473  */

   474 Qt::Alignment HbLabel::alignment() const

   475 {

   476     Q_D(const HbLabel);

   477     return d->mAlignment;

   478 }

   479 

   480 /*!

   481     \return true if both text and icon are empty; otherwise returns false.

   482 

   483 

   484     An empty icon is initialised by HbIcon() and empty text with QString().

   485     An icon initialised with HbIcon("") is empty. A string initialised with

   486     QString("") is not empty.

   487 

   488     \sa clear()

   489  */

   490 bool HbLabel::isEmpty() const

   491 {

   492     Q_D(const HbLabel);

   493     return d->mActivePrimitive == HbStyle::P_None;

   494 }

   495 

   496 /*!

   497     Returns a pointer to the QGraphicsItem primitive used by this label.

   498     \param primitive - the type of graphics primitive required.

   499     HbLabel supports HbStyle::P_Label_text and HbStyle::P_Label_icon.

   500     \return the QGraphicsItem used by the label. It is 0 if type \a primitive not currently in use.

   501     It is also 0 if the text or icon object is empty.

   502 

   503     \reimp

   504 

   505     \sa isEmpty()

   506  */

   507 QGraphicsItem * HbLabel::primitive(HbStyle::Primitive primitive) const

   508 {

   509     Q_D(const HbLabel);

   510     if (primitive == d->mActivePrimitive) {

   511         return d->mPrimitiveItem;

   512     }

   513     return HbWidget::primitive(primitive);

   514 }

   515 

   516 /*!

   517     Initializes \a option with the values from this HbLabel.

   518     HbStyleOptionLabel is used by HbStyle to perform changes in appearance

   519     of this label.

   520     \param option - the object in which the label's style options are set.

   521  */

   522 void HbLabel::initStyleOption(HbStyleOptionLabel *option) const

   523 {

   524     Q_D(const HbLabel);

   525 

   526     HbWidget::initStyleOption(option);

   527 

   528     option->alignment = d->mAlignment;

   529 

   530     if (!d->mText.isNull()) {

   531         option->text = d->mText;

   532         option->elideMode = d->mElideMode;

   533         option->textWrapMode = d->mTextWrapping;

   534         option->color = d->mColor;

   535     }

   536 

   537     if (!d->mIcon.isNull()) {

   538         option->icon = d->mIcon;

   539         option->aspectRatioMode = d->mAspectRatioMode;

   540     }

   541 }

   542 

   543 /*!

   544     Slot to be called when the style primitives need to be updated.

   545     This function does not initiate redrawing this widget.

   546 

   547     \reimp

   548  */

   549 void HbLabel::updatePrimitives()

   550 {

   551     Q_D(HbLabel);

   552     d->updatePrimitives();

   553     HbWidget::updatePrimitives();

   554 }

   555 

   556 int HbLabel::type() const

   557 {

   558     return HbLabel::Type;

   559 }

   560 

   561 /*!

   562     Plain text accessor. Returns empty string if not set.

   563  */

   564 QString HbLabel::plainText() const

   565 {

   566     Q_D(const HbLabel);

   567     if (d->mActivePrimitive == HbStyle::P_Label_text) {

   568         return d->mText;

   569     }

   570     return QString();

   571 }

   572 

   573 /*!

   574     Rich text text accessor. Returns empty string if not set.

   575  */

   576 QString HbLabel::html() const

   577 {

   578     Q_D(const HbLabel);

   579     if (d->mActivePrimitive == HbStyle::P_Label_richtext) {

   580         return d->mText;

   581     }

   582     return QString();

   583 }

   584 

   585 /*!

   586     Set color of text. If color is set to invalid value theme color is used.

   587  */

   588 void HbLabel::setTextColor( const QColor &textColor )

   589 {

   590     Q_D(HbLabel);

   591     if (d->mColor!=textColor) {

   592         d->mColor=textColor;

   593         if (!d->mText.isNull()) {

   594             updatePrimitives();

   595         }

   596     }

   597 }

   598 

   599 /*!

   600     Returns color of text or invalid value if theme color is used.

   601  */

   602 QColor HbLabel::textColor() const

   603 {

   604     Q_D(const HbLabel);

   605     return d->mColor;

   606 }

   607 

   608 #include "moc_hblabel.cpp"